Skip to content

HTTP API to Flussonic Media Server

On this page:

Authentication and authorization

With Flussonic API you can retrieve data and manage certain Flussonic features over HTTP.

Requests for information can be protected by using the view_auth user password; directive in the configuration file /etc/flussonic/flussonic.conf.

Requests for modification of a state and settings can be protected by using the edit_auth user password; directive in the configuration file.

To access the HTTP API, with authentication active you need to use a login and password in HTTP Basic Auth format.

Server information (server)

Information about Flussonic server.

URL: /flussonic/api/server

Example: http://FLUSSONIC-IP:80/flussonic/api/server

Parameters: none

Response: JSON like


{
  "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"
}

The list of streams, their clients and state (media)

State and configuration of streams, number of clients.

You can request all streams or specify only some streams separated by comma.

To get the list of all streams:

URL: /flussonic/api/media

Parameters:  none

To get the list of specified streams only:

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

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

Parameters:

  • name=STREAMNAME — stream name. Optional parameter

Response: JSON like


[
    {
        "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
            }
        }
    }
]

Stream information (media_info)

Information about specific stream: width, height, tracks.

URL: /flussonic/api/media_info/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name (required).

Response: JSON like


{
    "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
        }
    ]
}

Clients authorized to watch a stream can request its info:


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"}]}

Information about the original stream (input_media_info)

Information about the original incoming stream before it is transcoded.

URL: /flussonic/api/input_media_info/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name (required).

Response: JSON like


{
    "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
        }
    ]
}

If no transcoding is performed then API responds with an error:


{
    "error": "no_transcoder"
}

Stream quality and stream health (stream_health)

The HTTP status code in the response indicates when recent frames were registered in the stream.

URL: /flussonic/api/stream_health/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name (required).

Response:

  • HTTP 200 — STREAM_NAME exists and the last frame in it is relatively recent (less than one second ago)
  • HTTP 424 — stream exists but there are no recent frames.

URL is useful for monit, for example:


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

The list of active files (files)

A list of currently active files and the number of clients that watch them.

URL: /flussonic/api/files

Parameters:  none

Response: JSON like


{
    "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"
}

The number of open sessions (sessions)

Number of open sessions, that is, connections between clients and server.
If client pauses playback or automatic video playback start (autoplay) is disabled, then after a while the session will be closed.

URL: /flussonic/api/sessions

Parameters:  none

Response: JSON like


{
    "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
        }
    ]
}

If you want to display a list of connections for a single stream or file, you may add a name of this stream or file to a query string: /flussonic/api/sessions?name=vod/ir.mp4

The list of open sessions for a specific stream (sessions+stream_name)

A list of sessions that are open for the specified stream.

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

Parameters: 

  • STREAM_NAME — stream name (required).

Response: JSON like


{
    "items": [
        {
            "activated": true,
            "allowed": true,
            "bytes": 1895229, //the number of transmitted bytes
            "close_reason": null,
            "closed_at": null,
            "connected": false,
            "counters": null,
            "country": "NONE", //GeoIP location of a current user (viewer)
            "current_time": null,
            "duration": 309303,
            "id": "608910c7-577d-4fc3-b812-17c20d9e0e82", // session identifier
            "identity": {
                "token": null,
                "name": "fake",
                "ip": "192.168.100.9",
                "proto": "hls"
            },
            "ip": "192.168.100.9",
            "max_sessions": null,
            "name": "fake",
            "opened_at": 1619595463437,
            "parent_id": null,
            "pid": null,
            "priority": null,
            "proto": "hls",
            "query_string": "",
            "ref": null,
            "referer": "http://flussonic/fake/embed.html",
            "soft_limitation": false,
            "source_id": "60890f54-1aed-497d-8dff-4ccf29d6bbb3",
            "stalled": false,
            "started_at": 1619595463520,
            "token": null,
            "type": "play",
            "updated_at": 1619595770406,
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_3) AppleWebKit/537.36 (KHTML, like Gecko) Cypress/6.5.0 Chrome/87.0.4280.141 Electron/11.2.3 Safari/537.36",
            "user_id": null,
            "user_name": "fake"
        }
    ]
}

Refreshing a session (refresh_sessions)

You can control the time intervals at which Flussonic accesses to the authorization backend if for some reason you need to access it more often than the standard session lasts.

The refresh_sessions method resets the session timer, and Flussonic contacts the backend to re-authorize the media client. The result of the call is applied to the current session without reconnecting the player.

To refresh a number of active sessions, you need to pass a list of their identifiers as POST request body.


