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: 

Пример: http://example.flussonic.com:80/flussonic/api/server

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

Ответ: JSON вида

{
  "event": "server.info",
  "config2": true,
  "rproxy": false,
  "version": "21.06", // Flussonic server version
  "dvr": true,
  "status": [],
  "rtmp": 1935,
  "rtsp": 554,
  "net": {
    "eth0": {
      "addr": "95.216.207.88",
      "hwaddr": "96:00:00:8E:8C:01"
    }
  },
  "ssl_certificates": {
    "cacert": {
      "domains": [],
      "issuer_name": "MyCompany, LLC",
      "not_after": 1628801328,
      "not_before": 1597265328
    },
    "cert": {
      "domains": [
        "localhost",
        "streamer.local"
      ],
      "issuer_name": "MyCompany, LLC",
      "not_after": 1628801329,
      "not_before": 1597265329
    },
    "key": {
      "match_certificate": true
    }
  },
  "iptv": true,
  "vsaas": true,
  "partitions": [
    {
      "path": "root",
      "total_mb": 19098,
      "usage": 44
    },
    {
      "path": "_boot_efi",
      "total_mb": 60,
      "usage": 5
    }
  ],
  "transcoder_devices": [
    {
      "id": 0,
      "name": "CPU Encoder",
      "type": "cpu"
    }
  ],
  "disks": [
    "sda"
  ],
  "license_txt": "WXHMkf...",
  "transcoder": true,
  "opened_files": 0,
  "auth_token": "me",
  "memory_usage": 18,
  "total_clients": 0, // Total clients number
  "uptime": 159018, // Current Flussonic uptime in seconds
  "output_kbit": 0, // Current outbound speed
  "vsaas_branding": true,
  "capabilities": {
    "url_publish": true
  },
  "rproxy_running": false,
  "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"
  },
  "online_streams": 2, // Total active streams number
  "streamer_status": "running",
  "cpu_usage": 15,
  "ffmpeg": true,
  "hostname": "FLUSSONIC-IP", // Hostname
  "license_type": "online",
  "scheduler_load": 15,
  "build": 0,
  "iptv_running": false,
  "vsaas_running": false,
  "ad_injector": true,
  "started_at": 1623842922,
  "input_kbit": 870, // Current inbound speed
  "total_streams": 2, // Total streams number
  "http": 80,
  "id": "60b7c549-48c3-4f67-86c7-d7fd395a1b35"
}

