Server Playlist

Transform media files and live content into continuous live streams via Nimble Streamer

With Nimble Streamer server playlist you can create live streams by composing VOD files and live content into playlists.
The playlist is a JSON file with a simple grammar which allows setting streaming scenarios of various complexity.

The workflow is straight-forward

  1. Prepare files and/or input streams for further live streaming.
  2. Create JSON playlist which contains description of generated output live streams and their respective files' playback scenarios.
  3. Create Live Transcoder scenarios to re-align output if needed.
  4. Configure Nimble Streamer to use the designated JSON playlist.
  5. Nimble instance generates output live steams according to playlist.
  6. You can update the playlist any moment, it will be picked up by Nimble within playlist sync interval.

Take a look at a simple example of Server playlist usage: Generate NDI stream from local files.

Hint: you can also use our Playlist Generator as your every day tool for constructing your playlist.

Nimble Streamer native API allows getting current status of generated streams. Visit Nimble API page to find out more about general API usage and about"Get server playlist current status" method.

Using server playlists requires to complete some preliminary steps.

1. Prepare Nimble Streamer

Upgrade Nimble Streamer to the latest version.

Nimble Live Transcoder is required for using this feature.

  1. Subscribe to Transcoder license via your WMSPanel account profile.
  2. Install Nimble Transcoder on the server where you plan running playlist, and then register the license there.

2. Prepare content

Server playlists may use VOD files and live streams as input.

You need to prepare your content to have the same format.

If you don't prepare input files and streams properly, most players and content providers will not be able to handle such stream properly. Any changes in content parameters like codec, resolution or other parameters mentioned above in preparation section most probably will cause playback issues.

For video the content need to have identical codec, resolution, profile, bitrate, FPS, color scheme, pixel format (e.g. YUV420P, YUV422P, NV12) etc.
For audio it needs to have the same codec, profile e.g. AAC (LC, He, He2), sample rate, bitrate, channel count etc.
If you completed preparation properly, your ffprobe will show identical information for all files like "Video: h264 (High) (avc1 / 0x31637661), yuv420p, 640x360 [SAR 1:1 DAR 16:9], 434 kb/s, 25 fps, 25 tbr, 12800 tbn, 50 tbc (default)".
Only MP4 and MP3 containers are supported with H.264/AVC and H.265/HEVC video, MP3 and AAC audio codecs.

Additional transcoding of output is highly recommended. If some minor content properties do not match, this may still cause inconsistency on recipient side.
If you don't control your viewer setup and environment (e.g. you use several protocols, general-purpose players, CDN distribution etc), it is mandatory to post-process the output.
Use Live Transcoder to re-scale video resolution, apply proper encoder parameters and re-sample audio of your output. Check "Create transcoder scenario to re-align output" section below for more details.

Notice that our engineers provide technical support for server playlist only if your content was properly prepared and the transcoding is applied to output.

You may skip transcoding step if you have simple cases. E.g. if you loop one file then transcoding will be excessive. If you have a set of audio files which have identical content settings, that shouldn't be needed as well.

If you prepare input content and align output properly, you'll be able to play and deliver the resulting live stream via all supported live protocols such as HLS (MPEGTS, fMP4, Low Latency HLS, audio-only), MPEG-DASH, Icecast, MPEG-TS over HTTP, SRT, RTMP, RTSP, RIST and NDI.

But I don't want to prepare content and align it. In this case you'll have to use SLDP. Softvelum SLDP protocol supports changing the content on-the-fly so if you play SLDP with our SLDP players, they will decently handle format change even if you use un-prepared files or if you don't re-align content with Transcoder.
However, we still recommend content preparation to provide better user experience.

3. Enable server playlist processing

You need to use the following two parameters in order to enable server playlist on your Nimble Streamer instance.
Please refer to parameters reference to learn more about how to change Nimble Streamer parameters.

  • server_playlist_sync_url defines the location of server playlist configuration file, either HTTP/HTTPS URL or local file.
    server_playlist_sync_url =
    server_playlist_sync_url = /home/user/config/server_playlist.json
    If the URL doesn't begin with http or https, it's considered as a local file.
  • server_playlist_sync_interval defines synchronization interval for playlist, i.e how often server playlist configuration file will be updated by Nimble Streamer. So playlist update will be applied to Nimble within this time frame. By default it's 10000 milliseconds.
    If playlist task has SyncInterval parameter then SyncInterval will overlap the server_playlist_sync_interval.
    If playlist cannot be found, Nimble will retry every sync interval period.
    server_playlist_sync_interval = 10000

