# ТЗ: Видеокружочки в Telegram (lip sync)

## Общее описание

Система генерации и отправки анимированных видеокружочков (video notes) в Telegram.
Аватарка «говорит» голосом ElevenLabs с синхронизацией губ через VEED Fabric 1.0.

---

## Архитектура

```
Пользователь → Текст → send_video_note.sh → Telegram кружочек
                            │
                            ├── Шаг 1: ElevenLabs TTS (текст → MP3)
                            ├── Шаг 2: fal.ai Upload (фото + MP3 → URLs)
                            ├── Шаг 3: VEED Fabric 1.0 (фото + MP3 → MP4 с lip sync)
                            ├── Шаг 4: FFmpeg (MP4 → 512×512 квадрат)
                            └── Шаг 5: Telegram sendVideoNote (MP4 → кружочек)
```

---

## Компоненты

### 1. ElevenLabs TTS API
- **Назначение:** генерация голоса из текста
- **Endpoint:** `https://api.elevenlabs.io/v1/text-to-speech/{voice_id}`
- **Голос:** `TPIitICAZ8CqlGZ81AKm` (голос Стрим)
- **Модель:** `eleven_multilingual_v2`
- **Вход:** текст (до 5000 символов)
- **Выход:** MP3 файл
- **Ключ:** `ELEVENLABS_API_KEY` в `~/.openclaw/.env`

### 2. fal.ai Upload API
- **Назначение:** загрузка файлов на storage fal.ai
- **Endpoint:** `https://gateway.fal.ai/storage/upload`
- **Аутентификация:** `Authorization: Key {key_id}:{key_secret}`
- **Вход:** файл (изображение или аудио)
- **Выход:** публичный URL файла на fal.ai storage
- **Ключ:** `FAL_KEY` в `~/.openclaw/.env` (формат: `key_id:key_secret`)
- **Fallback:** если upload не работает — кодирование в base64 и передача как data URL

### 3. VEED Fabric 1.0 API (fal.ai)
- **Назначение:** генерация видео с lip sync из фото и аудио
- **Endpoint:** `https://queue.fal.run/veed/fabric-1.0`
- **Аутентификация:** `Authorization: Key {key_id}:{key_secret}`
- **Вход:**
  - `image_url` — URL фото аватарки (или base64 data URL)
  - `audio_url` — URL MP3 файла с голосом (или base64 data URL)
  - `resolution` — разрешение видео (`"720p"` или `"480p"`)
- **Выход:** JSON с URL готового MP4 видео
- **Архитектура:** асинхронная (queue + poll)
  1. POST → получает `request_id` + статус `IN_QUEUE`
  2. GET poll → статусы: `IN_QUEUE` → `IN_PROGRESS` → `COMPLETED`
  3. GET result → URL MP4 файла
- **Таймаут:** 300 секунд (5 минут)
- **Стоимость:** ~$0.40 за минуту видео

### 4. FFmpeg
- **Назначение:** конвертация видео в квадрат 512×512
- **Путь:** `/home/node/bin/ffmpeg-7.0.2-amd64-static/ffmpeg`
- **Операции:**
  - Масштабирование до 512×512 с обрезкой по центру
  - Конвертация в MP4 (H.264)
  - Округление длительности до целых секунд

### 5. Telegram sendVideoNote API
- **Назначение:** отправка кружочка в Telegram
- **Endpoint:** `https://api.telegram.org/bot{token}/sendVideoNote`
- **Параметры:**
  - `chat_id` — ID чата получателя
  - `video_note` — MP4 файл
  - `length` — размер кружочка (512 пикселей)
  - `duration` — длительность в секундах
- **Токен бота:** читается из `~/.openclaw/openclaw.json`

---

## Скрипт: send_video_note.sh

**Расположение:** `/home/node/.openclaw/workspace/scripts/send_video_note.sh`

**Использование:**
```bash
./send_video_note.sh "Текст для озвучки"
./send_video_note.sh "Текст" [VOICE_ID] [CHAT_ID]
```

**Параметры:**
- `Текст` — текст для озвучки (обязательный)
- `VOICE_ID` — ID голоса ElevenLabs (по умолчанию: `TPIitICAZ8CqlGZ81AKm`)
- `CHAT_ID` — ID Telegram чата (по умолчанию: `126472752`)

