HTTP API к Flussonic Media Server
Содержание:
- Аутентификация и авторизация
- Информация о сервере (server)
- Список потоков, их клиенты и состояние (media)
- Информация о потоке (media_info)
- Информация об исходном потоке (input_media_info)
- Проверка качества вещания потока (stream_health)
- Список открытых файлов (files)
- Список открытых сессий (sessions)
- Список открытых сессий для потока (sessions+stream_name)
- Обновить сессию (refresh_sessions)
- Закрыть сессию (close_sessions)
- Информация о состоянии плейлиста
- Карта записи архива за сутки (dvr_status)
- Удаление фрагмента DVR архива
- Список файлов VOD (list_files)
- Сохранить новый файл конфигурации (save_config)
- Обновить конфигурацию (update_config)
- Удалить поток (config/stream_delete)
- Создать или обновить поток (config/stream_create)
- Перечитать конфигурационный файл (reload)
- Перезапустить поток (stream_restart)
- Переключить источник у потока (stream_switch_source)
- Включить запись архива (dvr_enable)
- Выключить запись архива (dvr_disable)
- Серверы в кластере (cluster_servers)
- Использование устаревших команд
Аутентификация и авторизация
Flussonic Media Server предоставляет возможность получать информацию и управлять определенной функциональностью по HTTP.
Запросы на получение информации можно защитить с помощью директивы view_auth user password; в конфигурационном файле.
Запросы на модификацию состояния Flussonic Media Server можно защитить с помощью директивы edit_auth user password; в конфигурационном файле /etc/flussonic/flussonic.conf.
При включеной авторизации для доступа к HTTP API необходимо указывать логин и пароль в формате HTTP Basic Auth.
Информация о сервере (server)
Информация о сервере Flussonic Media Server.
URL: /flussonic/api/server
Пример: http://example.flussonic.com:80/flussonic/api/server
Параметры: нет
Ответ: JSON вида
{
"total_clients": 0, // Total clients number
"input_kbit": 947, // Current inbound speed
"dvr": true,
"partitions": [],
"version": "21.01", // Flussonic server version
"hostname": "flussonic1", // hostname
"vsaas_running": false,
"event": "server.info",
"build": 1,
"config2": true,
"total_streams": 2, // Total streams number
"status": [],
"rtmp": 1935,
"transcoder": true,
"auth_token": "me",
"rproxy_running": false,
"output_kbit": 510, // Current outbound speed
"online_streams": 2, // Total active streams number
"rproxy": false,
"ad_injector": true,
"retroview_enabled": false,
"rtsp": 554,
"transcoder_devices": [
{
"id": 0,
"name": "CPU Encoder",
"type": "cpu"
}
],
"ssl_certificates": {
"cacert": "...",
"cert": "...",
"key": "..."
},
"net": [],
"uptime": 12078, // Current Flussonic uptime in seconds
"ffmpeg": true,
"license_type": "online",
"cpu_usage": 5,
"scheduler_load": 0,
"retroview_configured": true,
"transcoder_defaults": {
"abitrate": 64,
"acodec": "aac",
"background": "#000000",
"deinterlace": false,
"deinterlace_rate": "frame",
"external": true,
"fps": "any",
"hw": "cpu",
"level": "3.1",
"preset": "veryfast",
"profile": "main",
"rc_lookahead": 10,
"strategy": "fit",
"vbitrate": 700,
"vcodec": "h264"
},
"started_at": 1610373808,
"iptv_running": false,
"streamer_status": "running",
"opened_files": 1,
"vsaas": true,
"http": 80,
"memory_usage": 26,
"id": "...",
"license_txt": "...",
"capabilities": {
"url_publish": true
},
"disks": [
"loop0",
"sda"
],
"iptv": true,
"vsaas_branding": true
}
Список потоков, их клиенты и состояние (media)
Состояние и настройки потоков, количество клиентов.
Вы можете запросить все потоки или указать только несколько потоков через запятую.
Чтобы получить список всех потоков:
URL: /flussonic/api/media
Параметры: нет
Чтобы получить список только указанных потоков:
URL: /flussonic/api/media?name=STREAMNAME
URL: /flussonic/api/media?name=STREAMNAME1,STREAMNAME2
Параметры:
name=STREAMNAME — имя потока. Необязательный параметр
Ответ: JSON вида
[
{
"entry": "stream",
"value": {
"name": "bunny", //stream name
"urls": [
{
"value": "file://vod/bunny.mp4", //source URL
"options": [] //source switching options
}
],
"stats": {
"alive": true, //true if there are recent frames in the stream
"bitrate": 150, //bitrate
"bufferings": 0,
"bytes_in": 49302069,
"bytes_out": 59834,
"client_count": 0, //number of clients (viewers) of this stream
"dvr_enabled": false,
"id": "3350ced5-9865-46be-9e09-3c1f6ffe8c6b",
"input_error_rate": 0, //number of errors registered per second
"last_access_at": 1612950727672,
"last_dts": 1612950859494.6785,
"last_dts_at": 1612950859494,
"lifetime": 1815593.6784667969,
"media_info": { //stream content info
"title": "bunny",
"tracks": [
{
"bframes": 0,
"bitrate": 95, //bitrate
"codec": "h264", //codec
"content": "video", //content type: video
"fps": 24.0,
"gop_size": 46,
"height": 160, //image height
"lang": "eng",
"last_gop": 48,
"level": "3.0",
"pix_fmt": "yuv420p",
"pixel_height": 160,
"pixel_width": 240,
"profile": "Baseline",
"sar_height": 1,
"sar_width": 1,
"track_id": "v1", // track id
"width": 240 //image width
},
{
"bitrate": 55, //bitrate
"channels": 2, //codec
"codec": "aac",
"content": "audio", //content type:audio
"lang": "eng",
"sample_rate": 48000,
"track_id": "a1" //track id
}
]
},
"opened_at": 1612949043876,
"out_bandwidth": 0, //out bandwidth
"remote": false, //the stream is not repeated from another Flussonic
"retry_count": 0, //number of automatic retries
"running": true, //stream is being broadcased, does not necessarily mean there are frames in the stream
"source_id": "f17cc4c0-ef93-444d-b7f2-7d1e79d223bf",
"start_running_at": 1612949043876,
"ts_delay": 98, //milliseconds since the most recent frame in the stream
"url": "file://vod/bunny.mp4" //URL of current source
},
"options": { //stream configuration
"disabled": false,
"static": true,
"title": "bunny",
"add_audio_only": false,
"retry_limit": 10,
"clients_timeout": 60,
"source_timeout": 60,
"cmaf_enabled": false,
"dvr_locked_write": false,
"dvr_offline": false,
"dvr_protected": false,
"epg_enabled": false,
"groups": [],
"motion_detector_enabled": false,
"no_index": false,
"pulse_off": false,
"thumbnails_enabled": false,
"vision_enabled": false
}
}
}
]
Информация о потоке (media_info)
Информация о конкретном потоке: ширина, высота, описание дорожек.
URL: /flussonic/api/media_info/STREAM_NAME
Параметры:
- STREAM_NAME — имя потока. Обязательный параметр
Ответ: JSON вида
{
"title": "bunny",
"tracks": [ //list of tracks
{
"bframes": 0,
"bitrate": 95,
"codec": "h264", //codec is h264
"content": "video", //content type is video
"fps": 24.0,
"gop_size": 46,
"height": 160, //image height
"lang": "eng",
"last_gop": 48,
"level": "3.0",
"pix_fmt": "yuv420p",
"pixel_height": 160,
"pixel_width": 240,
"profile": "Baseline",
"sar_height": 1,
"sar_width": 1,
"track_id": "v1", //track id
"width": 240 //image width
},
{
"bitrate": 55,
"channels": 2,
"codec": "aac", //codec is AAC
"content": "audio", //content type is audio
"lang": "eng", //language is English
"sample_rate": 48000,
"track_id": "a1" //track id
}
]
}
Информацию о потоке могут получать и клиенты, авторизованные для просмотра этого потока:
curl http://192.168.2.3:80/ort/media_info.json
{"title":"ort","tracks":[{"bframes":0,"bitrate":95,"codec":"h264","content":"video","fps":24.0,"gop_size":46,"height":160,"lang":"eng","last_gop":48,"level":"3.0","pix_fmt":"yuv420p","pixel_height":160,"pixel_width":240,"profile":"Baseline","sar_height":1,"sar_width":1,"track_id":"v1","width":240},{"bitrate":55,"channels":2,"codec":"aac","content":"audio","lang":"eng","sample_rate":48000,"track_id":"a1"}]}
Информация об исходном потоке (input_media_info)
Информация об оригинальном входящем потоке до транскодирования.
URL: /flussonic/api/input_media_info/STREAM_NAME
Параметры:
- STREAM_NAME — имя потока. Обязательный параметр
Ответ: JSON вида
{
"title": "bunny",
"tracks": [ //list of tracks
{
"bframes": 0,
"bitrate": 95,
"codec": "h264", //codec is h264
"content": "video", //content type is video
"fps": 24.0,
"gop_size": 46,
"height": 160, //image height
"lang": "eng",
"last_gop": 48,
"level": "3.0",
"pix_fmt": "yuv420p",
"pixel_height": 160,
"pixel_width": 240,
"profile": "Baseline",
"sar_height": 1,
"sar_width": 1,
"track_id": "v1", //track id
"width": 240 //image width
},
{
"bitrate": 55,
"channels": 2,
"codec": "aac", //codec is AAC
"content": "audio", //content type is audio
"lang": "eng", //language is English
"sample_rate": 48000,
"track_id": "a1" //track id
}
]
}
Если поток не транскодируется, то в ответе будет ошибка:
{
"error": "no_transcoder"
}
Проверка качества вещания потока (stream_health)
HTTP status code сигнализирует о том, когда в последний раз в потоке были кадры.
URL: /flussonic/api/stream_health/STREAM_NAME
Параметры:
- STREAM_NAME — имя потока. Обязательный параметр
Ответ запроса:
- HTTP 200 — если поток по имени STREAM_NAME приходит и последний кадр на нём был относительно недавно (меньше секунды назад).
- HTTP 424 — eсли в потоке давно не было кадров.
URL пригоден для настройки monit, например:
check process flussonic
start program = "service flussonic start"
stop program = "service flussonic stop"
if failed host localhost port 80
protocol HTTP request "/flussonic/api/stream_health/cam0" then restart
if 5 restarts within 5 cycles then timeout
Список открытых файлов (files)
Список транслируемых файлов и количество клиентов, которые их просматривают.
URL: /flussonic/api/files
Параметры: нет
Ответ: JSON вида
{
"files": [ //list of files that are currently active
{
"name": "vod/tmp.mp4", //internal identifier with a prefix
"worker_count": 1, //number of reading streams
"client_count": 0, //number of clients (viewers)
"bytes_out": 52939901, //number of transmitted bytes
"prefix": "vod", //prefix of this file
"bytes_in": 52939901, //number of read bytes
"url": "/storage/tmp.mp4" //path on HDD or an external storage
}
],
"event": "file.list"
}
Список открытых сессий (sessions)
Список открытых сессий, т.е. соединений клиентов с сервером. Если клиент нажал на паузу в проигрывателе или отключено автоматическое проигрывание видео (autoplay), то через некоторое время сессия будет закрыта.
URL: /flussonic/api/sessions
Параметры: нет
Ответ: JSON вида
{
"event": "user.list",
"sessions": [
{
"bytes_sent": 13380547, //the number of transmitted bytes
"country": "NONE", //GeoIP location of a current user (viewer)
"created_at": 1611143059210, //session start time
"current_time": null,
"id": "f39e2657f8055d80b87b08bdcc9ee57d23584355-1611143059210", //unique session identifier
"ip": "192.168.100.13",
"name": "fake",
"proto": "hls",
"query_string": "",
"referer": "http://flussonic/fake/embed.html",
"stalled": false,
"token": null,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Cypress/6.2.0 Chrome/87.0.4280.67 Electron/11.0.3 Safari/537.36",
"user_id": null
}
]
}
Для того, что бы вывести список подключений только одного потока или файла, надо указать имя потока или файла в query string: /flussonic/api/sessions?name=vod/ir.mp4
Список открытых сессий для потока (sessions+stream_name)
Список сессий открытых к заданному потоку.
URL: /flussonic/api/sessions?name=STREAM_NAME
Параметры:
- STREAM_NAME — имя потока. Обязательный параметр
Ответ: JSON вида
{
"event": "user.list",
"name": "fake",
"sessions": [
{
"bytes_sent": 13380547, //the number of transmitted bytes
"country": "NONE", //GeoIP location of a current user (viewer)
"created_at": 1611143059210, //session start time
"current_time": null,
"duration": 270,
"id": "f39e2657f8055d80b87b08bdcc9ee57d23584355-1611143059210", //unique session identifier
"ip": "192.168.100.13",
"name": "fake",
"proto": "hls",
"query_string": "",
"referer": "http://flussonic/fake/embed.html",
"stalled": false,
"token": null,
"type":"hls",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Cypress/6.2.0 Chrome/87.0.4280.67 Electron/11.0.3 Safari/537.36",
"user_id": null
}
]
}
Обновить сессию (refresh_sessions)
Можно управлять интервалами времени, через которые происходит обращение к авторизационному бэкенду, если по какой-то причине вам необходимо делать это чаще, чем стандартная длительность сессии.
Mетод refresh_sessions сбросит таймер сессии, и Flussonic обращается к бэкенду, чтобы заново авторизовать медиа-клиента. Результат обращения применяется к текущей сессии без переподключения плеера.
Чтобы обновить несколько активных сессий, передайте список их идентификаторов в теле POST запроса.
{"sessions": [
"acd6bbe0fe0ee40ec7f02f1b8c55ca4dbc062b09",
"2fcca1f646dea56adb4bdceea20136a1cba614d2"
]
}
URL: /flussonic/api/refresh_sessions
Параметры:
- HTTP request payload — список идентификаторов сессий Обязательный параметр
Ответ код 200
Закрыть сессию (close_sessions)
Чтобы закрыть несколько активных сессий, необходимо передать список их идентификаторов в теле POST запроса.
{"sessions": [
"acd6bbe0fe0ee40ec7f02f1b8c55ca4dbc062b09",
"2fcca1f646dea56adb4bdceea20136a1cba614d2"
]
}
URL: /flussonic/api/close_sessions
Параметры:
- HTTP request payload — список идентификаторов сессий Обязательный параметр
Ответ код 200
Информация о состоянии плейлиста (playlist)
HTTP API позволяет запросить текущее состояние серверного плейлиста и получить JSON ответ с данными.
URL: /flussonic/api/playlist/STREAM_NAME
Пример: http://example.flussonic.com:80/flussonic/api/playlist/example_stream
Параметры:
- STREAM_NAME — имя потока. Обязательный параметр
Ответ: JSON вида
{
"current_entry": "cam2", //The currently played item
"current_type": "stream", //The type of the currently played item
"duration": 10000, //Duration of the current item, in milliseconds('null' stands for 'undefined')
"position": 426 //Currently played position inside the current item, in milliseconds
}
Карта записи архива за сутки (dvr_status)
Карта записи архива за определенные сутки, состоящая из сегментов и секунд.
URL: /flussonic/api/dvr_status/YEAR/MONTH/DAY/STREAM_NAME
Параметры:
-
STREAM_NAME — имя потока Обязательный параметр
-
YEAR — год Обязательный параметр
-
MONTH — месяц Обязательный параметр
-
DAY — день Обязательный параметр
Ответ: JSON вида
[
{
"timestamp": 1610696040, //timestamp of a block
"path": "2021/01/15/07/34/00.ts", //path of recording on hdd
"bitrate": 470,
"segments": [
{
"second": 16, //starting from this second after beginning of a block
"utc": 1610696056, //segment timestamp
"duration": 1000, //segment duration
"size": 58777, //size in bytes
"bitrate": 470
},
{
"second": 17,
"utc": 1610696057,
"duration": 1000,
"size": 58777,
"bitrate": 470,
"jpeg":6710
}
// ...
],
"jpeg":6710
} //,
// ...
]
Удаление фрагмента DVR архива
Этот вызов позволяет удалить часть архива принудительно. Если какие-то сегменты защищены от удаления (lock), они удаляются всё равно.
Вызов удаляет фрагменты архива как локального, так и расположенного в облачном хранилище. Если участок архива скопирован в удаленное хранилище (Amazon S3) с помощью copy=[REMOTE PATH], то он скачивается на Flussonic для удаления из него сегментов и затем копируется обратно.
URL: /flussonic/api/dvr/delete
Параметры POST запроса:
- stream — имя потока, часть архива которого необходимо удалить.
- from — время начала интервала, который необходимо удалить, в UTC.
- duration — длительность интервала, который необходимо удалить, в секундах.
Пример вызова:
curl -u USER:PASS --data '{"stream":"ort","from":1483971680,"duration":1000}' http://FLUSSONIC-IP/flussonic/api/dvr/delete
Список файлов VOD (list_files)
Список имеющихся файлов для определенного префикса и источника.
URL: /flussonic/api/list_files?prefix=VOD_LOCATION&path=VOD_ROOT&subpath=SUB_PATH_IN_VOD_ROOT&from=FirstName&limit=COUNT
Параметры:
-
VOD_LOCATION — префикс VOD. Обязательный параметр
Веб-интерфейс: Список префиксов отображается на главной странице в разделе Files (VOD).
Файл конфигурации:file vod {...};. -
VOD_ROOT — корень VOD. Обязательный параметр
Веб-интерфейс: Список источников (хранилищ) отображается на вкладке соответствующего префикса. Новый источник можно добавить в поле New Path.
Файл конфигурации: элементы pathfile vod { path priv };.
Может быть адресом swift-хранилища и начинаться сswift://. -
SUB_PATH_IN_VOD_ROOT — место внутри хранилища VOD_ROOT. Обязательный параметр
Для корня хранилища его значение/ -
FirstName — список файлов начиная с этого имени. Можно указать неполное имя файла. Необязательный параметр
Ответ запроса не будет включать сам файл FirstName. -
COUNT — максимальное количество файлов в запросе. Необязательный параметр
Если используется вместе с FirstName, ответ будет включать COUNT файлов
начиная FirstName (не включая сам FirstName).
Ответ: JSON вида
{
"files": [ //list of files
{
"name": "autombr1.mp4", //file name
"type": "file", //type of the file ("file" or "directory")
"prefix": "vod" //prefix
},
{
"name": "autombr2.mp4","type": "file","prefix": "vod"
},
{
"name": "autombr3.mp4","type": "file","prefix": "vod"
}
]
}
Сохранить новый файл конфигурации (save_config)
Для обновления конфигурации необходимо передать текст нового файла конфигурации в качестве тела POST запроса.
Важное отличие от update_config в том, что новая конфигурация не только применяется к запущенному серверу, но и заменяет собой существующий файл конфигурации в /etc/flussonic/flussonic.conf.
URL: /flussonic/api/save_config
Параметры:
- HTTP request payload — текст нового файла конфигурации.
Обязательный параметр
В этом запросе вы передаете полный текст нового файла конфигурации как данные, приложенные к запросу.
Если использовать curl, то имеется в виду параметр --data-binary:
curl ... --data-binary '# Global settings:\nhttp 80;\nrtsp 554;\nrtmp 1935;\npulsedb /var/run/flussonic;'
Ответ: true в случае успешной обработки запроса.
Обновить конфигурацию (update_config)
Для обновления конфигурации необходимо передать текст нового файла конфигурации в качестве тела POST запроса.
Важное отличие от save_config в том, что новая конфигурация применяется к запущенному серверу, но сам файл конфигурации на жестком диске не изменяется.
URL: /flussonic/api/update_config
Параметры:
- HTTP request payload — текст нового файла конфигурации.
Обязательный параметр
В этом запросе вы передаете полный текст нового файла конфигурации как данные, приложенные к запросу.
Если использовать curl, то имеется в виду параметр --data-binary:
curl ... --data-binary '# Global settings:\nhttp 80;\nrtsp 554;\nrtmp 1935;\npulsedb /var/run/flussonic;'
Ответ: true в случае успешной обработки запроса.
Удалить поток (config/stream_delete)
Для удаления потока неободимо передать его имя в качестве тела POST запроса.
URL: /flussonic/api/config/stream_delete
Параметры:
- HTTP request payload — название потока.
Обязательный параметр
В этом запросе вы передаете название потока как данные, приложенные к запросу.
Если использовать curl, то имеется в виду параметр --data-binary:
curl ... --data-binary 'mystream'
Ответ: {"success":true} в случае успешной обработки запроса.
Создать или обновить поток (config/stream_create)
Для обновления конфигурации потока необходимо передать текст с настройками потока в качестве тела POST запроса.
На вход передается в точности тот же текст, который пишется в файле конфигурации для создания потока.
Важно: в данный момент не существует отдельной команды config/stream_update, поэтому уже созданный поток можно обновлять с помощью запроса config/stream_create.
URL: /flussonic/api/config/stream_create
Параметры:
- HTTP request payload — текст с конфигурацией потока.
Обязательный параметр
В этом запросе вы передаете конфигурацию потока как данные, приложенные к запросу.
Если использовать curl, то имеется в виду параметр --data-binary:
curl ... --data-binary 'stream mystream { url hls://myvideo.com/mystream; dvr /storage 1d 1G; }'
Ответ: {"success":true} в случае успешной обработки запроса.
Перечитать конфигурационный файл (reload)
Этот запрос необходимо выполнить для применения новой конфигурации к работающему серверу, если были внесены изменения в конфигурационный файл на диске /etc/flussonic/flussonic.conf.
URL: /flussonic/api/reload
Параметры: нет
Ответ: true в случае успешной обработки запроса.
Пример использования curl:
curl -u admin:pass0 http://flussonic:80/flussonic/api/reload
Перезапустить поток (stream_restart)
Полностью перезапускается один поток. Может помочь в случае проблем с источником.
URL: /flussonic/api/stream_restart/STREAM_NAME
Параметры:
- STREAM_NAME — идентификатор потока.
Обязательный параметр
Ответ: true в случае успешной обработки запроса.
Переключить источник у потока (stream_switch_source)
Поток переключается на использование источника, заданного параметром.
URL: /flussonic/api/stream_switch_source/STREAM_NAME?url=SOURCE_URL
Параметры:
-
STREAM_NAME — идентификатор потока.
Обязательный параметр -
SOURCE_URL — URL источника, на который надо переключиться. Должен быть указан в конфигурации потока.
Обязательный параметр
Включить запись архива (dvr_enable)
В настройках потока обязательно должна быть опция dvr или dvr_offline.
URL: /flussonic/api/dvr_enable/STREAM_NAME
Параметры:
- STREAM_NAME — идентификатор потока.
Обязательный параметр
Ответ: true в случае успешной обработки запроса.
Выключить запись архива (dvr_disable)
URL: /flussonic/api/dvr_disable/STREAM_NAME
Параметры:
- STREAM_NAME — идентификатор потока.
Обязательный параметр
Ответ: true в случае успешной обработки запроса.
Серверы в кластере (cluster_servers)
URL: /flussonic/api/cluster_servers
Параметры: нет
Ответ: JSON вида
{
"streamer": { //streamer name
"client_count": 0, //current count of clients
"config2": true,
"cpu_usage": 1, //CPU usage value in percentage
"fetch_delay": 1,
"id": "d31151a0-3208-486c-8c30-e72288127009",
"input_bitrate": 668,
"is_peer": true,
"is_source": false,
"key": "abcd", //cluster key
"memory_usage": 44, //memory usage value in percentage
"output_bitrate": 242, //output bitrate
"persistent": true,
"ports": { //list of streaming ports
"http": 8081,
"rtmp": 1936
},
"stream_count": 0, //current count of active streams
"uptime": 2682, //uptime in seconds
"version": "21.01" //verson of Flussonic
}
}
Использование устаревших API команд
Caution
Чтобы использовать устаревшие команды, такие как 'get_config', 'config/stream_list', включите переменную окружения FLUSSONIC_OLD_CONFIG:
- Отредактируйте unit файл сервиса Flussonic (
/lib/systemd/system/flussonic.service). Следует делать это, используя systemd override:
# systemctl edit flussonic
Эта команда откроет текстовый редактор (обычно `nano`).
- Добавьте строки:
[Service]
Environment=FLUSSONIC_OLD_CONFIG=true
Нажмите `Сtrl-X`, затем `Y`, чтобы сохранить и выйти.
- Перезапустите Flussonic:
# service flussonic restart