Nimble Streamer is a versatile media server software that can be used to transform media files and live content into continuous live streams via Nimble Streamer. The software comes with a playlist feature that allows you to create live streams by composing VOD files and live content into playout streams.
The playlists are composed of tasks that describe outgoing live streams, each with a set of content blocks. Blocks are played one after another based on their respective start times, and each task can have a set of streams, either VOD or live, to be played. The JSON playlist config can be updated at any time and is synchronized with Nimble Streamer at a designated interval. The Nimble Streamer API allows users to get the current status of generated streams.
Using server playlists requires some preliminary steps, but the software’s versatility makes it a powerful tool for transforming media files and live content into continuous live streams. Proper preparation of input files and streams is necessary to ensure compatibility and optimal playback. Overall, Nimble Streamer’s playlist feature is a robust and convenient way to create live streams from VOD files and live content.
The workflow for Nimble Playout (Server Playlist) is straight-forward.
- Prepare files and/or input streams for further live streaming.
- Create JSON playlist which contains description of generated output live streams and their respective files’ playback scenarios.
- Create Live Transcoder scenarios to re-align output if needed.
- Configure Nimble Streamer to use the designated JSON playlist.
- Nimble instance generates output live steams according to playlist.
- You can update the playlist any moment, it will be picked up by Nimble within playlist sync interval.
Please take a look at a simple example of Server playlist usage: Generate NDI stream from local files.
Hint: you can also use our Playout Wizard 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:
- Subscribe to Transcoder license via your WMSPanel account profile.
- 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, 640×360 [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, H.265/HEVC, VP8, VP9 and AV1 video, AAC, MP3 and Opus 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 should not be needed as well.
If you prepare input content and align output properly, you can 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. WebRTC WHEP and NDI outputs can be also generated via transcoder.
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 = http://127.0.0.1:8085/server_playlist.json
orserver_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 intervalperiod.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.
Example
Here’s an example of playlist config, we’ll use it as a reference.
{
"SyncInterval": 1000,
"Tasks": [
{
"Stream": "live/playlist",
"InactivityTimeout": 10,
"Blocks": [
{
"Id": "1",
"Start": "2021-08-01 08:00:00",
"Duration": 90000,
"Streams": [
{
"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"
}
]
},
{
"Id": "2",
"Start": "2021-08-01 09:00:00",
"TotalDuration": 120000,
"DefaultStream": {
"Type": "vod",
"Source": "/home/user/content/default.mp4",
"AudioStreamId": "1",
"VideoStreamId": "2"
},
"Streams": [
{
"Type": "vod",
"Duration": 10000,
"Source": "/home/user/content/intro_video.mp4"
},
{
"Type": "vod",
"Start": 10000,
"Source": "/home/user/content/video3.mp4"
},
{
"Type": "vod",
"Start": 20000,
"Source": "http://s3-us-west-1.amazonaws.com/some-path/bunny.mp4",
"Source_AWS": {"aws_access_key_id":"XXXXXXXXXX", "aws_secret_access_key":"XXXXXXXXXX", "aws_signature_version":"v1"}
},
{
"Type": "live",
"Duration": 600000,
"Source": "live/pregame"
},
{
"Type": "live",
"Source": "live/gamestream"
},
{
"Type": "vod",
"Start": 20000,
"MaxIterations": 100,
"Source": "/home/user/content/video4.mp4",
"Subtitles": [
{
"Code": "eng",
"Name": "English",
"Path": "/path/to/subtitles/file.srt"
}
]
}
]
},
{
"Id": "3",
"Start": "2021-08-01 10:00:00",
"Duration": 60000,
"Streams": [
{
"Type": "vod",
"Start": 0,
"Duration": 600000,
"MaxIterations": 0,
"Source": "/test/content/mp4/sample.mp4",
"Scte35Markers": [
{
"Start": "2023-11-03 04:00:00",
"Type": "Out",
"Duration": 2000
},
{
"Start": "2023-11-03 04:00:02",
"Type": "In"
}
]
}
]
}
]
},
{
"Stream": "live/radio",
"Blocks": [
{
"Id": "10",
"Start": "2021-08-01 08:00:00",
"MaxIterations": 2,
"DefaultStream": {
"Type": "live",
"Source": "live/default",
"StreamTitle": "Default track title",
"StreamUrl": "https://yoururl/default"
},
"Streams": [
{
"Type": "vod",
"Source": "/home/user/content/audio1.mp4"
},
{
"Type": "vod",
"Source": "/home/user/content/audio2.mp4",
"StreamTitle": "Track title",
"StreamUrl": "https://yoururl/stream2"
},
{
"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 the “vod” type, it can be either a path to a local file or an HTTP(S) URL pointing to an MP4 file.
In the case of local file, make sure that Nimble has read access to it. Notice that the file path format is platform-specific.
If a file is specified via the HTTP(S) URL, then it will be downloaded and stored in Nimble’s cache. Also in case of HTTP(S) source, the AWS S3 Authorization can be used via the Source_AWS object, added in Source object and delimited by a comma. Source_AWS has three key-value pairs: aws_access_key_id, aws_secret_access_key, and aws_signature_version. Each of these key-value pairs represents a configuration parameter for accessing AWS resources. Please refer to example above to see the usage.
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.
- StreamTitle and StreamUrl are fields for respective metadata of Icecast output.
If you have metadata in VOD source file, Nimble will combine artist and title into icecast StreamTitle. This title will be used by default to update ID3 for HLS audio and produce Icecast StreamTitle. This title will be added as RTMP-Icecast metadata as well, so you can push/pull such RTMP stream with it. You can also transcode playlist streams and Icecast/ID3/RTMP metadata will be preserved.
If you want to override StreamTitle and StreamUrl or define them specifically (e.g. if your files have no metadata), use these params in your stream setting here. - If Type of the stream is “vod” then it can contain “Subtitles” element. It allows inserting WebVTT subtitles into the output. The parameters of Subtitles are as follows.
- Code is the language code like “eng” or “spa”
- Name is the language name, e.g. “English” or “Spanish”
- Path is a local path to a file where the subtitles will be picked up from. The .srt file format is supported.
Please also also visit Nimble subtitles support page for more info in closed captioning.
- Scte35Markers section may contain an array of objects that represent SCTE-35 markers that will appear at a specific time in a stream. Each object must contain the following keys:
- The Start key is used for specifying the starting time of a marker. It could be set as UTC in a “YYYY-MM-DD HH:MM:SS” order or as offset in a file in milliseconds.
- The Type key defines a type of SCTE35 marker. The In or Out values are recognized. In case of Out type, the Duration key defines the duration for a marker in milliseconds.
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 Playout Wizard 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 Playout wizard
You can also use our Playout wizard 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.