Live streams

Flussonic is able to rebroadcast streaming video with multiplexing. That is, a copy of data is taken from the source and delivered to all users who requested this video.

Flussonic works with three types of streams: static — permanently kept running, live – user-published, and ondemand — requested on demand.

Static streams are launched upon server start, and Flussonic monitors them continuously. If for some reason (transcoder went off, antenna broke down) the data source disconnects, Flussonic will keep trying то reconnect until success or shutdown.

Usually, an IPTV channel is declared as a static stream.

stream ort tshttp://10.0.4.5:9000/channel/5;

In this config, ort is the name of the channel that must be used when requesting the stream from Flussonic, and tshttp://10.0.4.5:9000/channel/5 is the data source's URL.

Flussonic supports many types of data sources, which must be pointed at with URLs.

In order to add a stream via the web interface, open the Media tab:

Press "add static stream",

enter the name of the stream and the data source's URL. Then press "Save" and you will be redirected to a stream settings page:

Stream settings

Flussonic can work with three types of streams: static, on-demand, and published.

• stream mtv rtmp://origin/app/path; Short version of the static stream command. Flussonic will keep this stream continuously running.
• stream mtv { url rtmp://origin/app/path; } Full version of configuring a static stream. Use curly brackets for specifying additional options described below.
• ondemand mtv rtmp://origin/app/path; Short version of the on-demand stream command. Flussonic will launch this stream when needed and disconnect from its data source if no one requests it.
• ondemand mtv { url rtmp://origin/app/path; } Full version of configuring an on-demand stream. Use curly brackets for specifying additional options described below.
• live prefix; Short version of grouping streams for publishing. Flussonic will enable the admin to publish a stream into this prefix by the rules described below.
• live prefix { ... } Full version of grouping streams for publishing. Additional options listed below can be specified in curly brackets.

On-demand streams

If a stream is not needed all the time but only upon user's request, it is possible to tell Flussonic to turn it off when it is not being used and turn back on on demand.

To specify this kind of stream, simply change stream to ondemand:

ondemand cam1 rtsp://10.4.5.3/h264;

It is possible to specify the stream's lifetime after client's disconnect:

ondemand cam1 {
  url rtsp://10.4.5.3/h264;
  retry_limit 10;
  client_timeout 20;
}

The config line above has the following meaning: make no more than 10 attempts to reconnect with a data source if the connection is lost; when the last client leaves, run the stream idly for no longer than 20 seconds.

Data source types

RTSP

rtsp://camera/h264 RTSP camera. Note that the camera's IP is not enough to get the video from it. The path is also required. The path is not always indicated in the manual, so it might be needed to contact the camera's seller or manufacturer. Authorization is specified like so: rtsp://user:password@camera/h264

MPEG-TS HTTP

tshttp://source:8080/stream An HTTP MPEG-TS data source like VLC or another Flussonic.

You can specify a particular PIDs and Programs to take from an MPEG-TS stream:

tshttp://source:8080/stream program=21 pids=45,46,47

It is possible to set User-Agent http header via user_agent option: tshttp://source:8080/stream user_agent="Custom Agent v1.2"

Flussonic does not bypass subtitles by default. Add allow_subtitles=true option:

stream ort {
  url tshttp://source/stream allow_subtitles=true;
}

MPEG-TS TCP

tstcp://source:8080

A TCP MPEG-TS data source.

MPEG-TS UDP

udp://239.0.0.1:5001

The UDP (multicast) address for MPEG-TS broadcasting. Not recommended for use.

To send IGMP requests to a specific interface, the address must be specified in the following form: url udp://239.0.0.1:5000/192.168.0.15; where 192.168.0.15 is the IP of the server with the desired interface.

HLS

hls://source:8080/stream/index.m3u8

An HLS data source. May be combined with UDP delivery in order to provide a reliable, stable video delivery from upstream over a local network. Currently is unable to receive multi-bitrate HLS.

As with MPEG-TS HTTP user_agent option available: hls://source:8080/stream/index.m3u8 user_agent="Custom Agent v1.2"

At stream startup Flussonic checks that the source stream is not stalled. This check can be disabled with the skip_stalled_check option: hls://source:8080/stream/index.m3u8 skip_stalled_check=true

RTMP

rtmp://source/live/stream

RTMP source. Flussonic requires an RTMP URL to have at least two segments. The first segment is by default used as the name of the rtmp application. If the name of the rtmp application on the server is made up of more than one segment, the URL must have two slashes, which would explicitly divide the rtmp application and stream name.

timeshift

timeshift://stream/3600

Timeshift. Allows to create a stream identical to the stream but with a delay of 3600 seconds (one hour). More on this below under the timeshift section.

SHOUTcast

shout://source:8080

SHOUTcast data source.

Stream or group settings

auth

auth http://backend/; Turning on authorization for a stream. See more under the authorization section.

domain

domains

domains host1.ru *.host1.ru; Specifying the domains, within which playing this video is allowed. This does not work for those clients that do not pass the value of Referer. To work correcty in the WEB the flussonic domain must present in the list (the domain of the embed palyer).

allowed_countries

allowed_countries RU US CN; The list of two-character codes of countries where the access is allowed (for code reference see the MaxMind database).

url

url tshttp://transcoder:port/; URL of the data source. It is possible to list several URLs for trying the first available data source.

Important: If a UDP source is used, the configuration file must contain this particular UDP address only once. If multiple streams use the same UDP address, chances are it will not work.

urls

urls source1 source2; A list of data source URLs.

More info about switching sources

url_prefix

url_prefix prefix for instance url_prefix http://my.domain.address.com:8080 When using HLS protocol, the addresses of individual segments and playlists within the variant playlist will start with the specified prefix. This option may be used not only as part of an individual stream's settings but also in the global portion of the config file. If the option is specified globally, it will be applied to all streams on the server.

dvr

dvr /storage 1d 50% schedule=8:00-16:00; Turning on archiving feature. This command tells Flussonic to store archived data in the /storage/streamname directory and clean up that directory either once a day or when the disk gets 50% full. Instead of days, hours can be specified: 20h. Parameter schedule allows you to set a schedule on the DVR the form of intervals. The time is specified in UTC in hours and optionally with minutes, the interval can overlap midnight: 22-1:30. A schedule can contain multiple intervals, separated by a comma: 8:00-16:00,22-1:30.

dvr_offline

dvr_offline /storage 1d 50%; With this option specified, the stream will not turn on archiving on start. It will have to be turned on explicitly via API. This option used in place of dvr option.

udp

udp 239.0.0.1:5001 multicast_loop; udp 239.0.0.1:5001; This causes Flussonic to send the stream via MPEG-TS over UDP.

To set MULTICAST_TTL parameter on UDP socket use following syntax: udp 239.0.0.1:5001?ttl=8;.

To set constant bitrate (CBR) use following syntax: udp 239.0.0.1:5001?cbr=2000;, where 2000 is bitrate in kbit/sec.

thumbnails

thumbnails; Turns on generation of stream preview thumbnails. The flussonic-ffmpeg package must be installed.

segments

segments 5; Specifies the number of segments in the HLS and HDS playlists.

retry_limit

retry_limit 10; This sets the number of times Flussonic will try to connect to the data sources before closing a non-static stream.

clients_timeout

clients_timeout 10; This sets the time period (in seconds), for which Flussonic will keep serving a non-static stream after the client's last request.

source_timeout

source_timeout 10; Specifies the period of time, in seconds, for which Flussonic will wait for new frames to come from the data source. When this time passes, Flussonic will attempt to reconnect to the data source. Default source_timeout is 60 seconds.

password

password secret; The password that will be passed via query string (http or rtmp) for publication in a stream or group.

push

push rtmp://destination-server/name; This option tells Flussonic to publish the stream to another server.

backup

backup vod/blank.mp4; Setting this option for the stream will launch the specified file vod/blank.mp4 while the video from the data source is unavailable.

publish_enabled

publish_enabled; Specifying this option for the stream allows to publish video into it. Meaningless for a group of streams.

on_publish

on_publish http://host/publish.php; on_publish /etc/flussonic/publish.lua; Causes publishing to this stream or stream group to call a script or send HTTP request with such parameters as the stream name, publisher's IP, etc. In response it is possible to refuse publication or allow: the HTTP backend must return 200 OK or 403 Forbidden; the .lua script must return {true, {}} or {false, {}.

max_sessions

max_sessions 1000; Sets the limit on the quantity of sessions for the stream.

settings_rtp

rtp udp; Turns on obligatory use of UDP for working with RTSP cameras.

add_audio_only

add_audio_only; Adds to the HLS playlist a link to an audio-only stream. This is needed to validate the app in Apple devices.

no_prepush

no_prepush; Turns off the quick-start prepush feature. Might be useful for keeping real-time streaming.

prepush

prepush 10; Enables a buffer of specified duration, in seconds. If the client's connection to the server is interrupted or slowed down, it plays video from the buffer, which allows the player to start faster, but with a lag.

max_bitrate

max_bitrate 1000; Sets the bitrate limit for the stream being published.

logo

Version 4.6.15 and above. logo path=flu/embed-logo.png height=100 width=100 left=0 top=0; Add logo at playback. This logo will not be displayed on mobile devices and in the DVR player. To add logo to video use transcoder. path (required) — path relative to wwwroot directory. height, width — logo image size in px. If ony only one of these parameters is present then the other is scaled proportionally. Omit these parameters to display logo in the original size. left, top, right, bottom — logo image location specified by offset in px. For example, right bottom corner: right=0, bottom=0. Don't use left and right, top and bottom parameters together.

mpegts_pids

mpegts_pids pmt=4095 sdt=0x12 v1=211 v2=212 a0=220 t0=16#fb; This parameter sets PIDs values for outgoing MPEG-TS stream. It is possible to set PID for PMT, STD and tracks. Tracks numbered starting from one: a1=123 sets PID for the first audio track. It os possible set base index for the tracks of certain type using the 0 (zero) index. Example: t0=100 sets PID=101 for the first track, 102 for the second, and so on. Numbers can be given in decimal form (by default) or in hexadecimal with 0x prefix.

gop_duration

gop_duration 8; GOP size (GOP duration), interval between keyframes.

segment_count

segment_count 4; Number of segments for buffering.

disabled

disabled; Stop stream.

Stream playback

Stream screenshots

Flussonic can make screenshots of streaming video. To achieve this, the additional flussonic-ffmpeg package must be installed and the thumbnails option turned on in the stream settings.

stream ort {
  url udp://239.255.0.100:1234;
  thumbnails;
}

You can specify URL where Flussonic can get screenshots to reduce CPU usage for thumbnails. Many cameras has special URL with screnshots:

stream cam0 {
  url rtsp://10.0.4.3:554/h264;
  thumbnails http://10.0.4.3/cgi-bin/snapshot.cgi
}

Screenshot URL you can find in documentation for you camera model.

The stream's last screenshot is available at http://flussonic:8080/ort/preview.jpg

MJPEG screenshot stream is available at http://flussonic:8080/ort/preview.mjpeg

Substituting stream with a file

If for some reason the stream is inaccessible, Flussonic provides the option of substituting it with a video file.

stream rtr {
  url tshttp://10.0.4.5:9000/channel/5;
  backup vod/backup.mp4;
}

Note that if the original stream has no audio (e. g., from IP camera), the stand-in file should have no audio as well.

Wildcards

Sometimes the names of remote server streams are not known in advance, and it makes sense to use proxy with everything. Use special stream type:

rewrite nsk/* rtsp://nsk-origin:554/%s;

rewrite ams/* hls://ams-origin:8080/%s/index.m3u8;

If rewrite option is combined with an asterisk at the end of stream name, the substring that precedes the asterisk will replace "%s" in URL.

Recording video stream (DVR)

Flussonic has an excellent stream recording system. The stream archiver can record video, provide access to a particular video interval, export parts of the archive as mp4 files, clean up old archive files, and maintain ample free space on the storage disk.

To turn on the archiver, simply specify the dvr option in the stream config line:

stream foxlive {
  url tshttp://trancoder-5:9000/;
  dvr /storage 90% 5d;
}

See a more detailed archive management description under a dedicated section.

Time zone adjustment (Timeshift)

Flussonic can play the archive record of a stream with a fixed delay. Note that Flussonic maintains the delay painstakingly, so if for some reason the archive has lacunae, end users will be getting no video for the duration of the gap.

The timeshift feature uses a separate data source protocol:

stream ort {
  url tshttp://trancoder-5:9000/;
  dvr /storage 90% 5d;
}

stream ort-4h timeshift://ort/14400;

The delay is specified in seconds.

Stream delivery over UDP multicast

Flussonic is able to rebroadcast a stream from a data source over local network. Note that Flussonic will attempt to serve UDP as evenly in time as possible in order to avoid sharp network load increases.

stream ort {
  url tshttp://trancoder-5:9000/;
  udp 239.0.4.4:1234;
}

Stream settings for IP surveillance cameras

It is possible to tell Flussonic to request a stream from camera via UDP only. Sometimes this is necessary when working with the cameras that have issues with TCP.

stream cam1 {
  url rtsp://10.0.4.3:554/h264;
  rtp udp;
}

If there is no need to get audio from the camera (for instance, in G.726), Flussonic can be told to capture only one track. The number of the track must be specified in the stream settings line:

stream cam1 {
  url rtsp://10.0.4.3:554/h264;
  tracks 1;
}

In order to transcode a G.711a or G.711u audio coming from the camera into AAC, the other protocol must be specified:

stream cam1 {
  url rtsp2://10.0.4.3:554/h264;
}

Turning on audio-only HLS

When validating apps in AppStore, Apple may require the stream to have an audio-only version. If this command is added to the config:

stream cam1 {
  url rtsp://10.0.4.3:554/h264;
  add_audio_only;
}

and the stream has both video and audio, Flussonic will generate a multi-bitrate variant playlist of two streams: one standard, the other audio-only.

Capturing stream from another Flussonic

The details of transferring video between Flussonic servers are discussed in the Flussonic video stream clusterization article.

DRM in live

The details are discussed in the Apple DRM article.