talkback – Hören statt Lesen

talkback — Hören statt Lesen

Spricht Text aus jedem Projektverzeichnis laut vor, speichert das Audio und verbraucht niemals lautlos ein kontingentiertes Budget.

Standardmäßig auf Abruf. Es spricht, wenn danach gefragt wird – der Benutzer sagt „erkläre das laut“, oder das Skript wird direkt ausgeführt. Es spricht nicht von selbst, bis jemand den Talk-Modus aktiviert, und der Talk-Modus gehört jeweils nur einer Sitzung.

Verwendung

S=~/.claude/skills/talkback/scripts

$S/talkback.py "Hier ist, was sich geändert hat und warum es wichtig ist."   # ElevenLabs (Standard)
$S/talkback.py --fast "Wegwerf-Satz."                                      # lokal, sofort, kostenlos
$S/talkback.py --quota                                                      # was übrig ist
$S/talkback.py --voices                                                     # Stimmen auflisten
$S/talkback.py --dry-run "..."                                              # gesprochenen Text anzeigen, nichts synthetisieren
$S/talkback.py --help                                                       # alle Optionen

$S/talkback-hook.py --on                                                    # Talk-Modus EIN, nur diese Sitzung
$S/talkback-hook.py --off                                                   # Sprechen beenden
$S/talkback-hook.py --status                                                # wer spricht, ist der Hook verbunden
$S/talkback-hook.py --outputs                                               # Audio-Ausgänge auf diesem Rechner

Text kann auch per Pipe übergeben werden: git log -1 --pretty=%B | $S/talkback.py.

Wie der Agent es verwenden sollte

Hier leben zwei verschiedene Dinge. Einmaliges Sprechen ist ausgearbeitete Prosa, die Sie an talkback.py übergeben. Talk-Modus ist eine dauerhafte Einstellung, die Sie mit talkback-hook.py umschalten; Sie verfassen dessen Text nie, der Hook liest den aktuellen Turn.

Einmaliges Sprechen

Wenn der Benutzer um eine Erklärung bittet, schreiben Sie für das Ohr und sprechen Sie sie dann. Leiten Sie keinen rohen Markdown oder einen Diff in das Tool. Verfassen Sie zwei bis fünf Sätze in einfacher, gesprochener Prosa – was sich geändert hat, warum, was es für sie bedeutet – und übergeben Sie diese. Der Zuhörer kann nicht zurückscrollen, also beginnen Sie mit der Schlussfolgerung.

Verwenden Sie standardmäßig die gute Stimme – der Plan erlaubt es bequem. Greifen Sie zu --fast, wenn der Text eine Wegwerfsache ist oder Sie null Netzwerklatenz wünschen. Geben Sie an, welches Backend verwendet wurde, falls ein Fallback stattfand.

Steuerung des Talk-Modus

Was der Benutzer sagt, wird in einen Befehl übersetzt. Führen Sie ihn aus; erzählen Sie die Änderung nicht auch noch von Hand, denn der Hook wird den Turn, den Sie schreiben, vorlesen.

Der Benutzer sagt	Führen Sie aus
„Talk-Modus an“, „weiterreden“, „diese Sitzung erklären“	talkback-hook.py --on
„Aufhören zu reden“, „Stumm“, „Sei ruhig“	talkback-hook.py --off
„Nur die Highlights“, „weniger Details“	talkback-hook.py --on brief
„Sag mir nur die wichtigen Teile“	talkback-hook.py --on marker
„Benutze meine AirPods“, „Spiele es auf X ab“	talkback-hook.py --outputs, dann --on --output "<name>"
„Benutze die billige Stimme“, „Hör auf, das Kontingent zu verbrauchen“	talkback-hook.py --on --backend say
„Ist es an?“, „Warum höre ich nichts?“	talkback-hook.py --status
„Spricht da noch etwas anderes?“	talkback-hook.py --sessions
„Mach alles leise“ (alle Sitzungen)	talkback-hook.py --off --all

Drei Dinge, die Sie überprüfen sollten, bevor Sie dem Benutzer sagen, dass es funktioniert:

• --status zeigt an, ob der Hook registriert ist. Wenn nicht, führen Sie --install aus und teilen Sie mit, dass ein Neustart erforderlich ist.
• Wenn --status warnt, dass der Hook nach dem Start dieser Sitzung registriert wurde, ist der Talk-Modus an und wird hier keinen Ton erzeugen. Sagen Sie es – lassen Sie ihn nicht durch Stille darauf stoßen.
• Der Talk-Modus überlebt die Sitzung nicht. Nach einem Neustart oder einem /clear ist er wieder aus und benötigt --on. Das ist beabsichtigt, kein Fehler; sagen Sie es einmal, anstatt dass er erneut fragen muss.

