HTTP API к Flussonic Media Server

Содержание:

• Аутентификация и авторизация
• Информация о сервере (server)
• Список потоков, их клиенты и состояние (media)
• Информация о потоке (media_info)
• Информация об исходном потоке (input_media_info)
• Проверка качества вещания потока (stream_health)
• Список открытых файлов (files)
• Список открытых сессий (sessions)
• Список открытых сессий для потока (sessions+stream_name)
• Закрыть сессию (session_close)
• Информация о состоянии плейлиста
• Карта записи архива за сутки (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:8080/flussonic/api/server

Параметры: нет

Ответ: JSON вида

{
    "version": "4.6.1", // версия сервера Flussonic Media Server.
    "hostname": "streamer.example.com", // hostname
    "uptime": 43373, // Время работы Flussonic в секундах.
    "total_clients": 1592, // Общее число клиентов.
    "total_streams": 100, // Общее количество потоков.
    "online_streams": 95, // Общее количество активных потоков.
    "input_kbit": 1234, // Текущая скорость входящего трафика.
    "output_kbit": 123456 // Текущая скорость исходящего трафика.
}

Список потоков, их клиенты и состояние (media)

Состояние и настройки потоков, количество клиентов.

Вы можете запросить все потоки или указать только несколько потоков через запятую.

Чтобы получить список всех потоков:

URL: /flussonic/api/media

Параметры:  нет

Чтобы получить список только указанных потоков:

URL: /flussonic/api/media?name=STREAMNAME

URL: /flussonic/api/media?name=STREAMNAME1,STREAMNAME2

Параметры:

• name=STREAMNAME — имя потока. Необязательный параметр

Ответ: JSON вида

[ //list of streams
    {
        "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": 142, //bitrate
                "bufferings": 0,
                "bytes_in": 6481692,
                "bytes_out": 0,
                "client_count": 0, //number of clients (viewers) of this stream
                "dvr_enabled": false,
                "input_error_rate": 0, //number of errors registered per second
                "last_access_at": 1594903274840,
                "last_dts": 1594903512484.3335,
                "last_dts_at": 1594903512487,
                "lifetime": 237617.33349609375,
                "media_info": { //stream content info
                    "title": "bunny",
                    "tracks": [
                        {
                            "bitrate": 86, //bitrate
                            "codec": "h264", //codec
                            "content": "video", //content type: video
                            "fps": 24.0,
                            "height": 160, //image height
                            "lang": "eng",
                            "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": 56, //bitrate
                            "channels": 2,
                            "codec": "aac", //codec
                            "content": "audio", //content type:audio
                            "lang": "eng",
                            "sample_rate": 48000,
                            "track_id": "a1" //track id
                        }
                    ]
                },
                "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
                "running_transcoder": false,
                "start_running_at": 1594903274840,
                "ts_delay": 656, //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,
                "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 вида

{
    "width":1024,   //Ширина изображения
    "height":576,   //Высота изображения
    "streams":[   //Список элементов, составляющих поток
        {
            "content":"video",   //Тип содержимого. Видео.
            "codec":"h264",   //Кодек h264
            "track_id":1   //Номер трека. Элементы отсортированы по нему.
        },
        {
            "content":"audio",   //Тип содержимого. Аудио.
            "codec":"aac",   //Кодек AAC
            "lang":"ukr",   //Язык. Украинский.
            "track_id":2   //Номер трека.
        },
        {
            "content":"audio",   //Тип содержимого. Аудио.
            "codec":"aac",   //Кодек AAC
            "lang":"rus",   //Язык. Русский.
            "track_id":3   //Номер трека.
        }
    ]
}

Информацию о потоке могут получать и клиенты, авторизованные для просмотра этого потока:

curl http://192.168.2.3:8080/ort/media_info.json

{"width":320,"height":240,"streams":[{"size":"320x240","content":"video","codec":"h264","bitrate":115,"track_id":1,"fps":25.0,"width":320,"height":240,"pixel_width":320,"pixel_height":240,"sar_width":1,"sar_height":1,"length_size":4,"profile":"Baseline","level":"2.1"},{"content":"audio","codec":"aac","bitrate":25,"track_id":2}]}

Информация об исходном потоке (input_media_info)

Информация об оригинальном входящем потоке до транскодирования.

URL: /flussonic/api/input_media_info/STREAM_NAME

Параметры: 

• STREAM_NAME — имя потока. Обязательный параметр

Ответ: JSON вида

{
    "height": 240,
    "streams": [
        {
            "codec": "h264",
            "content": "video",
            "fps": 25,
            "height": 240,
            "length_size": 4,
            "level": "2.1",
            "pixel_height": 240,
            "pixel_width": 320,
            "profile": "Baseline",
            "sar_height": 1,
            "sar_width": 1,
            "size": "320x240",
            "track_id": "v1",
            "width": 320
        },
        {
            "bitrate": 25,
            "codec": "aac",
            "content": "audio",
            "lang": "eng",
            "track_id": "a1"
        }
    ],
    "width": 320
}

Если поток не транскодируется, то в ответе будет ошибка:

{
    "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 = "/etc/init.d/flussonic start"
stop  program = "/etc/init.d/flussonic stop"
if failed host localhost port 8080
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":[   //Список транслируемых файлов
        {
            "name":"vod/ir.mp4",    //Внутренний идентификактор с префиксом
            "worker_count":1, //Сколько запущено потоков чтения этого файла
            "client_count":1,    //Количество клиентов, смотрящих поток
            "url":"priv/ir.mp4",    //Путь на диске или внешнем хранилище
            "bytes_out":1792522,    //Количество отданных данных
            "bytes_in":1792522,    //Количество считанных данных
            "prefix":"vod"    //Префикс, в который добавлен файл
        }
    ]
}

Список открытых сессий (sessions)

Список открытых сессий, т.е. соединений клиентов с сервером. Если клиент нажал на паузу в проигрывателе или отключено автоматическое проигрывание видео (autoplay), то через некоторое время сессия будет закрыта.

URL: /flussonic/api/sessions

Параметры:  нет

Ответ: JSON вида

{
    "sessions":[    //
        {
            "id":"3100c9414a8666450a47246520a921076f4738e5",
            //НЕуникальный идентификатор сессии
            "session_id":
            "3100c9414a8666450a47246520a921076f4738e5-1396588629135",
            //Уникальный идентификатор сессии
            "ip":"127.0.0.1",    //IP клиента
            "name":"vod/ir.mp4",    //Внутренний идентификактор с префиксом
            "created_at":1396588629135,    //Время старта сессии
            "duration":5109,    //Длительность сессии
            "type":"hds",    //Тип потока
            "bytes_sent":828010,    //Количество посланых по сети байт
            "country":"NONE",    //GeoIP location пользователя
        }
    ]
}

Для того, что бы вывести список подключений только одного потока или файла, надо указать имя потока

в query string: /flussonic/api/sessions?name=vod/ir.mp4

Список открытых сессий для потока (sessions+stream_name)

Список сессий открытых к заданному потоку.

URL: /flussonic/api/sessions?name=STREAM_NAME

Параметры: 

• STREAM_NAME — имя потока. Обязательный параметр

Ответ: JSON вида

{
    "name":"euro",    //Имя потока
    "sessions":[    //Список сессий
        {
            "id":"e927bf4dca1ea90622318d4b4a0a60ab650bc6d9",
            //НЕуникальный идентификатор сессии
            "session_id":
            "e927bf4dca1ea90622318d4b4a0a60ab650bc6d9-1396867792624",
            //Уникальный идентификатор сессии
            "ip":"127.0.0.1",    //IP клиента
            "name":"euro",    //Имя потока
            "created_at":1396867792624,    //Время старта сессии
            "duration":30614,    //Длительность сессии
            "type":"hls",    //Тип потока
            "bytes_sent":5712330,    //Количество посланных по сети байт
            "country":"NONE"    //GeoIP location пользователя
        }
    ]
}

Закрыть сессию (close_sessions)

Чтобы закрыть несколько активных сессий необходимо передать список их идентификаторов в теле POST запроса. Используйте \n в качестве разделителя.

URL: /flussonic/api/close_sessions

Параметры: 

• HTTP request payload — список идентификаторов сессий через \n Обязательный параметр

Ответ код 200

Информация о состоянии плейлиста (playlist)

HTTP API позволяет запросить текущее состояние серверного плейлиста и получить JSON ответ с данными.

URL: /flussonic/api/playlist/STREAM_NAME

Пример: http://example.flussonic.com:8080/flussonic/api/playlist/example_stream

Параметры: 

• STREAM_NAME — имя потока. Обязательный параметр

Ответ: JSON вида

{
    "current_entry":"vod/ir.mp4",   //Идентификатор текущего элемента в плейлисте
    "current_type":"file",   //Тип текущего элемента в плейлисте
    "duration":null,   //Длительность текущего элемента в миллисекундах (null - неизвестна)
    "position":5.22e4   //Позиция проигрывания внутри текущего элемента, в миллисекундах
}

Карта записи архива за сутки (dvr_status)

Карта записи архива за определенные сутки, состоящая из сегментов и секунд.

URL: /flussonic/api/dvr_status/YEAR/MONTH/DAY/STREAM_NAME

Параметры: 

• STREAM_NAME — имя потока Обязательный параметр
• YEAR — год Обязательный параметр
• MONTH — месяц Обязательный параметр
• DAY — день Обязательный параметр

Ответ: JSON вида

[   //Список блоков
    {
        "timestamp":1396864800,    //Таймстемп блока
        "path":"2014/04/07/10/00",    //Путь до записи на жестком диске
        "bitrate":2052,    //Битрейт
        "segments":[
            {
                "second":1,    //Начиная с этой секунды от начала блока
                "utc":1396864801,    //Таймстемп сегмента
                "duration":5357,    //Длина сегмента
                "size":1383868,    //Размер в байтах
                "bitrate":2066,    //Битрейт
                "jpeg":"2014/04/07/10/00/01.jpg"    //Скриншот сегмента
            },

            {"second":6,"utc":1396864806,"duration":7211,
            "size":1842964,"bitrate":2044,
            "jpeg":"2014/04/07/10/00/06.jpg"},

            {"second":13,"utc":1396864813,"duration":7109,
            "size":1739188,"bitrate":1957,
            "jpeg":"2014/04/07/10/00/13.jpg"}
        ]
    }
    {"timestamp":1396865400,"path":"2014/04/07/10/10","bitrate":1964,
    "segments":[ {"second":0,"utc":1396865400,"duration":7194,
    "size":1800664, "bitrate":2002,"jpeg":"2014/04/07/10/10/00.jpg"}]}
]

Удаление фрагмента 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":[   //Список файлов
        {
            "name":"0.fla",   //Название файла
            "type":"file",   //Тип (file или directory)
            "prefix":"vod"   //Префикс
        },
        {"name":"1.fla","type":"file","prefix":"vod"},
        {"name":"10.fla","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:8080/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-2": //Имя сервера в кластере
        {
            "client_count":0, //Текущее количество клиентов.
            "config2":true,
            "cpu_usage":1, //Использование процессора в процентах.
            "fetch_delay":0,
            "id":"91a25b1a-22f0-414b-858f-4abc727d0de2",
            "is_peer":true,
            "is_source":false,
            "key":"WzkF7f9VYndoH6G3VOVz6iSNlOh4h8CF", //Ключ кластера.
            "memory_usage":26, //Использование оперативной памяти в процентах.
            "output_bitrate":0, //Суммарный исходящий битрейт.
            "persistent":true,
            "ports":{ //Список используемых портов.
                "http":80,
                "rtmp":1935
                },
            "stream_count":0, //Текущее количество потоков.
            "uptime":251908, //Время с последнего перезапуска, в секундах.
            "version":"4.7.3" //Версия Flussonic Media Server.
        }
}

Использование устаревших API команд

Важно. Чтобы использовать устаревшие команды, такие как 'get_config', 'config/stream_list', включите переменную окружения FLUSSONIC_OLD_CONFIG:

1. Отредактируйте unit файл сервиса Flussonic (/lib/systemd/system/flussonic.service). Следует делать это, используя systemd override:

   # systemctl edit flussonic
   

   Эта команда откроет текстовый редактор (обычно nano).

2. Добавьте строки:

   [Service]
   Environment=FLUSSONIC_OLD_CONFIG=true
   

   Нажмите Сtrl-X, затем Y, чтобы сохранить и выйти.

3. Перезапустите Flussonic:

   # /etc/init.d/flussonic restart
   

   ---