API стриминга

Как воспроизводить станции RadioMV в вашем приложении, на сайте или в веб-сервисе и как показывать метаданные «сейчас в эфире». Всё на этой странице общедоступно — API-ключ и регистрация не требуются.

Быстрый старт

Замените {station} на идентификатор из списка станций, например:

Базовый URL и правила для хостов

Всегда начинайте с https://stream.radiomv.com. Он автоматически направляет каждого слушателя на ближайший сервер (гео-маршрутизация).

HTTPS или HTTP: везде, где возможно, используйте https://. Обычный http:// намеренно оставлен рабочим для аудио-эндпоинтов (.mp3, .m3u), чтобы встраиваемые и аппаратные плееры без поддержки TLS могли подключаться.

Станции

Основные станции

Круглосуточные программы и музыка.

Библейские станции

Непрерывное чтение Библии, круглосуточно.

С точки зрения интеграции библейские станции ведут себя точно так же, как основные — те же URL, те же плееры, тот же API метаданных (в заголовке — текущая книга и глава). Единственное отличие: в их HLS-мастер-плейлистах нет уровня качества ultra.

Вариант 1 — HLS (рекомендуется)

HLS — рекомендуемый способ воспроизведения RadioMV в любой современной среде: iOS, Android, браузеры, смарт-ТВ, VLC, ffmpeg. Качество адаптируется к скорости соединения слушателя автоматически.

Достаточно одного URL — мастер-плейлиста:

Передайте этот URL вашему плееру. Он сам обнаружит варианты качества, выберет подходящий и будет загружать аудиосегменты.

Уровни качества

Что мастер-плейлист объявляет сегодня:

У библейских станций нет уровня ultra. Сегменты — 6-секундные fMP4/CMAF (.m4s).

Встраивание на сайт (hls.js + Safari)

Safari воспроизводит HLS нативно; остальным браузерам нужен hls.js:

<audio id="player" controls></audio>
<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
<script>
    const url = "https://stream.radiomv.com/stream/slavic.m3u8";
    const audio = document.getElementById("player");
    if (audio.canPlayType("application/vnd.apple.mpegurl")) {
        audio.src = url;                    // Safari / iOS
    } else if (Hls.isSupported()) {
        const hls = new Hls();
        hls.loadSource(url);
        hls.attachMedia(audio);
    }
</script>

CORS открыт (Access-Control-Allow-Origin: *) на всех эндпоинтах стриминга и метаданных, поэтому это работает с любого веб-домена.

Вариант 2 — MP3 (простые плееры и «железо»)

Один поток MP3 с фиксированным качеством 128 кбит/с, совместимый с Icecast/SHOUTcast. Работает со всем, что умеет воспроизводить MP3 по URL: теги <audio>, VLC, Winamp, интернет-радиоприёмники, микроконтроллеры.

Рекомендуемая схема — сначала разрешить адрес, потом играть:

1. Загрузите плейлист:
   GET /stream/{station}.m3u
2. Тело ответа — одна строка: прямой URL MP3-потока на сервере, назначенном этому слушателю.
3. Подключите плеер к этому URL.
4. При каждом переподключении или новом сеансе воспроизведения сначала заново загружайте .m3u. Никогда не сохраняйте полученный URL — он указывает на один конкретный сервер, и сохранённый адрес перестанет работать, если этот сервер будет заменён. Устройства, которые запрашивают адрес заново, восстанавливаются сами; устройства, закэшировавшие конечный URL, — это те самые, что «вечно подключаются».

Прямой URL (тоже поддерживается — например, для обычного тега <audio>, где схема с плейлистом непрактична):

Метаданные ICY (SHOUTcast)

Если клиент отправляет заголовок Icy-MetaData: 1, поток будет содержать названия текущих треков в стандартном формате ICY. В ответе присутствуют:

icy-name: English
icy-br: 128
icy-metaint: 16000

icy-metaint — интервал в байтах между блоками метаданных. Если не отправлять Icy-MetaData: 1, вы получите чистый MP3-поток без встроенных метаданных — тогда используйте JSON API метаданных.

Метаданные «сейчас в эфире»

