Publishing Video to the Server

Flussonic Media Server can accept video from external systems and devices that initiate broadcast. This is called publishing to Flussonic.

Publishing can be used in a situation where the external system has no static IP or where it is located behind the firewall in a private IP network. In this case, Flussonic has no way of directly sending a request for video.

What we call publishing to Flussonic:

• Transmitting video from a mobile device to Flussonic.
• Transmitting video from OBS (Open Broadcaster Software) or vMix to Flussonic. Learn more
• Transmitting video from a webpage to Flussonic via WebRTC. Learn more

What we don't call publishing to Flussonic:

• Receiving a multicast
• Ingesting a stream from some source

In those cases, Flussonic Media Server has to connect to the data source. Whereas the case where the connection is not initiated by Flussonic itself is called publishing. For example, publishing is when a mobile device connects to Flussonic to transmit video.

Publishing video to social networks is not publishing to Flussonic and therefore it does not meet Flussonic's definition of publishing as used in this documentation.

Supported protocols

Flussonic Media Server can receive requests for video publishing via the RTMP, RTSP, HTTP MPEG-TS, WebRTC, and SRT (20.08) protocols.

Contents:

• Publishing to a static stream
  • Configuring publishing to a static stream via the web UI
• Publishing with a dynamic name
• Publishing via RTMP
• Publishing via RTSP
• Publishing via MPEG-TS
• Publishing via WebRTC
• Publishing via SRT
• Authorization for stream publishing
• Extended validation of a publication source
• Dynamic stream configuration management
• DVR archives and dynamic names of streams
• Re-publishing
• Configuring adaptive bitrate (ABR) for WebRTC publications

Publishing to a static stream

If you know what stream name an external system will use to publish video to Flussonic, you can create a stream with that name and a input publish:// data source.

stream published {
  input publish://;
}

To apply the settings, run the command:

service flussonic reload

The new input publish:// data source offers far more flexibility - it adds options for timeout, transcoding, and WebRTC support.

Learn more about how to set up publishing to a static stream

URLs for publishing via different protocols

You can publish videos to Flussonic using the following URLs:

• rtsp://flussonic-ip/published
• http://flussonic-ip/published/mpegts
• rtmp://flussonic-ip/published
• rtmp://flussonic-ip/static/published

URLs for RTMP — important points

When the RTMP stream name is short, a third-party software may not be able to recognize which part of the URL is the name of the application, and which part is the name of the stream.

Flussonic Media Server automatically omits rtmp from the application name. If the software requires you to specify some kind of application name, you should use the name static. For example:

• server URL: rtmp://flussonic-ip/static
• stream name: published

If you use a complex stream name, like client15/published1, you can specify:

• server URL: rtmp://flussonic-ip/client15
• stream name: published1

With this configuration, you will be able to use all of the stream's settings and options.

However, if you have explicitly configured a stream with complex static/published name in Flussonic, the static part will be considered as a part of the stream name.

Configuring publishing to a static stream via the web UI

You can add the input publish:// data source to a stream via the web interface.

Creating a static stream for publishing

To create a static stream with a publishing source:

1. In the admin interface, create a stream: Media > Stream > add.
2. Enter a Stream name.
3. Specify publish:// as the Source URL. Alternatively, save the stream, go to the Input tab, and click accept under Published input.
4. Click create to save the stream.

To specify additional options for a published source, click options:

Viewing URLs for publishing via different protocols

To view links for publishing:

1. Click on the stream name in Media and go to the Overview tab.
2. All available links for publishing will be displayed in the Publish links section.

Removing a publishing source from a stream

To remove a publishing source from stream settings:

1. Click on the stream name in Media and go to the Input tab.
2. Click ignore below the Published input, or click the recycle bin icon to the right of the publish:// source.

1. Click save to apply the settings.

Publishing with a dynamic name

Why use dynamic names and publishing locations?

You might want to use dynamic names for published streams if one or more of the following is true:

• Your publications last for a limited period of time (unlike a 24/7 TV channel broadcast).

• You manage a lot of publications, and it is too much work to create a separate stream for each of them.

• You do not know the names of the incoming streams in advance. For example, you are dealing with a third-party application – like a web chat – that generates a new unique identifier for each stream that it publishes to Flussonic.

Flussonic solves these problems by allowing you to create a publishing location (publication prefix) where you can specify common settings for multiple streams.

A dynamic name means that the full name of a stream is formed from a pre-configured publication prefix and the name defined in an external app.

If the name of a published stream is not known beforehand, or if you expect many published streams, you should set up a publication prefix:

template chats {
  prefix chats;
  input publish://;
}

Here, chats is the publication prefix.

All streams published under the chats prefix will have settings that you specify in the template directive. All stream settings are described in Stream settings.

You can specify several prefixes in the template directive to create several publishing locations. You can also specify an empty prefix ("") to publish a stream with any prefix or even without a prefix. Learn more at Templates and prefixes.

URLs for publishing via different protocols

In case of publishing with a dynamic name, you will need to publish streams under names with a prefix, for example:

• rtsp://flussonic-ip/chats/tempname
• http://flussonic-ip/chats/tempname/mpegts
• rtmp://flussonic-ip/chats/tempname

The part of the name that goes after chats is defined in the client app. Flussonic Media Server does not "know" the stream name in advance.

Please note that if you use the static part in the URL for RTMP publising with a dynamic name, the static part will be considered as an application name and omitted when creating a stream in Flussonic. For example:

rtmp://flussonic-ip/static/test

In this case, a stream test will be created in Flussonic. If you don't want static to be omitted, configure explicitly a stream for publishing with the static name static/test instead of using a template.

Transcoding a published stream

Publishing via WebRTC to live locations

You can use the following transcoder settings for WebRTC published streams with dynamic names:

• output_audio=(keep|add_aac|aac). Specifies audio transcoding options. You can get the resulting audio for playback in AAC (aac), AAC+Opus (add_aac), or Opus (keep - do not transcode audio). By default, add_aac is used – this means that an input stream, which usually has audio in Opus, will also have a track in AAC in the output.

• prefer_codec=(h264|vp8|vp9|av1). Offers to choose one of the listed video codecs at the start of the publication. The default codec is H264. Video encoded in VP8, VP9, and AV1 is currently transferred without transcoding.

Example:

template chats {
    prefix chats;
    input publish://;
    prefer_codec av1;
}

You can also configure transcoding for publishing to a static stream.

Publishing via RTMP to live locations

If published RTMP streams contain audio in PCMU, then you can transcode it to AAC, or specify that the audio tracks must not be transcoded:

• output_audio=(keep|add_aac|aac). Specifies audio transcoding options. You can get the resulting audio for playback in AAC (aac), AAC+Opus (add_aac), or Opus (keep). So, to have audio without changes, you should use keep. By default, add_aac is used. It means that an input stream, which usually has audio in Opus, will also have a track in AAC in the output.

template chats {
  prefix chats;
  input publish://;
  output_audio aac;
}

Publishing via RTMP

There are several difficulties that come with publishing via RTMP. The RTMP protocol does not support proper URLs. When connecting to a server using RTMP, the client must specify both the server name and the application name, and then specify the name of the stream to be played or published to.

Usually, the shortened version is used where the application name and the stream name are concatenated. For example, the pair rtmp://rtmp.myhosting.com/chats and tmp is turned into rtmp://rtmp.myhosting.com/chats/tmp.

The standard practice when interpreting the RTMP pseudo-URL rtmp://rtmp.myhosting.com/chats/tmp is to truncate the path after the server name at the first slash symbol and use the first part of the string as the application name.

This approach is being used only for RTMP and Flussonic Media Server does not support this concept.

Instead Flussonic uses the following logic when publishing via RTMP:

