LucasLBrito/narracao-voz

Narration mit Neuralstimme

Pfade: ${CLAUDE_PLUGIN_ROOT} ist das Stammverzeichnis dieses Plugins. Falls die Variable nicht gesetzt ist, befindet sich das Stammverzeichnis zwei Ordner über dem "Base directory" dieses Skills (<stamm>/skills/<skill>). Falls die Skills direkt nach ~/.claude/skills kopiert wurden, verwenden Sie ~/.claude/skills anstelle von ${CLAUDE_PLUGIN_ROOT}/skills.

Skript: ${CLAUDE_PLUGIN_ROOT}/skills/narracao-voz/scripts/narracao.py. Erfordert pip install edge-tts und Internet: der Text wird an den Microsoft-Sprachdienst gesendet (kostenlos, kein Schlüssel erforderlich). Fügen Sie nichts in das Skript ein, das der Benutzer nicht nach außen senden möchte.

Verwendung

N=${CLAUDE_PLUGIN_ROOT}/skills/narracao-voz/scripts/narracao.py
python $N <verzeichnis>                    # audio/szene01.mp3 ... + szene01.json (Wortzeiten)
python $N <verzeichnis> --mostrar          # zeigt den Text MIT den Ausspracheersetzungen (ohne Generierung)
python $N <verzeichnis> --so 3 7           # erstellt nur die Szenen 3 und 7 neu
python $N <verzeichnis> --tempos 3         # "  2.41s  schlüssel" ... zur Synchronisation der Animation
python $N <verzeichnis> --voz pt-BR-FranciscaNeural --rate +0%
python $N --vozes                    # listet die verfügbaren portugiesischen Stimmen auf

Eingabe: <verzeichnis>/roteiro.json, eine Liste von Zeichenketten (ein Sprechtext pro Szene). Stimme und Geschwindigkeit können in video.json festgelegt werden ("voz", "rate"). Standard: pt-BR-AntonioNeural, +8%.

Einzelsprachausgabe (Jingle, Ansage, Nachricht, Stimmtest), ohne Verzeichnis oder Skript:

python $N --texto "Hallo zusammen! Heute geht es um Docker." --saida C:/tmp/ansage.mp3
python $N --texto "..." --saida C:/tmp/f.mp3 --voz pt-BR-FranciscaNeural --rate +0%

Die grundlegende Aussprachekarte gilt auch hier. Für mehrere Einzelausgaben bevorzugen Sie ein Verzeichnis mit roteiro.json: es wird ein MP3 pro Sprechtext erstellt.

Nützliche pt-BR-Stimmen: pt-BR-AntonioNeural (männl., die der Videos), pt-BR-FranciscaNeural (weibl.), pt-BR-ThalitaMultilingualNeural (weibl., besser mit englischen Begriffen). Vollständige Liste: --vozes. Es gibt auch Stimmen aus Portugal (pt-PT-...) und anderen Sprachen.

Für das Sprechen schreiben

Das Skript wird von einer Maschine gelesen. Schreiben Sie, wie man spricht, nicht wie man schreibt:

Auf dem Bildschirm / Schriftlich	Im Skript
1995	eintausendneunhundertfünfundneunzig
Port 22	Port zweiundzwanzig
SCP, AWS (buchstabierte Akronyme)	S C P, A W S (einzelne Buchstaben)
git push -u origin main	git push, Bindestrich u, origin main
feat/login	feat Schrägstrich login
.gitignore, .env	Punkt gitignore, Punkt env
~/.ssh/known_hosts	die Datei known hosts
<, >, =	kleiner als, größer als, gleich

• Kurze Sätze. Das Komma wird zur Pause: verwenden Sie es für den Rhythmus ("Verbindung, Schlüsselaustausch und Authentifizierung.").
• Gesprächston: "lass uns verstehen", "kennen Sie das...?", "und das Beste:", "zusammenfassend:".
• 25–45 Wörter pro Szene (10–16 s bei +8%).
• Vermeiden Sie Klammern und Gedankenstriche: die Stimme weiß nicht, was sie damit anfangen soll.

Aussprache englischer Begriffe

Die pt-BR-Stimme liest Englisch wie Portugiesisch. Die Korrektur besteht darin, den Begriff durch eine Schreibweise zu ersetzen, die richtig klingt, nur im Audio (das Skript und der Bildschirm behalten das ursprüngliche Wort).

• Basiskarte mit ~70 Dev-Begriffen: scripts/pronuncia_base.json (git, commit, push, GitHub, branch, Docker, deploy, API, JSON, frontend, Python, npm...).
• Projektbegriffe: <verzeichnis>/pronuncia.json, im gleichen Format. Überschreibt die Basiskarte. Um einen Austausch aus der Basiskarte zu deaktivieren, ordnen Sie den Begriff sich selbst zu: {"status": "status"}.
• Der Austausch erfolgt pro ganzem Wort, ohne Groß-/Kleinschreibung, und längere Begriffe werden zuerst ersetzt ("Pull Request" vor "pull").

So finden Sie die richtige Schreibweise:

1. Schreiben Sie, wie ein Brasilianer es laut lesen würde, mit Betonung auf der starken Silbe: commit → "comít", push → "púch", GitHub → "guít-râb", release → "rilís", cache → "kéch".
2. Verwenden Sie einen Bindestrich, um Teile zu trennen: "és-és-êitch" (SSH), "ci-él-ái" (CLI).
3. Generieren Sie nur diese eine Szene (--so N), hören Sie zu und passen Sie an. Wenn der Benutzer sagt, dass etwas falsch klang, korrigieren Sie es in der pronuncia.json des Projekts. Wenn es sich um einen gebräuchlichen Dev-Begriff handelt, fügen Sie ihn auch in der pronuncia_base.json hinzu, damit die nächsten Videos bereits korrekt sind.

Mit der Animation synchronisieren

Jede audio/szeneNN.json enthält [{"t": 2.41, "palavra": "schlüssel"}, ...], in Sekunden ab Beginn der Szene. Verwenden Sie diese t (oder 0,2 s früher) als Eingabezeit des Elements, das das Wort repräsentiert. Das Wort erscheint bereits mit der ersetzten Schreibweise ("comít"), was normal ist.

Häufige Probleme

Symptom	Ursache / Lösung
No module named edge_tts	python -m pip install edge-tts
Verbindungsfehler / 403	Kein Internet, oder Microsoft hat etwas geändert: pip install -U edge-tts
Stimme zu schnell oder zu langsam	--rate +0% (langsamer) oder +15% (schneller)
Begriff falsch ausgesprochen	pronuncia.json (oben)
Szene zu lang (> 20 s)	Teilen Sie den Sprechtext in zwei Szenen auf