Drehbuch und Stimme
Die Stimme ist der Takt des Videos. Jeder Schlag der Animation ist an ein Wort der Erzählung gebunden
(T[clip] + w(clip, "word") in build.py), daher kommen das Drehbuch und seine Clips vor der Animation,
und das Ändern eines Satzes regeneriert einen Clip und timt alles danach neu. In der Produktion, aus der
diese Skills stammen, hat das Austauschen der gesamten TTS-Engine ein fertiges Video ohne manuelle
Bearbeitung neu getimt, genau wegen dieses Designs. Erst zu animieren und dann die Stimme einzupassen,
bedeutet, bei jeder Änderung Audio zu strecken oder Beats von Hand zu verschieben.
Schreibe nur unter <video_dir>/audio/ (plus den Skript-Abschnitt in BRIEF.md). Jeder Satz muss in
TRUTH.md belegt sein und CLAIMS.md respektieren; wenn ein benötigter Satz keine Quelle hat, fordere an,
dass er überprüft oder gestrichen wird.
Skripte, aufgerufen wie in docs/contracts.md:
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/script-and-voice/scripts"
"$PVS_HOME/bin/pvs-py" "$S/check_script.py" <video_dir> # lint lines.tsv
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir> [--only N3,N4] [--provider say] [--force] [--restore]
"$PVS_HOME/bin/pvs-py" "$S/pronounce_check.py" <video_dir> [--only N3] # Hat der ASR die Markenwörter gehört?
"$PVS_HOME/bin/pvs-py" "$S/make_sfx.py" <video_dir> [--list] # sfx.tsv, oder Bibliothek auflisten
1. Das Drehbuch ist eine Tabelle von Momenten
Eine Aufnahme des Produkts ist eine Referenz, kein Zeitstrahl: echte Ladezeiten und Bildschirmwechsel dürfen nicht im Video vorkommen. Schreibe das Drehbuch als Momente, jeder mit dem, was auf dem Bildschirm passiert, dem Satz (oder Stille) und wie lange er dauert. Ein Moment dauert so lange wie der längere seiner Aktion und seines Satzes. Komprimiere echte Wartezeiten: vierzig Sekunden Laden werden zu etwa zwei Sekunden eines denkenden Zustands.
Füge die Tabelle in BRIEF.md unter ## Script ein, in Kapitel-Reihenfolge:
| Moment | Auf dem Bildschirm | Zeile | Text (oder Stille) | Hält an |
|---|---|---|---|---|
| Eröffnung | Produktname über der unscharfen App | N1 | Das ist Acme Tasks, die To-do-Liste, die deinen Tag plant. | 0,8 s danach |
| Warten | Der Plan wird erstellt | (Stille) | 2,0 s |
Wähle dann die Vorlage für das Videoformat und folge seiner Struktur: lies
references/script-templates.md (Pitch, Tour, Docs-Seite, Tutorial, stille Schleife).
Wie die Zeilen geschrieben werden und warum:
- Erkläre die wichtigen Funktionen; zähle sie nicht auf. Sage, was eine Funktion für den Betrachter tut, während die UI es ausführt. In der Produktion, aus der diese Skills stammen, geschahen 9 von 26 Versionen, weil ein Video eine Funktion nannte, ohne sie zu erklären. COVERAGE.md sagt, welche Funktionen auf dem Bildschirm erklärt werden müssen: jede Zeile, die mit „muss erklären“ markiert ist, benötigt mindestens einen Satz, der sie erklärt.
- Erkläre jeden Schritt so, als hätte jemand das Produkt noch nie gesehen. Wer die Person ist, was sie verlangt, was jeder Schritt tut. Eine schnelle, unerklärte Eröffnung wurde in der Überprüfung abgelehnt.
- Eine Idee pro Satz und ein Satz pro Clip. Ein geänderter Satz kostet dann einen Clip.
- Benenne, was der Cursor berührt, während er es berührt. Die Beats verankern sich an diesen Wörtern, daher müssen das Nomen auf dem Bildschirm und das Wort im Clip identisch sein.
- Verwende das echte UI-Label, selbst wenn der Prüfer ein anderes Wort dafür verwendet. Das Video stimmt dann mit dem überein, was der Betrachter im Produkt sehen wird.
- Schreibe Zahlen und Zeiten als Wörter („zehn Uhr morgens“, „dreißig Minuten später“). TTS-Engines lesen Ziffern inkonsistent und die Spracherkennung vergleicht Wörter, nicht Ziffern.
- Lasse Luft um Wartezeiten herum. Etwa drei Sekunden, bevor ein Telefon klingelt, „etwa eine Minute“ anstelle einer genauen Zahl, die niemand überprüfen kann.
- Ende mit einem vollständigen Satz, etwas langsamer vorgelesen. Ein Slogan-Fragment als letzte Zeile klang in der Überprüfung abgeschnitten; ein vollständiger Satz mit der Positionierung aus CLAIMS.md tat es nicht.
- Halte die Person innerhalb eines Videos konsistent: erste Person als der fiktive Benutzer („Zuerst verbinde ich meinen Kalender.“) oder dritte Person über ihn. Verwende nur die fiktive Besetzung aus product.yaml mit demselben Namen in jedem Video.
- Die Positionierung stammt aus CLAIMS.md, nicht aus den Quelldokumenten: ein Quelldokument kann einen Ausdruck enthalten, den das Team verboten hat, und die Regel gewinnt.
2. lines.tsv
audio/lines.tsv, tabulatorgetrennt, Kopfzeile id role speed text, ein Clip pro Zeile in
Wiedergabereihenfolge, #-Zeilen sind Kommentare. Vollständiges Format und wie build.py das Ergebnis
liest: references/audio-formats.md.
- id:
N1,N2,N7bfür Erzählung; andere Buchstaben für Figuren (A1für einen Agenten,C1für einen Kunden). Das Einfügen einer Zeile zwischen N7 und N8 alsN7bhält jede andere ID und jeden Anker, der sie verwendet, stabil. - role: ein Schlüssel von
voice.rolesin product.yaml (narrator,agent,customeroder eine Lesevariante wienarrator_close, siehe Abschnitt 3). Die Rolle, nicht die ID, wählt die Stimme. - speed: 1.0 standardmäßig, 0,7 bis 1,2. Verwende 0,9 bis 0,96 für die Eröffnungs- und Schlusszeilen.
- text: genau so, wie er auf dem Bildschirm und in den Untertiteln erscheint, mit der kanonischen Schreibweise der Produktnamen. Schreibe hier niemals eine Umschrift; die Aussprache lebt in product.yaml.
Bevor Zeilen einer ausgelieferten Version geändert werden, kopiere lines.tsv nach lines-v<N>.tsv und
timings.json nach timings-v<N>.json, damit die vorherige Version neu erstellt werden kann.
Führe check_script.py nach jeder Bearbeitung aus. Es schlägt fehl bei doppelten IDs, unbekannten
Rollen, Geschwindigkeiten außerhalb des Bereichs, Clips über 40 Wörtern, verbotenen Begriffen,
never_say-Phrasen, Legacy-Namen und Umschreibungen im Skript, und warnt bei langen Clips, Ziffern und
Gedankenstrichen. Behebe jeden Fehler vor der Vertonung: eine verbotene Phrase, die den TTS erreicht,
kostet einen Take, und eine, die einen Render erreicht, kostet eine Version.
3. Besetzung
Lies references/casting-and-pronunciation.md, bevor du Stimmen vorschlägst. Kurz gefasst:
- Biete zuerst realistische Stimmen an. Die Standardstimme des Produkts und die günstigsten Modelle wurden in der Überprüfung als „sehr unecht“ beurteilt; das natürlichste verfügbare Modell ist es für Figuren wert.
- Vorsprechen im Kontext: zwei echte aufeinanderfolgende Zeilen pro Rolle, drei bis sechs Kandidaten pro Rolle.
- Schlage jede Wahl zum Veto als geschlossene Frage mit einer empfohlenen Voreinstellung vor („Erzähler: Stimme B, warm und gemächlich. Behalten?“). Offene Listen von Optionen blieben tagelang unbeantwortet.
- Entscheide die Behandlung pro Rolle:
treatment: phonefür jemanden in einem Telefonat,treatment: roomfür ein aufgenommenes Meeting, nichts für den Erzähler. - Eine zeilenweise Lesart (gleichmäßiger, langsamer, weniger Stil) ist eine Rollenvariante, die auf dieselbe Stimme mit anderen Einstellungen zeigt, sodass die Wahl in der Konfiguration liegt und einen erneuten Durchlauf übersteht.
voice.provider: say (oder --provider say) verwendet die kostenlose macOS-Stimme und whisper für
Wortzeitmarken. Verwende es für Entwürfe, Tests und Timing-Arbeiten, bevor ein Schlüssel existiert;
liefer mit der echten Stimme aus.
4. Generiere die Clips
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir>
Für jede Zeile schreibt es Markenwörter nur für den TTS um, behält den unbearbeiteten Take in
audio/raw/ (der vorherige Take verschiebt sich nach audio/raw/prev/), entfernt Stille, wandelt auf
48 kHz Mono um, wendet die Behandlung der Rolle an, normalisiert auf voice.clip_lufs (ffmpeg
loudnorm, zwei Durchgänge; Spitzen unter -1,5 dBTP), blendet beide Kanten ein/aus und fügt den Eintrag
des Clips in audio/timings.json ein.
Warum jeder Verarbeitungsschritt existiert:
- Rohe Takes werden immer archiviert und sind immer die Quelle. Ein früherer Client normalisierte von einer veralteten Rohdatei nach einem vollständigen Neu-Render; hier wird ein Clip immer aus dem Take neu erstellt, der ihn produziert hat.
- Der Schwanz wird höchstens 0,6 s nach dem letzten Wort abgeschnitten, mit einer Ausblendung. Ein TTS-Take kann mit einem Klick oder dem Einsatz einer anderen Phrase enden; ein solcher Klick wurde als „seltsamer Schnitt“ im Audio ausgeliefert.
- Jeder Clip mit derselben Lautstärke. Eine Figurenstimme kam vor der Normalisierung 6 dB lauter als der Erzähler heraus.
- Unveränderte Zeilen werden übersprungen (Hash aus Text, Stimme und Einstellungen in
audio/raw/cache.json), sodass ein vollständiger Durchlauf nach dem Bearbeiten einer Zeile den Anbieter einmal aufruft. Wenn sich nurclip_lufsoder die Verarbeitung geändert hat, werden Clips kostenlos aus den archivierten Takes neu erstellt.--forcefordert trotzdem einen neuen Take an.
Der Schlüssel wird vom Skript aus der Umgebung oder PVS_HOME/.env gelesen und niemals ausgegeben.
Lies .env niemals selbst und frage niemals nach dem Schlüssel im Chat: wenn er fehlt, sage dem
Benutzer, er solle die Zeile selbst zu .env hinzufügen, oder wechsle zu say.
Führe pronounce_check.py nach jedem neuen Take aus. Es transkribiert jeden Clip ohne Aufforderung an
den ASR, markiert Marken- und Besetzungswörter, die nicht erkannt wurden, Legacy-Namen, die gehört
wurden, und Vokale, die abgewichen sind (Abschnitt 5). Eine Markierung bedeutet zuhören, nicht
regenerieren: ASRs hören Markenwörter, die richtig ausgesprochen wurden, falsch.
5. Aussprache
Das Drehbuch und der Bildschirm behalten die echte Schreibweise. product.pronounce ändert nur, was an
den TTS gesendet wird, und tts.py bildet die Zeitmarken zurück, sodass timings.json das Wort auf dem
Bildschirm in w und die Umschrift in say enthält ({"w": "Acme", "say": "AK-mee", ...}). Anker in
build.py verwenden das Wort auf dem Bildschirm.
product:
pronounce:
Acme: AK-mee # einfache Umschrift
Acme Tasks: {say: AK-mee Tasks, vowel: ae, confusable: ey} # mit einem Erstvokal-Check
Wenn ein Prüfer sagt, der Name klinge falsch, probiere drei oder vier Umschriften an einer Zeile aus,
messe sie mit dem Vokal-Check, behalte diejenige, die besteht, und überprüfe dann jede andere Zeile, die
das Wort enthält: die Anbieter variieren pro Take. Details und die Vokaltabelle: references/casting-and-pronunciation.md.
6. Takes
- Maximal zwei Takes pro Zeile, es sei denn, der Benutzer sagt etwas anderes; Anbieterkontingente werden normalerweise innerhalb eines Teams geteilt. Sage, wie viele Zeichen ein vollständiger Durchlauf kosten wird, bevor du ihn ausführst.
- Regeneriere nur die Zeile, die es braucht:
tts.py <video_dir> --only N7 --force. - Wenn der neue Take schlechter ist, tauscht
--only N7 --restoreihn mit seinen Zeitmarken zurück. - Für eine Tonfall-Anmerkung („zu aufgeregt“, „klingt wie ein halber Satz“) erstelle zwei oder drei Varianten als Rollenvarianten oder Geschwindigkeitsänderungen, und lasse den Prüfer sie im Kontext mit der vorherigen Zeile vergleichen.
- Eine Zeile ändern, in der Reihenfolge: kopiere die Versionsdateien, bearbeite die Zeile,
check_script.py,tts.py --only <id>,pronounce_check.py --only <id>, dann baut der Komponist neu; alles nach diesem Clip verschiebt sich von selbst.
7. Soundeffekte
Verwende nur aufgenommene Sounds aus der Bibliothek, die mit HyperFrames ausgeliefert wird
(make_sfx.py --list). Synthetisiertes Tippen klang wie „ein Strohhalm, nicht eine Tastatur“ und ein
synthetisierter Wusch wie „weißes Rauschen“ in der Überprüfung, daher werden Wusche und Anhebungen vom
Skript verweigert, und nichts läuft unter der Erzählung als Musik, es sei denn, das Briefing verlangt
es. Die Produktion, aus der diese Skills stammen, wurde ohne Musikteppich und ohne Ducking ausgeliefert,
und niemand hat es vermisst.
- Tippen:
typing_track(text, start, cps)baut eine Spur aus einzelnen Tastenanschlägen, die aus einer echten Aufnahme herausgeschnitten wurden, mit einem stärkeren Anschlag auf Leerzeichen und einem gesäten Rhythmus, sodass sie deterministisch ist und derselbe Text immer gleich klingt. Lass es genau so lange dauern wie der Beat, der den Text zeigt (dur=), und lass die getippten Wörter auf den gesprochenen landen. - Klicks und Pops:
library_sfx("click", start)auf dem Frame, den der Cursor drückt. audio/sfx/CREDITS.mdlistet jede verwendete Bibliotheksdatei auf und trägt die Lizenz der Bibliothek.- Vorgeschlagene Pegel: Erzählung 1,0, Figuren 1,0, Klicks 0,35 (0,22 bei einem Zieh-Loslassen), Tippen 0,45, Pops 0,12 bis 0,3. Zwei Clips auf derselben Audiospur dürfen sich niemals überschneiden: starte einen Clip mindestens 0,02 s nachdem der vorherige endet, oder verschiebe ihn auf eine andere Spur.
build.py importiert die Funktionen; make_sfx.py <video_dir> mit einer audio/sfx.tsv erstellt
dieselben Dateien von der Kommandozeile vor (Format im Docstring des Skripts).
8. Übergabe an den Komponisten
Liefere unter <video_dir>/audio/: lines.tsv, clips/<id>.wav, timings.json und sfx/ mit
CREDITS.md. Sage dem Komponisten, an welche Wörter sich jeder Beat anheften soll (das Nomen, das der
Cursor berührt, das Wort, auf dem das Tippen landet) und die Wartezeiten aus der Momententabelle.
Bearbeite timings.json niemals von Hand: es wird aus den Clips regeneriert, und eine manuelle
Bearbeitung geht beim nächsten Durchlauf verloren.
Melde dem Benutzer: die vertonten Zeilen, die Dauer jedes Clips, alle Aussprache-Markierungen und was du gehört hast, die verwendeten Stimmen (mit der empfohlenen Voreinstellung für alles noch Offene) und die verbrauchten Zeichen des Anbieters.