Playlist Generator
Command Line Arguments
–help, -h
Print the help to the console and exit.
–version, -v
Print the version to the console and exit.
–config-file, -c
Default value: /etc/fhls.json
The path to the configuration file.
–log-config, -l
Default value: fhls.log.json
The path to the logging configuration file.
–log-file
Default value: fhls.log
The logger output file. This option is ignored if –log-config is specified.
Configuration File
The default configuration file location: /opt/smartlabs/smartmedia/plgen/config/config.json
core, section
The basic process settings
threads, integer
Default value: 5
The number of operating system threads to process incoming requests.
interface, string
Default value: 0.0.0.0
The interface to listen for incoming FastCGI connections.
port, integer
Default value: 9000
The port for incoming FastCGI connections.
user, string
The name of the user the rights of which will be delegated to the smplgen process.
If no parameter value is specified (an empty string), the process is delegated the rights of the user group that started it.
group, string
The name of the group the rights of which will be delegated to the smplgen process.
If no parameter value is specified (an empty string), the process is delegated the rights of the user group that started it.
rpc_port, integer
Default value: 0
The port for JsonRPC clients to connect. If the value is “0”, JsonRPC is disabled.
rpc_event_queue_size, integer
Default value: 1000
The size of the RPC message queue to send. If the queue size is too small and the polling period is too long, some messages may be lost.
behavior_stat, boolean
Default value: false
Collection and processing of user request statistics. Setfalse to disable statistics collection and true to enable.
behavior_stat_limit_sec, integer
Default value: 0
Limit the storage time of records on the user request statistics (in seconds, 0 — unlimited).
behavior_stat_limit_size, integer
Default value: 100
Limit the number of records for one user receiving request statistics (0 — do not save statistics, the service launch without restrictions is not provided).
mongo, section
MongoDB access settings for playlist generation.
uri, string
MongoDB connection URI.
db, string
Database name.
channels_table
Name of the table that stores information about recorded and deleted channels.
channels_db
Name of the database that stores information about recorded and deleted channels.
events_table
The name of the table containing events to be added to the playlist.
content, section
Playlist generation settings which are common for all playlist types.
range_request_max_sec, integer
Default value: 36000
The maximum time (in seconds) the client can request for Range/Live.
range_availability_fraction, float
Type: float
Default value: 0.7
The content proportion required for a positive response to the HTTP Redirector request about content availability.
max_live_gap, integer
Default value: 60
The time (in seconds) since the last record available for content after which the Live stream is considered to be lost.
havecontent_add_cost, boolean
Default value: false
Whether to add the content cost value in response to the havecontent request on this server.
havecontent_cost, integer
Default value: 0
The cost of content on this server.
enable_thumbnails_in_playlists
Default value: false
Whether to add thumbnail descriptions to the playlist. Thumbnais can be used by players for preview purposes during positioning.
hls, section
Playlist generation settings for HLS content.
uri_path, string
The URI base path for HLS content requests processing. If not specified, requests are not processed.
live_max_chunks, integer
Default value: 10
The maximum number of chunks in the Live playlist.
live_max_iframes_chunks, integer
Default value: hls → chunk_duration × hls → live_max_chunks × 2
The maximum number of chunks in the Live playlist containing rewind data.
live_playlist_rebound_sec, integer
Default value: 10
The time lag (in seconds) of the first chunk when generating the Live playlist.
empty_playlist_404, boolean
Default value: true
Whether to return HTTP error 404 instead of empty playlists.
enable_discontinuity_at_start, boolean
Default value: false
Prevents adding an EXT-X-DISCONTINUITY tag to the playlist before the first chunk when generating a playlist.
playlist_content_type_mpegurl, boolean
Default value: false
Whether to return the appropriate Content-Type for playlists.
key_url, string
Set of values name (DRM name) + url (mask). Allows to generate encryption key URL depending on the requested DRM server.
key_url_drm_name_param, string
Default value: drm_name
The name of the HTTP GET request parameter, in which the name of the requested DRM server is sent.
playlist_version_header_name, string
The name of the HTTP header, in which the required HLS protocol version will be sent.
playlist_version_get_param, string
The name of the HTTP GET request parameter, in which the required HLS protocol version will be sent.
closefull_delay_sec, integer
Default value: 40
The utcend value lagging behind the current time (in seconds) at which the requested closefull playlist will be forcibly closed with the appropriate tag. If the value is 0, the closefull playlist will be opened until the data after the requested range appears.
playlist_variant_desc_sort, boolean
Default value: false
Whether to sort bitrates in variant playlist in descending order.
min_video_duration_sec, float
Type: float
Default value: 0.0
If specified, an HTTP error 404 will be returned instead of a playlist containing one chunk and less than the specified time.
disable_tag_ext_x_map, boolean
Default value: false
The option to prevent adding #EXT-X-MAP tag to playlists.
add_url_params, array of sections
Default value: []
List of sections like
{“name”: “a”, “value”: “b”}
with additional URL parameters that will be added to all URIs in playlists.
ts_uri_prefix_header_name, string
Default value: HTTP_X_SMARTLABS_HLS_URI_PREFIX
The name of the FastGCI parameter, in which the prefix for all file URIs in playlists is sent.
playlist_uri_prefix_header_name, string
Default value: HTTP_X_SMARTLABS_HLS_URI_PREFIX
The name of the FastGCI parameter, in which the prefix for URI playlists in the variant playlist is sent.
recrypt_uri_prefix_header_name, string
Default value: HTTP_X_SMARTLABS_RECRYPT_URI_PREFI
Name of the FastCGI parameter to pass the prefix added to the URI of encrypted chunks in media playlists. It is necessary for the client to request encrypted chunks from the SmartMEDIA Recryptor (smrecrypt) service. The prefix is added only if the chunks are encrypted with the `cenc` scheme for the Widevine DRM, and the client requests a playlist for the Apple FairPlay DRM (re-encryption to the `cbcs` scheme is required) by passing the drm=fairplay parameter in the request.
uri_prefix_without_path, boolean
Default value: false
If the value is true, do not add a relative path to the files’ and playlists’ URI, because it is assumed that the passed parameter already contains the necessary data.
enable_session, boolean
Default value: false
Enables session processing — the request unique identifier to be added to the URI between uri_path and content path.
variant_check_content, boolean
Default value: false
Enables full content check (as with the have_content request from the HTTP Redirector). Can cause a serious slowdown of the server.
enable_version_7, boolean
Default value: true
Enables HLS version 7 support.
enable_vod_offset, boolean
Default value: false
Allows to specify the offset parameter in the URL for VOD content — the offset from the beginning of the TV program in seconds.
disable_discontinuity_sequence, boolean
Default value: false
Flag to prohibit the use of the tag #EXT-X-DISCONTINUITY-SEQUENCE when playlist generation.
enable_discontinuity_on_key_rotation, boolean
Default value: true
Flag to add the tag #EXT-X-DISCONTINUITY at the time of changing the encryption keys.
enable_events, boolean
Default value: true
Flag to add information about events into the HLS playlists.
mongo, section
MongoDB settings for HLS playlist generation.
header_table, string
The collection name where the stream information is stored (works only if MongoDB access is configured in the “core” section).
index_table, string
The collection name where the chunks information is stored (works only if MongoDB access is configured in the “core” section).
dash, section
Playlist generation settings for MPEG-DASH content.
uri_path, string
The URI base path for DASH content requests processing. If not specified, requests are not processed.
playlist_validation, boolean
Default value: false
Whether to test the playlist structure after generation.
min_buffer_time_sec, integer
Default value: 15
The MPD@minBufferTime attribute in the generated playlists, in seconds.
time_shift_buffer_depth, time units
Default value: 30m
The MPD@timeShiftBufferDepth parameter for Live playlist.
max_live_periods, integer
Default value: 2
The maximum number of periods displayed in the Live playlist.
min_period_gap_sec, float
Type: float
Default value: 0.5
If the time (in seconds) between the beginning of the periods for different bitrates (as well as the duration of one period in a particular bitrate) is less than the specified one, such periods will be ignored. The value should not exceed the minimum duration of the chunk in each of the bitrates.
add_http_header_access_control, boolean
Default value: true
Whether to add the Access-Control-Allow-Origin: * parameter to the HTTP header when generating DASH playlists and chunks. Does not work when chunks are returned by the nginx module.
add_presentation_time_offset_utc, boolean
Default value: true
Whether to add to the segments time in the Live DASH playlist a value allowing to bind them to UTC.
ss_dvr_window_duration_sec, integer
Default value: 600
The duration of the generated Live Smooth Streaming playlist, in seconds.
ss_live_look_ahead, integer
Default value: 2
The SmoothStreamingMedia@LookAheadFragmentCount attribute value in Live Smooth Streaming playlists.
ss_live_url, string
Default value: ${dir}/{start time}.mp4
The template for the SmoothStreamingMedia@StreamIndex@Url attribute in Live Smooth Streaming playlists. The substrings in the SmoothStreamingMedia@StreamIndex@Url attribute are replaced as follows:
- ${dir} — relative directory of the recorded track,
- ${timescale} — multiplier to convert time in seconds to relative time units used in playlists (the SmoothStreamingMedia@TimeScale attribute),
- ${bitrate} — track bitrate.
ss_range_url, string
Default value: ${dir}/{start time}.mp4
The template for the SmoothStreamingMedia@StreamIndex@Url attribute in Range Smooth Streaming playlists. The substrings ${dir}, ${timescale}, ${bitrate} in the SmoothStreamingMedia@StreamIndex@Url field are replaced similarly to the dash → ss_live_url parameter.
If the ${offset} substring is present, the time of each chunk in the playlist becomes less than the original by such a value to make the minimum time equal to 0. The ${offset} substring is replaced by this value (in timescale units).
For example, if the original times of the chunks were 1000 2000 3000 4500 6000 7000, the offset will be 1000, and the following times will be recorded in the playlist: 0 1000 2000 3500 5000 6000.
ss_enable_subtitles
Default value: false
Whether to include subtitle tracks to the SmoothStreaming playlists. Some devices, especially SmartTVs don’t support SmoothStreaming playlists with subtitles, so it’s disabled by default.
location, string
The base URL from which the content of the “Location” element in the playlist is generated (by adding the channel name, etc.)
live_playlist_rebound_sec, integer
Default value: 60
If the URL parameter utcstart (see “Additional URL Parameters”) is not specified when requesting the Live playlist, it is calculated as follows:
utcstart = <current_utc_time> – dash → live_playlist_rebound_sec.
live_window_duration_sec, integer
Default value: 120
The maximum total duration of chunks in the Live playlist, in seconds. If this value is exceeded, the chunks from the beginning of the playlist are removed.
live_add_period_duration, boolean
Default value: true
Whether to add Period@duration for all periods of the Live playlist except the last one.
location_header_name, string
Default value: “HTTP_X_SMARTLABS_DASH_LOCATION”
Allows you to set the value of the MPD@Location tag in the HTTP header with the corresponding name.
base_url_header_name, string
Default value: “HTTP_X_SMARTLABS_DASH_BASE_URL”
Allows you to set the value of the MPD@BaseURL tag in the HTTP header with the corresponding name.
ss_enable_adaptive_video, boolean
Default value: false
Enables multibitrate SmoothStreaming playlists generation (compatible with smcvr version 6.1.0 or newer).
utc_timing_path
The base URI path to handle time requests associated with the playlist. If not specified, requests are not processed.
utc_timing_url
The value of the value property of the MPD@UTCTiming tag in the urn:mpeg:dash:utc:http-iso:2014 format. The tag will not be added to the resulting MPD if the property is not set.
suggested_presentation_delay_chunks, integer
Default value: 0
Number (N) of segments for MPD@suggestedPresentationDelay value calculation.
If the value is set, MPD@suggestedPresentationDelay is calculated as a sum of durations of the last N segments. Hence, player receives recommendation to start playback at the certain position, with some offset from Live (but however it can ignore such recommendation).
If the value is zero or not set, the MPD@suggestedPresentationDelay attribute is not added to the playlist and start position is to be chosen only by the player.
availability_time_offset, float
Type: float
If set, the attribute `@availabilityTimeOffset` with the corresponding value is added into the `SegmentTemplate` tag of Live playlists.
ll_suggested_presentation_delay_msec, integer
Default value: 3000
The value of the `MPD@suggestedPresentationDelay` attribute in the low-latency playlists.
enable_events, boolean
Default value: true
Flag to add information about events into the DASH playlists.
always_add_utc_timing
Default value: false
Whether the MPD@UTCTiming tag will be added to the playlist.
If false the MPD@UTCTiming tag will be added to the playlist only when the offset URL parameter is present.
Otherwise, the offset parameter won’t be taken into account.
utc_timing_type
Default value: direct
Defines the format of the MPD@UTCTiming tag:
- the direct value correspond to the urn:mpeg:dash:utc:direct:2014 format, date and time values are added directly to the MPD in the tag’s value;
- the http value corresponds to the urn:mpeg:dash:utc:http-iso:2014 format, date and time should be retrieved with another HTTP request;
- empty value disables the MPD@UTCTiming insertion.
mongo, section
MongoDB settings for MPEG-DASH playlist generation.
header_table, string
The name of the collection with the stream information (works only if MongoDB access is configured in the “core” section).
index_table, string
The name of the table with the chunks information (works only if MongoDB access is configured in the “core” section).
base_url, string
Specifies the content of the BaseURL element in the playlist.
zero_availability, boolean
Default value: false
Whether to set the MPD@availabilityStartTime value to “1970-01-01T00:00:00.000000Z” when generating live playlists (the default MPD@availabilityStartTime value is dependent on the URL parameter utcstart, see “Additional URL Parameters”).
fill_periods_gap, string
Default value: empty string
The way to fill the gap between periods in DASH playlist, if the MongoDB database is used as an index storage.
Possible values are:
- none (or empty string) — do not fill;
- period — add empty period;
- chunks — add empty chunks.
Metadata response (metadata.json) generation settings.
metadata, section
Settings for the metadata response.
events_limit, integer
Default value: 1000
Maximum number of events in the metadata response.
default_features
Array of metadata types to be added to the response by default when the URL argument features is absent.
Possible values are: all, events, thumbnails, urlvariants. Empty (default) value corresponds to all and means that all types will be included:
- events – list of events in the stream, such as advertisements, gaps in the stream and so on;
- thumbnails – thumbnail images, which can be used by players for preview purposes during positioning;
- urlvariants – available variants of the stream. For instance, the stream can be available as DASH and HLS simultaneously, so both options with their corresponding URLs will be listed.
profiles, array of objects
Settings for possible limits for tracks to be embedded into the playlist.
The player can set the limit by passing the HTTP GET parameter profile with one of the unique profile IDs contained in this array.
id, string
Unique profile ID.
parent, string
Unique ID of the parent profile. If a track passes the limits of the current profile, it is checked against the limits set by the parent one. The current profile settings override the parent profile settings. The value can be empty.
min_bitrate, integer
Default value: 0
The minimum possible value of the track bitrate. 0 — no limits.
max_bitrate, integer
Default value: 0
The maximum possible value of the track bitrate. 0 — no limits.
codecs, Array of strings
Regular expressions, to one of which must match the track codec. If the array is empty, then there are no limits for the codec.
zero_availability, boolean
Default value: not specified
Allows to override the zero_availability value for the specified profile.
min_width, integer
Default value: 0
Only for video. The minimum possible frame width. 0 — no limits.
max_width, integer
Default value: 0
Only for video. The maximum possible frame width. 0 — no limits.
min_height, integer
Default value: 0
Only for video. The minimum possible frame height. 0 — no limits.
max_height, integer
Default value: 0
Only for video. The maximum possible frame height. 0 — no limits.
min_sample_rate, integer
Default value: 0
Only for audio. The minimum possible sample rate. 0 — no limits.
max_sample_rate, integer
Default value: 0
Only for audio. The minimum possible sample rate. 0 — no limits.
Example Configuration
|
JSON |
|
{ “core”: { “interface”:“0.0.0.0”, “port”:9001, “threads”:7, “rpc_port”:49966, “rpc_event_queue_size”:10000 }, “content”: { “range_request_max_sec”:72000 } “hls”: { “uri_path”:“/hls”, “playlist_content_type_mpegurl”:false, “live_playlist_rebound_sec”:40, “key_url”: [ { “url”:“http://ya.ru/key?t=${TYPE}&r=${RESOURCE-ID}&p=${POSITION}” }, { “name”:“drm1”, “url”:“http://ya1.ru/key?t=${TYPE}&r=${RESOURCE-ID}&p=${POSITION}” }, { “name”:“drm2”, “url”:“http://ya2.ru/key?t=${TYPE}&r=${RESOURCE-ID}&p=${POSITION}” } ], “key_url_drm_name_param”:“ddrrmm”, “stream_info_before_chunk”:true, “playlist_version_get_param”:“hls_ver”, “add_url_params”: [ { “name”:“abc”, “value”:“123” }, { “name”:“name”, “value”:“value” }, { “name”:“color”, “value”:“red” }, { “name”:“anddd”, “value”:“&&&” } ] }, “dash”: { “uri_path”:“/dash” } } |
HLS / DASH / Smooth Streaming Playlist URL Request Structure
The URL looks schematically as follows:
http[s]://<server_name>[:<port>]/<path>/<content>/<playlist_type>[?<params>]
where:
server_name
The IP address or domain name of the smplgen server.
port
The TCP port of the server.
path
The path specified by the HTTP server settings, which determines the local location of the main directory with the content.
content
The name of the VOD TS file or directory with VOD or Live content.
playlist_type
The playlist type. Possible values are:
- variant.m3u8 — HLS variant playlist for the MPEG2-TS container including links to the possible bitrates and, optionally, rewind data for them;
- playlist.m3u8 — HLS media playlist containing information about media segments;
- iframes.m3u8 — HLS playlist containing information about IFrames (required for rewind);
- subtitles.m3u8 — HLS playlist (only for VOD) with reference to the WebVTT subtitle file;
- audio.m3u8 — HLS playlist (only for VOD) with reference to the AAC+ADTS audio track;
- playlist.mpd — DASH playlist;
- Manifest — Smooth Streaming playlist.
params
Additional parameters depending on the playlist type. See “Additional URL Parameters”.
Additional URL Arguments
offset, integer
Default value: 0
In the case of VOD content, determines from which position (in seconds) to start the generation of the playlist — is set to a positive value. In case of Live content, allows to play the channel with a lag of a predetermined value (in seconds) — is set to a negative value.
havecontent
Required for HTTP Redirector service requests. Instead of the playlist, a fractional number is returned — the proportion of content on this server, or an HTTP error 404, if no content is found.
user_agent, string
Type of player device.
quality, integer
In the case of multibitrate content, indicates the stream with which bandwidth will be the first in the variant playlist. Required for some devices that do not pre-select the bitrate, and always playing the first one in the list.
profile, string
Default value: hls
The profile name, allows to limit the list of bitrates in the variant playlist. The value is written in the following format: “<channel_regex>”: { “bitrates” : {<bitrate_list>}, “devices”: {<devices_list>}}
utcstart, integer (unix timestamp)
Required to request Media and IFrames playlists of the Live stream; defines the time (UTC unix time) at which the player starts viewing content (in fact, it is a session ID, but can be the same for several clients). Must be set based on the lag of the stream from the real time. When requesting a variant playlist for Live content, it can be omitted, but it will automatically be added to Media and IFrames playlist links using the following formula:
<current_time> – hls.live_playlist_rebound_sec
utcend, integer (unix timestamp)
Used in conjunction with the utcstart parameter; allows to get a playlist for recorded PVR-content, limited by time from utcstart to utcend.
closefull
Used in conjunction with the utcstart and utcend parameters to request content when utcend is greater than the current time.
Without this parameter, the server will return a 404 error in most cases because the content is not yet available.
With this parameter, the playlist will not be closed (for HLS — #EXT-X-ENDLIST tag; for DASH — type of the static playlist), if data is still expected in the requested interval.
content_type, string
It can be text or mpegurl, sets the appropriate content type in the response HTTP header. Used for debugging.
forceutctiming
Redefines always_add_utc_timing configuration value and forces adding of MPD@UTCTiming tag into DASH Live manifests regardless of the other URL arguments.
Conflicts with noutctiming argument. Makes sense only for DASH playlists.
noutctiming
Redefines always_add_utc_timing configuration value and forces elimination of MPD@UTCTiming tag in DASH Live manifests.
Conflicts with forceutctiming argument. Makes sense only for DASH playlists.
features, array of strings, comma separated
Contains the list of metadata types which should be included into the response. Makes sense only for metadata requests/responses (metadata.json). Possible values are: all, events, thumbnails, urlvariants.
Can be used for the response size optimization in cases when client needs only metadata of specific type. If the request argument is absent types defined in default_features are used.
Request Types Depending on the Content
VOD
The request of static content (HLS only).
Live
The request of dynamic content that is in the process of recording close to real time.
Range/PVR
The request of previously recorded dynamic content with a certain time interval (specified by the utcstart and utcend parameters).
URL Examples
- http://myserver.com:8080/hls/video.ts/variant.m3u8 — the request of VOD variant playlist;
- http://myserver.com/hls/video.ts/playlist.m3u8?offset=300 — the request of VOD media playlist, in which the first 5 minutes will be skipped;
- https://myserver.com/hls/CHANNEL_1/variant.m3u8 — the request of Live variant playlist;
- http://myserver.com/hls/CHANNEL_1/playlist.m3u8 — the request of Live media playlist;
- http://127.0.0.1/hls/CHANNEL_1/playlist.m3u8?utcstart=1461676000&utcend=1461676600 — the request of media playlist for PVR program with a duration of 10 minutes;
- http://10.65.50.38/dash/cets_2_mp4_test/playlist.mpd?utcstart=1461757800&utcend=1461757900 — the request of DASH playlist for PVR program;
- http://10.65.50.38/dash/CH_RUSSIA24.ism/Manifest — the request of Live Smooth Streaming playlist.