Dokumentation

Schnell eingerichtet

Sie arbeiten mit Claude, Codex oder einem anderen Agenten? Kopieren Sie einfach den folgenden Prompt und geben Sie die Installation vollständig aus der Hand.

Install AddSpeech on this site by following https://addspeech.com/skill.md

Diese Anweisungen sind eine ganz gewöhnliche Seite, die Sie öffnen und lesen können, bevor Sie irgendetwas einfügen. Sie ermittelt selbst, womit Ihr Projekt gebaut ist, fragt, bevor sie schreibt, und kein Teil Ihres Projekts geht an uns.

Wenn Sie dieselbe Seite als Skill unter ~/.claude/skills/addspeech/SKILL.md ablegen, können Sie sie auf der nächsten Website beim Namen aufrufen, statt wieder einen Link einzufügen. Es ist so oder so dieselbe Datei.

Installation

Alles darunter richtet sich nach dieser Wahl: der Installationsschritt, die Beispiele und wie jede Option geschrieben wird. Sie wird in diesem Browser gemerkt, die nächste Seite steht also gleich richtig.

Kein Paket, nur ein Effekt, der das Tag beim Mounten hinzufügt und beim Unmounten wieder entfernt - genau das Stück, das ein kopiertes Script-Tag falsch macht, sobald ein Router im Spiel ist.

AddSpeech.jsx

import { useEffect } from 'react';

export function AddSpeech({ target = 'textarea' }) {
  useEffect(() => {
    const script = document.createElement('script');

    script.src = 'https://cdn.addspeech.com/widget.js';
    script.dataset.key = 'as_pub_your_key_here';
    script.dataset.target = target;
    document.body.append(script);

    return () => {
      script.remove();
    document.querySelector('addspeech-microphone')?.remove();
    };
  }, [target]);

  return null;
}

Er steht im Quelltext der Seite, so wie ein Publishable Key von Stripe oder ein key von Google Maps. Ein key pro Domain, und in dieser Installation ist er dort mit Absicht lesbar. Er funktioniert nur auf den Domains, die in Ihrem Konto stehen, wer ihn also auf die eigene Website kopiert, hat nichts davon.

Wenn er dort gar nicht erst auftauchen soll, kann ihn Ihr eigener Server behalten und jeder Seite pro Aufnahme ein kurzlebiges Token geben. Das ist die Option session weiter unten, und das ist die Installation, die wir jedem empfehlen, der einen Server hat, auf den er sie stellen kann.

Mehr ist nicht nötig. Von allein füllt das Mikrofon die textarea der Seite - die, in der zuletzt getippt wurde, wenn es mehrere gibt - ein Formular mit einem einzigen Nachrichtenfeld braucht also gar kein target. Setzen Sie data-target dazu, einen CSS-Selektor wie den, den Sie querySelector geben würden, wenn das Feld ein input statt einer textarea ist, oder wenn von mehreren textareas nur eine Ihnen gehört. Auf einer Seite, auf der nichts passt, erscheint der Knopf gar nicht - das Script-Tag darf also in der Vorlage stehen, die jede Seite verwendet, und das Mikrofon taucht nur dort auf, wo ein Formular ist.

Voraussetzungen

Eine kurze Liste, die eine gewöhnliche Website größtenteils schon erfüllt.

Verwendung

Alles, was man dem Widget sagen kann, gesagt als Attribute am Script-Tag. Pflicht ist nur der key; der Rest hat Standardwerte, die so gewählt sind, dass ein weggelassenes Attribut etwas Sinnvolles ergibt und nicht etwas Kaputtes.

Die Zeilen unten nennen jede Option so, wie ein Script-Tag sie nennt. Auf React schreibt man dieselbe Option so:

script.dataset.theme = 'spotlight';

Abweichende Einstellungen an einem Feld

Alles oben Genannte lässt sich auch am Feld selbst sagen, mit data-speech- vor dem Namen. Gefragt wird zuerst das Feld, das Script-Tag ist der Rückfall. Eine Ausnahme kostet also genau ein Attribut, und alles, was Sie nicht erwähnen, folgt weiter der Seite. Ein Formular mit einer Betreffzeile über einem Nachrichtenfeld kann beide verschieden beschriften oder den Countdown an den Rand des langen Feldes legen und dem kurzen einen Ring lassen.