{"sessions": [
    "acd6bbe0fe0ee40ec7f02f1b8c55ca4dbc062b09",
    "2fcca1f646dea56adb4bdceea20136a1cba614d2"
    ]
}

URL: /flussonic/api/refresh_sessions

Parameters: 

  • HTTP request payload — the list of session identifiers (required).

Response: code 200

Closing a session (close_sessions)

To close several active sessions, you need to pass a list of their identifiers as POST request body.


{"sessions": [
    "acd6bbe0fe0ee40ec7f02f1b8c55ca4dbc062b09",
    "2fcca1f646dea56adb4bdceea20136a1cba614d2"
    ]
}

URL: /flussonic/api/close_sessions

Parameters: 

  • HTTP request payload — list of session identifiers (required).

Response: code 200

Playlist status information

You can request information about the state of a server-side playlist of the specified stream.

URL: /flussonic/api/playlist/STREAM_NAME

Example: http://example.flussonic.com:80/flussonic/api/playlist/example_stream

Parameters: 

  • STREAM_NAME — the name of a stream that contains the playlist (required).

Response: JSON like


{
    "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
}

Recordings map (dvr_status)

DVR recording map for a particular day, consisting of segmengs and seconds.

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

Parameters: 

  • STREAM_NAME — stream name (required)

  • YEAR — year (required)

  • MONTH — month (required)

  • DAY — day (required)

Response: JSON like


[
    {
        "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
    } //,
    // ...
]

Deleting fragments of a DVR archive

This call enables you to forcibly delete a part of a DVR archive. Locked intervals are also deleted by this call.

This call supports both local and cloud DVR storages. If the specified interval is a part of the archive that was copied to a remote storage (Amazon S3) with copy=[REMOTE PATH], it is downloaded to Flussonic to delete appropriate segments and then is copied back to the remote storage.

URL: /flussonic/api/dvr/delete

POST request parameters:

  • stream — stream name.
  • from — time in UTC of the beginning of the interval that you want to delete.
  • duration — the duration of the interval that you want to delete, in seconds.

Usage example:


curl -u USER:PASS --data '{"stream":"ort","from":1483971680,"duration":1000}' http://FLUSSONIC-IP/flussonic/api/dvr/delete

The list of VOD files (list_files)

List of available files for a specific prefix and path.

URL: /flussonic/api/list_files?prefix=VOD_LOCATION&path=VOD_ROOT&subpath=SUB_PATH_IN_VOD_ROOT&from=FirstName&limit=COUNT

Parameters:

  • VOD_LOCATION — VOD prefix (required).
    Web interface: the list of prefixes is displayed on the main page in Files (VOD) section.
    Configuration file: file vod {...};.

  • VOD_ROOT — VOD root (required).
    Web interface: The list of sources (storages) for a prefix is displayed in corresponding tab of Files (VOD) section. New source can be added in New Path field.
    Configuration file: "path" elements in file vod { path priv };.
    VOD root can be an address of swift storage and start with swift://.

  • SUB_PATH_IN_VOD_ROOT — location inside VOD_ROOT (required).
    For root of a storage it equals /

  • FirstName — the list of files that start from this name. You can just specify the beginning of the file name (optional).
    The response will not contain FirstName itself.

  • COUNT — the maximum number of files in the query (optional).
    If it is used with FirstName, the response will contain COUNT files, starting with FirstName (excluding FirstName itself).

Response: JSON like


{
    "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"
        }
    ]
}

Saving a new configuration file (save_config)

To update the Flussonic configuration, you need to pass the text of the new configuration file as a POST request body.

An important difference from update_config is that the new configuration is not only applied to a running server, but also replaces the existing configuration file /etc/flussonic/flussonic.conf.

URL: /flussonic/api/save_config

Parameters:

  • HTTP request payload — the text of the new configuration file (required).
    For example, for curl this parameter is --data-binary:

curl ... --data-binary '# Global settings:\nhttp 80;\nrtsp 554;\nrtmp 1935;\npulsedb /var/run/flussonic;'

Response: true if the request was processed successfully.

Updating the configuration file (update_config)

To update the Flussonic configuration, you need to pass the text of the new configuration file as a POST request body.

An important difference from save_config is that the new configuration is applied to a running server, but the configuration file on disk does not change.

URL: /flussonic/api/update_config

Parameters:

  • HTTP request payload — the text of a new configuration file (required).
    For example, for curl this parameter is --data-binary:

curl ... --data-binary '# Global settings:\nhttp 80;\nrtsp 554;\nrtmp 1935;\npulsedb /var/run/flussonic;'