Im marker-Modus – und immer dann, wenn die Rückmeldung eine für das Ohr geschriebene Zusammenfassung sein soll und nicht der Turn selbst – beenden Sie die Nachricht mit einem Marker:

<!-- talkback: Authentifizierungsschicht umgestaltet, drei Aufrufstellen, Tests grün. -->

Backends

Backend	Kosten	Qualität	Hinweise
elevenlabs (Standard)	kontingentiert	beste	quota-geschützt, fällt automatisch auf say zurück
say (--fast)	kostenlos, unbegrenzt	ausreichend	macOS-nativ, ~sofort, kein Netzwerk
omnivoice	kostenlos, unbegrenzt	gut	lokal + privat; benötigt laufendes Backend. Ungeprüft – siehe unten

Die Leiter

elevenlabs → omnivoice → say, beste zuerst. Eine Sprosse, die den Job nicht übernehmen kann – kein Schlüssel, Kontingent bis zur Reserve aufgebraucht, lokaler Server ausgefallen, Synthesefehler – gibt an die nächsttiefere weiter, sodass die Stimme nachlässt, anstatt dass das Audio fehlt. TALKBACK_CHAIN ändert die Reihenfolge.

Die explizite Anforderung einer Sprosse startet die Leiter dort und steigt nur ab: --fast bedeutet „jetzt lokal“ und steigt nie wieder zu einem kontingentierten Backend hoch. Jeder Fallback gibt den Grund auf stderr aus und das gewählte Backend landet im Ledger, sodass eine verschlechterte Ausführung nie stillschweigend verschlechtert ist.

--strict verwandelt jeden Fallback in einen harten Fehler (exit 1), für Skripte, die nicht stillschweigend degradieren dürfen.

Kontingent

Der Account ist Creator-Tarif: 130.958 Zeichen/Monat. Eine zweiminütige gesprochene Erklärung umfasst etwa 1.500 Zeichen, also etwa 87 davon pro Monat – genug, dass die gute Stimme die Standardeinstellung sein kann, nicht eine Ausnahme.

Überprüfen Sie zum Zeitpunkt der Verwendung, niemals aus dem Gedächtnis – talkback.py --quota liest es live. Der Tarif hat sich bereits einmal geändert, und eine Zahl in einem Dokument ist veraltet, sobald sich der Plan bewegt.

Vor der Synthese liest das Tool das Live-Kontingent und behält eine Reserve von 250 Zeichen, sodass eine lange Erklärung nie das gesamte Guthaben aufbrauchen kann. Wenn die Anfrage nicht passen würde, warnt es auf stderr und verwendet stattdessen say.

Anmeldedaten werden in dieser Reihenfolge aufgelöst: $ELEVENLABS_API_KEY → ~/.elevenlabs/api_key (geschrieben von elevenlabs auth login) → ELEVENLABS_API_KEY in ~/broomva/.env.local. Auf diesem Rechner existieren zwei verschiedene Schlüssel, die jedoch zum selben Account auflösen, daher prüft der eine auch den anderen.

Der Creator-Tarif entsperrt außerdem die sofortige und professionelle Stimmklonung (30 Stimmslots, 1 professionell). --voices listet auf, was der Account derzeit verwenden kann.

Das Paket @elevenlabs/cli wird zur Laufzeit nicht verwendet und kann dies nicht – seine gesamte Oberfläche ist auth · agents · tools · tests · components, die gehostete ConvAI-Agentenprojekte verwaltet. Es hat keinen Synthesebefehl. Die CLI ist hier nur für auth login nützlich, das die Schlüsseldatei schreibt.

OmniVoice-Tarif ist ungeprüft

Das omnivoice-Backend wurde gegen die dokumentierte Form implementiert, jedoch nie getestet – das lokale Backend war bei der Auslieferung nicht verfügbar. Es degradiert sauber (fällt auf say zurück oder schlägt unter --strict fehl). Um es in Betrieb zu nehmen, siehe das omnivoice-Skill; das Repository befindet sich bereits unter ~/broomva/external/OmniVoice-Studio.

Sprach-Text-Verarbeitung

Agentenprosa ist nicht zum Hören geschrieben, daher wird der Text zuerst aufbereitet:

• Code-Fences → (code weggelassen); URLs → (link)
• Überschriften und Aufzählungen werden zu Satzbrüchen, sodass Listen nicht zusammenlaufen
• Tiefe Pfade werden auf den Basisnamen gekürzt (src/lib/engine.py → engine.py); verwenden Sie --keep-paths, um sie vollständig zu hören
• Markdown-Hervorhebungen werden nur dort entfernt, wo sie eine Spanne begrenzen – ein bloßer Unterstrich innerhalb von backend_chain bleibt erhalten, denn das Entfernen würde ein Symbol, nach dem der Zuhörer suchen könnte, in eines verwandeln, das er nicht finden kann.

