Flussonic Media Server documentation

Содержание

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: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 вида

[ //Список транслируемых потоков
  {
    "entry": "stream",
    "value": {
      "name": "euro", //Название потока
      "urls": [ //Список всех источников
        {
          "value": "tshttp://192.168.1.2:6502", //URL источника
          "options": [ //Опции резервирования источника
            [
              "priority",
              "1"
            ],
            [
              "source_timeout",
              "30"
            ]
          ]
        }
      ],
      "stats": {
        "alive": true, //Отдавал ли поток кадры в последнее время
        "bitrate": 3690, //Битрейт
        "bufferings": 0,
        "client_count": 0, //Количество клиентов, смотрящих поток
        "dash": true, //Включен ли DASH
        "hds": true, //Включен ли HDS
        "hls": true, //Включен ли HLS
        "input_error_rate": 0, //количество регистрируемых ошибок в секунду
        "last_access_at": 1493279230436,
        "media_info": { //Информация о содержимом потока
          "height": 576, //Высота изображения
          "streams": [
            {
              "bitrate": 191, //Битрейт
              "codec": "mp2a", //Кодек
              "content": "audio", //Тип содержимого:аудио
              "lang": "eng", //Язык
              "track_id": "a1" //Номер трека
            },
            {
              "bitrate": 3256, //Битрейт
              "codec": "mp2v", //Кодек
              "content": "video", //Тип содержимого: видео
              "size": "1024x576", //Размеры изображения
              "track_id": "v1" //Номер трека
            }
          ],
          "width": 1024 //Ширина изображения
        },
        "out_bandwidth": 4002, //Скорость отдачи по сети
        "push_stats": { //Статистика копирования потока, количество байт
          "tshttp://container4:8080/static1/mpegts": 2000918592
        },
        "remote": false, //Зеркалирование потока с удаленного сервера
        "retry_count": 0, //Количество автоматических перезапусков
        "running": true, //Ведется вещание потока, не обязательно означает, что в потоке есть кадры
        "start_running_at": 1493279194382,
        "ts_delay": 113, //Миллисекунды с момента когда в потоке был кадр
        "url": "tshttp://192.168.1.2:6502" //URL текущего источника
      },
      "options": { //Информация о конфигурации потока
        "static": false, 
        "retry_limit": 10,
        "clients_timeout": 60,
        "source_timeout": 60,
        "pushes": [ 
          [
            "tshttp://container4:8080/static1/mpegts"
          ]
        ],
        "add_audio_only": false,
        "dash_off": false,
        "dvr_protected": false,
        "hds_off": false,
        "hls_off": false,
        "m4f_off": false,
        "m4s_off": false,
        "mpegts_off": false,
        "pulse_off": false,
        "rtmp_off": false,
        "rtsp_off": false,
        "webrtc_off": 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.
        }
}