Nimble Streamer configuration

Nimble Streamer general settings are stored in /etc/nimble/nimble.conf file.

Nimble's parameters are either mandatory and included in default setup or optional and may be set up for some features and improvements.


Important: to apply config changes, please re-start Nimble instance by running:

sudo service nimble restart

Mandatory parameters 

Those parameters are set during installation and initial setup.

• port contains port number which Nimble is listening to. Default value is 8081. You may also specify several ports separated by comma (e.g. port = 80, 8081). See also listen_interfaces parameter below.
• worker_threads is described in this article.
• max_cache_size is a maximum size of RAM data cache in megabytes. It's 64 MB by default.
• cache_path is a path to the disk cache storage, with default value /var/cache/nimble.
• max_disk_cache_size is a size of file cache measured in Mb, the default value is 4096 MB.
• panel_domain and panel_port contain URL and port used for syncing with WMSPanel.
• panel_uuid and panel_password has credentials for safe communication with WMSPanel.
• logging is used for getting information about what happens inside of Nimble.

For logging, you may use both Nimble log files and syslog. Possible values for both types are error, info, verbose and debug. The syntax is

logging = file:<value>, syslog:<error>

or

logging = <value>, syslog:<value>

Examples:

logging = info, syslog:error
logging = info, syslog:info
logging = file:info, syslog:error

Please also check access logs section below.

Besides mandatory settings, you may use the following parameters to set up additional features and improvements.

Optional parameters

Some customers need access logs for further analysis. A few parameters can be used for that purpose.

log_access = file, syslog

log_access enables access log. You may set it to be saved to acecss.log file and syslog. You may use these values in any combinations, e.g. specify only syslog.
Access log record contains the following fields:

client_ip - - [date] "request" return_code bytes_received bytes_sent time_to_process_request_in_microseconds "referrer" "user-agent"

Besides connections stats, you can log session the same way. Session log contains one entry for playback session and URL used to open the session. Nimble uses session IDs to track specific player sessions, not just for logs aggregation. It's enabled via log_sessions parameter which works the same way as log_access:

log_sessions = true, syslog

Session log records contains the following fields:

client IP - - [date] "request" return_code "user-agent" session_duration session_id

Log files will be rotated, i.e. you can define max size of each log file and their maximum number.

max_log_file_size

This is the amount of MBs for each log file in rotation.

max_log_files_to_keep

This is the number of log files being kept in rotation.


You may control a maximum life time of VOD disk cache chunks via vod_cache_timeout parameter. The default value is 1 hour so the chunks are stored for an hour after the last request. If you want chunks to be stored for 2 days, just set up this:

vod_cache_timeout = 48

If you need your disk cache to be cleaned up after some minimum amount of time using LRU approach, use vod_cache_min_storage_time parameter which specifies amount of hours for cached item, 1 is the default value. Check VOD cache usage details for more information. If you need LRU time to be set to 2 hours, set it up like this:

vod_cache_min_storage_time = 2

Both vod_cache_timeout and vod_cache_min_storage_time parameters support several measurement units like 10s, 10m, 10h which stand for seconds, minutes and hours respectively. If they are not specified, then hour is the default unit.

In some cases an admin needs to set chunk duration different from default value. This is what vod_chunk_duration parameter is for. You may set amount of seconds for VOD chunks from 1 to 50. Example:

vod_chunk_duration = 3

If you'd like to use RAM cache prior to disk cache in VOD scenarios, use this parameter:

vod_to_ram_cache_first = true

In this case RAM cache will be used until it's full.

To specify how much RAM may be used fo VOD cache, use ram_cache_for_vod_threshold parameter. E.g. 0.5 means 50%:

ram_cache_for_vod_threshold = 0.5

By default, it's 0.8.

Nimble Streamer internal transmuxer buffer sometimes may not be enough to fit generated HLS chunk. This may lead to "[tmux1] E: buffer is too small to generate" error in Nimble Streamer logs. By default the buffer is 64MB. You can increase it using "vod_transmuxing_buffer"

vod_transmuxing_buffer = 128

When streaming VOD HLS, you may need to specify an exact video and/or audio track to use for playback. Nimble Streamer supports MP4 tracks selection for HLS and you may use nimble_video_index and nimble_audio_index parameters for it. If you need to use other parameters' name, please use the following config entries:

nimble_video_index = <name for video>
nimble_audio_index = <name for audio>

E.g.

nimble_audio_index = audioIndex

If you use SRT or WebVTT subtitles file for a VOD file and would like to define default language, use "vod_subtitle_default_language_id" parameter with alpha3 code like this:

