HyperFrames Medienvorverarbeitung
Drei CLI-Befehle, die Assets für Kompositionen erstellen: tts (Sprache), transcribe (Zeitstempel) und remove-background (transparentes Video). Jedes lädt beim ersten Ausführen ein Modell herunter und speichert es im Cache unter ~/.cache/hyperframes/. Gib die Ausgabe in das Projekt ein und referenziere sie aus der Kompositions-HTML – siehe das Skill hyperframes für die Konventionen zu Audio/Video-Elementen.
Text-to-Speech (tts)
Erzeuge Sprachaudio lokal mit Kokoro-82M. 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
Stimmenauswahl
Passe die Stimme an den Inhalt an. Standard ist af_heart.
| Inhaltstyp | Stimme | Grund |
|---|---|---|
| Produktdemo | 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 |
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 das Phonemizer-Locale automatisch anhand des Präfixes – 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
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. 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 schreibe in eine .txt-Datei und übergib den Pfad. Eingaben mit über ~5 Minuten Sprachdauer 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 Nutzung (~311 MB + ~27 MB Stimmen, zwischengespeichert in ~/.cache/hyperframes/tts/).
Transkription (transcribe)
Erstelle ein normiertes transcript.json mit Wort-für-Wort-Zeitstempeln.
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)
Verwende 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. Dadurch wird die Originalsprache stillschweigend zerstört.
- 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 Audiodaten |
small | 466 MB | Mittel | Standard – die meisten Inhalte |
medium | 1,5 GB | Langsam | Wichtige Inhalte, verrauschte Audiodaten, Musik |
large-v3 | 3,1 GB | Am langsamsten | Produktionsqualität |
Musik mit Gesang: Mindestens ab medium beginnen; produzierte Titel müssen oft manuell per SRT/VTT importiert werden. Für Qualitätsprüfungen von Untertiteln (obligatorisch nach jeder Transkription), das Bereinigungs-JS, Wiederholungsregeln und den OpenAI/Groq-API-Importpfad siehe hyperframes/references/transcript-guide.md.
Ausgabeform
Kompositionen verwenden ein flaches Array von Wortobjekten. Das id-Feld (w0, w1, ...) wird während der Normalisierung hinzugefügt, um stabile Referenzen in Untertitel-Overrides 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 eines Videos oder Bildes, sodass das Motiv (normalerweise 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 (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 Lauf lädt ~168 MB Gewichte nach ~/.cache/hyperframes/background-removal/models/ herunter.
NICHT u2net für Ausstech-Sticker mit weißem Umriss verwenden
remove-background (u2net) ist eine Segmentierung markanter Objekte – es segmentiert den
Körper des Motivs und schneidet einen weißen Ausstech-Umriss ab, da die weiße Kontur
um die Figur nicht "das Objekt" ist. Für transparente Telegram-/Messaging-Sticker, die mit einem weißen Umriss auf einem einfarbigen, bekannten Hintergrund gerendert werden, keye den Hintergrund, anstatt das Motiv zu segmentieren:
- Flood-Fill des einfarbigen Hintergrunds. PIL
ImageDraw.floodfillgesät von Punkten entlang aller vier Kanten (Schritt ~24px), markierte Pixel → Alpha 0, alles andere undurchsichtig. Dies erhält den weißen Umriss SOWIE einfarbige Objekte im Inneren SOWIE getrennte Inseln (eine fliegende Tasse, getrennt vom Körper, behält ihren eigenen Umriss). Erfordert, dass der Generierungs-Prompt das Motiv auf einen einfarbigen, gleichmäßigen Hintergrund setzt und explizit nach dem weißen Ausstech-Umriss fragt. - Variante ohne Umriss (sauberer als das Entfernen eines eingebrannten Umrisses): Führe jedes Bild erneut als Image-to-Image aus – übergib das fertige Rendering als
--refund prompte "erzeuge identische Pose/Objekte, aber ENTFERNE den weißen Umriss und setze es auf einen einfarbigen reinen Chroma-Key-Grün (#00b140)", dann keye das Grün mit einem weichen Chroma-Key, niemals einer binären Maske (alpha = clip((HIGH-(G-max(R,B)))/(HIGH-LOW),0,1), LOW≈30 HIGH≈95, plus globalen DespillG = min(G, max(R,B))). Ein binärer Flood-Fill + Erosion erzeugt treppenartige/aliasierte Kanten – weiche das binäre Alpha (GaussianBlur(0.8)) für eine glatte Kante anstelle von Erosion. - Größe für Messaging-Sticker: Beschneide auf die feste Alpha-Bounding-Box und skaliere die lange Seite exakt auf das Ziel (z.B. 512) – fülle nicht auf ein 512²-Quadrat auf (das lässt das Motiv klein mit leerem Raum darum herum).
Gilt NICHT für: menschliche Ausschnitte für Video-Overlays (u2net ist dort korrekt); Kunst ohne Ausstech-Umriss; Motive auf einem ungleichmäßigen/unruhigen Hintergrund (Flood-Fill benötigt eine einfarbige Key-Farbe).
Ebenentrennung (--background-output)
Übergib --background-output (oder -b), um ein zweites transparentes Video neben dem Ausschnitt zu erzeugen: gleiches Quell-RGB, 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... | Verwende es für |
|---|---|---|
-o subject.webm | Die Maske – Motiv undurchsichtig, Hintergrund transparent | Vordergrund-Ebene, lege sie oben |
--background-output plate.webm | Invers – Umgebung undurchsichtig, Motivbereich transparent | Untere Ebene; platziere Text oder Grafiken zwischen dieser und dem Motiv |
Beide Ausgaben teilen sich die gleiche --quality-Voreinstellung und laufen von einem einzigen Inferenzdurchgang – die Codierkosten verdoppeln sich ungefähr, die Segmentierungskosten bleiben gleich. Nur gültig für Videoeingaben und .webm/.mov-Ausgaben.
Loch-geschnittene Platte, keine inpaintierte saubere Platte. Der Motivbereich in plate.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 das Motiv war?
| Anwendungsfall | Richtiges Werkzeug |
|---|---|
| Text/Grafiken zwischen dem Ausschnitt und der Platte (der Grund, warum dieser Befehl existiert) | Loch-Schnitt (--background-output) |
| Motiv vor einer unabhängigen Szene | Nur subject.webm; ignoriere die Platte |
| Zeige den Raum ohne die Person, allein über keinem anderen Inhalt | Saubere Platte – benötigt einen Inpainter (LaMa, ProPainter, E2FGVI). Nicht dieser Befehl. |
| Ersetze das Motiv durch ein anderes Motiv | Saubere Platte – wie oben |
Wenn ein Benutzer nach "dem Raum mit entfernter Person" fragt und beabsichtigt, ihn alleinstehend anzuzeigen, greife nicht zu --background-output. Sage ihnen, dass sie einen Inpainter benötigen.
Typische geschichtete Komposition (der kanonische Loch-Schnitt-Anwendungsfall):
<!-- 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; ...">MACH ES 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 Text-hinter-Motiv-Muster unten, aber du benötigst das originale presenter.mp4 nicht im Projekt – die Platte ersetzt es. Nützlich, wenn du nur die beiden transparenten Ebenen ausliefern und dem Benutzer erlauben möchtest, beliebige Inhalte dazwischen zu platzieren.
Ausgabeformat
| Format | Wann |
|---|---|
.webm (VP9 + Alpha) | Standard. Kompositionen spielen dies direkt über <video>. |
.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 fügt sich das .webm wie jedes andere stummgeschaltete Autoplay-Video in eine Komposition ein – siehe das 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 Farbübereinstimmung |
balanced | 18 | Standard. Für die meisten Anwendungen visuell identisch |
best | 12 | Master-/Endauslieferung. Größte Datei, engste Übereinstimmung |
Kompositionsmuster – wähle das richtige
Das ausgeschnittene WebM ist eine neu codierte Kopie des RGB des Quell-MP4. Diese Wahl hat Konsequenzen, je nachdem, was du dahinter platzierst:
| Muster | Was hinter dem Ausschnitt ist | Ergebnis |
|---|---|---|
| Ausschnitt über einer anderen Szene (häufigster Fall) | Statisches Bild, Farbverlauf 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 seinem eigenen Quell-MP4 (Text-hinter-Motiv) | Gleiches MP4, aus dem der Ausschnitt generiert wurde | Zwei RGB-Quellen für dieselbe Person. Bei Standard---quality balanced (crf 18) ist die Verdopplung kaum sichtbar; bei --quality fast (crf 30) siehst du eine leichte Farbverschiebung/Randhalo. |
| … |
[abgeschnitten für die Übersetzung]