<input
  id="subject"
  data-speech-label="Dictate"
  data-speech-counter="ring"
/>

<textarea
  id="message"
  data-speech-anchor="field"
  data-speech-counter="bar"
  data-speech-grow="true"
></textarea>

Das Widget kleidet sich für das Feld, in das in diesem Moment geschrieben wird, es bleibt also ein Mikrofon und nicht eines pro Feld. Der key ist das eine Attribut, das hier nichts zu suchen hat: ein zweiter key auf einer Seite ist ein zweites Konto.

Am Feld selbst einen Blick wert

Zwei Attribute an Ihrem eigenen Feld statt am Script-Tag. Eine Transkription ist ein Absatz, den niemand Korrektur gelesen hat, lassen Sie also die Rechtschreibprüfung des Browsers an: die rote Wellenlinie ist für den, der gerade gesprochen hat, der schnellste Weg zu dem einen Namen, der falsch angekommen ist, und das Verbessern ist ein Doppelklick. Die meisten Browser tun das bei einer textarea schon von selbst, aber nicht alle, und es ausdrücklich zu setzen macht es überall wahr. Autocapitalize hält die Sätze, die danach auf dem Telefon von Hand dazukommen, mit den gesprochenen im Einklang.

<textarea
  id="message"
  spellcheck="true"
  autocapitalize="sentences"
  rows="4"
></textarea>

Gestaltung

Das Widget wohnt in einem Shadow Root, denn das ist die einzige verlässliche Art, ein Stylesheet zu überleben, das jemand anderes geschrieben hat: nichts von Ihnen greift hinein, und nichts von uns tritt auf Ihre Seite aus. Derselbe Schutz würde das Umgestalten unmöglich machen, deshalb sind zwei Türen darin mit Absicht offen geblieben.

Custom Properties

Setzen Sie eine davon aus Ihrem eigenen Stylesheet auf das Widget, und sie schlägt das, worum das Script-Tag gebeten hat. Genau das macht einen Dark Mode, eine andere Farbe je Bereich der Website oder eine Regel für den Druck überhaupt erst möglich.

--as-accent

Die eine Farbe, aus der alles andere abgeleitet wird.

--as-face

Der Hintergrund des Knopfes selbst, normalerweise der Akzent.

--as-ink

Das Symbol und das Wort auf dem Knopf, normalerweise weiß.

--as-deep

Der Schatten unter dem Knopf, normalerweise eine dunklere Fassung des Akzents.

--as-lift

Der Knopf unter dem Zeiger, normalerweise eine hellere Fassung des Akzents.

--as-radius

Wie rund die Ecken des Knopfes sind.

--as-scale

Wie groß der Knopf ist, als schlichtes Vielfaches seiner normalen Größe - 0.8 ist die Einstellung small, 1.2 die Einstellung large. Dass es eine Property ist und nicht nur ein Attribut, ist der ganze Punkt: sie lässt sich in einer Media Query setzen, der Knopf kann am Schreibtisch also eine Größe haben und unter einem Daumen eine andere.

--as-font

Die Schrift des Knopfes und der Statuszeile.

--as-hot

Die Farbe einer laufenden Aufnahme, die Ihrem Akzent folgt, solange Sie nichts anderes sagen. Dass aufgenommen wird, sagen der pulsierende Halo, der Countdown und das Wort, das sie stoppt, und nicht die Farbe - setzen Sie das hier also auf Rot, wenn Sie die alte Konvention zurückhaben wollen.

addspeech-microphone {
  --as-accent: #7c3aed;
  --as-radius: 12px;
}

@media (prefers-color-scheme: dark) {
  addspeech-microphone {
    --as-accent: #a78bfa;
  }
}

Parts

Für das, was eine Custom Property nicht ausdrücken kann: ein schwererer Knopf, eine Statuszeile, die zu Ihren eigenen Meldungen passt. Jeder Name hier unten ist ein Versprechen - wie ein Element innerhalb des Widgets heißt, darf sich mit jeder Version ändern, was Sie in Ihr Stylesheet schreiben, nicht.