vod_subtitle_default_language_id = fra

Read more about VOD subtitles support in Nimble Streamer.


If your media is audio-only, Nimble Streamer produces audio-only HLS with significantly reduced size. However some players require MPEG-TS chunks, e.g. old STBs etc. So we added the following parameter to generate VOD HLS with MPEG-TS chunks.

mpegts_for_audio_vod = true

The mode is created specifically for the mentioned scenario only. In all other cases, this option works the same as default "HLS" option.

By default, Nimble Streamer sets Cache-Control header for playlists and chunks to "no-cache". To change this behavior, use playlist_cache_control and chunk_cache_control parameters and set proper value for it. E.g.

playlist_cache_control = max-age=30
chunk_cache_control = max-age=120

will set 30 seconds as maximum age for playlists cache and 120 seconds for chunks.

There are cases when Nimble Streamer is placed behind the reverse proxy. This is usually done for security reasons. To get IP address of end user for geo stats and hotlinking protection, Nimble needs to process X-Forwarded-For HTTP header for incoming connection. To make it work, you need to add the following parameter.

cdn_origin = true

Nimble Streamer keeps parameters from input URL in HLS and MPEG-DASH playlists so if anything is appended to playback URL, it's added for chunklists and chunks. If you need to stop  passing through parameters, you can disable keep_request_params_enabled parameters which is enabled by default. This will cut off any parameters:

keep_request_params_enabled = false

You may also change Nimble Streamer user agent name for accessing origin server when working as re-streaming edge. Just add this string in the config file:

user_agent = User-Agent-Name

By default, Nimble Streamer listens for incoming client request via the port specified by port parameter on all available interfaces. You may specify exact interfaces to listen at via the listen_interfaces parameter.

listen_interfaces = 127.0.0.1, 172.16.1.9

The default value is plain "listen_interfaces = *".

enable_ipv6 parameter makes Nimble Streamer to support IPv6

enable_ipv6 = true

By default Nimble Streamer checks user session ID against his IP address to avoid fraud. If this needs to be overlapped for telecom-related reasons, you can disable it by setting up this parameter:

restrict_session_ip = false

This will make Nimble skip IP address check for each session. Read the following HLS metrics calculation article for detailed description of this use case among other.

Each streaming session has its ID to handle precise stats calculation and other related capabilities. The default timeout for expiring session IDs is 1 hour, but it is possible to change it using "session_timeout" variable in nimble.conf, e.g.

session_timeout = 60

The value is set in minutes.

When re-streaming content, you may need to pass through headers from player to origin server. Nimble can make a pass-through along with adding headers' prefixes.
To enabled this, add this option:

pass_headers = true

The default prefix is "X-Peer-Header-". If you need to change that, use "passed_header_prefix" parameter:

passed_header_prefix = X-Passthru-

Some scenarios require using absolute paths in playlists and chunk lists, especially when using load balancing techniques. This is what absolute_path parameter is for

absolute_path = <IP>:<port>

If your port is 80 then you may skip :<port> part.

A few parameters about CORS. Several players may require Access-Control-* headers in server responses for controlling cross-origin resources sharing. Use the following parameters for that:

access_control_allow_origin = <some value>
access_control_allow_credentials = <some value>
access_control_expose_headers = <content-length>
access_control_allow_headers = <some value>

Some of possible values are
access_control_allow_origin = *
access_control_allow_credentials = true
access_control_allow_headers = Range
and so on.
Also, some streamer may need to define crossdomain.xml content. Use the following parameter to specify the domain within the XML file which is going to be sent from Nimble Streamer:

crossdomain_xml_allow_access_from_domain = <your.domain>

E.g. crossdomain_xml_allow_access_from_domain = wmspanel.com
You may also define and return an entire file using crossdomain_xml parrameter:

crossdomain_xml = /etc/nimble/crossdomain.xml

Read this CORS-related article for details regarding cross-domain policy.


If you use Nimble Streamer geo-location balancing or WMSAuth geo-location restriction you may set up your Nimble instance to automatically update geo-location database. Just put this parameter into your config:

update_geoip_database = true

Nimble will be checking and updating the geo base once a day.

When using geo and IP-based restriction, Nimble Streamer returns 403 response code if a viewer is not allowed to view the stream via HTTP protocol. If you want to return some other code, use wmsauth_geo_deny_error_code and wmsauth_ip_range_deny_error_code config parameters like this:

wmsauth_geo_deny_error_code = 451
wmsauth_ip_range_deny_error_code = 451

