HyperFrames Media

Создание аудио- и медиаассетов для HyperFrames-композиций: озвучка (TTS), фоновая музыка, звуковые эффекты, транскрипция, субтитры и удаление фона — через единый аудиодвижок scripts/audio.mjs.

Аудиодвижок — один источник для TTS, BGM, SFX

Воркфлоу НЕ реализуют аудио самостоятельно и не используют копии вендорных библиотек. Есть один движок — scripts/audio.mjs — который принимает нейтральный audio_request.json и записывает audio_meta.json (плюс ассеты в assets/voice|bgm|sfx):

node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json

Все три возможности деградируют по одному переключателю — наличию HeyGen-учётных данных ($HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen):

Формат запроса (audio_request.json): { provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }. Поле bgm.mode: retrieve | generate | none; при отсутствии — auto.

Формат вывода (audio_meta.json, ключи по id): { tts_provider, voice_id, bgm, bgm_pending, …, voices, sfx, total_duration_s }.

Флаг --only tts,bgm,sfx запускает подмножество и дополняет существующий --out.

Предварительная проверка — статус входа перед любым аудио

Всегда выполняйте перед генерацией голоса или BGM. Отсутствие HeyGen-учётных данных — не повод молча переключиться на локальные движки: сначала рекомендуйте войти в систему и дайте пользователю решить.

npx hyperframes auth status

• Вошли → выводит аккаунт; продолжайте.
• Не вошли (exit 1) → выводит инструкцию по регистрации. Рекомендуйте войти: npx hyperframes auth login — браузерный OAuth, создаёт аккаунт. Для существующего HeyGen API-ключа: npx hyperframes auth login --api-key (сохраняется в ~/.heygen). ОСТАНОВИТЕСЬ и ждите выбора пользователя перед генерацией — это реальная точка принятия решений.
• npx hyperframes auth status --json возвращает { configured, recommended_action, offline_engines } для детерминированного ветвления.

Цепочки провайдеров

TTS

BGM и SFX

Обязательные правила

• Один движок, никаких копий. Производите аудио через scripts/audio.mjs. Не реализуйте TTS/BGM/SFX внутри воркфлоу — пишите адаптер audio_request.json и вызывайте движок.
• «HeyGen доступен» = разрешимые учётные данные, не CLI. Опубликованный hyperframes tts может быть только с Kokoro.
• Voice ID зависят от провайдера. am_michael — только Kokoro; HeyGen UUID не работают с Kokoro. При указании --voice также фиксируйте --provider.
• Всегда передавайте --model в transcribe. Дефолтный small.en молча переводит не-английское аудио.
• HeyGen возвращает временны́е метки слов; ElevenLabs / Kokoro — нет. Движок автоматически цепляет transcribe для последних двух.
• Субтитры потребляют плоский массив слов с { id, text, start, end }.
• BGM/SFX по умолчанию — получение из HeyGen; fallback — генерация (BGM) или встроенная библиотека (SFX). Называйте эффекты конкретно (glass shatter, не dramatic sound); отсутствие совпадений пропускает, не блокирует рендер. SFX на громкости ~0.35 под голосом + BGM.
• HTML субтитров воркфлоу — сгенерированный вывод. Источник переиспользуемого скина — .hyperframes/caption-skin.html; не редактируйте compositions/captions.html напрямую.

Маршрутизация по задачам