Создание, редактирование, запуск и удаление SRT сервера/шлюза с помощью Callaba Cloud API

В этом руководстве мы подробно рассмотрим REST методы, обеспечивающие стриминг по протоколу SRT.

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

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

SRT Gateway — это простой шлюз, который умеет принимать ваши SRT потоки. Например, для последующего рестрима в соц.сети или записи на сервере.

SRT Server — сервер, который способен маршрутизировать, перенаправлять, а также отдавать потоки нескольким клиентам одновременно.

Технология SRT реализована в Callaba Cloud в двух этих режимах : SRT Gateway и SRT Server.

UDP — протокол транспортного уровня, который использует SRT. Нам понадобится знать только то, что мы будем занимать или освобождать UDP порты в системе.

Restful API — набор методов или ручек, которые вы будете дергать, чтобы добиться желаемого результата. Например, /start запустит SRT сервер, а /stop — остановит и т.д.

Swagger — графический инструмент, позволяющий выполнять запросы в API.

JWT Token — токен авторизации в API, позволяет получить доступ к методам. По умолчанию все методы защищены от публичного использования и недоступны извне без авторизации, за исключением некоторых методов, предоставляющих метаданные.

API Queue — очередь выполнения заданий. Все действия в API выполняются через механизм очереди и сначала попадают в API Queue. Этот инструмент также доступен в общем API и позволяет добавлять и контролировать ваши собственные задания, независимо от работы стриминговых модулей.

Теперь, когда мы познакомились с основными понятиями мы можем приступить к интеграцию SRT протокола в наше приложение.

Создание SRT сервера/шлюза