If you need to handle progressive download or re-streaming for any extension other then the extension supported by default, you can use this parameter:

custom_pd_exts = <list>

E.g. "custom_pd_exts = nff,ts" to support .NFF and .TS

If youd like to enable the processing of progressive download from remote HTTP storage, you need to use this parameter:   

enable_pd_for_remote_vod=true

Read this article for more details.

If you process MPEG2TS streams, you may need to set inactivity check interval.

mpegts_inactivity_check_interval = <minutes>

mpegts_inactivity_check_interval = 20 mean stream will be restarted after 3 * mpegts_inactivity_check_interval = 60 seconds.
The problem is in fact sometimes your mpeg2ts streams stop sending data for some period and then start again. This period may be more than default 15 seconds, hence the separate parameter for controlling it.

If you have significant load when processing MPEG2TS, you may want to use

mpeg2ts_camera_threads = <number> 

mpeg2ts_lock_free_enabled = true

Please read this article for more details.

In case of large bitrate streams through UDP via MPEG-TS or RTSP, some customers see artifacts or video freeze. This is described in this FAQ post. This parameter should help:

udp_so_receive_buffer = <UDP buffer in bytes>

Multiple Pull-mode clients may request stream when Nimble Streamer provides SRT in "Listen" mode, so to enable multipoint listener feature by adding this parameter:

srt_multipoint_listener_enabled = true

In some high loaded systems the number of simultaneous RTMP connection can be significant. By default Nimble processes 2500 simultaneous connection per each rtmp working thread, but you can increase/decrease this value with the following parameter:

rtmp_max_viewers = <viewers count>

You can control RTMP working thread count. Read this article for more details on this parameter. You can change this value with the following parameter:

rtmp_working_thread = <working threads>

If you use pull by request with RTMP, you may change the buffer on origin to improve playback experience on edge.

rtmp_buffer_items = <buffer_size>

Read this article for details.


transmuxer_threads parameter sets a number of threads used for processing VOD HLS/MPEG-DASH transmuxing requests. Use it in case you have a high load use cases.

transmuxer_threads = <threads count>

Read this article for more details on this parameter.

If you need to enable EXT-X-PROGRAM-DATE-TIME field for your live HLS streams, you need to set this parameter:

hls_add_program_date_time = true

If you need to enable EXT-X-PROGRAM-DATE-TIME for your DVR chunk lists, you need to add similar parameter:

dvr_hls_add_program_date_time = true

You can get thumbnails of recorded DVR using specific URL and it's always enabled by default. To disable it, use this parameter:

dvr_thumbnails_enabled = false

By default, Apple devices show closed caption button on all for HLS streams. In order to prevent this, HLS spec requires the HLS playlist to include "CLOSED-CAPTIONS=NONE" field for each stream. Use the following parameter to add that field:

hls_add_closed_caption_none = true

Normally Nimble Streamer generates chunk name with the following template: l_<stream_index>_<timestamp>_<number>.ts
To skip stream_index part for certain cases, use

add_stream_index_to_hls_chunk_name = false

With this parameter set to false, different substreams in ABR stream will have the same chunk names (e.g. l_250920_31.ts). It may affect behavior of Apple devices as they look up the same chunk name when switching into another resolution, and play from first present chunk if it was not found (so it "jumps back"). For other device types chunk names don't matter.

If you want to initialize HLS sequence (segment index) based on stream timestamps, enable this parameter:

init_hls_sequence_by_timestamp = true

MPEG-DASH allows specifying certain profile in a manifest. You can use this parameter:

dash_live_profiles = urn:mpeg:dash:profile:isoff-live:2011

That is the default value but you can use any other from the list of supported ones.

A few parameters are available to adjust SLDP support in Nimble Streamer.
Maximum SLDP clients per working thread are set by this:

websocket_live_max_viewers = <working threads>

It's 2500 by default.

SLDP workers count is set here.

websocket_live_worker_threads = <workers count>

Read this article for more details on this parameter.

Important: to apply config changes, please re-start Nimble instance by running:

sudo service nimble restart

Performance tuning

There are several parameters and techniques which can be used for fine tuning of Nimble Streamer performance for live streaming. Read this article to learn more about this.

I you face any issues with Live Transcoder, please follow Troubleshooting Live Transcoder article for more details.



Nimble Streamer has status API for accessing some basic server metrics in real-time. Read this description to see what config parameters changes are needed for that.

If you have any questions or issues regarding Nimble Streamer usage and configuration, feel free to contact us any time.