Response: true if the request was processed successfully.

Removing a stream (config/stream_delete)

To delete a stream, you need to pass its name as the POST request body.

URL: /flussonic/api/config/stream_delete

Parameters:

  • HTTP request payload — stream name (required). For example, for curl, this parameter is --data-binary:

curl ... --data-binary 'mystream'

Response: {"success":true} if the request was processed successfully.

Creating and updating a stream (config/stream_create)

To update stream configuration, you need to pass the text with the stream settings as POST request body. It is exacly the same text you would use to add a new stream to the configuration file.
Warning: At the moment there is no separate config/stream_update command, so the existing stream can be updated with theconfig/stream_create query.

URL: /flussonic/api/config/stream_create

Parameters:

  • HTTP request payload — text of a stream configuration (required). For example, for curl this parameter is --data-binary:

curl ... --data-binary 'stream mystream { url hls://myvideo.com/mystream; dvr /storage 1d 1G; }'

Response: {"success":true} if the request was processed successfully.

Reloading the configuration file (reload)

You must perform this query to apply the new configuration to a running server if you have made changes to the configuration file /etc/flussonic/flussonic.conf.

URL: /flussonic/api/reload

Parameters: none

Response: true if the request was processed successfully.

Example that uses curl to run the call:


curl -u admin:pass0 http://flussonic:80/flussonic/api/reload

Restarting a stream (stream_restart)

Full restart of a specific stream. May be useful in a case of broken source.

URL: /flussonic/api/stream_restart/STREAM_NAME

Parameters:

  • STREAM_NAME — stream identifier (required).

Response: true if the request was processed successfully.

Switching stream source (stream_switch_source)

Use new source for the stream.

URL: /flussonic/api/stream_switch_source/STREAM_NAME?url=SOURCE_URL

Parameters:

  • STREAM_NAME — stream identifier (required).

  • SOURCE_URL — New source URL. Must be present among configured sources of the stream (required).

Enabling the DVR module (dvr_enable)

Pre-requisite: the option dvr or dvr_offline must be specified in stream settings.

URL: /flussonic/api/dvr_enable/STREAM_NAME

Parameters:

  • STREAM_NAME — stream identifier (required).

Response: true if the request was processed successfully

Disabling the DVR module (dvr_disable)

Stops writing a stream into archive.

URL: /flussonic/api/dvr_disable/STREAM_NAME

Parameters:

  • STREAM_NAME — stream identifier (required).

Response: true if the request was processed successfully

Information about servers in a cluster (cluster_servers)

Gets the information about Flussonic servers in a cluster.

URL: /flussonic/api/cluster_servers

Parameters: none

Response: JSON like


{
    "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"
    }
}

Using deprecated API calls

Caution

If you use deprecated calls such as 'get_config' or 'config/stream_list', then please enable the environmental variable FLUSSONIC_OLD_CONFIG:

  1. Edit Flussonic service unit file (/lib/systemd/system/flussonic.service) — do it by using the systemd's override mechanism.

systemctl edit flussonic

This command opens a text editor (nano by default).

  1. Add these lines:

[Service]
Environment=FLUSSONIC_OLD_CONFIG=true

Press Ctrl-X, then Y to save and exit.

  1. Restart Flussonic:

service flussonic restart

EPG upload

Flussonic allows you to upload EPG files through HTTP API.

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

POST request parameters:

  • file — XMLTV file for upload
  • filename — explicitly change the name field of a file upload part (optional)

Usage example:


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

Every uploaded file raises transponder_uploaded_xmltv event.

Flussonic:

  • checks whether xmltv_url directory exists.
  • checks the received data: each file must contain EPG, have a valid name and an .xml extension. If some files are invalid HTTP 400 error will be raised and no file will be uploaded.
  • stores files in the xmltv_url directory with SHA-1 added to the filename to avoid overwriting of the existing files. So the rtr.xml file will be stored under the name rtr.HEX_HASHUM.xml.
  • all XMLTV files from the xmltv_url directory get reread by the transponder.

Multiple XMLTV files may contain the information about some particular TV program, as we will discuss further.

By default, Flussonic doesn't delete XMLTV files. However, you can configure its deletion.
To enable it you need to specify the keep_epg parameter in eit section in the transponder configuration:


eit {
    xmltv_url xmltv_dir1;
    keep_epg 10h;
  }

