Audio source

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

Эта страница — про source_url: что туда можно положить и каким требованиям ссылка должна удовлетворять.

Что можно передать в source_url

source_url — это публичная http(s)-ссылка на аудио. Платформа сама скачивает/тянет источник и воспроизводит его в канале.

Трек

Прямая ссылка на аудиофайл (например https://cdn.example.com/track.mp3).

Плейлист

Ссылка на плейлист — последовательное воспроизведение треков.

HLS

Ссылка на HLS-манифест для потокового воспроизведения.

Icecast / поток

Ссылка на Icecast/онлайн-радио — live-поток в канал.

Файл может быть как статическим (трек), так и потоковым (HLS, Icecast) — платформа обрабатывает оба случая.

Требования к ссылке

source_url валидируется так же строго, как webhook-URL: разрешён только публичный http(s). Приватные и локальные адреса (localhost, 127.0.0.1, 10.0.0.0/8, 192.168.0.0/16, link-local и т. п.) отклоняются — это защита от SSRF.

• Схема — только http или https.
• Адрес — публично резолвимый. Приватные/локальные хосты и IP → ответ 400.
• Длина — у source_url есть лимит длины; слишком длинная ссылка → 400.

Бот не знает ничего о голосовом сервере и не передаёт никаких параметров подключения — только ссылку на контент.

Запуск воспроизведения

POST /api/bot/spaces/{space_id}/voice/{channel_id}/play

curl -X POST https://api.reasonspace.ru/api/bot/spaces/{space_id}/voice/{channel_id}/play \
  -H "Authorization: Bot bot_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://cdn.example.com/track.mp3",
    "loop": false,
    "volume": 100
  }'

await bot.client.voice_play(
    channel_id,
    "https://cdn.example.com/track.mp3",
    space_id=space_id,
    loop=False,
    volume=100,
)

{
  "session_id": "019c3851-...",
  "status": "playing"
}

Поле	Тип	По умолчанию	Описание
source_url	string	—	Публичная http(s)-ссылка на аудио (обязательно)
loop	bool	false	Зацикливать источник
volume	int	100	Громкость воспроизведения (0–100)

Требования: scope voice.publish_audio, channel_id ∈ allowed_channel_ids, бот в статусе active.

Зацикливание и громкость

• loop: true — источник проигрывается заново после окончания (удобно для ambient-петель и фоновой музыки).
• volume — уровень громкости от 0 до 100; значение по умолчанию 100.

await bot.client.voice_play(
    channel_id,
    "https://cdn.example.com/ambient-loop.mp3",
    space_id=space_id,
    loop=True,
    volume=60,
)

Остановка

POST /api/bot/spaces/{space_id}/voice/{channel_id}/stop → 204.

await bot.client.voice_stop(channel_id, space_id=space_id)

Отдельной «тишины» по таймеру реализовывать не нужно — платформа сама держит воспроизведение и останавливает его по stop либо по окончании источника (если loop=false).

Ошибки

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

Дальше

Voice playback

Как устроена односторонняя модель воспроизведения и приватность.

Presence

Как бот отображается в voice и почему не видит участников.

Voice API

Полный API reference voice-эндпоинтов.