Skip to content

HTTP API к Flussonic Media Server

Содержание:

Аутентификация и авторизация

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.
    Файл конфигурации: элементы path file 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:

  1. Отредактируйте unit файл сервиса Flussonic (/lib/systemd/system/flussonic.service). Следует делать это, используя systemd override:
# systemctl edit flussonic
Эта команда откроет текстовый редактор (обычно `nano`).
  1. Добавьте строки:
[Service]
Environment=FLUSSONIC_OLD_CONFIG=true
Нажмите `Сtrl-X`, затем `Y`, чтобы сохранить и выйти.
  1. Перезапустите Flussonic:
# service flussonic restart