::part(button)

Der Knopf selbst, Symbol und Wort inbegriffen.

::part(label)

Nur das Wort auf dem Knopf.

::part(icon)

Nur das Mikrofon.

::part(status)

Die Zeile, die sagt, was gerade geschieht - zuhören, transkribieren oder was schiefgegangen ist.

::part(countdown)

Die Pille unter dem Knopf, die die letzten zehn Sekunden in Worten herunterzählt.

::part(hint)

Die kleine Erinnerung an die Tastatur, die während einer Aufnahme zu sehen ist.

::part(tip)

Die kleine Blase über dem Knopf, die das Tastenkürzel nennt, auf einem Gerät mit Zeiger.

::part(backdrop)

Das Leuchten oder die abgedunkelte Seite dahinter, je nach Thema.

::part(bar)

Die Countdown-Linie am unteren Rand des Fensters, wenn Sie diesen Zähler gewählt haben.

::part(badge)

Der kleine AddSpeech-Link unter dem Knopf, im kostenlosen Tarif.

addspeech-microphone::part(button) {
  box-shadow: none;
  font-weight: 600;
}

addspeech-microphone::part(status) {
  font-family: "Your Face", sans-serif;
}

Das Widget trägt seinen Zustand außerdem an sich selbst, als gewöhnliche Attribute, sodass Sie genauso gut einen Moment gestalten können wie ein Element.

addspeech-microphone[data-state="listening"]::part(label) {
  text-transform: uppercase;
}

Alles, was sich bewegt, ist für jeden, dessen System um weniger Bewegung bittet, bereits abgeschaltet. Jedes Thema behält den Teil, der sagt, dass das Mikrofon an ist, und verliert nur den Teil, der sich bewegt. Dieses Verhalten sollte nicht überschrieben werden.

Beispiele

Vier fertige. Jedes davon ist alles, was auf der Seite stehen muss.

Jedes ist darunter gezeichnet. Das sind Bilder und keine laufenden Mikrofone - eine Seite, die Sie beim Lesen viermal um Aufnahmeerlaubnis bittet, wäre eine seltsame Art, für eine einzige Zeile Skript zu werben. Das laufende steht auf der Startseite.

Das Kleinste, was funktioniert

Ein Mikrofon in der unteren Ecke des Feldes, das es füllt, in unserer Farbe, auf der einen textarea der Seite. Nichts eingestellt, nichts gewählt.

AddSpeech.jsx

script.src = 'https://cdn.addspeech.com/widget.js';
script.dataset.key = 'as_pub_your_key_here';

In Ihren Farben, am Rand des Fensters

Am Bildschirmrand schwebend statt im Feld sitzend, in Ihrer eigenen Farbe, mit kantigeren Ecken und Ihrem eigenen Wort neben dem Mikrofon. Ein frei stehender Knopf ist der einzige, der ein Wort tragen kann: im Feld verankert steht er ohnehin neben dem, was er füllt, und dann fällt das Wort weg.

AddSpeech.jsx

script.src = 'https://cdn.addspeech.com/widget.js';
script.dataset.key = 'as_pub_your_key_here';
script.dataset.anchor = 'window';
script.dataset.accent = '#7c3aed';
script.dataset.radius = '12';
script.dataset.label = 'Dictate';
script.dataset.sound = 'chime';

Auf einem Dashboard

Nichts auf der Seite bewegt sich außer dem Knopf, der gedrückt wurde, das Tastenkürzel geht an die Seite zurück, und die Schrift ist die, die ohnehin schon geladen ist.

AddSpeech.jsx

script.src = 'https://cdn.addspeech.com/widget.js';
script.dataset.key = 'as_pub_your_key_here';
script.dataset.theme = 'subtle';
script.dataset.position = 'left';
script.dataset.font = 'inherit';
script.dataset.shortcut = 'off';

Eine gesprochene Antwort

Für eine Seite, deren ganze Aufgabe es ist, einzusammeln, was jemand sagt: die Seite tritt zurück, das Mikrofon kommt in die Mitte, und der Kasten wächst mit dem Absatz, der darin landet.

AddSpeech.jsx