Список потоков, их клиенты и состояние (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/example_stream/media_info.json
{"title":"example_stream","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 вида

{
  "items": [
    {
      "activated": false,
      "allowed": true,
      "bytes": 205,
      "close_reason": null,
      "closed_at": null,
      "connected": false,
      "counters": null,
      "country": "RU",
      "current_time": null,
      "duration": 786,
      "dvr": false,
      "id": "60f97b15-6f5c-4d70-a993-6bcdb8c4c02d",
      "ip": "95.179.127.54",
      "max_sessions": null,
      "name": "clock",
      "opened_at": 1626962709665,
      "parent_id": null,
      "pid": null,
      "priority": null,
      "proto": "hls",
      "query_string": "token=1626962709234824409",
      "referer": null,
      "soft_limitation": false,
      "source_id": "60f97514-e7a8-48c5-8efd-354d6b748150",
      "stalled": false,
      "started_at": null,
      "token": "1626962709234824409",
      "type": "play",
      "updated_at": 1626962709667,
      "user_agent": "curl/7.64.0",
      "user_id": null,
      "user_name": "clock"
    },
    {
      "activated": false,
      "allowed": true,
      "bytes": 210,
      "close_reason": null,
      "closed_at": null,
      "connected": false,
      "counters": null,
      "country": "RU",
      "current_time": null,
      "duration": 288,
      "dvr": true,
      "id": "60f97b16-c80b-4652-9c01-b81b89b6bb4f",
      "ip": "95.179.127.54",
      "max_sessions": null,
      "name": "clock",
      "opened_at": 1626962710164,
      "parent_id": null,
      "pid": null,
      "priority": null,
      "proto": "hls",
      "query_string": "token=1626962709234824409",
      "referer": null,
      "soft_limitation": false,
      "source_id": "60f97514-e7a8-48c5-8efd-354d6b748150",
      "stalled": false,
      "started_at": null,
      "token": "1626962709234824409",
      "type": "play",
      "updated_at": 1626962710166,
      "user_agent": "curl/7.64.0",
      "user_id": null,
      "user_name": "clock"
    }
  ]
}

Обновить сессию (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 -u admin:pass0 http://flussonic:80/flussonic/api/reload

Ответ: {"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,
        "fetch_delay": 1,
        "is_peer": true,
        "is_source": false,
        "key": "abcd", //cluster key
        "persistent": false,
        "ports": { //list of streaming ports
            "http": 8081
        },
        "output_bitrate": 242, //output bitrate
        "stream_count": 0, //current count of active streams
        "version": "21.01", //verson of Flussonic
        "uptime": 2682, //uptime in seconds
        "input_bitrate": 668,
        "memory_usage": 44, //memory usage value in percentage
        "cpu_usage": 1, //CPU usage value in percentage
        "id": "d31151a0-3208-486c-8c30-e72288127009"
    }
}

Использование устаревших 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

Загрузка программы передач (EPG)

Flussonic позволяет загрузить EPG-файлы через HTTP API.

URL: /flussonic/api/transponder/upload_xmltv/TRANSPONDER_NAME

Параметры POST запроса:

  • file — файл XMLTV для загрузки.
  • filename — загрузка файла под указанным именем (необязательный).

Пример вызова:

curl -u USER:PASS -F "file=@file1.xml" -F "file=@file2.xml;filename=upload_name2.xml" \
  http://FLUSSONIC-IP/flussonic/api/transponder/upload_xmltv/tp1

Информация о загрузке каждого файла сигнализируется событием transponder_upload_xmltv.

Flussonic:

  • Проверяет, что в качестве xmltv_url в транспондере указан существующий каталог.
  • Производит проверку принятых данных: каждый файл должен содержать EPG, иметь расширение .xml и валидное имя. Если файл повреждён или не соответствует требованиям, то выведется ошибка HTTP 400 и ни один из файлов не будет загружен.
  • Сохраняет файлы в xmltv_url каталог с добавлением SHA-1 к имени во избежание перезаписи. Так файл rtr.xml будет сохранён под именем rtr.HEX_HASHUM.xml.
  • Все файлы XMLTV из каталога xmltv_url перечитываются транспондером.

Информация об одной и той же телепередаче на канале может содержаться в нескольких файлах XMLTV.

По умолчанию Flussonic не удаляет файлы XMLTV, но Вы можете это настроить.
Для этого добавьте параметр keep_epg в конфигурационный файл транспондера в секцию eit и укажите его значение:

eit {
    xmltv_url xmltv_dir1;
    keep_epg 10h;
  }

Значение keep_epg задаёт отрезок времени, которое должно пройти после самой поздней по времени передачи в данном XMLTV файле. В примере выше keep_epg 10h он составляет 10 часов. По истечении этого времени файл подлежит удалению. Если файл не удалось распарсить или он пуст, то он не будет удалён. Сам процесс удаления производится 1 раз в 8 часов, т.е. файлы XMLTV сначала накапливаются, а потом всем скопом удаляются. Даже если файлы были скопированы в каталог в обход API, то они также могут быть удалены. На каждый удалённый файл отправляется событие transponder_deleted_xmltv.
Как только live_transponder получает новую программу передач от xmltv_loader, то отсылает событие transponder_upload_xmltv.

Ниже буду приведены некоторые описания ошибок, которые могут появиться на каком-либо этапе:

Код ответа HTTP Контекст Код ошибки Описание Пример ответа в формате JSON
- входной файл not_xml_ext файла имеет отличное от .xml расширение { "errors": { "filename1.txt": "not_xml_ext"} }
- входной файл unsafe_filename в имени файла содержится "/" { "errors": { "dir/filename2.xml": "unsafe_filename"} }
- входной файл invalid_xml не удалось распарсить xml из данного файла { "errors": { "filename3.xml": "invalid_xml" } }
- входной файл no_epg в файле отсутствует программа передач { "errors": { "filename4.xml": "no_epg" } }
404 конфигурация транспондера не определён Транспондер с данным именем не существует или у него не задан xmltv_url -
500 конфигурация транспондера remote вместо локальной директории в xmltv_url указан URL "remote"
500 конфигурация транспондера enotdir xmltv_url найден на диске, но не является каталогом "enotdir"

Если во время проверки одного файла будет несколько ошибок, то ответ в формате JSON будет выглядеть следующим образом:

{
  "errors": {
    "filename.txt": "not_xml_ext",
    "filename.txt": "invalid_xml"
  }
}

Caution

При хранении нескольких файлов XMLTV может возникнуть ситуация, в которой время передачи какого-либо телеканала в разных файлах XMLTV будет отличаться. В таком случае запись о передаче начавшейся позже не сохранится в таблице для present/following (текущей/следующей передач). Например, в одном файле хранится запись о длительности передачи с 9:00 до 10:00. В другом - этой же передачи, но с 9:30 до 10:30. Значит, запись во втором файле (с 9:30 до 10:30) не сохранится в таблице для present/following, поскольку в один момент времени может идти только одна передача. Однако во всех остальных таблицах записи будут сохранены.

Обновление версии Flussonic

Вы можете обновить версию Flussonic через HTTP API.
Для этого Вам необходимо:

1. Проверить возможность обновления. Для этого нужно посмотреть статус подсистемы обновлений.

URL: /flussonic/api/updater/status

Параметры: * USER — имя пользователя * PASS — пароль пользователя * FLUSSONIC:80 — имя хоста Flussonic и порт

Пример с использованием curl:

curl -s -u USER:PASS http://FLUSSONIC-IP:80/flussonic/api/updater/status |jq

Ответ:

{
  "available_to_update": true,
  "available_versions": [
    "21.03",
    "21.02",
......
  ],
  "installed_version": "20.03",
  "is_updating": false,
  "last_update_error": null,
  "launched_version": "21.04.1-37-geb802e2"
}

где:

  • available_to_update — возможно ли обновление. Может принимать следующие значения:
    • true — есть возможность обновления Flussonic. Обновление возможно только в этом случае.
    • falseFlussonic не может быть обновлён из-за каких-либо ошибок:
{
  "available_to_update": false,
  "error_codes": [
    "must_be_root"
  ],
  "error_descriptions": [
    "Don't have root rights"
  ]
}
  • available_versions — список доступных версий;
  • installed_version — установленная версия Flussonic (при перезапуске Flussonic отобразится именно эта версия);
  • launched_version — версия Flussonic, отвечающая в данный момент;
  • is_updating — выполняется ли в данный момент какой-либо блокирующий процесс. Может принимать следующие значения:
    • false — блокирующие процессы отсутствуют;
    • true — присутствуют блокирующие процессы;
  • last_update_error — текст ошибки, возникшей в последний раз при выполнении какого-либо действия (возвращает null после выполнения ещё одного действия).

2. Обновить индекс пакетов и список доступных версий (аналог apt update в терминале). Может занять от нескольких минут до нескольких десятков минут (в самом плохом случае). Результат выполнения можно посмотреть в статусе подсистемы обновлений (см. п.1 выше).

Параметры:

  • new_version — версия для установки

Пример с использованием curl:

curl -s --request POST -u USER:PASS http://FLUSSONIC-IP:80/flussonic/api/updater/update_available_versions |jq

Список возможных ошибок:

Ошибка Описание
not_available когда available_to_update принимает значение false: available_to_update: false
busy подсистема обновлений уже выполняет какой-то запрос
bad_api_request ошибка в запросе (например, не POST метод)

3. Запросить установку новой версии Flussonic (аналог apt install в терминале). Может занять от нескольких минут до нескольких десятков минут (в самом плохом случае). Результат также можно посмотреть в статусе подсистемы обновлений (см. п.1 выше).

Note

Только что установленная Вами версия не будет запущена автоматически!

curl -s --request POST -u USER:PASS http://FLUSSONIC:80/flussonic/api/updater/update --header 'Content-Type: application/json' --data-raw '{"new_version": "20.12"}' | jq

Параметры:

  • new_version — версия для установки (в нашем примере - это 20.12).

Ответ:

{
  "available_versions": [
    "21.04.1",
.......
  ],
  "installed_version": "20.03",
  "is_updating": true,
  "last_update_error": null,
  "launched_version": "21.04.1-37-geb802e2"
}

Список возможных ошибок:

Ошибка Описание
not_available когда available_to_update принимает значение false: available_to_update: false
busy подсистема обновлений уже выполняет какой-то запрос
bad_api_request ошибка в запросе (например, отсутствует поле new_version)
bad_version указанная версия отсутствует в списке доступных

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

Обновление версии продукта через HTTP API позволяет избежать конфликта зависимостей, т.к. система сама обновит все зависимые от Flussonic пакеты, необходимые для его корректной работы. Работает и в случае понижения версии продукта.

4.Перезапустите Flussonic, чтобы изменения вступили в силу:

curl -s --request POST -u a:p http://localhost:3011/flussonic/api/updater/restart

Для перезагрузки Flussonic необходимо выполнение следующих условий:

  1. статус is_updating принимает значение false: is_updating: false;
  2. версия установленная (installed_version) не равна версии запущенной (launched_version).

Иначе Flussonic не перезапустится.

Список возможных ошибок:

Ошибка Описание
not_available когда available_to_update принимает значение false: available_to_update: false или не выполнено одно из условий для перезагрузки (см. выше)
bad_api_request ошибка в запросе (например, не POST метод)

При выполнении метода будет запущено событие reboot_on_upgrade с полями launched_version и installed_version.

Теперь Вы знаете как обновить версию Flussonic через HTTP API.