Softvelum news: Nimble Streamer, Larix Broadcaster and more

Nimble Streamer uses sessions to track users' stats as it's important to see how the content is consumed. It's used in every end-user connection unless you use HTTP origin feature to remove the session identifier.

Every session is based on user IP to be able to distinct them from one another. Normally if a session starts with some IP, it keeps using that IP until the connection is closed. If the original connection IP changes, Nimble Streamer will close the connection because IP change most probably means that someone else uses your session ID which is not good from security standpoint. The viewers with closed connection will get response code 403.

However in some cases the IP change doesn't mean anything bad. For example, if your Android users use Lite mode (also known as Data Saver), Google will use its own proxy servers to accelerate the data usage. Also, your users may use other trusted proxies for their own legit purposes.

For cases like these you may use a few features of Nimble Streamer.

Disable IP check

First of all you may disable session IP check. This can be done using this parameter

restrict_session_ip = false

in nimble.conf. Please read this article for details on parameters' setup and usage.

Once you disable it, your streams' direct links may be used by several viewers so you should use this approach only in case your viewers use trusted proxy servers.

Tune hotlink protection

If you use hotlink protection from WMSAuth paywall feature set and your viewers use proxies as described above, they will get error 403 and you'll find "cannot find hash match" in Nimble logs. That will happen even if you disable session IP check.

So the next thing you should do after disabling restrict_session_ip, is to use different headers for obtaining end-user IP in WMSAuth code for your web page. This can be X_FORWARDED_FOR header or others, depending on your server and proxy software. Read this article regarding proxy usage to learn more about headers' usage.

Let us know if you experience any issues with the described features.

1. Set up Certbot

First go to Certbot website and scroll down to "My HTTP website is running" line. Choose "None of the above" option in Software field and then your OS in "System" field.

Let's use Ubuntu 18.04 for our example.

You'll be redirected to https://certbot.eff.org/lets-encrypt/ubuntubionic-other page with necessary instructions.

Follow steps 1 through 4 to install and setup Certbot.

2. Set up certificate

On step 5 - "Install your certificate" - you need to add use your new certificate in Nimble Streamer configuration.

Add these lines to your /etc/nimble/nimble.conf file:

ssl_port = 443
ssl_certificate = /etc/letsencrypt/live/your.domain.name/fullchain.pem
ssl_certificate_key = /etc/letsencrypt/live/your.domain.name/privkey.pem

and then re-start Nimble Streamer with this command:

sudo service nimble restart

You can find more info about nimble.conf on this page.

If you need more complex setup scenario like multiple domains or encryption methods, you can follow this article to set up SSL certificate properly.

By this step, you'll have Nimble Streamer instance running with valid SSL certificate.

3. Set up certificate renewal

The last step will be to set up the automatic renewal of certificate. Certbot does this perfectly, however we'll need to make it call Nimble Streamer for reload the certificate. This can be done via Nimble Streamer native API.

First, set up management API as described on this page under "Starting point: enable API access" point.
Here's an example you can use:

management_listen_interfaces = 127.0.0.1
management_port = 8083

Then re-start Nimble Streamer instance:

sudo service nimble restart

Second step will be to run the renew command as described in "Test automatic renewal" section, with additional post-hook parameter like this:

sudo certbot renew --post-hook 'curl -X POST http://127.0.0.1:8083/manage/reload_ssl_certificates'

Once Certbot renews the certificate it will reload the SSL certificate by making proper API call.

That's it. If you have any questions or issues, feel free to contact us via helpdesk.

ABR capabilities

Adaptive bitrate (ABR) is one of the key features available as part of SLDP. It's supported on both sides of transmission:

Nimble Streamer server allows switching per player command among available bitrates which are set up as part of ABR stream
SLDP Player provides controls for switching between bitrates if a stream has information about available sub-streams.

Switching of channels may be performed nearly instantly. A player sends command to a server to send media from another bitrate and once the data is received, it takes just a time equal to GOP duration to start displaying a new sub-stream.

SLDP and ABR setup

General process of SLDP playback setup in Nimble Streamer doesn't differ from RTMP playback setup. This article shows step-by-step procedure which is pretty simple with WMSPanel control panel web UI.