script.src = 'https://cdn.addspeech.com/widget.js';
script.dataset.key = 'as_pub_your_key_here';
script.dataset.theme = 'spotlight';
script.dataset.grow = 'true';

Ihren Formularen Namen geben

Ihre Kontoseite schlüsselt den Monat nach Formular auf: wie viele Antworten jedes eingesammelt hat und wie lang eine übliche war. Das liest sich nur dann gut, wenn Ihre Formulare Namen haben, und so bekommen sie welche.

Ein Formular wird nach dem ersten benannt, das es gibt: ein data-speech-name am Feld oder am Formular, die id des Formulars, der name des Formulars, der name des Feldes und, wenn es nichts davon gibt, die Adresse, an die das Formular gesendet wird. Die meisten Websites bekommen also vernünftige Namen, ohne etwas zu ändern - aber der Anfang dieser Liste ist der Teil, den Sie in der Hand haben.

<form action="/customer-support/refund" data-speech-name="Refund Form">
  <textarea name="reason"></textarea>
</form>

Lohnt sich, sobald eine Seite mehrere Formulare trägt, oder wenn die id etwas ist, das ein Baukasten erzeugt hat. „Retouren“ und „Reklamation“ sagen Ihnen auf einen Blick etwas; „form-7ab“ nicht.

Bei diesem letzten Notbehelf wird nur der Pfad verwendet, und davon nur die letzten zwei Segmente. Die Query fällt weg, und jedes Segment, das nach einer Kennung aussieht - eine Bestellnummer, eine ULID, ein Hash, wird durch :id ersetzt, bevor es gespeichert wird. Eine Formularvorlage auf achttausend Produktseiten bleibt ein Formular, und eine Bestellnummer wird nie aufgeschrieben.

Nichts davon handelt von der Person, die das Formular ausfüllt. Festgehalten werden der Name des Formulars und die Stunde des Tages auf der Uhr des Besuchers, und beides beschreibt Ihre Website und nicht Ihren Besucher. Für das, was jemand gesagt hat, gibt es weiterhin keine Spalte.

Wissen, dass gesprochen wurde

Wenn es Ihnen nützt zu wissen, welche Einsendungen diktiert und welche getippt wurden, geben Sie dem Formular ein verstecktes Feld namens _mic. Das Widget füllt dieses Feld aus; es fügt es nie hinzu. Ein Formular ohne dieses Feld verhält sich genau so wie heute.

<form method="post" action="/contact">
  <textarea name="message"></textarea>

  <input type="hidden" name="_mic">
</form>

Es wird in dem Moment auf true gesetzt, in dem die Wörter im Feld landen, und zu keinem früheren. Wer das Mikrofon öffnet und es sich dann anders überlegt, oder wessen Aufnahme leer zurückkommt, schickt das Formular mit dem Feld noch leer ab - bei Ihnen kommt also entweder „true“ an oder gar nichts.

Was das wert ist, ist echt, aber bescheiden. Es sagt, dass in diesem Browser Audio aufgenommen, zu uns geschickt und mit Wörtern darin zurückgekommen ist, und das ist erheblich mehr Mühe, als ein Script sich macht, das ein Formular ausfüllt. Damit ist es das Abwägen wert, neben dem, worauf Sie ohnehin schon schauen.

Es ist kein Beweis dafür, dass ein Mensch das Formular ausgefüllt hat, und wir sagen das lieber, als es als einen zu verkaufen. Audio lässt sich aus einem Lautsprecher in ein Mikrofon spielen oder gleich ganz erzeugen, von jedem, der bereit ist, einen Nachmittag darauf zu verwenden. Behandeln Sie es wie einen Honeypot: ein billiges Signal, das man gerne mitnimmt, nie das, was zwischen Ihrem Formular und der Welt steht.

Was mit der Aufnahme geschieht

