HyperFrames Media
Erstellen Sie die Audio- und Medien-Assets, die eine Komposition benötigt – Sprachausgabe (TTS), Hintergrundmusik + Soundeffekte, Transkription, Untertitel, Hintergrundentfernung – und nutzen Sie diese Daten dann in HTML. Informationen zum Platzieren von Assets in Kompositionen finden Sie unter hyperframes-core.
Die Audio-Engine – eine Quelle für TTS · BGM · SFX
Workflows erstellen Audio NICHT manuell oder mit einer eigenen Kopie. Es gibt eine Engine – scripts/audio.mjs – die eine neutrale audio_request.json entgegennimmt und audio_meta.json (plus Assets unter assets/voice|bgm|sfx) schreibt:
# <MEDIA_DIR> = Verzeichnis dieses Skills
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
Alle drei Fähigkeiten degradieren über EINEN Schalter – ob ein HeyGen-Zugangsdaten vorliegen (ermittelt aus $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen, nicht über die CLI):
| Fähigkeit | HeyGen-Zugangsdaten vorhanden | nicht vorhanden |
|---|---|---|
| TTS | HeyGen Starfish REST (native Wort-Zeitstempel) | → ElevenLabs → Kokoro (Kette transcribe für Wörter) |
| BGM | HeyGen Musik-Abruf | Lyria → MusicGen lokale Generierung (getrennt) |
| SFX | HeyGen Soundeffekt-Abruf (min_score 0.4) | eingebundene 21-Dateien-Bibliothek (assets/sfx/) |
- Anfrage (
audio_request.json):{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }.idverbindet jede Zeile mit dem Modell des Aufrufers (eine Frame-Nummer, eine Szenen-ID, …).bgm.mode=retrieve | generate | none; weglassen für automatisch (abrufen bei Zugangsdaten, sonst generieren). Ein expliziterretrieveist strikt – er überspringt statt eine getrennte Generierung zu starten (für Aufrufer ohnewait-bgm-Schritt). - Ausgabe (
audio_meta.json, ID-basiert):{ tts_provider, voice_id, bgm, bgm_pending, …, voices: [{ id, path, duration_s, words }], sfx: [{ id, name, file, source, offset_s, duration_s, volume }], total_duration_s }. --only tts,bgm,sfxführt eine Teilmenge aus und führt mit einem vorhandenen--outzusammen (z. B. TTS+BGM früh, SFX sobald Cues existieren).- BGM-Generierung wird getrennt gestartet (
bgm_pending: true) – führen Siescripts/wait-bgm.mjsvor der Zusammenstellung aus. scripts/heygen-tts.mjsist eine einmalige CLI über denselben Code (ein Text → wav + Wörter) für den Fall, dass Sie nur HeyGen TTS ohne eine Anfragedatei benötigen.
Die vollständige Flag-Liste + das audio_meta.json-Schema befinden sich im Header von scripts/audio.mjs. Die folgenden Referenzen decken die Anbieterdetails und Randfälle hinter jeder Fähigkeit ab.
Vorab-Check – Anmeldestatus vor jeglichem Audio anzeigen
Führen Sie dies immer vor der Sprach- oder BGM-Generierung aus – innerhalb eines vollständigen Workflows oder einer einmaligen „Generiere mir BGM/Sprachausgabe“-Anfrage. Keine HeyGen-Zugangsdaten zu haben ist kein Grund, stillschweigend auf lokale Engines zurückzufallen: Empfehlen Sie zunächst die Anmeldung und lassen Sie den Benutzer entscheiden. Führen Sie den gemeinsamen Vorab-Check aus und geben Sie dessen Ausgabe wörtlich weiter – improvisieren Sie keine eigene „Fehlender Schlüssel“-Eingabeaufforderung und bieten Sie nicht an, Schlüssel in eine pro-Repo .env zu schreiben:
npx hyperframes auth status
- Angemeldet → es gibt das Konto aus; fortfahren.
- Nicht angemeldet (
exit 1ist hier zu erwarten – „nicht angemeldet“ ist ein normaler Zustand, kein Fehler) → es gibt eine Registrierungs-basierte Anleitung aus. Empfehlen Sie die Anmeldung:npx hyperframes auth loginist Browser-OAuth – es meldet an und erstellt ein Konto (immer über die CLI dieses Repos verfügbar). Um einen vorhandenen HeyGen API-Key (von app.heygen.com/settings/api) zu verwenden, führen Sienpx hyperframes auth login --api-keyaus – es speichert in das gemeinsame~/.heygen(keine pro-Repo.env). Die Ausgabe listet auch die lokalen Engines auf, auf die Sprachausgabe/BGM zurückfallen, sowie einenpip-Hinweis, wenn Abhängigkeiten fehlen. Geben Sie diese Ausgabe unverändert weiter – paraphrasieren Sie sie nicht in eigene Worte. Dann STOPPEN Sie und warten Sie, bis der Benutzer wählt – anmelden oder „los“ / „lokal“ sagen, um offline fortzufahren – bevor Sie etwas generieren. Dies ist ein echter Entscheidungspunkt, keine beiläufige Notiz: Falten Sie es nicht in eine andere Frage und fahren Sie nicht eigenständig darüber hinaus. (Ausnahme: Im autonomen / nicht-interaktiven Modus notieren Sie den Status und fahren offline fort.) npx hyperframes auth status --jsongibt{ configured, recommended_action, offline_engines }für deterministische Verzweigungen zurück.- Wenn die CLI nicht ausgeführt werden kann (nicht im PATH und
npxkann sie nicht abrufen) → empfehlen Sie trotzdem die Anmeldung (npx hyperframes auth login) und STOPPEN für die Entscheidung des Benutzers – behandeln Sie „keine Zugangsdaten“ nicht als stillschweigendes grünes Licht für die lokale Generierung.
Die Zugangsdatenauflösung, vollständige Schlüsselpriorität und die Liste der lokalen Abhängigkeiten finden Sie in references/requirements.md.
Anbieterketten (die Details hinter der Engine)
TTS – der erste verfügbare Anbieter gewinnt (die Engine oder npx hyperframes tts "..."):
| Reihenfolge | Anbieter | Erkannt wenn | Wort-Zeitstempel |
|---|---|---|---|
| 1 | HeyGen (Starfish) | $HEYGEN_API_KEY / hyperframes auth login | Ja, nativ – übergeben Sie --words narration.words.json zum Erfassen |
| 2 | ElevenLabs | $ELEVENLABS_API_KEY gesetzt | Nein – danach transcribe-Kette |
| 3 | Kokoro-82M (lokal, 54 Stimmen) | immer (kein Schlüssel erforderlich) | Nein – danach transcribe-Kette |
Die veröffentlichte
hyperframes ttsCLI ist oft der Nur-Lokal-Build (ihr--helpsagt „Kokoro-82M“, kein--provider/--words) und fällt selbst mit gesetztem$HEYGEN_API_KEYstillschweigend auf Kokoro zurück. Deshalb ist der HeyGen-Pfad der Engine das eigenständigescripts/heygen-tts.mjs(REST), NICHT die CLI; die CLI wird nur für den Kokoro-Pfad verwendet. Siehereferences/tts.md.
BGM & SFX – standardmäßig aus der HeyGen-Audiobibliothek abgerufen (/v3/audio/sounds), gleiche Zugangsdaten wie HeyGen TTS, mit dem Rückfall ohne Zugangsdaten aus der obigen Tabelle:
| Asset | HeyGen type | Landet in | Rückfall (keine Zugangsdaten) |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3 (Abruf) · track.wav (Generierung) | Lyria / MusicGen Generierung |
| SFX | sound_effects (min_score 0.4) | assets/sfx/<slug>.mp3 | Eingebundene 21-Dateien-Bibliothek (assets/sfx/* + manifest.json) |
Siehe references/bgm.md und references/sfx.md.
Routing
| Aufgabe | Lesen |
|---|---|
Die Audio-Engine – Anfrage/Meta-Schema, --only, der Schalter | scripts/audio.mjs (Header-Kommentar) |
npx hyperframes tts / heygen-tts.mjs – Anbieter, Stimmen, Wörter | references/tts.md |
| BGM – HeyGen-Abruf + lokale Lyria/MusicGen Generierung | references/bgm.md |
| SFX – HeyGen-Abruf (min_score 0.4) + eingebundene lokale Bibliothek | references/sfx.md |
npx hyperframes transcribe – Whisper, Modellregeln, Ausgabeform | references/transcribe.md |
npx hyperframes remove-background – transparente Ausschnitte | references/remove-background.md |
| TTS → Transkription → Untertitel (keine aufgezeichnete Sprachausgabe) | references/tts-to-captions.md |
| Untertitel-Erstellung – Stilerkennung, Layout, Wortgruppierung, Ausstieg | references/captions/authoring.md |
| Transkript-Verarbeitung – Eingabeformate, Qualitätsfilter, Bereinigung, APIs | references/captions/transcript-handling.md |
| Untertitel-Bewegung – Karaoke, Markereffekte, audio-reaktiv | references/captions/motion.md |
| Modell-Caches, Systemabhängigkeiten, Fehlerbehebung | references/requirements.md |
Nicht verhandelbare Regeln
- Eine Engine, keine kopierten Versionen. Audio über
scripts/audio.mjs(oderheygen-tts.mjsfür einmalige HeyGen TTS) produzieren. TTS/BGM/SFX nicht innerhalb eines Workflows neu implementieren – schreiben Sie einenaudio_request.json-Adapter und rufen Sie die Engine auf. - „HeyGen verfügbar“ = auflösbare Zugangsdaten, nicht die CLI. Der gesamte Schalter hängt von
heygenCredential()ab; die veröffentlichtehyperframes ttskann Nur-Kokoro sein, und es gibt überhaupt keinen Befehlhyperframes bgm/hyperframes sfx. - Sprach-IDs sind anbieterabhängig.
am_michaelist Nur-Kokoro; HeyGen-UUIDs funktionieren nicht mit Kokoro. Wenn Sie--voiceübergeben, setzen Sie auch--providerfest, um eine stille Anbieterabweichung bei Änderung der Benutzerumgebung zu vermeiden. - Immer
--modelantranscribeübergeben. Der CLI-Standardsmall.enübersetzt stillschweigend nicht-englische Audiodaten. Siehereferences/transcribe.md→ „Sprachregel“. - HeyGen gibt Wort-Zeitstempel zurück; ElevenLabs/Kokoro nicht. Die Engine fügt automatisch
transcribefür die letzten beiden hinzu; eigenständig übergeben Sie--wordsan HeyGen oder führentranscribegegen die Audiodatei aus. - Untertitel verbrauchen das flache Wort-Array-Format mit
{ id, text, start, end }. Siehereferences/transcribe.md→ „Ausgabeform“. remove-background --background-outputist Lochschnitt, kein Inpainting. Für „Szene ohne die Person“ ist ein anderes Werkzeug erforderlich. Siehereferences/remove-background.md→ „Wann NICHT das richtige Werkzeug“.- BGM/SFX standardmäßig HeyGen-Abruf; der Rückfall ohne Zugangsdaten ist Generierung (BGM) oder die eingebundene Bibliothek (SFX).
/audio/soundssortiert nach einer Textabfrage – benennen Sie Effekte konkret (glass shatter, nichtdramatic sound); ein fehlender Treffer überspringt, blockiert nie das Rendern. SFX liegen bei ~0,35 Lautstärke unter Stimme + BGM. Siehereferences/sfx.md/references/bgm.md. - Behandeln Sie Workflow-Untertitel-HTML als generierte Ausgabe. Für pressegestützte Videos befindet sich die wiederverwendbare Skin-Quelle unter
.hyperframes/caption-skin.htmlund das Workflow-Skript schreibtcompositions/captions.html; bearbeiten Sie nicht generiertescompositions/captions.html, um die Skin zu korrigieren. Erstellen Sie es über dencaptions.mjsdes Workflows neu oder verwenden Sie den expliziten Überschreibungsmechanismus dieses Workflows, sofern vorhanden.