**Зависимости:**
- curl
- python3
- ffmpeg (статический, путь в переменной `FFMPEG_BIN`)
- Переменные в `~/.openclaw/.env`: `ELEVENLABS_API_KEY`, `FAL_KEY`

**Временные файлы:**
- Все промежуточные файлы создаются в `/tmp/video_note_*`
- Автоматически удаляются после завершения

---

## Pipeline (подробно)

### Шаг 1: Генерация голоса (ElevenLabs TTS)
```
POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}
Headers: xi-api-key, Content-Type: application/json
Body: {"text": "...", "model_id": "eleven_multilingual_v2"}
Output: MP3 файл
```

### Шаг 2: Определение длительности аудио
```
ffprobe -v error -show_entries format=duration -of csv=p=0 tts.mp3
Output: длительность в секундах (float)
```

### Шаг 3: Загрузка файлов на fal.ai
```
POST https://gateway.fal.ai/storage/upload
Headers: Authorization: Key {key_id}:{key_secret}, Content-Type: application/octet-stream
Body: бинарные данные файла
Output: {"file_url": "https://..."}
```
Для каждого файла: аватарка (JPG) и аудио (MP3).

### Шаг 4: Отправка задачи VEED Fabric 1.0
```
POST https://queue.fal.run/veed/fabric-1.0
Headers: Authorization: Key {key_id}:{key_secret}, Content-Type: application/json
Body: {"image_url": "...", "audio_url": "...", "resolution": "480p"}
Output: {"request_id": "...", "status": "IN_QUEUE"}
```

### Шаг 5: Ожидание результата (poll)
```
GET https://queue.fal.run/veed/fabric-10/requests/{request_id}/status
Headers: Authorization: Key {key_id}:{key_secret}
Цикл: каждые 5 секунд, до 300 секунд
Статусы: IN_QUEUE → IN_PROGRESS → COMPLETED
```

### Шаг 6: Получение результата
```
GET https://queue.fal.run/veed/fabric-1.0/requests/{request_id}
Headers: Authorization: Key {key_id}:{key_secret}
Output: {"video": {"url": "https://v3b.fal.media/..."}}
```

### Шаг 7: Скачивание видео
```
curl -L -o lipsync_raw.mp4 "{video_url}"
```

### Шаг 8: Конвертация в квадрат 512×512
```
ffmpeg -i lipsync_raw.mp4 \
  -vf "crop='min(iw,ih)':'min(iw,ih)',scale=512:512" \
  -c:v libx264 -preset fast -crf 23 \
  -an -t {duration} -y video_note.mp4
```

### Шаг 9: Отправка в Telegram
```
POST https://api.telegram.org/bot{token}/sendVideoNote
Body (multipart):
  - chat_id: 126472752
  - video_note: @video_note.mp4
  - length: 512
  - duration: {duration_int}
```

---

## Аватарка

**Расположение:** `/home/node/.openclaw/workspace/data/avatars/stream-avatar.jpg`

**Требования к аватарке:**
- Формат: JPG или PNG
- Лицо: анфас, хорошо видно
- Размер: не менее 512×512 пикселей
- Фон: нейтральный или любой

**Для смены аватарки:** заменить файл `stream-avatar.jpg`

---

## Ограничения

- **Длительность:** до 60 секунд (лимит Telegram video note)
- **Размер:** до 50 МБ (лимит Telegram)
- **Стоимость VEED:** ~$0.40 за минуту видео
- **Стоимость ElevenLabs:** зависит от тарифа (символы)
- **Время обработки:** ~80 секунд на 8 секунд видео (VEED Fabric 1.0)
- **Разрешение:** 512×512 (квадрат, как требует Telegram)

---

## Интеграция в OpenClaw

**Через Стрим (координатор):**
- Стрим вызывает скрипт через `exec`: `send_video_note.sh "текст"`
- Или передаёт задачу Dev-агенту через `sessions_spawn`

**Через Dev-агента:**
- Dev может вызывать скрипт из любого проекта
- Передаёт текст и получает отправленный кружочек

**Стоимость за вызов:**
- ElevenLabs TTS: ~$0.01–0.03 за 10 секунд голоса
- VEED Fabric 1.0: ~$0.07 за 10 секунд видео
- **Итого: ~$0.10 за один кружочек**