• Es wird nichts aufbewahrt. Das Audio wird innerhalb derselben Anfrage transkribiert und verworfen, jedes Mal - es gibt keinen Eimer, in dem es zuerst landet, und keine Einstellung, die daran etwas ändert.
• Nichts läuft offen über die Leitung. Ein Browser gibt einer Seite, die nicht auf HTTPS läuft, ohnehin kein Mikrofon, und die Aufnahme erreicht uns über dieselbe verschlüsselte Verbindung - das Audio ist unterwegs also nirgends mitzulesen, zwischen dem, der spricht, und dem Text, der zurückkommt.
• Ein key wird über einfaches HTTP abgewiesen, auch wenn die Adresse so in die Liste der erlaubten Domains eingetragen wurde, und es gibt keine Einstellung, die das abschaltet. Die einzige Ausnahme ist localhost, wo der Verkehr die Maschine nicht verlässt und wo Menschen bauen.
• Auf dem, was hier durchgeht, wird nichts trainiert. Unsere Modelle nicht und die von irgendwem sonst auch nicht.
• Stille wird nicht berechnet, und eine Anfrage, die auf unserer Seite fehlgeschlagen ist, auch nicht.
• Sollte sich daran je etwas ändern, steht es auf dieser Seite, bevor es geschieht.

Jemanden empfehlen

In jedem Konto steckt ein Link. Wer sich über Ihren Link anmeldet, bringt Ihnen fills ein, die Sie dem Monat zuschlagen können, der Ihnen passt.

• Ausgezahlt wird in fills, nicht in Geld. Keine Rechnung, die Sie schreiben müssen, keine Schwelle, die Sie erst erreichen müssen, und keine Auszahlung, auf die Sie warten - die Belohnung ist das Produkt selbst, und sie taucht einfach in Ihrem Konto auf.
• Eine kostenlose Anmeldung ist 25 fills wert, ein Freelancer 300 und eine Agency 750. Das sind feste Zahlen und kein Prozentsatz, eine Preisänderung ändert also nie stillschweigend, was eine Empfehlung wert ist.
• Ein Guthaben wird einen Monat lang zurückgehalten, bevor es ausgegeben werden kann, und das Konto, das es eingebracht hat, muss eine Domain eingerichtet und das Mikrofon mindestens einmal wirklich benutzt haben. Das gilt für kostenlose wie für bezahlte Anmeldungen; bei einem bezahlten Tarif muss das Abonnement den Monat außerdem überstanden haben, denn eine Kartenzahlung kann noch zurückgeholt werden.
• Sie entscheiden, in welchem Monat sie landen. Legen Sie alle auf den nächsten Monat, wenn Sie einen vollen erwarten, oder verteilen Sie sie. Was ein Monat nicht verbraucht, kommt an seinem Ende auf Ihr Guthaben zurück - zu hoch zu schätzen kostet Sie also nichts.
• Der Topf kommt zuletzt dran. Eine Website verbraucht zuerst ihr eigenes Monatskontingent und greift erst danach auf Ihre fills zu, eine Zuteilung kann einen Monat also nie billiger machen, als er ohnehin schon war.
• Ihrem Link zu folgen setzt kein neues Cookie. Der Code wird in der Sitzung gemerkt, die es ohnehin schon gibt, und ist weg, sobald der Browser schließt - ein kürzeres Gedächtnis als das in der Branche übliche, und das einzige, das wir ehrlich beschreiben können. Sie sehen, wie viele Leute kamen und wie viele sich angemeldet haben; wer, sehen Sie nie.

Ihr Link, Ihre Klicks und Ihre Conversions stehen auf Ihrer Kontoseite, unter Refer someone.

Wenn es nicht funktioniert

Das Widget zeichnet nie einen Fehler auf Ihre Seite. Stimmt etwas mit der Zeile nicht, die Sie eingefügt haben, wird das in der Browser-Konsole gemeldet, mit unserem Namen davor; sonst wird nichts geschrieben. Eine laufende Website ist nicht der Ort für unsere Fehlermeldungen.

Ein Mikrofon, das überhaupt nicht erscheint, ist fast immer eines von drei Dingen: die Seite läuft nicht auf HTTPS, der Selektor passt auf nichts, oder der key ist auf dieser Domain nicht erlaubt. Die Konsole sagt, welches davon.

Alles andere: schreiben Sie an [email protected]. Alles, was nach einem Sicherheitsproblem aussieht: schreiben Sie bitte zuerst dorthin und geben Sie uns die Gelegenheit, es zu beheben, bevor es öffentlich ist.