4. Playlist grammar

Server playlist config is a JSON text file. It consists of a number of tasks, each describing one outgoing stream. In addition, you may specify sync interval as described in "Elements of playlist" section further.


Here's an example of playlist config, we'll use it as a reference.

  "SyncInterval": 1000,
      "Stream": "live/playlist",
      "InactivityTimeout": 10,
      "Blocks": [
          "Start":"2021-08-01 08:00:00",
          "Duration": 90000,
            {"Type":"vod", "Duration": 10000, "Source":"/home/user/content/intro_video.mp4"},
            {"Type":"vod", "Start": 10000, "Source":"/home/user/content/video1.mp4"},
            {"Type":"vod", "Start": 20000, "MaxIterations": 100, "Source":"/home/user/content/video2.mp4"}
          "Start":"2021-08-01 09:00:00",
          "TotalDuration": 120000,
          "DefaultStream": {
            "Source": "/home/user/content/default.mp4",
            {"Type":"vod", "Duration": 10000, "Source":"/home/user/content/intro_video.mp4"},
            {"Type":"vod", "Start": 10000, "Source":"/home/user/content/video3.mp4"},
            {"Type":"live", "Duration": 600000, "Source":"live/pregame"},
            {"Type":"live", "Source":"live/gamestream"},
            {"Type":"vod", "Start": 20000, "MaxIterations": 100, "Source":"/home/user/content/video4.mp4"}
      "Stream": "live/radio",
      "Blocks": [
          "Start":"2021-08-01 08:00:00",
          "MaxIterations": 2,
          "DefaultStream": {
            "Source": "live/default"
            {"Type":"vod", "Source":"/home/user/content/audio1.mp4"},
            {"Type":"vod", "Source":"/home/user/content/audio2.mp4"},
            {"Type":"live", "Source":"radio/liveshow"},
            {"Type":"vod", "TotalDuration": 60000, "Source":"/home/user/content/long_audio.mp4"}

Elements of playlist

There are two top-level elements in a playlist:

  • SyncInterval is an optional parameter which defines synchronization interval for playlist in milliseconds. It has the same meaning as server_playlist_sync_interval parameter described above. If SyncInterval is not set then server_playlist_sync_interval value will be used.
  • Tasks element contains an array of tasks, representing outgoing live streams, see description below.

Each task describes one outgoing stream composed with its own individual list of content blocks.
All blocks are played one by one according to their respective start time. When the last block finishes playing, the stream of current task will be terminated after the inactivity timeout is over (see respective element below), unless the next block has arrived and has started playback on its start time.
The following elements are used in a task.

  • Stream element defined the name of outgoing stream. It's composed as "application_name/stream_name". This is how it will be displayed in streaming statistics and will be handled by other features and products like Live Transcoder, Paywall etc.
  • InactivityTimeout sets the time in seconds during which the output stream will remain available after the last block finishes the playback. By default it's 30 seconds. If InactivityTimeout is set to "0" then the output stream will not be terminated due to inactivity.
  • Blocks element contains an array of content blocks which will be played one after another in a queue starting from particular point in time, see description below.
    The content of "Blocks" element can be moved into a separate JSON file, while using BlocksLocation element instead, with full path to this file. Don't forget to put Blocks into {} brackets to make it a valid JSON.

If a task is removed from the playlist, then the output stream will disappear after the next sync-up.

Each block has the following elements:

  • Id is a unique ID of a particular block.
  • Start is GMT time when the block must start playback.
  • MaxIterations: a block can be repeated in a loop multiple times until the next block starts its playback. This parameter defines how many times can it be repeated at most. By default it's 1 unless TotalDuration is not set. If TotalDuration is set then MaxIterations is considered as "endless". If MaxIterations is set to "0" then it's considered as "endless".
  • Duration is a maximum playback duration of current iteration, in milliseconds. Once the duration is reached, the playback starts from the beginning of the block, unless MaxIterations or TotalDuration are reached.
  • TotalDuration defines maximum duration in milliseconds during which the block will be played regardless of number of streams and their duration. When total duration is reached, the block content playback is stopped and the output stream is kept alive within inactivity interval.
  • DefaultStream: if the current live stream which is supposed to be playing now, is unavailable for some reason, you may specify a default stream which will be played instead, see description below.
  • Streams is a list of files and live streams to be played, see detailed description below.

A block is a solid piece and its content must not be changed between updates. If a block needs to be changed then a new ID must be applied to it.
The block which has been played will never be played again.

If both TotalDuration and MaxIterations are specified then the earliest event will take effect.

DefaultStream may have Type parameter be either "live" or "vod". The Source defines where the content is taken from, see Streams elements description below.
Also, for "vod" type, it also supports AudioStreamId and VideoStreamId parameters to select a respective track if a VOD file has several tracks, see Streams elements description below.

Streams element contains the array of "streams", they are descriptors of files and live streams to be played and their respective properties.
One stream is played at a time, and they are played from first one to the last one in the list during an iteration.

Each stream has the following elements:

  • Type is either "vod" for VOD source file, or "live" for live input source stream.
  • Source is a location of original content.
    For "vod" type it's a path to a local file which will be played. Make sure Nimble has read permissions to that file.
    For "live" type it's an source stream name, defined as "application_name/stream_name" as seen in output streams at Nimble Streamer Live Streams page in WMSPanel.
  • Start ("vod" type only) defines the offset in milliseconds where the playback will start from within the specified file. By default it's 0, which means the file will start from the beginning.
  • Duration defines how long a stream will play, in milliseconds. Once the duration is reached or end of file is reached, the playback starts from the beginning of the stream, unless (for "vod" type only) MaxIterations or TotalDuration are reached.
  • MaxIterations ("vod" type only): a stream can be repeated in a loop multiple times. This parameter defines how many times it can be repeated at most. By default it's 1 unless TotalDuration is not set. If TotalDuration is set then MaxIterations is considered as "endless". If MaxIterations is set to "0" then it's considered as "endless".
  • TotalDuration defines maximum duration in milliseconds during which the stream will be played.
    For "live" type it means the same as Duration and if both parameters are set, the one with the smallest value will be used.
    For "vod" type, if MaxIterations is not set while TotalDuration is set then MaxIterations is considered as "endless".
  • If both TotalDuration and MaxIterations are specified for "vod" type then the earliest described event will take effect.
  • AudioStreamId and VideoStreamId ("vod" type only) define tracks' IDs in case a video file has multiple video or audio tracks. By default, tracks 0 will be taken for video and audio. If ID is "-2" then the track will not be played at all.

Key frames notice: the playback transitions from one file to another only at key frames. So block's length may be a few seconds longer due the GOP size of the original content. The same applies to Start parameter of a stream: if the Start offset does not match a key frame then the playback will start from the next nearest key frame.

Hint: you can use our Playlist Generator as your every day tool for easy constructing of your playlists.

5. Create transcoder scenario to re-align output

As described in section 2 above, we highly recommend using Live Transcoder to re-scale video resolution, apply common codec parameters and re-sample audio. Please refer to Live Transcoder documentation reference to learn more about its usage, e.g. watch this overview and read about re-sampling audio.

Basic scenario is shown below. It has video and audio decoders, scale filter to set resolution to 720p, "aformat" to set sample rate and encoders to set proper codecs' parameters.

6. Use Playlist Generator

You can also use our Playlist Generator to construct playlists for Nimble Streamer.

7. Video tutorials

Take a look at these video tutorials showing playlist features and web UI in action:

Contact us to share your use cases, workflow and feature-related feedback.

This website or its third-party tools use cookies, which are necessary to its functioning and required to achieve the purposes illustrated in the Privacy Policy. If you want to know more or withdraw your consent to all or some of the cookies, please refer to the Privacy Policy.
By closing this banner, scrolling this page, clicking a link or continuing to browse otherwise, you agree to the use of cookies.