Нам понадобятся :

  1. Активный инстанс с Callaba Cloud. Если вы впервые сталкиваетесь с AWS, зарегистрироваться можно здесь (займет не больше 5 минут) https://aws.amazon.com/marketplace/pp/prodview-npubds4oydmku
  2. Тестовое видео, чтобы убедиться, что мы отправили и получили поток на сервер
  3. Программа, через которую будет отправляться это тестовое видео. Мы будем использовать замечательный FFmpeg, поэтому, если у вас нет его на компьютере, вы можете скачать и установить его здесь (https://ffmpeg.org/download.html)

Кажется, теперь всё готово и можно приступать. Поехали!

Откройте дашборд Callaba Cloud (если вы сталкиваетесь с этим впервые, есть пошаговая инструкция, как запустить Callaba Cloud).

Перейдите в раздел API Docs

Теперь необходимо авторизоваться в Swagger.

Авторизация в Swagger

1. Выполните метод /auth/login расположенный самым первым. Если вы используете AWS Используйте ID вашего инстанса, в качестве пароля.

2. Скопируйте токен в буфер обмена

3. Затем в правом верхнем углу Swagger нажмите Authorize

4. В появившемся окошке вставьте токен и нажмите Authorize

Теперь всё готово к тому, чтобы создать первый SRT сервер или SRT Gateway.

Прокрутите вниз на странице Swagger до методов SRT-Servers:

Основные методы :

  1. /servers/create: Создание SRT сервера
  2. /servers/update: Редактирование SRT сервера
  3. /servers/remove: Удаление и остановка SRT сервера
  4. /servers/start: Запуск SRT сервера
  5. /servers/stop: Остановка SRT сервера
  6. /getAllByType: Получить список SRT серверов
  7. /getById: Получить конкретный SRT сервер по идентификатору

Теперь давайте рассмотрим детально работу с этими методами. Создадим наш первый сервер с помощью API и пустим в него поток.

Создание SRT сервера

1. В развернутой вкладе метода create найдите справа кнопку Try it out и нажмите на нее

2. Далее вы увидите, что Request body стал активен и содержит параметры запроса, все эти параметры — обязательные. На самом деле параметров гораздо больше, но в этом примере мы рассмотрим основные. Давайте разберемся что означает каждый из них:

Фрагмент кода

{
“server_name”: “Awesome SRT server”,
“server_type”: “SERVER_TYPE_SRT”,
“server_port”: 1935,
“server_latency”: 200,
“server_maxbw”: -1,
“server_timeout”: 60,
“server_rcvbuf”: 48234496,
“server_active”: true
}

Server_name — имя сервера. Значение должно быть уникальным, можно использовать только латинские буквы и цифры. Используйте его в своих приложениях, для унифицированных человекопонятных метаданных.

Server_type — тип создаваемого SRT сервера. Используйте SERVER_TYPE_SRT в качестве передаваемой строковой константы, если вам необходимо поднять SRT Server или Gateway. Другие типы SRT будут рассмотрены в других примерах.

Server_port — SRT использует протокол UDP в качестве транспорта, поэтому указывайте порт, который будет занимать ваш сервер для UDP. Несмотря на то, что UDP и TCP используют независимое управление, старайтесь избегать дублирования и использования одних и тех же портов. Если же вы всё-таки используете для SRT и RTMP одни и те же номера портов, то тщательно тестируйте поведение.

Server_latency — Задержка SRT. Мы рекомендуем устанавливать задержку с RTT * 4 или по меньшей мере в 2.5 раза, но не меньше 120 мс. (RTT — round-trip time)

Если у вас нет данных о вашей сети, воспользуйтесь методом получения метаданных /utils/speedtest из этого API :

curl -X ‘POST’ http://PUBLIC-IP-v4:3021/utils/speedtest

Результатом выполнения этого запроса будет json содержащий поле latency. Это и есть RTT.

Server_maxbw — Максимальная пропускная способность сети. Указывается значение в байтах. Здесь вы должны учесть все участки сети, от вашего компьютера до роутера, от вашего роутера до AWS инстанса. Указывайте максимально допустимое значение в байтах. Или используйте значение upload из /utils/speedtest .

Однако помните, что этот метод предоставляет информацию пропускной способности AWS инстанса и не учитывает возможные ограничения например вашего роутера. Используйте минимальное значение.

ВАЖНО! Если вы не укажете это значение, существует вероятность, что канал рано или поздно забьется попытками восстановления пакетов, поэтому рассмотрите возможность использования усредненного значения, учитывающее большинство ваших пользователей. Обязательно тестируйте это с различными квотами на канал.

Server_timeout — Таймаут ожидания потока в секундах. По истечению времени, в случае отсутствия данных, соединение будет считаться сброшенным.

Server_rcvbuf — Буфер приемника сервера. Для передачи видео в 4k и больше мы рекомендуем значение в 48234496 байт. Для меньших потоков значение можно постепенно уменьшать до появления ошибок в сети. Для этого есть метод /utils/getStat и он возвращает сигналы диагностики сети.

Параметр буфер приемника является не менее важным, чем задержка, и в случае нехватки буфера позволяет диагностировать следующие ошибки:

  • Когда приложение на сервере недостаточно быстро считывает и высвобождает буфер приемника. Например, при записи на HDD не справляется диск, или процессор занят другими задачами. Рассмотрите возможность анализа характеристик и соответствующих реакций в вашей инстраструктуре
  • Когда декодер на сервере недостаточно быстро высвобождает и распаковывает фреймы. Рассмотрите возможность использования более мощных инстансев, если вы часто сталкиваетесь с появлением этих ошибок в журнале статистики /utils/getStat .

Теперь, когда мы рассмотрели каждый параметр, давайте выполним этот запрос и попробуем отправить и принять видео этого SRT сервера

curl -X ‘POST’ \ ‘http://localhost:3021/servers/create' \ -H ‘accept: application/json’ \ -H ‘x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxODE5MGJhZTA5ZmQ3N2ZjZTgwOWQxYSIsImlhdCI6MTYzNjI5NjIwMCwiZXhwIjoxNjM4ODg4MjAwfQ.JVePwlRf9GC5cneHy92eAnIl9KkhhjCvxS6Wk3o3q2g’ \ -H ‘Content-Type: application/json’ \ -d ‘{ “server_name”: “Awesome SRT server”, “server_type”: “SERVER_TYPE_SRT”, “server_port”: 1935, “server_latency”: 200, “server_maxbw”: -1, “server_timeout”: 60, “server_rcvbuf”: 48234496, “server_active”: true }’

Чтобы протестировать созданный нами SRT сервер, отправим на него поток видео с помощью ffmpeg.

Синтаксис формирования stream-id следующий:

srt://HOST:PORT?streamid={publisher | receiver}/{server_name_code}/{unique string}

{publisher | receiver} — используйте publisher, чтобы отправить поток, и receiver, чтобы получить стрим

{server_name_code} — этот параметр вернет вам сервер

{unique string} — используйте уникальную произвольную строку

ffmpeg -re -i “/Volumes/MY_MAC/1080.mp4” -c copy -f mpegts “srt://PUBLIC-IP-v4:1935?streamid=publisher/awesome-srt-server/srt-stream-01”

Далее давайте проверим воспроизведение потока, заменим в stream-id publisher на receiver

ffplay “srt://PUBLIC-IP-v4:1935?streamid=receiver/awesome-srt-server/srt-stream-01”

Итак мы создали SRT сервер с помощью REST, а также смогли отправить и принять видео с помощью ffmpeg. На этом основная часть туториала закончена, теперь посмотрим на некоторые другие методы, доступные в API.

Редактирование SRT сервера

/servers/update

Чтобы изменить параметры SRT сервера, используйте метод /servers/update. При выполнении этого метода, существующий сервер будет остановлен, а все подключенные к нему стримеры будут отключены, учитывайте это при разработке вашего приложения.

Удаление SRT сервера

/servers/remove

Используйте метод /servers/remove, чтобы остановить потоки и удалить сервер по идентификатору. Созданные дочерние процессы, такие как, рестрим или рекординг также будут удалены. Учитывайте это при разработке вашего приложения.

Получение данных сервера по идентификатору

/servers/getById

Используйте /servers/getById если вам необходимо получить информацию о созданном ранее SRT сервере.

Получение списка всех SRT серверов

/servers/getAllByType

Используйте /servers/getAllByType если вам необходимо получить список всех серверов.

Остановка SRT сервера

/servers/stop

Используйте /servers/stop чтобы остановить работу сервера. Метод отключает подключенные к нему потоки, затем освобождает выделенный им порт

Запуск SRT сервера

/servers/start

Используйте /servers/start чтобы начать работу сервера. Метод открывает сокет для подключения по SRT и выделяет соответствующий UDP порт.

На этом всё.
В этом вводном туториале мы рассмотрели основные методы работы с SRT в Callaba Streaming Engine.
Если у вас возникнут вопросы напишите нам ([email protected]), мы с радостью на них ответим.