ABR setup in Nimble Streamer is described in this article and it's also straight-forward. It includes input streams processing and output setup. Notice the graceful adaptive bitrate stream approach use in Nimble.

If you don't have various renditions from and need to create them from your original stream, you may use our Live Transcoder, and try wildcard setup in particular to simplify this process. Also check this Transcoder video showing the setup process.

If you use Transcoder, you should also perform key frame alignment for all single-bitrate streams. Sometimes when you switch between different stream's renditions you can see a some short glitch. This happens because a player need a new GOP to start the playback. Different streams may have their key frames aligned differently, so each new GOP will start from different point. To avoid that, you need to perform key frame alignment. Use this article to set key frame alignment in your transcoding scenarios.

SLDP Player usage

Having SLDP stream, you can now use our players to provide the playback to your users.

You may use 3 options:

HTML5 player provides playback in any browser which supports MSE. This includes basically any Windows or Linux platform. Even Android browsers will allow you to load and play SLDP via HTML5 SLDP player.
Android native app provides playback in case you don't want to use web playback on user devices.
iOS native app is needed in case you need to play SLDP on Apple mobile devices. You can use it as a fallback for browser player.

All players are free of charge. They also have respective SDKs so you could customize them for your user experience.

SLDP HTML5 player setup also needs these parameters to make full-featured ABR playback:

1. Enable ABR by setting

adaptive_bitrate = true

2. Set initial resolution which you want your uses to see by this setting

initial_resolution = <resolution>

3. If you use key frame alignment as described above, you need to use this parameter to obtain smooth rendition switching:

key_frame_alignment = true

4. You may also use latency_tolerance parameter to tune the streaming latency as described in this article.

That's it. With steps described above you will have full-featured SLDP ABR playback on any platform you need.

Also, you can take a look at the SLDP frequent questions to improve your SLDP usage. And read Reliable Low Latency Delivery with SRT+SLDP post in Haivision blog describing a combination of both protocols for building reliable delivery networks.

Visit SLDP website and contact us in case of any questions regarding SLDP technology usage.

Nimble Advertizer has wide variety of options to insert ads, including inserting ads per SCTE-35 markers. So if your original stream has those markers and your Advertizer is set up to trigger ads for it, your output will have proper ads.

In addition to reacting to available SCTE-35 markers, Nimble Advertizer is able to insert new markers right at the moment you need them using Nimble API. This will trigger almost immediate ads insertion so it's a good way to implement your own "big red button" for per-request ads insertion. Here's how you can do it.

Set up Advertizer

SCTE-35 insertion feature set is part of Nimble Advertizer. So first you need to create and subscribe for Advertizer license.

Then you need to set up Advertizer according to Advertizer tech spec. This includes preparation of ads files and setup configuration. As part the setup, you'll define what streams will be reacting to markers. You can read article explaining SCTE-35 markers handling mechanics, including example of handler response.

Set up Nimble API

Markers insertion is performed via Nimble native API. Use this API page to enable API first and then get familiar with "Insert SCTE-35 marker" call. Try to call that method on some test streams to see how it triggers the insertion of ads.

Use markers insertion

Once you have your Advertizer ready for markers handling and know how to use proper API call, you may develop further setup for triggering ads via API call in your production environment.

Besides immediate insertion via Advertizer, you may pass through the inserted SCTE-35 markers for further processing. Read this article for details of this functionality.

If you find any issues with SCTE-35 feature set, please file us a support ticket so we could help you.

Enable the DVB subtitles processing for MPEG2TS and HLS streams

If your incoming MPEG2TS or HLS stream has DVB subtitles and you need to have those subtitles to be passed through to output MPEG-TS and HLS, you need to add the following parameter into your Nimble config:

dvb_subtitles_processing_enabled = true

Once you add it and re-start Nimble Streamer, your output HLS and MPEG-TS will have DVB subtitles if your source streams have them.

Passing DVB subtitles through Live Transcoder

If you need to transcode your streams (e.g. make multiple resolutions or put graphics on top) and keep DVB subtitles from the source stream, you'll need to make some additional changes to your transcoding scenarios. Also notice that you must have dvb_subtitles_processing_enabled parameter to be enabled as described above.

Let's take a look at a simple scenario which allows keeping original stream as well as make lower resolutions.

