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/. Die Ausgabe in das Projekt einfügen und dann aus der Komposition HTML referenzieren – siehe das hyperframes-Skill für die Audio/Video-Element-Konventionen.
Text-to-Speech (tts)
Sprachaudio lokal mit Kokoro-82M generieren. Kein API-Key.
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
Stimmenauswahl
Stimme an den Inhalt anpassen. Standard ist af_heart.
| Inhaltstyp | Stimme | Grund |
|---|---|---|
| Produkt-Demo | af_heart/af_nova | Warm, professionell |
| Tutorial / Anleitung | am_adam/bf_emma | Neutral, leicht verständlich |
| Marketing / Werbung | af_sky/am_michael | Energisch oder autoritär |
| Dokumentation | bf_emma/bm_george | Klares britisches Englisch, formell |
| Lässig / Sozial | af_heart/af_sky | Zugänglich, natürlich |
Mehrsprachigkeit
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. Die 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
--lang nur zum Überschreiben der automatischen Erkennung verwenden (stilisierte Akzente). Gültige Codes: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh. Für nicht-englische Phonemisierung ist espeak-ng systemweit erforderlich (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 Sprache können von einer Aufteilung in Segmente profitieren.
Anforderungen
Python 3.8+ mit kokoro-onnx und soundfile (pip install kokoro-onnx soundfile). Modell-Download bei erster Verwendung (~311 MB + ~27 MB Stimmen, zwischengespeichert in ~/.cache/hyperframes/tts/).
Transkription (transcribe)
Ein normalisiertes transcript.json mit Wort-für-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 .en-Modelle NIE, 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 | Wann verwenden |
|---|---|---|---|
tiny | 75 MB | Am schnellsten | Schnelle Vorschauen, Pipeline-Tests |
base | 142 MB | Schnell | Kurze Clips, klare Audios |
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 bei medium beginnen; fertige Tracks benötigen oft manuellen SRT/VTT-Import. Für Untertitel-Qualitätskontrollen (obligatorisch nach jeder Transkription), die JS-Bereinigung, Wiederholungsregeln und den OpenAI/Groq-API-Importpfad, siehe hyperframes/references/transcript-guide.md.
Ausgabeformat
Kompositionen verwenden ein flaches Array von Wortobjekten. Das Feld id (w0, w1, ...) wird während der Normalisierung für stabile Referenzen in Untertitel-Overrides hinzugefügt; es ist optional für Abwärtskompatibilität.
[
{ "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
{ "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }
]
Hintergrundentfernung (remove-background)
Entfernt den Hintergrund aus einem Video oder Bild, sodass das Motiv (typischerweise eine Person – Avatar, Präsentator, Sprecher) 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 (Bearbeitung)
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 Durchgang
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 zusammen mit dem Ausschnitt auszugeben: gleiches RGB der Quelle, Alpha ist 255 − Maske statt 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 für |
|---|---|---|
-o subject.webm | Die Maske – Motiv undurchsichtig, Hintergrund transparent | Vordergrundebene, oben platzieren |
--background-output plate.webm | Invers – Umgebung undurchsichtig, Motivbereich transparent | Untere Ebene; Text oder Grafiken zwischen diese und das Motiv setzen |
Beide Ausgaben teilen denselben --quality-Vorgabewert und laufen in einem einzigen Inferenzdurchlauf – die Codierungskosten verdoppeln sich etwa, die Segmentierungskosten bleiben gleich. Nur gültig für Videoeingaben und .webm/.mov-Ausgaben.
Ausgestanzte Platte, keine nachbearbeitete saubere Platte. Der Motivbereich in plate.webm ist vollständig transparent – etwas Undurchsichtiges darunter komponieren, 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 das Motiv war?
| Anwendungsfall | Richtiges Werkzeug |
|---|---|
| Text/Grafiken zwischen Ausschnitt und Platte (Grund für die Existenz dieses Befehls) | Ausstanzung (--background-output) |
| Motiv in eine nicht verwandte Szene einfügen | 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 – siehe oben |
Wenn ein Benutzer nach „dem Raum mit der entfernten Person“ fragt und beabsichtigt, ihn eigenständig anzuzeigen, greifen Sie nicht zu --background-output. Sagen Sie ihnen, dass sie einen Inpainter benötigen.
Typische geschichtete Komposition (der kanonische Anwendungsfall für Ausstanzungen):
<!-- z=1 die inverse-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 leben zwischen den beiden Ebenen -->
<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>
<!-- z=3 der Ausschnitt schwebt das Motiv wieder ü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 Muster „Text hinter Motiv“ unten, aber Sie benötigen nicht das originale presenter.mp4 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 einzufügen.
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 | Einzelbild-Ausschnitt (stehendes Motiv, über einem Hintergrund gelegt). |
Chrome dekodiert VP9 Alpha nativ, daher lässt sich das .webm wie jedes andere stummgeschaltete Autoplay-Video in eine Komposition einfügen – siehe das hyperframes-Skill für die <video>-Track-Konventionen.
Qualitätsvoreinstellungen
--quality fast|balanced|best steuert nur den VP9-Codierer-CRF – die Segmentierungsqualität ist fest.
| Voreinstellung | CRF | Wann |
|---|---|---|
fast | 30 | Iterieren, kleinere Datei, lockererer Farbabgleich |
balanced | 18 | Standard. Für die meisten Anwendungen visuell identisch |
best | 12 | Master / endgültige Auslieferung. Größte Datei, engster Abgleich |
Compositing-Muster – das richtige auswählen
Das Ausschnitt-Webm ist eine neu codierte Kopie des RGB der Quell-MP4. Diese Wahl hat Konsequenzen, je nachdem, was Sie dahinter platzieren:
| Muster | Was hinter dem Ausschnitt ist | Ergebnis |
|---|---|---|
| Ausschnitt über einer anderen Szene (am häufigsten) | Standbild, Farbverlauf oder nicht verwandtes Video | Sieht großartig aus. Das RGB des Ausschnitts ist die einzige Quelle des Motivs – keine Verdopplung, kein Rand-Halo. Dafür ist remove-background gemacht. |
| Ausschnitt über seiner eigenen Quell-MP4 (Text hinter Motiv) | Gleiche MP4, aus der der Ausschnitt erstellt wurde | Zwei RGB-Quellen für dieselbe Person. Bei Standard---quality balanced (crf 18) ist die Verdopplung kaum sichtbar; bei --quality fast (crf 30) sehen Sie eine leichte Farbverschiebung / Rand-Halo. Verwenden Sie --quality best (crf 12) für Master. |
| Ausschnitt über einer anderen Aufnahme derselben Person | Filmmaterial desselben Motivs | Sieht aus wie zwei verschiedene Personen, die sich überlappen. Nicht tun. |
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; ...">MAKE IT 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 wichtige Regeln:
- Das Ausschnitt-Video in ein nicht zeitgesteuertes
<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), daher wird das direkte Animieren der Deckkraft des Videos stillschweigend überschrieben. Der Wrapper hat keinedata-*-Attribute, wird also von Ihrem CSS/GSAP gesteuert. - Beide Videos verwenden
data-start="0"unddata-media-start="0", damit das Framework sie synchron ab t=0 dekodiert. Ein spätes Einbinden des Ausschnitts (data-start=3.3) führt zu einem Such- und Aufwärmvorgang, der ein Frame von der Basis-MP4 entfernt landet – sichtbar als ein Frame von Fehlausrichtung am Schnitt.
Dann die Wrapper-Deckkraft mit GSAP am Schnitt umschalten: tl.set(cutoutWrap, { opacity: 1 }, 3.3).
TTS → Transkribieren → Untertitel
Wenn es keine vorab aufgezeichnete Voiceover gibt, eine generieren und zurück transkribieren, um Wort-für-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