docs: add Phase 12 - voice message playback

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 <noreply@anthropic.com>

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)

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 |
 
 ## Подсказки
 

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<i64, String>,
 
+  // Audio (PLANNED - Фаза 12)
+  audio_player: Option<AudioPlayer>,
+  playback_state: Option<PlaybackState>,
+  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

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% (во время воспроизведения)