Here you see /live/source stream being processed to get /live/output_480p output stream down-scaled to 480p (via Scale filter box) and keep the original rendition as /live/output_original stream.

There are 2 ways of passing the DVB - via video and via audio pipeline. We'll demonstrate both ways.

The /live/output_original stream has video being passed through - you can see long line with blue-to-orange gradient. This way, if you have full HD stream as input, you won't waste resources decoding and encoding the content to the same rendition. But the audio is split to decoder and encoder. Let's see their settings.

In the source stream decoder you see the enabled Forward DVB subtitles checkbox. It enables the transcoder to grab the subtitles for processing. In audio encoder setting, you click on Expert setup section to see the Forward DVB subtitles checkbox again. Check it to make the encoder take the subtitles which were previously grabbed into the pipeline by the decoder. After saving the transcoder scenario and re-starting the incoming stream, the output will have the DVB subtitles in the result stream.

The /live/output_480p stream has audio being passed through while video is transformed to lower rendition. So here we use video pipeline to pass DVB subtitles. It's set up the same way - both in decoder and encoder elements.

You need to check Forward DVB subtitles checkbox in video decoder and in video encoder settings under Expert setup section. As in case of audio, once you save the scenario and re-start input stream, the output will have the initial DVB subtitles.

Enable RTMP Icecast metadata

First, the incoming stream must have the RTMP Icecast metadata delivered. So you need to enable RTMP Icecast metadata processing as described in this article. If you don't set up the designated application or entire server processing the RTMP Icecast metadata, it will not be available for transcoder scenarios.

Set up Transcoder

In this sample scenario we use transcoder for re-sampling audio from the existing RTMP stream. You may see a decoder, then a filter to perform sampling and then an encoder.

The forwarding needs to be specified on both decoder and encoder sides. In the audio decoder element you need to check the Forward RTMP metadata checkbox to set the transcoder to take metadata into the pipeline.

Now go to video encoder element and click on Expert setup.

Here you need to check the Forward RTMP metadata checkbox to make the transcoder grab the metadata from the pipeline and make it part of output stream.

Once you save the scenario and re-start the input stream, the output stream will have the metadata which then can be used for transmuxing into Icecast or re-publishing.

1. Enable RTMP Icecast metadata

To use this real-time injection you need to enable RTMP Icecast metadata feature first.

Follow "Generating Icecast metadata from RTMP" article to set up the processing of Icecast metadata in RTMP for further usage. Basically it's a matter of one checkbox in WMSPanel UI for given server instance or for some specific application.

Once this feature is enabled, any incoming stream will

2. Enable Nimble API

Nimble Streamer native API allows working directly with server instance in order to get its status and control its behavior in some cases.

To start using it, you need to enable it on server side via configuration file. Please follow Pre-setup section in Nimble Streamer API reference to proceed. Once you have properly set up server, you can run the ingestion.

So whatever app or server you will enable this feature for, the incoming stream will get the metadata which you later will be able to transfer and process via RTMP.

3. Perform the injection

At this point we assume that you have a live stream to ingest metadata into, let it be "live" application and "radio" stream.

Then assuming your management interface is 127.0.0.1 and port is 9999 you can make this POST call:

curl -vvv http://127.0.0.1:9999/manage/icecast_metadata/live/radio -d "{\"streamtitle\":\"News\", \"streamurl\":\"URL2\"}"

This includes /manage/icecast_metadata method with for live/radio stream and set streamtitle and streamurl metadata parameters.

If you don't need to set streamurl you can run it this way:

curl -vvv http://127.0.0.1:9999/manage/icecast_metadata/live/radio -d "{\"streamtitle\":\"News\"}"

to apply streamtitle only.

You can find more about this and other native API methods on API reference page.

Further usage

As we've mentioned before, this metadata injection API call allows adding that data into the live stream, as if it's been ingested by some encoder before that stream entered into Nimble Streamer instance. This means that you may use ingested metadata in any output RTMP or output Icecast processing use case like those:

Transmuxing from RTMP into Icecast, the metadata will be appended into Icecast.
RTMP re-publish from origin to edge servers, where edges can transmux RTMP to Icecast with metadata.
Pass metadata through Live Transcoder in case initial RTMP stream needs some transformations. The transcoded streams can then be used the same ways - for transmuxing or re-publishing.

