From 776271ff36d74f4b19c6cca6fed2836e656f3a73 Mon Sep 17 00:00:00 2001 From: Mikhail Kilin Date: Thu, 5 Feb 2026 02:51:04 +0300 Subject: [PATCH] docs: add Phase 12 - voice message playback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documented new feature for playing voice messages directly from TUI with full playback controls and visual feedback. Documentation Changes: - ROADMAP.md: Added Phase 12 with 7 stages - Stage 1: Audio infrastructure (audio module, AudioPlayer, VoiceCache) - Stage 2: TDLib integration (VoiceNoteInfo, download_voice_note) - Stage 3: UI for playback (progress bar, status indicators, footer) - Stage 4: Hotkeys (play/pause, stop, seek, volume control) - Stage 5: Configuration and UX (AudioConfig, ticker updates) - Stage 6: Error handling and fallback (system player) - Stage 7: Additional improvements (prefetching, animations) - CONTEXT.md: Added PLANNED section for Phase 12 - Technical stack: rodio 0.17, TDLib downloadFile - Platforms: Linux (ALSA/PulseAudio), macOS (CoreAudio), Windows (WASAPI) - Architecture: src/audio/ module with 3 submodules - LRU cache (100 MB limit) - Async loading, ticker for progress updates - Configuration options in config.toml - Fallback to system players (mpv, ffplay) - HOTKEYS.md: Added new hotkeys - `Space` - play/pause (in voice message selection mode) - `s` / `ы` - stop playback - `←` / `→` - seek -5s/+5s (during playback) - `↑` / `↓` - volume +/-10% (during playback) - Added new "Voice Playback" section - Added new "Voice Playback Mode" section - PROJECT_STRUCTURE.md: Added audio/ module documentation - player.rs - AudioPlayer with rodio - cache.rs - VoiceCache for downloaded OGG files - state.rs - PlaybackState (status, position, duration, volume) - Updated dependencies section (rodio 0.17) - Updated App state with audio fields Technical Details: - rodio 0.17 Pure Rust audio library (cross-platform) - OGG Opus support (Telegram voice message format) - Visual progress bar: ▶ ████████░░░░░░ 0:08 / 0:15 - Status indicators: ▶ (playing), ⏸ (paused), ⏹ (stopped), ⏳ (loading) - Smart caching with size limits - Async non-blocking file download - Ticker for smooth progress updates (100ms) - Graceful fallback to system players New Configuration (config.toml): - enabled: bool - enable/disable audio playback - default_volume: f32 - volume (0.0 - 1.0) - seek_step_seconds: i32 - seek step in seconds (default 5) - autoplay: bool - autoplay on selection - cache_size_mb: usize - cache size limit in MB - show_waveform: bool - show waveform visualization - system_player_fallback: bool - use system player fallback - system_player: String - system player command (mpv, ffplay) Status: PLANNED (documentation complete, implementation pending) Co-Authored-By: Claude Sonnet 4.5 --- CONTEXT.md | 45 +++++++++++++++ HOTKEYS.md | 30 ++++++++++ PROJECT_STRUCTURE.md | 41 +++++++++++++ ROADMAP.md | 135 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 251 insertions(+) diff --git a/CONTEXT.md b/CONTEXT.md index a0ec577..bfacd58 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -79,6 +79,51 @@ - Производительность: кэширование, асинхронность, lazy loading - **Статус**: PLANNED (документация готова в ROADMAP.md) +**🎤 PLANNED: Прослушивание голосовых сообщений (Фаза 12)** +- **Описание**: Воспроизведение голосовых сообщений прямо из TUI с визуальным feedback +- **Технологии**: + - rodio 0.17 - Pure Rust аудио библиотека (кроссплатформенная) + - TDLib downloadFile API для загрузки OGG файлов + - Поддержка платформ: Linux (ALSA/PulseAudio), macOS (CoreAudio), Windows (WASAPI) + - Fallback на системный плеер (mpv, ffplay) если rodio не работает +- **Архитектура**: + - `src/audio/` - новый модуль (player, cache, state) + - `AudioPlayer` - управление воспроизведением (play, pause, stop, seek, volume) + - `VoiceCache` - LRU кэш загруженных файлов (лимит 100 MB) + - `PlaybackState` - текущее состояние (status, position, duration, volume) + - Асинхронная загрузка в фоне (не блокирует UI) +- **UX фичи**: + - Progress bar в сообщении (▶ ████████░░░░░░ 0:08 / 0:15) + - Статусы: ▶ (playing), ⏸ (paused), ⏹ (stopped), ⏳ (loading) + - Хоткеи: Space (play/pause), s (stop), ←/→ (seek ±5s), ↑/↓ (volume) + - Waveform визуализация (опционально, из Telegram API) + - Автоматическая остановка при закрытии чата + - Индикатор загрузки с процентами +- **Конфигурация** (config.toml): + - enabled: bool - включить/отключить аудио + - default_volume: f32 - громкость (0.0 - 1.0) + - seek_step_seconds: i32 - шаг перемотки (5 сек) + - autoplay: bool - автовоспроизведение + - cache_size_mb: usize - размер кэша + - show_waveform: bool - показывать waveform + - system_player_fallback: bool - использовать системный плеер + - system_player: String - команда плеера (mpv, ffplay) +- **План реализации**: + - Этап 1: Инфраструктура аудио (модуль audio, AudioPlayer, VoiceCache) + - Этап 2: Интеграция с TDLib (VoiceNoteInfo, download_voice_note) + - Этап 3: UI для воспроизведения (progress bar, индикаторы, footer) + - Этап 4: Хоткеи для управления (play/pause, stop, seek, volume) + - Этап 5: Конфигурация и UX (AudioConfig, ticker для обновления) + - Этап 6: Обработка ошибок и fallback (системный плеер) + - Этап 7: Дополнительные улучшения (префетчинг, анимация) +- **Ожидаемый результат**: + - Голосовые воспроизводятся с визуальным индикатором прогресса + - Полный контроль: play, pause, stop, seek, volume + - Кэширование загруженных файлов + - Graceful fallback на системный плеер + - Кроссплатформенность (Linux, macOS, Windows) +- **Статус**: PLANNED (документация готова в ROADMAP.md) + **🐛 FIX: HashMap keybindings коллизии - дубликаты клавиш** - **Проблема #1**: `KeyCode::Enter` был привязан к 3 командам (OpenChat, SelectMessage, SubmitMessage) - **Проблема #2**: `KeyCode::Up` был привязан к 2 командам (MoveUp, EditMessage) diff --git a/HOTKEYS.md b/HOTKEYS.md index 83bd31d..1f640d3 100644 --- a/HOTKEYS.md +++ b/HOTKEYS.md @@ -57,6 +57,28 @@ **Примечание**: Изображения отображаются inline в чате автоматически. Используйте `v` для просмотра в полном размере. +## Прослушивание голосовых сообщений + +### Управление воспроизведением + +| Клавиша | Русская раскладка | Действие | +|---------|-------------------|----------| +| `Space` | | Воспроизвести/Пауза (в режиме выбора голосового) | +| `s` | `ы` | Остановить воспроизведение | + +### Во время воспроизведения + +| Клавиша | Действие | +|---------|----------| +| `Space` | Пауза / Возобновить | +| `s` / `ы` | Остановить | +| `←` | Перемотка назад (по умолчанию -5 сек) | +| `→` | Перемотка вперед (по умолчанию +5 сек) | +| `↑` | Увеличить громкость (+10%) | +| `↓` | Уменьшить громкость (-10%) | + +**Примечание**: Голосовые сообщения показывают progress bar во время воспроизведения: `▶ ████████░░░░░░ 0:08 / 0:15` + ## Модалки подтверждения ### Удаление сообщения @@ -118,6 +140,7 @@ - Копировать: `y` / `н` - Реакция: `e` / `у` - Просмотр изображения: `v` / `м` (если выбрано сообщение с фото) +- Воспроизведение голосового: `Space` (если выбрано голосовое сообщение) - Отменить: `Esc` ### Режим редактирования @@ -139,6 +162,12 @@ - Навигация: `←/→` (предыдущее/следующее изображение) - Закрыть: `Esc` +### Режим воспроизведения голосового +- Пауза/Возобновить: `Space` +- Остановить: `s` / `ы` +- Перемотка: `←/→` (-5с / +5с) +- Громкость: `↑/↓` (+/- 10%) + ## Поддержка русской раскладки Все основные vim-клавиши поддерживают русскую раскладку: @@ -155,6 +184,7 @@ | `y` | `н` | Copy (Yank) | | `e` | `у` | Emoji reaction | | `v` | `м` | View image | +| `s` | `ы` | Stop audio | ## Подсказки diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md index 0369425..8aaf2a3 100644 --- a/PROJECT_STRUCTURE.md +++ b/PROJECT_STRUCTURE.md @@ -23,6 +23,11 @@ tele-tui/ │ │ ├── mod.rs │ │ ├── auth.rs │ │ └── main_input.rs +│ ├── audio/ # Прослушивание голосовых (PLANNED) +│ │ ├── mod.rs # Экспорт публичных типов +│ │ ├── player.rs # AudioPlayer на rodio +│ │ ├── cache.rs # VoiceCache для OGG файлов +│ │ └── state.rs # PlaybackState │ ├── media/ # Работа с изображениями (PLANNED) │ │ ├── mod.rs # Экспорт публичных типов │ │ ├── image_cache.rs # LRU кэш для загруженных изображений @@ -108,6 +113,34 @@ tele-tui/ #### state.rs - `AppScreen` enum — текущий экран (Loading, Auth, Main) +### audio/ — Прослушивание голосовых сообщений (PLANNED - Фаза 12) + +#### player.rs +- `AudioPlayer` — управление воспроизведением голосовых сообщений +- Использует rodio для кроссплатформенного аудио +- API методы: play(), pause(), resume(), stop(), seek(), set_volume() +- Обработка OGG Opus файлов (формат голосовых в Telegram) +- Отдельный поток для воспроизведения (через rodio Sink) + +#### cache.rs +- `VoiceCache` — LRU кэш для загруженных голосовых файлов +- Хранение в ~/.cache/tele-tui/voice/ +- Лимит по размеру (MB) с автоматической очисткой +- MAX_VOICE_CACHE_SIZE = 100 MB (настраивается в config) +- Проверка существования файла перед воспроизведением + +#### state.rs +- `PlaybackState` — текущее состояние воспроизведения +- Поля: message_id, status, position, duration, volume +- `PlaybackStatus` enum — Stopped, Playing, Paused, Loading +- Ticker для обновления позиции (каждые 100ms) + +#### mod.rs +- Экспорт публичных типов +- `VoiceNoteInfo` struct — метаданные голосового (file_id, duration, waveform) +- `AudioConfig` — конфигурация из config.toml +- Fallback на системный плеер (mpv, ffplay) + ### media/ — Работа с изображениями (PLANNED - Фаза 11) #### image_cache.rs @@ -320,6 +353,11 @@ App { // Drafts drafts: HashMap, + // Audio (PLANNED - Фаза 12) + audio_player: Option, + playback_state: Option, + voice_cache: VoiceCache, + // Media (PLANNED - Фаза 11) image_loader: ImageLoader, image_protocol: StatefulProtocol, // Terminal capabilities @@ -351,6 +389,9 @@ App { - `crossterm` 0.28 — terminal control - `ratatui-image` 1.0 — отображение изображений в TUI (PLANNED) +### Audio (PLANNED) +- `rodio` 0.17 — Pure Rust аудио библиотека (кроссплатформенная) + ### Media (PLANNED) - `image` — загрузка и обработка изображений - `ratatui-image` — рендеринг в ratatui с поддержкой Sixel/Kitty/iTerm2 diff --git a/ROADMAP.md b/ROADMAP.md index f3b3c0f..693b7fd 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -290,3 +290,138 @@ - `v` / `м` - открыть изображение в полном размере (режим выбора) - `←` / `→` - навигация между изображениями (в режиме просмотра) - `Esc` - закрыть полноэкранный просмотр + +## Фаза 12: Прослушивание голосовых сообщений [PLANNED] + +### Этап 1: Инфраструктура аудио [TODO] +- [ ] Модуль src/audio/ + - player.rs - AudioPlayer на rodio + - cache.rs - VoiceCache для загруженных файлов + - state.rs - PlaybackState (статус, позиция, громкость) +- [ ] Зависимости + - rodio 0.17 - Pure Rust аудио библиотека + - Feature flag "audio" в Cargo.toml +- [ ] AudioPlayer API + - play() - воспроизведение файла + - pause() / resume() - пауза/возобновление + - stop() - остановка + - seek() - перемотка + - set_volume() - регулировка громкости + - get_position() - текущая позиция +- [ ] VoiceCache + - Кэш загруженных OGG файлов в ~/.cache/tele-tui/voice/ + - LRU политика очистки + - MAX_VOICE_CACHE_SIZE = 100 MB + +### Этап 2: Интеграция с TDLib [TODO] +- [ ] Обработка MessageContentVoiceNote + - Добавить VoiceNoteInfo в MessageInfo + - Извлечение file_id, duration, mime_type, waveform + - Метка формата (OGG Opus обычно) +- [ ] Загрузка файлов + - Метод TdClient::download_voice_note(file_id) + - Асинхронная загрузка через downloadFile API + - Обработка состояний (pending/downloading/ready) +- [ ] Кэширование + - Сохранение путей к загруженным файлам + - Не перезагружать уже скачанные голосовые + - Проверка существования файла перед воспроизведением + +### Этап 3: UI для воспроизведения [TODO] +- [ ] Индикатор в сообщении + - Иконка 🎤 и длительность голосового + - Progress bar во время воспроизведения + - Статус: ▶ (playing), ⏸ (paused), ⏹ (stopped), ⏳ (loading) + - Текущее время / общая длительность (0:08 / 0:15) +- [ ] Модификация render_messages() + - render_voice_note() для голосовых сообщений + - render_progress_bar() для индикатора воспроизведения + - Hint "[Space] Воспроизвести" если не играет +- [ ] Footer с управлением + - Отображение доступных команд при воспроизведении + - "[Space] Play/Pause [s] Stop [←/→] Seek [↑/↓] Volume" +- [ ] Waveform визуализация (опционально) + - Конвертация waveform данных из Telegram в ASCII bars + - Использование символов ▁▂▃▄▅▆▇█ для визуализации + +### Этап 4: Хоткеи для управления [TODO] +- [ ] Новые команды + - PlayVoice - Space в режиме выбора голосового + - PauseVoice - Space во время воспроизведения + - StopVoice - s / ы + - SeekBackward - ← (перемотка назад на 5 сек) + - SeekForward - → (перемотка вперед на 5 сек) + - VolumeUp - ↑ (увеличить на 10%) + - VolumeDown - ↓ (уменьшить на 10%) +- [ ] Контекстная обработка + - Space работает как play/pause в зависимости от состояния + - ← / → для seek только во время воспроизведения + - ↑ / ↓ для громкости только во время воспроизведения +- [ ] Поддержка русской раскладки + - s / ы - stop + - Остальные клавиши универсальны (Space, стрелки) + +### Этап 5: Конфигурация и UX [TODO] +- [ ] AudioConfig в config.toml + - enabled: bool - включить/отключить аудио + - default_volume: f32 - громкость по умолчанию (0.0 - 1.0) + - seek_step_seconds: i32 - шаг перемотки в секундах + - autoplay: bool - автовоспроизведение при выборе + - cache_size_mb: usize - размер кэша голосовых + - show_waveform: bool - показывать waveform визуализацию + - system_player_fallback: bool - использовать системный плеер + - system_player: String - команда системного плеера (mpv, ffplay) +- [ ] Асинхронная загрузка + - Не блокировать UI во время загрузки файла + - Индикатор загрузки с процентами + - Возможность отмены загрузки +- [ ] Обновление UI + - Ticker для обновления progress bar (каждые 100ms) + - Плавное обновление позиции воспроизведения + - Автоматическая остановка при достижении конца + +### Этап 6: Обработка ошибок [TODO] +- [ ] Graceful fallback на системный плеер + - Если rodio не работает - использовать mpv/ffplay + - Логирование ошибок через tracing + - Предупреждение пользователю если аудио недоступно +- [ ] Обработка ошибок загрузки + - Таймаут загрузки (30 сек) + - Повторная попытка по запросу + - Сообщение об ошибке в UI +- [ ] Ограничения + - Максимальный размер файла для кэша + - Автоматическая очистка старых файлов + - Предупреждение для очень длинных голосовых (>5 мин) + +### Этап 7: Дополнительные улучшения [TODO] +- [ ] Управление воспроизведением + - Автоматическая остановка при закрытии чата + - Сохранение позиции при паузе + - Автопереход к следующему голосовому (опционально) +- [ ] Оптимизация + - Lazy loading (загрузка только при воспроизведении) + - Префетчинг следующего голосового (опционально) + - Минимальная задержка при нажатии Play +- [ ] Визуальные улучшения + - Анимация progress bar + - Цветовая индикация статуса (зеленый - playing, желтый - paused) + - Иконки в зависимости от статуса + +### Технические детали +- **Аудио библиотека:** + - rodio 0.17 (Pure Rust, кроссплатформенная) + - Поддержка OGG Opus (формат голосовых в Telegram) + - Контроль воспроизведения через Sink API +- **Платформы:** + - Linux (ALSA, PulseAudio) + - macOS (CoreAudio) + - Windows (WASAPI) +- **Fallback:** + - mpv --no-video (универсальный плеер) + - ffplay -nodisp (из ffmpeg) +- **Новые хоткеи:** + - `Space` - воспроизвести/пауза (в режиме выбора голосового) + - `s` / `ы` - остановить воспроизведение + - `←` / `→` - перемотка -5с / +5с (во время воспроизведения) + - `↑` / `↓` - громкость +/- 10% (во время воспроизведения)