The keep_epg parameter specifies the amount of time since the latest TV program. In the example above keep_epg 10h equals to 10 hours. By the time it runs out file has to be deleted. If the file couldn't be parsed or is empty, it will not be removed. All the files get deleted once in 8 hours, i.e. XMLTV files that had to be deleted through this time will be. Even if the files were copied into the directory they still can be removed. transponder_deleted_xmltv event is raised after every file removal.
As soon as live_transponder receives new EPG from xmltv_loader, it raises the transponder_upload_xmltv event.

There are a few error descriptions that may occur:

HTTP code Scope Error code Description Response Body Example
- input file not_xml_ext file does not have .xml extension { "errors": { "filename1.txt": "not_xml_ext"} }
- input file unsafe_filename file name contains "/" { "errors": { "dir/filename2.xml": "unsafe_filename"} }
- input file invalid_xml could not parse xml from the file { "errors": { "filename3.xml": "invalid_xml" } }
- input file no_epg file does not contain EPG { "errors": { "filename4.xml": "no_epg" } }
404 transponder config not defined There is either no transponder with such name or xmltv_url is not specified -
500 transponder config remote xmltv_url is not a local directory, but a URL "remote"
500 transponder config enotdir xmltv_url is not a catalog "enotdir"

If more than 1 error occured while trying to upload a file, then Response Body will look as follows:


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

Caution

When storing multiple XMLTV files, a following situation may occur: the time of some TV program may differ from one XMLTV file to another. In this case, the record of the TV program that started later will not be stored in the table for present/following program.
For example, one file contains the following record: "Morning news" starts at 9:00 a.m. and ends at 10:00 a.m. Another file has the following record: "Morning news" starts at 9:30 a.m. and ends at 10:30 a.m. This means that the record of the second file ("Morning news" lasting from 9:30 to 10:30) will not be stored in the table for present/following program, since only one TV program takes place at a time. However, in all the other tables these records will be stored.

Flussonic update

You can update Flussonic through HTTP API.

To do that you need to

1. Check if an update is available. To do that you have to call for the status of an updates subsystem.

URL: /flussonic/api/updater/status

Parameters:

  • USER — admin username
  • PASS — admin password
  • FLUSSONIC-IP:80 — Flussonic hostname and port

Usage example with curl:


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

Response:


{
  "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"
}

Here:

  • available_to_update — if the version may be updated. May take the following values:
    • trueFlussonic can be updated. Only in this case the update is possible.
    • falseFlussonic cannot be updated due to some errors:

{
  "available_to_update": false,
  "error_codes": [
    "must_be_root"
  ],
  "error_descriptions": [
    "Don't have root rights"
  ]
}

  • available_versions — a list of all the available versions
  • installed_version — the installed version of Flussonic (when restarting Flussonic current version will be shown)
  • launched_version — the version of Flussonic that is responding
  • is_updating — if there are any processes running that prevent the system from updating. May take the following values:
    • false — no other processes running
    • true — some process running
  • last_update_error — the text of the error that occurred the last time some action was performed (results in null after performing some other action)

2. Update the indexing package list and the list of available versions of Flussonic (similar to apt update in the terminal). It may take a few minutes (10+ minutes in worst cases). To view the result call for the status of the updates subsystem (see point 1 above).

Usage example with curl:


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

List of possible errors:

Error Description
not_available when available_to_update is set to false: available_to_update: false
busy some process is running in the updates subsystem
bad_api_request something is wrong with the request (for example, not POST request)

3. Request an update (similar to apt install in the terminal). It may take a few minutes (10+ minutes in worst cases). To view the result call for the status of the updates subsystem (see point 1 above).

Note

The version that has just been installed will not be launched automatically!


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

Parameters:

  • new_version — version to install (in our example it's 20.12)

Response:


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

List of possible errors:

Error Description
not_available when available_to_update is set to false: available_to_update: false
busy some process is running in the updates subsystem
bad_api_request something is wrong with the request (for instance, new_version is missing)
bad_version no such version in the list of available versions

After some time check the status of the updates subsystem to ensure the new version of Flussonic has been installed.

Updating your version of Flussonic through HTTP API allows you to prevent any dependency conflicts as it will update all of the packages necessary for the correct work of Flussonic. Even in case of downgrading.

4.Restart Flussonic to apply the changes:


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

Flussonic can restart under certain conditions. For this to happen, the following conditions must be met:

  1. is_updating equals to false: is_updating: false
  2. the installed_version does not equal the launched_version

List of possible errors:

Error Description
not_available when available_to_update is set to false: available_to_update: false or one of one of the conditions for rebooting is not met (see above)
bad_api_request something is wrong with the request (for example, not POST request)

This method will raise the reboot_on_upgrade event with launched_version and installed_version.

Now you know how to update Flussonic through HTTP API.