RTMP will still carry the data outbound as you need.

Contact us if you have any questions regarding any of our features.

1. Create a processing script

Nimble Streamer uses POST request to call your URL. Your script MUST get request body first.

Request body will look differently for different types of calls. Here are examples, with additional formatting, the fields are described below.

RTMP is published into Nimble:
{"ID":"c581b1c2-686a-8140-8deb-f44031fa393f",
"Signature": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTg",
"Puzzle": "42342-33434-343434-34343",
"publish":[{
"stream":"live\/4k",
"protocol":"RTMP",
"time":1569999976249,
"type":"push",
"remote_ip":"127.0.0.1"
}]}

Nimble started receiving output from Live Transcoder:
{"ID":"c581b1c2-686a-8140-8deb-f44031fa393f",
"publish":[{
"stream":"live\/4k_ao_aac",
"protocol":"ENCODER",
"time":1569999976374,
"type":"pull"
}]}

Icecast stream is not pulled anymore:
{"ID":"c581b1c2-686a-8140-8deb-f44031fa393f",
"unpublish":[{
"stream":"live\/4k",
"protocol":"ICECAST",
"time":1570000823258
}]}

Two major types of calls are available:

"publish" means that the incoming live stream has appeared in Nimble Streamer input.
"unpublish" means the stream is not in the input of Nimble Streamer anymore.

The following fields are used:

"stream" shows application and stream name in the call.
"protocol" is one of the following values: RTMP, RTSP, ICECAST, MPEG-TS (which covers MPEGTS and also pulled HLS) and ENCODER (output stream of Nimble Live Transcoder)
"time" is publish/unpublish event epoch time in milliseconds.
"remote_ip" is provided in case the stream is a published, it shows the IP of source.

"Signature" and "Token" is what your script MAY check to make sure that it was Nimble Stream who sent it.

Signature = BASE64(MD5(ID + Puzzle + Token))

You can find a small PHP sample of processing the incoming request in out github samples repo.

2. Set up API in WMSPanel

2.a Global setting

Go to Control / API Settings and choose Global push API tab.

Here you need to use two fields:

Enter handler URL into Streams (un)publish handler URL field;
Click on Enable publish/unpublish notifications checkbox.

After you click Save, the first sync-up will be sent to your handler within several seconds.

API parameters also include Token field as well as Enable mutual authorization check box. Those should be used if you'd like to use signature as described in section 1 above.

2.b Server instance setting

You may also make per-server setup. Just click on Servers push API tab to be able to define same settings for each individual server.

3. Test the complete solution

Now you can set up a testing stream or use existing one to try this feature. Just publish that stream to and get notified by the panel via the script. In the github example above you'll get a new log entry.

WMSPanel provides a test handler you can use for trying your calls. You'll be able to debug your scrip real-time.

Once you test it, you can use it in production together with other API features and frameworks.

Install required packages

Run the following command to install required packages on Ubuntu:

sudo apt-get install intel-media-va-driver-non-free libmfx1

Notice hat they are available on 19.04 and later releases.

Set up Nimble Streamer Transcoder

Follow Transcoder Ubuntu installation procedure to install it on your server.
Use Ubuntu 18.04 instruction there as it works fine on 19.04.

This articles describes how to use this encoder: H.264/AVC QuickSync encoder parameters.
After that you'll be all set to use Intel acceleration on Ubuntu with our live Transcoder.

If you face any questions, feel free to contact us for any questions.

Related documentation

Related documentation

1. Set up Certbot

2. Set up certificate

3. Set up certificate renewal

Related documentation

ABR capabilities

SLDP and ABR setup

SLDP Player usage

Set up Advertizer

Set up Nimble API

Use markers insertion

Related documentation

Enable the DVB subtitles processing for MPEG2TS and HLS streams

Passing DVB subtitles through Live Transcoder

Related documentation

Enable RTMP Icecast metadata

Set up Transcoder

Related documentation

Related documentation

1. Enable RTMP Icecast metadata

2. Enable Nimble API

3. Perform the injection

Further usage

Related documentation

1. Create a processing script

2. Set up API in WMSPanel

3. Test the complete solution

Related documentation

Install required packages

Set up Nimble Streamer Transcoder

Related documentation

Related documentation