JSON, без авторизации, CORS открыт. Для библейских станций в заголовке — текущая книга и глава; для основных — текущий трек или программа.

Массив — что в эфире на всех станциях.

Объект — что в эфире на одной станции:

{
    "station": "english",
    "name": "English",
    "title": "The Righteous Requirement of the Law | Clip 1 | Derek Prince",
    "artist": "J Scott Rakozy",
    "updated_at": 1787445124
}

updated_at — Unix-время в секундах. artist может быть пустым. Неизвестные дополнительные поля считайте совместимыми расширениями формата.

Поток Server-Sent Events — держит соединение открытым и отправляет каждое изменение строкой data: с тем же JSON:

const es = new EventSource("https://stream.radiomv.com/api/metadata/slavic/events");
es.onmessage = (e) => {
    const now = JSON.parse(e.data);
    document.getElementById("title").textContent = now.title;
};

Проверка из командной строки

# Что сейчас в эфире
curl -s https://stream.radiomv.com/api/metadata/slavic

# Живой поток метаданных (Ctrl-C для выхода)
curl -N https://stream.radiomv.com/api/metadata/slavic/events

# HLS мастер-плейлист
curl -s https://stream.radiomv.com/stream/slavic.m3u8

# Воспроизведение в VLC / ffplay / mpv
vlc https://stream.radiomv.com/stream/slavic.m3u8
ffplay -nodisp https://stream.radiomv.com/stream/slavic.m3u8

# MP3: получить плейлист, затем проверить поток по адресу из него
curl -s http://stream.radiomv.com/stream/slavic.m3u

Идентифицируйте своё приложение (User-Agent)

Пожалуйста, отправляйте User-Agent, который называет ваше приложение или сервис, а не стандартное значение вашей HTTP-библиотеки. Так мы узнаём вашу интеграцию в аналитике слушателей, замечаем, когда очередной ваш релиз меняет поведение, и можем связаться с вами до того, как внесём изменение, которое вас затронет.

Желаемый формат (стандартный формат HTTP User-Agent):

User-Agent: YourApp/2.1 (Android 14; https://yourapp.example)

• Сначала токен продукта (YourApp/версия). Держите имя неизменным между релизами — меняйте только версию. Именно стабильный токен позволяет нам считать ваших слушателей вашими.
• В скобках: платформа и URL или email, по которому с вами можно связаться.
• Не оставляйте значение библиотеки по умолчанию (okhttp/4.12.0, Dalvik/…, curl/8.x, Lavf/…). Обезличенные библиотечные агенты неотличимы от трафика скрейперов и ботов — а именно его проверяют в первую очередь при расследовании злоупотреблений.

Формат ни на что не влияет технически — отсутствующий или обезличенный User-Agent всё равно будет играть. Но идентифицируемый агент даёт вам лучшую поддержку и предупреждение об изменениях заранее.

Правила добрососедства

• Одно потоковое соединение на активного слушателя. Не держите потоки открытыми для тех, кто не слушает.
• Переподключайтесь с нарастающей задержкой. При ошибке потока повторите через ~2 с, затем увеличивайте (4 с, 8 с, … с потолком около 30 с). Шквал переподключений во время сетевого сбоя замедляет восстановление для всех.
• Заново разрешайте адрес при переподключении (MP3): загружайте .m3u снова, а не переиспользуйте прошлый URL потока. Для HLS это происходит само — просто перезагрузите URL мастер-плейлиста.
• Для метаданных используйте SSE, а не частый опрос.
• Идентифицируйте своё приложение в заголовке User-Agent (см. выше).
• Не проксируйте и не перепубликуйте потоки. Давайте пользователям прямые ссылки на URL выше — так для них продолжают работать гео-маршрутизация и адаптация качества.

Стабильность этого контракта

URL и форматы JSON, описанные на этой странице, — поддерживаемый публичный интерфейс. Всё, что вы обнаружите за пределами этой страницы (внутренние хосты, недокументированные пути, дополнительные поля), может измениться без предупреждения. Если эта страница расходится с наблюдаемым поведением — сообщите нам, и мы исправим то, что окажется неверным.