Gespeicherte Audios

Jede Äußerung landet in ~/.talkback/audio/ als mp3 (konvertiert über ffmpeg, falls vorhanden) mit einem Zeitstempel und einem Sluggified-Dateinamen und wird an ~/.talkback/ledger.jsonl angehängt. Verwenden Sie --no-save, um sie zu verwerfen, --out-dir, um das Ziel zu ändern.

Talk-Modus – Die Sitzung während des Verlaufs erklären

Der Talk-Modus bewirkt, dass der Agent am Ende jedes Turns eine kurze Rückmeldung spricht, solange die Sitzung läuft. Er ist standardmäßig aus, wird von Hand eingeschaltet und gehört zu einer Sitzung.

$S/talkback-hook.py --on                    # volle Details, jeder Turn, DIESE Sitzung
$S/talkback-hook.py --on brief              # nur die ersten Zeilen
$S/talkback-hook.py --on marker             # nur Turns mit einem Marker
$S/talkback-hook.py --on --backend elevenlabs   # die gute Stimme, kontingentiert
$S/talkback-hook.py --on --output "AirPods Pro"  # welcher Lautsprecher diese Sitzung verwendet
$S/talkback-hook.py --off                   # Sprechen beenden (diese Sitzung)
$S/talkback-hook.py --off --all             # Kill-Switch, überall
$S/talkback-hook.py --status                # Modus, Backend, wer sonst noch spricht
$S/talkback-hook.py --sessions              # jede derzeit sprechende Sitzung

Warum auf Sitzungsebene begrenzt

Der Stop-Hook wird einmal global und dauerhaft registriert – ein Schalter, den man während einer Sitzung nicht umlegen kann, ist kein Schalter. Also feuert der Hook in jeder Sitzung, und das Flag ist das, was die Begrenzung bewirkt: Der Talk-Modus ist eine Eigenschaft einer Sitzung, nicht des Rechners.

Das Flag ist ~/.talkback/sessions/<sitzungs-id>; eine Sitzung, die nie zugestimmt hat, hat keines, also beendet sich der Hook mit 0 ohne Ton. Das hält sechs parallele Agenten in sechs Arbeitsbäumen stumm, während die eine Sitzung, die Sie beobachten, spricht. Das Design vor 0.3.0 hatte ein einziges maschinenweites Flag, weshalb es nie eingeschaltet wurde: Das Aktivieren machte jeden Agenten auf der Box gleichzeitig hörbar.

Die Sitzungs-ID wird aus CLAUDE_CODE_SESSION_ID oder CLAUDE_SESSION_ID gelesen; --session <id> setzt sie explizit. Wenn keine davon antwortet, gibt der Befehl pass --session <id> aus und beendet sich mit 2, anstatt zu raten – früher fiel er auf das neueste Transkript im Arbeitsverzeichnis zurück, was bedeutete, dass bei zwei geöffneten Sitzungen in einem Verzeichnis --on diejenige Sitzung aktivierte, die zuletzt berührt wurde, nicht die, die darum bat.

Auf der Hook-Seite ist das session_id des Payloads maßgeblich: Wenn es vorhanden ist, ist es der einzige Schlüssel, den das Tor autorisiert. Der Transkript-Dateinamensstamm wird nur verwendet, wenn dieses Feld fehlt. Beide wurden einmal gemeinsam akzeptiert, was dazu führte, dass ein Payload, der Sitzung A und das Transkript von Sitzung B nannte, Bs Opt-In auflöste und in A sprach.

--session <id>, das auf eine andere Sitzung abzielt, ist beabsichtigt und keine Sicherheitsgrenze. Sitzung A, die talkback-hook.py --session B --off ausführt, aktiviert oder deaktiviert Bs Talk-Modus ohne Bs Zustimmung – es gibt keine Besitzprüfung, die ein Flag an die Sitzung bindet, die es gesetzt hat. Das ist eine Funktion, die absichtlich beibehalten wurde, nicht rückgängig gemacht: Jede Sitzung auf der Box läuft als derselbe OS-Benutzer, daher kann jede Sitzung bereits direkt die Flag-Datei einer anderen Sitzung unter ~/.talkback/sessions/ schreiben. Eine Besitzprüfung innerhalb der CLI würde nur den höflichen Weg über das Flag stoppen, nicht den direkten – eine Grenze mit demselben Prinzip kann einen Schreiber, der das Prinzip teilt, nicht aufhalten. Das Flag begrenzt den Ton, sodass parallele Agenten standardmäßig stumm bleiben; es begrenzt nicht die Kontrolle, und nichts hier sollte so gelesen werden, als täte es das.

Detailstufen