1. The server concatenates the application name with the path being published. Thus, the pairs rtmp://rtmp.myhosting.com/chats/my, chat-15 and rtmp://rtmp.myhosting.com/chats, my/chat-15 produce the published stream name chats/my/chat-15
2. The program searches for the first publishing prefix this name contains. In our example, that would be the prefix chats
3. Then, all authorization interfaces and the like use the complete stream name: chats/my/chat-15.

To test that publishing over RTMP works, you can use ffmpeg:

ffmpeg -re -i /opt/flussonic/priv/bunny.mp4 -vcodec copy -acodec copy -f flv rtmp://localhost/chats/tmp

This command should cause a new stream to appear in the web interface:

Publishing via RTSP

Some clients can publish video over RTSP.

Flussonic Media Server supports automatic selection between UDP and TCP transport and will receive the stream using the protocol selected by the client.

The stream name must be complete: chats/my/chat-15

ffmpeg -re -i /opt/flussonic/priv/bunny.mp4 -vcodec copy -acodec copy -f rtsp rtsp://localhost/chats/my/chat-15

Publishing via MPEG-TS

When transcoding a stream using ffmpeg, it is possible to publish video over HTTP. Video can be published with mpegts added at the end of the URL:

ffmpeg -re -i /opt/flussonic/priv/bunny.mp4 -vcodec copy -vbsf h264_mp4toannexb -acodec copy -f mpegts http://localhost:80/chats/my/chat-15/mpegts

Authorization for stream publishing

Flussonic Media Server can verify a password when publishing a stream. Enter the password in the configuration file as follows:

template chats {
    prefix chats;
    password mypass;
    input publish://;
}
stream published {
    password secure;
    input publish://;
}

RTMP

To publish a password-protected RTMP stream, use the following example: rtmp application rtmp://192.168.2.3/live and stream name mystream?password=mypass

HTTP MPEG-TS

To publish an HTTP MPEG-TS stream, you can enter the data as follows:

http://192.168.2.3:80/s1/mpegts?password=secure
ffmpeg -re -i video.mp4 -vcodec copy -acodec copy -f flv rtmp://192.168.2.3/live/mystream?password=mypass
ffmpeg -re -i video.mp4 -vcodec copy -bsf h264_mp4toannexb -acodec copy -f mpegts http://192.168.2.3:80/s1?password=secure

Extended validation of a publication source

Flussonic Media Server allows you to configure an HTTP handler or a user script handler that will check additional information about the publisher (that is, the source of a published stream) before accepting or rejecting the stream.

template chats {
  prefix chats;
  input publish://;
  on_publish http://examplehost:5000/publish-check;
}
template chats2 {
  prefix chats2;
  input publish://;
  on_publish /etc/flussonic/publish_check.lua;
}

Flussoniс will send an HTTP POST request with a JSON body to an HTTP handler with the following fields:

To start publishing, an HTTP handler should return HTTP status code 200.

Visit Flussonic API Reference to familiarize yourself with the current Flussonic methods, fields, its possible values, and responses.

Dynamic stream configuration management

Flussonic allows you to override the existing configuration for publishing streams per session using the authorization backend. Simply put, you can customize the configuration for publishing streams to Flussonic externally using a third-party service.

Flussonic sends a GET request with a set of parameters in JSON format to the authorization backend before the publishing starts. And based on this data, the authorization backend returns a customized configuration to Flussonic, overriding the existing one.

To enable this feature, use the on_publish option in the template or stream settings and specify the path to authorization backend like so:

template on-publish-example {
  prefix example;
  input publish://;
  on_publish http://IP-ADDRESS:PORT/PATH_TO_SCRIPT;
}

where http://IP-ADDRESS:PORT/PATH_TO_SCRIPT is a path to authorization backend.

Let's have a look at the example to clear the things up. We will customize pushing to YouTube for a publisher.

Step 1. Choose the authorization backend.

Here is a JSON-formatted example that your web service should provide to override the push endpoints to push the stream to. It is not necessary to pass the full config in JSON file: you can pass only the part that you want to modify in the "config":{} body. Like so:

{"config":{"pushes":[{"url":"rtmp://a.rtmp.youtube.com/live1/RANDOM_STREAM_KEY"},{"url":"rtmp://a.rtmp.youtube.com/live2/RANDOM_STREAM_KEY"}]}}

Flussonic will automatically calculate the difference and apply the appropriate changes.

Step 2. Add the path to authorization backend in the stream or template settings.

To do that use the on_publish option in a template or stream settings to specify path to the auth backend:

template live-test {
  prefix test;
  input publish://;
  on_publish http://IP-ADDRESS:PORT/PATH_TO_SCRIPT;
}

Flussonic sends a GET request with a set of parameters to the authorization backend. Based on these parameters, authorization backend returns customized configuration. After that, Flussonic overrides the existing configuration.

Step 3. Publish the stream to Flussonic.

Now we can publish RTMP stream to Flussonic using the following URL:

rtmp://FLUSSONIC-IP/test/example-stream

For more information about configuring templates and prefixes, see: Templates and prefixes.

So when we start to publish the example-stream, Flussonic overrides the config and changes the push endpoints to rtmp://a.rtmp.youtube.com/live1/RANDOM_STREAM_KEY and rtmp://a.rtmp.youtube.com/live2/RANDOM_STREAM_KEY.

DVR archives and dynamic names of streams

You can configure the DVR archive for a publishing prefix:

template recorded {
  prefix recorded;
  input publish://;
  dvr /storage 3d 500G;
}

In this case, the published video will be recorded, and will be available even if the publication is terminated.

When the client stops publishing the video, the stream will disappear after some time, and Flussonic Media Server will keep a very little information about it. Information about this stream will be stored in the index of the archive, and Flussonic Media Server will not lose the files on the disk.

If configured, the system of purging of the archive will delete published streams according to the schedule.

Republishing

To republish the streams, use push with a template (%s):

template pushed {
  prefix pushed;
  input publish://;
  push rtmp://CDN-SERVER:1936/mylive/%s;
}

With the configuration above, Flussonic republishes the pushed/mystream stream, using the following URL: rtmp://CDN-SERVER:1936/mylive/mystream.

Configuring adaptive bitrate (ABR) for WebRTC publications

When a client device is publishing from a browser to Flussonic, Flussonic can control the browser from which the publication is carried out so that the browser adjusts the bitrate of the publication to the bandwidth of the channel. This prevents packet loss when the bandwidth of the Internet connection is insufficient. If you reduce the channel width, the client must reduce the publication bitrate, if you expand the channel, the client must increase the publication bitrate.

To change ABR settings via the Flussonic UI:

To specify additional options for a published source, click options next to the source URL. Adaptive bitrate settings are under WebRTC > ABR:

The following settings in the file correspond to these settings in the UI:

stream published_stream_name {
  input publish:// abr_loss_lower=2 abr_loss_upper=10 abr_mode=1 abr_stepdown=50 frames_timeout=1 max_bitrate=2200 min_bitrate=500 output_audio=aac priority=0 source_timeout=5;
}

Options for adjusting the bitrate from the browser-publisher to the channel width up to Flussonic (ABR)

Flussonic recommends the browser bitrate within the min_bitrate - max_bitrate range, depending on the presence and amount of packet losses during publication.
Flussonic recommends lowering the bitrate when the amount of losses is more than abr_loss_upper and increasing it when the amount of losses is less than abr_loss_lower. Decreasing and increasing are performed by steps of size abr_stepdown and abr_stepup, respectively. After the specified number of auto-adjustment cycles (abr_cycles) passes, Flussonic considers the bitrate to be optimal, and it is no longer analyzed. By default, abr_cycles=5. If abr_cycles=0, the adjustment process takes place all the time while the publication lasts.

Also, Flussonic calculates the actual maximum bitrate. It remembers the bitrate values at which the losses grew up to abr_loss_upper and considers their average value over the past number of cycles to be the new maximum bitrate value (current).