HyperFrames Medienvorverarbeitung
Drei CLI-Befehle, die Assets für Kompositionen erstellen: tts (Sprache), transcribe (Zeitstempel) und remove-background (transparentes Video). Jeder lädt beim ersten Start ein Modell herunter und speichert es unter ~/.cache/hyperframes/. Das Ergebnis wird in das Projekt eingefügt und in der Kompositions-HTML referenziert – siehe den Skill hyperframes für die Audio-/Video-Element-Konventionen.
Text-to-Speech (tts)
Sprach-Audio lokal mit Kokoro-82M erzeugen. Kein API-Key erforderlich.
npx hyperframes tts "Text hier" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list # alle 54 Stimmen
Stimmauswahl
Stimme zum Inhalt passend wählen. Standard ist af_heart.
| Inhaltstyp | Stimme | Grund |
|---|---|---|
| Produkt-Demo | af_heart/af_nova | Warm, professionell |
| Tutorial / Anleitung | am_adam/bf_emma | Neutral, leicht zu folgen |
| Marketing / Promotion | af_sky/am_michael | Energisch oder autoritär |
| Dokumentation | bf_emma/bm_george | Klares britisches Englisch, förmlich |
| Lässig / Sozial | af_heart/af_sky | Zugänglich, natürlich |
Mehrsprachig
Die Sprach-IDs kodieren die Sprache im ersten Buchstaben: a=Amerikanisches Englisch, b=Britisches Englisch, e=Spanisch, f=Französisch, h=Hindi, i=Italienisch, j=Japanisch, p=Brasilianisches Portugiesisch, z=Mandarin. Das CLI erkennt das Phonemizer-Gebietsschema automatisch aus dem Präfix – kein --lang nötig, wenn die Stimme zum Text passt.
npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav
Verwenden Sie --lang nur, um die automatische Erkennung zu überschreiben (stilisierte Akzente). Gültige Codes: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh. Nicht-englische Phonemisierung erfordert espeak-ng systemweit (brew install espeak-ng / apt-get install espeak-ng).
Geschwindigkeit
0.7-0.8– Tutorial, komplexer Inhalt, Barrierefreiheit1.0– natürliches Tempo (Standard)1.1-1.2– Intros, Übergänge, schwungvoller Inhalt1.5+– selten angemessen; sorgfältig testen
Lange Skripte
Bei mehr als ein paar Absätzen in eine .txt-Datei schreiben und den Pfad übergeben. Eingaben über ~5 Minuten Sprachdauer können von einer Aufteilung in Segmente profitieren.
Voraussetzungen
Python 3.8+ mit kokoro-onnx und soundfile (pip install kokoro-onnx soundfile). Modell-Download bei erster Nutzung (~311 MB + ~27 MB Stimmen, zwischengespeichert in ~/.cache/hyperframes/tts/).
Transkription (transcribe)
Ein normalisiertes transcript.json mit Wort-Zeitstempeln erstellen.
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt # vorhandene importieren
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
Sprachregel (Nicht verhandelbar)
Verwenden Sie niemals .en-Modelle, es sei denn, der Benutzer gibt ausdrücklich an, dass das Audio auf Englisch ist. .en-Modelle (small.en, medium.en) übersetzen nicht-englisches Audio ins Englische, anstatt es zu transkribieren. Dies zerstört stillschweigend die Originalsprache.
- Sprache bekannt und nicht-englisch →
--model small --language <code>(kein.en-Suffix) - Sprache bekannt und englisch →
--model small.en - Sprache unbekannt →
--model small(kein.en, kein--language) – Whisper erkennt automatisch
Standardmodell ist small, nicht small.en.
Modellgrößen
| Modell | Größe | Geschwindigkeit | Verwendung |
|---|---|---|---|
tiny | 75 MB | Am schnellsten | Schnelle Vorschauen, Pipeline-Tests |
base | 142 MB | Schnell | Kurze Clips, klares Audio |
small | 466 MB | Mittel | Standard – die meisten Inhalte |
medium | 1,5 GB | Langsam | Wichtige Inhalte, verrauschtes Audio, Musik |
large-v3 | 3,1 GB | Am langsamsten | Produktionsqualität |
Musik mit Gesang: mindestens mit medium beginnen; produzierte Tracks erfordern oft manuellen SRT/VTT-Import. Für Caption-Qualitätsprüfung (nach jeder Transkription obligatorisch), das Bereinigungs-JS, Wiederholungsregeln und den OpenAI/Groq API-Importpfad siehe hyperframes/references/transcript-guide.md.
Ausgabeformat
Kompositionen konsumieren ein flaches Array von Wortobjekten. Das Feld id (w0, w1, ...) wird während der Normalisierung hinzugefügt, um stabile Referenzen in Caption-Overrides zu ermöglichen; es ist optional aus Gründen der Abwärtskompatibilität.
[
{ "id": "w0", "text": "Hallo", "start": 0.0, "end": 0.5 },
{ "id": "w1", "text": "Welt.", "start": 0.6, "end": 1.2 }
]
Hintergrundentfernung (remove-background)
Entfernt den Hintergrund aus einem Video oder Bild, sodass das Motiv (typischerweise eine Person – Avatar, Moderator, sprechender Kopf) als transparentes Overlay in einer Komposition sitzt.
npx hyperframes remove-background subject.mp4 -o transparent.webm # Standard: VP9 Alpha WebM
npx hyperframes remove-background subject.mp4 -o transparent.mov # ProRes 4444 (Schnitt)
npx hyperframes remove-background portrait.jpg -o cutout.png # Einzelbild-Ausschnitt
npx hyperframes remove-background subject.mp4 -o subject.webm \
--background-output plate.webm # beide Ebenen in einem Durchlauf
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # erkannte Anbieter
Verwendet u2net_human_seg (MIT). Erster Start lädt ~168 MB Gewichte nach ~/.cache/hyperframes/background-removal/models/.
Ebenentrennung (--background-output)
--background-output (oder -b) übergeben, um ein zweites transparentes Video neben dem Ausschnitt auszugeben: gleiches RGB der Quelle, Alpha ist 255 − Maske anstelle von Maske. Der Ausschnitt ist das Motiv mit transparentem Hintergrund; die Platte ist die ursprüngliche Umgebung mit einem transparenten Loch, wo das Motiv war.
| Datei | Alpha ist… | Verwendung |
|---|---|---|
-o subject.webm | Die Maske – Motiv deckend, Hintergrund transparent | Vordergrundebene, oben platzieren |
--background-output plate.webm | Invers – Umgebung deckend, Motivbereich transparent | Untere Ebene; Text oder Grafiken zwischen diese und das Motiv setzen |
Beide Ausgaben teilen dieselbe --quality-Voreinstellung und werden in einem einzigen Inferenzdurchlauf berechnet – die Codierungskosten verdoppeln sich in etwa, die Segmentierungskosten bleiben gleich. Nur gültig für Videoeingaben und .webm/.mov-Ausgaben.
Loch-Platte, keine nachbearbeitete saubere Platte. Der Motivbereich in plate.webm ist vollständig transparent – komponieren Sie etwas Deckendes darunter, um das Loch zu füllen. Der einzelne Test, ob --background-output das richtige Werkzeug ist: Wird jemals etwas durch die Silhouette des Motivs sichtbar sein, wo das Motiv zuvor war?
| Anwendungsfall | Richtiges Werkzeug |
|---|---|
| Text/Grafiken zwischen Ausschnitt und Platte (Daseinsberechtigung dieses Befehls) | Loch-Platte (--background-output) |
| Motiv auf eine unzusammenhängende Szene setzen | Nur subject.webm; Platte ignorieren |
| Den Raum ohne die Person zeigen, allein über keinem anderen Inhalt | Saubere Platte – benötigt einen Inpainter (LaMa, ProPainter, E2FGVI). Nicht dieser Befehl. |
| Das Motiv durch ein anderes Motiv ersetzen | Saubere Platte – gleicher Fall wie oben |
Wenn ein Benutzer nach „dem Raum ohne die Person“ fragt und beabsichtigt, ihn eigenständig anzuzeigen, verwenden Sie nicht --background-output. Sagen Sie ihm, dass er einen Inpainter benötigt.
Typische geschichtete Komposition (der kanonische Anwendungsfall für die Loch-Platte):
<!-- z=1 die invers-Alpha-Platte füllt alles außer dem Motivbereich -->
<video
src="plate.webm"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<!-- z=2 Grafiken / Text liegen zwischen den beiden Ebenen -->
<h1 id="headline" style="z-index:2; ...">MACHEN SIE ES IN HYPERFRAMES</h1>
<!-- z=3 der Ausschnitt schwebt das Motiv zurück über die Überschrift -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
<video
src="subject.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
Dies ist funktional äquivalent zum Text-hinter-Motiv-Muster unten, aber Sie benötigen das Original presenter.mp4 nicht im Projekt – die Platte ersetzt es. Nützlich, wenn Sie nur die beiden transparenten Ebenen ausliefern möchten und dem Benutzer erlauben, beliebigen Inhalt dazwischen zu platzieren.
Ausgabeformat
| Format | Wann |
|---|---|
.webm (VP9 + Alpha) | Standard. Kompositionen spielen dies direkt über <video> ab. |
.mov (ProRes 4444) | Schnitt in DaVinci/Premiere/FCP. Große Dateien. |
.png | Einzelbild-Ausschnitt (stehendes Motiv, über einen Hintergrund gelegt). |
Chrome dekodiert VP9 Alpha nativ, daher fügt sich das .webm wie jedes andere stummgeschaltete Autoplay-Video in eine Komposition ein – siehe den Skill hyperframes für die <video>-Track-Konventionen.
Qualitätsvoreinstellungen
--quality fast|balanced|best steuert nur den CRF des VP9-Codierers – die Segmentierungsqualität ist fest.
| Voreinstellung | CRF | Wann |
|---|---|---|
fast | 30 | Iterieren, kleinere Datei, lockerere Farbanpassung |
balanced | 18 | Standard. Visuell identisch für die meisten Anwendungen |
best | 12 | Master / finale Auslieferung. Größte Datei, engste Anpassung |
Compositing-Muster – das richtige wählen
Der Ausschnitt-WebM ist eine neu codierte Kopie des RGB der Quell-MP4. Diese Wahl hat Konsequenzen, je nachdem, was dahinter platziert wird:
| Muster | Was hinter dem Ausschnitt ist | Ergebnis |
|---|---|---|
| Ausschnitt über einer anderen Szene (am häufigsten) | Standbild, Verlauf oder unabhängiges Video | Sieht großartig aus. Das RGB des Ausschnitts ist die einzige Quelle des Motivs – keine Verdopplung, kein Randhalo. Dafür ist remove-background gemacht. |
| Ausschnitt über seiner eigenen Quell-MP4 (Text hinter Motiv) | Dieselbe MP4, aus der der Ausschnitt erzeugt wurde | Zwei RGB-Quellen für dieselbe Person. Bei --quality balanced (crf 18) ist die Verdopplung kaum sichtbar; bei --quality fast (crf 30) sieht man eine leichte Farbverschiebung / Randhalo. Für Master --quality best (crf 12) verwenden. |
| Ausschnitt über einer anderen Aufnahme derselben Person | Filmmaterial desselben Motivs | Sieht aus wie zwei separate Personen, die sich überlappen. Nicht tun. |
Text hinter Motiv (Überschrift hinter einem Moderator):
<video
src="presenter.mp4"
id="bg"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<h1 id="headline" style="z-index:2; ...">MACHEN SIE ES IN HYPERFRAMES</h1>
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
<video
src="presenter.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
Zwei Schlüsselregeln:
- Den Ausschnitt in ein nicht getaktetes
<div>einwickeln und die Deckkraft des Wrappers animieren, nicht die des Video-Elements. Das Framework erzwingt Deckkraft:1 für aktive Clips (jedes Element mitdata-start/data-duration), sodass das direkte Animieren der Video-Deckkraft stillschweigend überschrieben wird. Der Wrapper hat keinedata-*-Attribute, daher gehört er Ihrem CSS/GSAP. - Beide Videos verwenden
data-start="0"unddata-media-start="0", sodass das Framework sie synchron ab t=0 dekodiert. Ein spätes Einblenden des Ausschnitts (data-start=3.3) führt zu einem Seek + Aufwärmen, das einen Frame von der Basis-MP4 entfernt landet – sichtbar als ein Frame Fehlausrichtung am Schnitt.
Dann GSAP die Deckkraft des Wrappers am Schnitt umschalten: tl.set(cutoutWrap, { opacity: 1 }, 3.3).
TTS → Transkribieren → Untertitel
Wenn es keine vorab aufgenommene Sprachausgabe gibt, eine erzeugen und zurück transkribieren, um Wort-Zeitstempel für Untertitel zu erhalten:
npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav # → transcript.json