Modus	Spricht
full (Sitzungsstandard)	den gesamten Turn, jeden Turn – angeführt vom Marker, wenn der Agent einen geschrieben hat
brief	die ersten TALKBACK_HOOK_CHARS (320) Zeichen von Turns über TALKBACK_HOOK_MIN_CHARS (80); ein Marker gewinnt, wenn vorhanden
marker	nur Turns mit einem <!-- talkback: ... --> Marker, und nur den Markierungstext
off	niemals – geschrieben von --off, wenn ein globales Flag die Sitzung sonst wieder aktivieren würde

full ist der Standard, denn der Sinn einer Rückmeldung ist, wegzugehen und zurückzukommen und zu wissen, was passiert ist. Ein gekürzter Auszug ist eine Vorschau auf die Antwort, nicht die Antwort – Sie müssten immer noch den Bildschirm lesen, was der Talk-Modus vermeiden soll. Was weggelassen wird, ist nur das, was gar nicht gehört werden kann (Code-Fences, URLs, tiefe Pfade – siehe Sprach-Text-Verarbeitung), niemals das, was nur lang ist. full hat auch keine Längenuntergrenze: „Erledigt, Tests grün“ ist ein Ergebnis, das Sie wollen, wenn Sie nicht am Rechner sind, kein Rauschen.

brief und marker sind für einen langen unbeaufsichtigten Bogen, bei dem Sie die Form des Fortschritts wollen, nicht das Transkript davon.

TALKBACK_FULL_MAX_CHARS setzt eine Obergrenze für full, standardmäßig aus – eine Obergrenze macht full wieder zu brief, und zwar genau bei den Turns, die es wert sind, vollständig gehört zu werden.

Rückmeldungen durchlaufen die gesamte Backend-Leiter – zuerst ElevenLabs, absteigend nur, wenn eine Sprosse nicht verwendbar ist. Volle Details bei jedem Turn verbrauchen daher echtes Kontingent: Ein Turn mit 1.500 Zeichen ist ~1 % des monatlichen Creator-Guthabens, sodass eine lange Sitzung die Reserve erreicht, woraufhin sie auf der nächsten Sprosse weiterredet, anstatt still zu werden. --on --backend say hält es niedrig, --on brief verkürzt es.

Wenn eine Rückmeldung in die nächste läuft

Eine vollständige Rückmeldung kann noch abgespielt werden, wenn der nächste Turn endet. TALKBACK_ON_OVERLAP entscheidet, was passiert:

Wert	Verhalten
interrupt (Standard)	die neue Rückmeldung unterbricht die alte – der neueste Zustand ist der, den es zu hören lohnt
queue	sie werden in der Reihenfolge abgespielt, sodass eine lange detaillierte Rückmeldung nie abgeschnitten wird; Sie fallen zurück, hören aber alles

queue ist die richtige Einstellung für einen unbeaufsichtigten Bogen, den Sie später vollständig anhören möchten; interrupt ist richtig, wenn Sie am Rechner sind und die neueste Information wollen.

Der Marker

Um einen einzelnen Turn zu aktivieren – im marker-Modus oder um eine für das Ohr geschriebene Zusammenfassung anstelle der Eröffnungszeilen der Nachricht zu sprechen – beenden Sie die Nachricht mit:

<!-- talkback: Authentifizierungsschicht umgestaltet, drei Aufrufstellen, Tests grün. -->

Im full-Modus wird der Marker zur Schlagzeile: Er wird zuerst gesprochen, dann der gesamte Turn dahinter, sodass die Rückmeldung mit der Schlussfolgerung beginnt, ohne die Details zu verlieren. Im brief-Modus ersetzt der Marker den Auszug, und ein markerloser Turn fällt auf die einleitenden Sätze zurück, die an einer Satzgrenze abgeschnitten werden.

Welcher Lautsprecher

Das Audio kommt von dem Rechner, auf dem Claude Code läuft. Eine Sitzung, die Sie von einem Telefon, einem Tablet oder einem anderen Laptop aus steuern, klingt dennoch auf dem Host, daher ist der Hebel, der zählt, die Auswahl, auf welchem der Host-Ausgänge es landen soll – AirPods, die mit dem Mac gekoppelt sind, ein AirPlay-Lautsprecher, ein Bildschirm, die eingebauten Lautsprecher.

$S/talkback-hook.py --outputs             # was dieser Host abspielen kann
$S/talkback-hook.py --on --output "AirPods Pro"
$S/talkback.py -d "MacBook Pro Lautsprecher" "einmaliger Satz auf einem gewählten Gerät"

Die Ausgabe wird pro Sitzung gespeichert, daher bleibt die Wahl des Geräts für die Dauer der Sitzung erhalten.

…

[gekürzt zur Übersetzung]