HyperFrames Media-Vorverarbeitung
Drei CLI-Befehle, die Assets für Kompositionen erstellen: tts (Sprache), transcribe (Zeitstempel) und remove-background (transparentes Video). Jeder lädt beim ersten Ausführen ein Modell herunter und cacht es unter ~/.cache/hyperframes/. Lege die Ausgabe in das Projekt, und referenziere sie aus der Kompositions-HTML – siehe das hyperframes-Skill für die Audio-/Video-Element-Konventionen.
Text-to-Speech (tts)
Generiere lokal Sprachaudio mit Kokoro-82M. Kein API-Key erforderlich.
npx hyperframes tts "Text hier" --voice af_nova --output erzaehlung.wav
npx hyperframes tts skript.txt --voice bf_emma --output erzaehlung.wav
npx hyperframes tts --list # alle 54 Stimmen
Stimmenauswahl
Passe die Stimme an den Inhalt an. Standard ist af_heart.
| Inhaltstyp | Stimme | Grund |
|---|---|---|
| Produktdemo | af_heart/af_nova | Warm, professionell |
| Tutorial / How-to | am_adam/bf_emma | Neutral, leicht verständlich |
| Marketing / Werbung | af_sky/am_michael | Energiegeladen oder autoritär |
| Dokumentation | bf_emma/bm_george | Klar britisches Englisch, formell |
| Lässig / Sozial | af_heart/af_sky | Zugänglich, natürlich |
Mehrsprachig
Stimm-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 die Phonemizer-Lokalisierung automatisch aus dem Präfix – kein --lang erforderlich, 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
Verwende --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 schreibe in eine .txt-Datei und übergib den Pfad. Eingaben über ~5 Minuten Sprache können von einer Aufteilung in Segmente profitieren.
Anforderungen
Python 3.8+ mit kokoro-onnx und soundfile (pip install kokoro-onnx soundfile). Modell wird bei erster Nutzung heruntergeladen (~311 MB + ~27 MB Stimmen, gecacht in ~/.cache/hyperframes/tts/).
Transkription (transcribe)
Erstelle ein normalisiertes transcript.json mit Wort-Zeitstempeln.
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe untertitel.srt # bestehende importieren
npx hyperframes transcribe untertitel.vtt
npx hyperframes transcribe openai-response.json
Sprachregel (Nicht verhandelbar)
.en-Modelle niemals verwenden, es sei denn, der Benutzer gibt ausdrücklich an, dass das Audio 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 | Wann verwenden |
|---|---|---|---|
tiny | 75 MB | Am schnellsten | Schnelle Vorschauen, Pipeline-Tests |
base | 142 MB | Schnell | Kurze Clips, klare Audio |
small | 466 MB | Mäßig | Standard – für 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: beginne mindestens mit medium; produzierte Tracks benötigen oft manuellen SRT/VTT-Import. Für Caption-Qualitätsprüfungen (obligatorisch nach jeder Transkription), die Bereinigung in JS, Wiederholungsregeln und den OpenAI/Groq API-Importpfad siehe hyperframes/references/transcript-guide.md.
Ausgabeformat
Kompositionen verarbeiten ein flaches Array von Wortobjekten. Das id-Feld (w0, w1, ...) wird während der Normalisierung hinzugefügt, um stabile Referenzen in Caption-Überschreibungen zu ermöglichen; es ist optional für 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)
Entferne den Hintergrund aus einem Video oder Bild, sodass das Motiv (typischerweise eine Person – Avatar, Präsentator, sprechender Kopf) als transparentes Overlay in einer Komposition sitzt.
npx hyperframes remove-background motiv.mp4 -o transparent.webm # Standard: VP9 Alpha WebM
npx hyperframes remove-background motiv.mp4 -o transparent.mov # ProRes 4444 (Bearbeitung)
npx hyperframes remove-background portrait.jpg -o ausschnitt.png # Einzelbildausschnitt
npx hyperframes remove-background motiv.mp4 -o motiv.webm \
--background-output platte.webm # beide Ebenen in einem Durchlauf
npx hyperframes remove-background motiv.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # erkannte Anbieter
Verwendet u2net_human_seg (MIT). Erster Lauf lädt ~168 MB Gewichte herunter nach ~/.cache/hyperframes/background-removal/models/.
Ebenentrennung (--background-output)
Übergib --background-output (oder -b), um ein zweites transparentes Video neben dem Ausschnitt zu erstellen: 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 an der Stelle des Motivs.
| Datei | Alpha ist… | Verwendung |
|---|---|---|
-o motiv.webm | Die Maske – Motiv undurchsichtig, Hintergrund transparent | Vordergrund-Ebene, darüber legen |
--background-output platte.webm | Invertiert – Umgebung undurchsichtig, Motivbereich transparent | Bodenebene; Text oder Grafiken zwischen diese und das Motiv setzen |
Beide Ausgaben teilen sich dieselbe --quality-Voreinstellung und werden in einem einzigen Inferenzdurchlauf erstellt – die Kodierungskosten verdoppeln sich etwa, die Segmentierungskosten bleiben gleich. Nur gültig für Videoeingaben und .webm/.mov-Ausgaben.
Lochausgestanzte Platte, keine nachbearbeitete saubere Platte. Der Motivbereich in platte.webm ist vollständig transparent – komponiere etwas Undurchsichtiges darunter, um das Loch zu füllen. Der einzige Test, ob --background-output das richtige Werkzeug ist: Wird jemals etwas durch die Silhouette des Motivs sichtbar sein, wo sich das Motiv befand?
| Anwendungsfall | Richtiges Werkzeug |
|---|---|
| Text/Grafiken zwischen Ausschnitt und Platte (Existenzgrund dieses Befehls) | Lochausstanzung (--background-output) |
| Motiv auf eine nicht verwandte Szene | Nur motiv.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 – wie oben |
Wenn ein Benutzer nach „dem Raum mit der entfernten Person“ fragt und beabsichtigt, ihn eigenständig anzuzeigen, greife nicht zu --background-output. Sage ihnen, dass sie einen Inpainter benötigen.
Typische geschichtete Komposition (der kanonische Anwendungsfall der Lochausstanzung):
<!-- z=1 die Platte mit invertiertem Alpha füllt alles außer dem Motivbereich -->
<video
src="platte.webm"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<!-- z=2 Grafiken / Text zwischen den beiden Ebenen -->
<h1 id="headline" style="z-index:2; ...">MACH ES IN HYPERFRAMES</h1>
<!-- z=3 der Ausschnitt legt das Motiv wieder über die Überschrift -->
<div class="ausschnitt-wrap" style="position:absolute;inset:0;z-index:3">
<video
src="motiv.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
Dies ist funktional äquivalent zum Muster „Text-hinter-Motiv“ unten, aber du benötigst die ursprüngliche presenter.mp4 nicht im Projekt – die Platte ersetzt sie. Nützlich, wenn du nur die beiden transparenten Ebenen ausliefern möchtest und dem Benutzer erlauben willst, beliebigen Inhalt dazwischen zu platzieren.
Ausgabeformat
| Format | Wann |
|---|---|
.webm (VP9 + Alpha) | Standard. Kompositionen spielen dies direkt über <video> ab. |
.mov (ProRes 4444) | Bearbeitung in DaVinci/Premiere/FCP. Große Dateien. |
.png | Einzelbildausschnitt (stehendes Motiv, über einem Hintergrund). |
Chrome dekodiert VP9-Alpha nativ, daher kann das .webm wie jedes andere stummgeschaltete Autoplay-Video in eine Komposition eingefügt werden – siehe das hyperframes-Skill für die <video>-Track-Konventionen.
Qualitätsvoreinstellungen
--quality fast|balanced|best steuert nur den CRF des VP9-Kodierers – die Segmentierungsqualität ist festgelegt.
| 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 – wähle das richtige
Das ausgeschnittene WebM ist eine neukodierte Kopie des RGB der Quell-MP4. Diese Wahl hat Konsequenzen, je nachdem, was dahinter gelegt wird:
| Muster | Was hinter dem Ausschnitt ist | Ergebnis |
|---|---|---|
| Ausschnitt über einer anderen Szene (am häufigsten) | Statisches Bild, Verlauf oder nicht verwandtes Video | Sieht großartig aus. Das RGB des Ausschnitts ist die einzige Quelle des Motivs – keine Verdoppelung, kein Rand-Halo. 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 Standard --quality balanced (crf 18) ist die Verdoppelung kaum sichtbar; bei --quality fast (crf 30) siehst du eine leichte Farbverschiebung / Rand-Halo. Verwende --quality best (crf 12) für Master. |
| Ausschnitt über einer anderen Aufnahme derselben Person | Aufnahmen desselben Motivs | Es wird aussehen, als würden sich zwei verschiedene Personen überlappen. Tu das nicht. |
Text-hinter-Motiv (Überschrift hinter einem Präsentator):
<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; ...">MACH ES IN HYPERFRAMES</h1>
<div class="ausschnitt-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:
- Wickel das ausgeschnittene Video in ein nicht-getimetes
<div>und animiere die Deckkraft des Wrappers, nicht des Video-Elements. Das Framework erzwingt deckkraft:1 auf aktiven Clips (jedes Element mitdata-start/data-duration), daher wird das Animieren der Deckkraft des Videos direkt stillschweigend überschrieben. Der Wrapper hat keinedata-*-Attribute, daher gehört er deinem CSS/GSAP. - Beide Videos verwenden
data-start="0"unddata-media-start="0", damit das Framework sie synchron ab t=0 dekodiert. Ein spätes Einhängen des Ausschnitts (data-start=3.3) führt zu einem Seek + Aufwärmen, das einen Frame von der Basis-MP4 abweicht – sichtbar als ein Frame Fehlausrichtung am Cut.
Dann GSAP-Flip der Wrapper-Deckkraft am Cut: tl.set(cutoutWrap, { opacity: 1 }, 3.3).
TTS → Transkribieren → Untertitel
Wenn es keine voraufgezeichnete Voiceover gibt, generiere eine und transkribiere sie zurück, um Wort-Zeitstempel für Untertitel zu erhalten:
npx hyperframes tts skript.txt --voice af_heart --output erzaehlung.wav
npx hyperframes transcribe erzaehlung.wav # → transcript.json
…
[gekürzt zur Übersetzung]