wiki/tasks/karaoke/README.md

Караоке-генератор v0.1 (MVP) 🎤

CLI-инструмент, который принимает аудиофайл песни и генерирует видео с синхронизированным текстом (стиль "караоке/субтитры").

---

Быстрый старт

# Установка зависимостей
pip install -r requirements.txt

# Генерация караоке из аудио
python karaoke.py --audio song.mp3

# С готовым текстом
python karaoke.py --audio song.mp3 --text lyrics.lrc
python karaoke.py --audio song.mp3 --text lyrics.txt
python karaoke.py --audio song.mp3 --text lyrics.srt

# С кастомным выходным файлом и моделью
python karaoke.py --audio song.mp3 --whisper-model small --output my_karaoke.mp4

---

Зависимости

Python (Python 3.10+)

Пакет	Версия	Зачем
faster-whisper	1.2.1	Транскрипция аудио с таймингами
moviepy	2.1.2	(опционально) видео-рендер
pillow	10.4.0	Рендер текстовых кадров
requests	2.33.1	HTTP-запросы к API
numpy	2.4.0	Математика
python-dotenv	1.2.2	Загрузка .env

Системные

• FFmpeg — должен быть в PATH или указан через FFMPEG_BIN/FFPROBE_BIN
  • В проекте используется статик из ~/bin/ffmpeg-7.0.2-amd64-static/

---

Переменные окружения

Переменная	Описание	По умолчанию
PEXELS_API_KEY	Ключ Pexels API для поиска видео-фонов	— (будет чёрный фон)
GIGACHAT_CREDS	OAuth креды GigaChat (Base64)	из ~/.openclaw/.env
GIGACHAT_BASE_URL	URL GigaChat API	из ~/.openclaw/.env
FFMPEG_BIN	Путь к ffmpeg	~/bin/ffmpeg-7.0.2-amd64-static/ffmpeg
FFPROBE_BIN	Путь к ffprobe	~/bin/ffmpeg-7.0.2-amd64-static/ffprobe

---

Структура проекта

tasks/karaoke/
├── karaoke.py          # CLI точка входа, argparse
├── transcribe.py       # Whisper транскрипция + LRC/SRT парсер
├── nlp.py              # GigaChat NLP → {mood, scenes}
├── video_bg.py         # Pexels API + чёрный фон fallback
├── render.py           # FFmpeg/MoviePy рендер
├── requirements.txt    # pinned зависимости
├── README.md           # этот файл
└── PROJECT.md          # полное ТЗ

---

Как это работает

1. Транскрипция — Whisper извлекает текст + тайминги из аудио
2. NLP — GigaChat анализирует настроение и сцены (fallback без API)
3. Видео-фон — Pexels API ищет видео; если нет — чёрный фон
4. Рендер — FFmpeg накладывает текст на видео с fade-in/out

---

CLI аргументы

--audio AUDIO          Путь к аудиофайлу (обязательный)
--text TEXT            Путь к файлу с текстом (.lrc/.srt/.txt)
--output OUTPUT        Выходной файл (по умолчанию: output.mp4)
--whisper-model SIZE   tiny/base/small/medium/large (по умолч.: base)
--device DEVICE        cpu/cuda (по умолч.: cpu)
--language LANG        Код языка (ru/en/...) или авто (None)

---

Выходной формат

• Видео: 1280x720, H.264, 30fps
• Аудио: оригинальное, AAC 192kbps
• Текст: белый, 48px, с чёрной тенью; активная строка жёлтая
• Fade-in/out: ~0.3 сек

---

Лицензия

MIT / Internal Project