Voice playback

Reason Space Voice — это аудио-каналы внутри Space'ов. Бот может проигрывать аудио в таком канале: музыку, объявления, TTS-сообщения. Бот задаёт источник звука — платформа проигрывает его участникам канала.

Бот не слышит участников. Он только проигрывает аудио — поток односторонний.

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

Бот не подключается к голосовому каналу сам. Он не получает токен, не работает с медиа и не держит голосовую сессию. Бот лишь даёт платформе ссылку на источник аудио (source_url) — а платформа сама проигрывает его в канал.

flowchart LR
  Bot["Сервер бота"] -->|"POST /voice/{}/play (source_url)"| API[Reason Space API]
  API -->|проигрывает источник| Voice["Voice-канал"]
  Voice -->|звук| Users["Участники канала"]

Никакого «подключения к комнате», голосового клиента или обработки звука на стороне бота нет. Бот управляет проигрыванием двумя вызовами: play и stop.

Приватность — гарантирована архитектурой

Боты — это сторонний недоверенный код. Поэтому модель voice устроена так, чтобы бот физически не мог слышать участников канала.

У бота нет принимающей медиа-сессии. Поток аудио идёт только в одну сторону — от платформы к участникам. Бот не получает и не может получить звук из канала.

Это не договорённость и не настройка, которую можно ослабить, — это свойство самой архитектуры: принимать звук просто нечем.

Эндпоинт загруженности (GET …/voice) возвращает только число участников и факт присутствия бота — без идентификаций участников (user_id, display_name не раскрываются).

Подробнее: Privacy.

Поток воспроизведения

Запустить проигрывание (play)

POST /api/bot/spaces/{space_id}/voice/{channel_id}/play с телом { source_url, loop?, volume? }. Платформа начинает проигрывать источник в канал и возвращает { session_id, status }. Источник — публичная http(s)-ссылка на аудио (трек, плейлист, HLS, Icecast, файл). См. Audio source.

Остановить проигрывание (stop)

POST /api/bot/spaces/{space_id}/voice/{channel_id}/stop → 204. Проигрывание прекращается, бот перестаёт занимать канал.

При loop=false (по умолчанию) проигрывание завершается само по окончании источника. volume — громкость в процентах (по умолчанию 100).

Требования к боту

• Scope voice.publish_audio — для запуска проигрывания (play / stop).
• Scope voice.join — для просмотра загруженности каналов (GET …/voice).
• channel_id входит в allowed_channel_ids membership'а.
• Бот активен (active).
• Voice включён гейтом voice на сервере.

source_url

source_url — это публичная http(s)-ссылка на аудио. Платформа валидирует её так же, как webhook-URL (SSRF-защита) и применяет лимит длины. Приватные и локальные адреса отклоняются (400). Подробные требования и примеры источников — на странице Audio source.

Ошибки

Код	Когда
403	Нет нужного scope, либо voice выключен на сервере
400	Невалидный или небезопасный source_url (приватный/локальный адрес, превышение лимита длины)
501	Voice playback не сконфигурирован на сервере
429	Превышен rate-limit

Дальше

Audio source

Требования к source_url, поддерживаемые источники и форматы.

Voice API

Полный API reference: play, stop, загруженность каналов.