Advanced Settings

Core

  • RTMP– The block which holds all RTMP settings.
  • Server- Declares RTMP server instance.
  • Listen- Adds a listening socket for accepting RTMP connections.
  • Application- Creates an RTMP application. Unlike RTMP location, application name cannot be a pattern.
  • Timeout (Socket timeout)- This value is primarily used for writing. Most of time RTMP module does not expect any activity on all sockets except for publisher socket. If you want the broken socket to get quickly disconnected use active tools like keepalive or RTMP ping. The default is 1 minute.
  • Ping (RTMP ping interval)- Zero turns ping off. RTMP ping is a protocol feature for active connection check. A special packet is sent to a remote peer and a reply is expected within a timeout specified with the ping_timeout directive. If ping reply is not received within this time then the connection is closed. The default value for ping is 1 minute. Default ping timeout is 30 seconds.
  • Ping_timeout- See ping description above.
  • Max_streams- Sets the maximum number of RTMP streams. Data streams are multiplexed into a single data stream. Different channels are used for sending commands, audio, video, etc. The default value is 32 which is usually ok for many cases.
  • Ack_window- Sets RTMP acknowledges window size. It’s the number of bytes received after which peer should send acknowledge packet to the remote side. The default value is 5000000.
  • Chunk_size- Maximum chunk size for stream multiplexing. The default is 4096. The bigger the value the lower CPU overhead. This value cannot be less than 128.
  • Max_queue
  • Max_message- The maximum size of the input data message. All input data comes split into messages (and further in chunks). A partial message is kept in memory while waiting for it to complete. In theory, the incoming message can be very large which can be a problem for server stability. Default value 1M is enough for many cases.
  • Buflen- Sets default buffer length. Usually, the client sends the RTMP set_buflen command before playing and resets this setting. The default is 1000 ms.
  • Out_queue
  • Out_cork
  • Access (Allows)- Allow publishing/playing from addresses specified or from all addresses. Allow/deny directives are checked in order of appearance.
  • Deny See allow for description.
  • Exec- Exec_push Specifies external command with arguments to be executed on every stream published. When publishing stops the process is terminated. Full path to binary should be specified as the first argument. There are no assumptions about what this process should do. However, this feature is useful with FFmpeg for stream transcoding. FFmpeg is supposed to connect to RTMP as a client and output transcoded stream back to RTMP as publisher. Shell-style redirects can be specified in the exec_push directive for writing output and accepting input. Make sure there’s no space between redirection character and stream name/number. You can specify the full path to the command to execute or short command name. In the latter case, binary is looked up in directories specified by the PATH environment variable. By default, it clears the environment which will usually make RTMP module run only binaries located in standard directories like /bin and /usr/bin. To make this always work please keep the original PATH variable value with the following directive. The following FFmpeg call transcodes incoming stream to HLS-ready stream (H264/AAC). FFmpeg should be compiled with libx264 & libfaac support for this example to work.
  • Exec_pull- Specifies external command with arguments to be executed on play event. The command is executed when the first client connects to the stream and is killed when the last one disconnects. This directive makes it possible to pull the remote stream in any format for local clients. The feature works reliably only in single-worker mode. The reason for this is we cannot make sure the external process always connects to the right worker. It will obviously connect to a random one. While this will still work in most cases it’s not a recommended architecture, it will be unstable and buggy. Directive arguments are the same as for exec_push. In the above configuration, exec_pull directive serves all streams. That leads to certain limitations on remote stream name format. It should be possible to construct the remote URL using available variables like the $app, $name, etc. When it’s not possible you can add exec_options on a directive which permits setting additional stream options in exec-family directives. The only option supported now is name option.
  • Exec – Exec is an alias of exec_push
  • Exec_options- The directive toggles exec options mode. When activated you can add exec-family directive options. The only exec option supported is name. This option makes it possible to apply exec only to the specified stream. The Default is off.
  • Exec_static- Similar to exec but runs specified command at the start. Does not support substitutions since has no session context.
  • Exec_kill_signal- Sets process termination signal. The default is kill (SIGKILL). You can specify a numeric or symbolic name (for POSIX.1-1990 signals).
  • Respawn- If turned on respawns child process when it’s terminated while publishing is still on. The default is on.
  • Respawn_timeout- Sets respawn timeout to wait before starting a new child instance. The default is 5 seconds.
  • Exec_publish- Specifies external command with arguments to be executed to publish an event. The return code is not analyzed. Substitutions of exec are supported here as well. In addition, the args variable is supported holding query string arguments.
  • Exec_play- Specifies external command with arguments to be executed on play event. The return code is not analyzed. Substitution list is the same as for exec_publish.
  • Exec_play_done- Specifies external command with arguments to be executed on the play_done event. The return code is not analyzed. Substitution list is the same as for exec_publish.
  • Exec_publish_done Specifies external command with arguments to be executed on the publish_done event. The return code is not analyzed. Substitution list is the same as for exec_publish.
  • Exec_record_done Specifies external command with arguments to be executed when recording is finished.
  • Live-¬†Live Toggles live mode i.e., one-to-many broadcasting.
  • Meta (Sets metadata sending mode)- The value of on makes subscribers receive reconstructed metadata packets containing predefined fields like width, height, etc. The value of copy makes clients receive an exact copy of publisher metadata block including both standard and specific fields. The value of off turns off sending any RTMP metadata to subscribers. The defaults to on.
  • Interleave (Toggles interleave mode)- In this mode, audio and video data are transmitted on the same RTMP chunk stream. Defaults to off.
  • Wait_key- Makes video stream start with a keyframe. Defaults to off.
  • Wait_video- Disable audio until the first video frame is sent. Defaults to off. Can be combined with wait_key to make client receive video keyframe with all other data following it. However, this usually increases connection delay. You can tune keyframe interval in your encoder to reduce the delay. Recent versions of IE need this option to be enabled for normal playback.
  • Publish_notify- Send NetStream.Play.PublishNotify and NetStream.Play.UnpublishNotify to subscribers. Defaults to off.
  • Drop_idle_publisher- Drop publisher connection which has been idle (no audio/video data) within a specified time. The default is off. Note this only works when the connection is in publish mode (after sending publish command).
  • Sync (Synchronize audio and video streams)- If subscriber bandwidth is not enough to receive data at publisher rate, some frames are dropped by the server. This leads to the synchronization problem. When timestamp difference exceeds the value specified as sync argument an absolute frame is sent fixing that. The default is 300ms.
  • Play_restart- If enabled RTMP sends NetStream.Play.Start and NetStream.Play.Stop to each subscriber every time the publisher starts or stops publishing. If disabled each subscriber receives those notifications only at the start and end of playback. The default is off.
  • Idle_streams- If disabled RTMP prevents subscribers from connecting to idle/nonexistent live streams and disconnects all subscribers when stream publisher disconnects. The default is on.
  • Record (Record Toggles record mode)- The stream can be recorded in the FLV file.
  • Record_path- Specifies the record path to put recorded FLV files to.
  • Record_suffix (Sets record file suffix)- Defaults to ‘.FLV’. Record suffix can be a pattern in strftime format.
  • Record_unique- If turned on appends a current timestamp to recorded files. Otherwise, the same file is re-written each time new recording takes place. The default is off.
  • Record_append (Toggles file append mode)- When turned on recorder appends new data to the old file or creates it when it’s missing. There’s no time gap between the old data and the new data in the file. The default is off.
  • Record_lock When turned on currently recorded file gets locked with the fcntl call. That can be checked from elsewhere to find out which file is being recorded. The default is off. On FreeBSD, you can use flock tool to check that. On Linux flock and fcntl are unrelated so you are left with writing a simple script checking file lock status. Here’s an example of such script isunlocked.py.
  • Record_max_size- Set maximum recorded file size.
  • Record_max_frames- Sets the maximum number of video frames per recorded file.
  • Record_interval- Restart recording after this number of milliseconds. Off by default. Zero means no delay between recordings. If record_unique is off then all record fragments are written to the same file. Otherwise, the timestamp is appended which makes files differ (given record_interval is longer than 1 second).
  • Recorder (Create a recorder block)- Multiple recorders can be created within a single application. All the above mentioned recording-related directives can be specified in recorder{} block. All settings are inherited from higher levels.
  • Record_notify- Toggles sending NetStream.Record.Start and NetStream.Record.Stop status messages (onStatus) to the publisher when a specific recorder starts or stops recording file. Status description field holds recorder name (empty for default recorder). Off by default.
  • Video on demand¬† Play- Play FLV or mp4 file from a specified directory or HTTP location. If the argument is prefixed with http:// then it is assumed that file should be downloaded from remote HTTP location before playing. Note playing is not started until the whole file is downloaded. Multiple play locations can be specified in a single play directive. When multiple play directives are specified the location lists are merged and inherited from higher scopes. An attempt to play each location is made until a successful location is found. If such location is not found error status is sent to the client. Indexed FLVs are played with random seek capability. Unindexed FLVs are played with seek/pause disabled (restart-only mode). Use FLV indexer (for example, yamdi) for indexing. If you play FLVs recorded with the record directive please do not forget to index them before playing. They are created unindexed. MP4 files can only be played if both video and audio codec is supported by Rtmp. The most common case is H264/AAC. Playing /var/flvs/dir/file.flv: The two slashes after vod make ffplay use vod and application name and the rest of the URL as playpath.
  • Play_temp_path- Sets location where remote VOD files are stored before playing. Default is /tmp;
  • Play_local_path- Sets location where remote VOD files copied from play_temp_path directory after they are completely downloaded. Empty value disables the feature. By default, it’s empty. The feature can be used for caching remote files locally. This path should be on the same device as play_temp_path.
  • Relay– Pull Creates pull relay. The stream is pulled from a remote machine and becomes available locally. It only happens when at least one player is playing the stream locally. Url syntax: [rtmp://]host[:port][/app[/playpath]]. If the application is missing then the local application name is used. If playpath is missing then current stream name is used instead. If a value for a parameter contains spaces then you should use quotes around the WHOLEkey=value pair like this: ‘pageUrl=FAKE PAGE URL’.
  • Push- Push has the same syntax as a pull. Unlike pull-push directive publishes a stream to the remote server.
  • Push_reconnect- Timeout to wait before reconnecting pushed connection after disconnect. The default is 3 seconds.
  • Session_relay- Toggles session relay mode. In this mode, the relay is destroyed when the connection is closed. When the setting is off relay is destroyed when the stream is closed so that another relay could possibly be created later. The default is off.
  • Notify– On_connect Sets HTTP connection callback. When clients issues connect command an HTTP request is issued asynchronously and command processing is suspended until it returns a result code. If HTTP 2xx code is returned then RTMP session continues. The code of 3xx makes RTMP redirect to another application whose name is taken from the Location HTTP response header. Otherwise, the connection is dropped. Note this directive is not allowed in application scope since the application is still unknown at the connection stage. HTTP request receives a number of arguments. POST method is used with application/x-www-form-urlencoded MIME type. In addition to the above-mentioned items, all arguments passed explicitly to connect command are also sent with the callback. You should distinguish connect arguments from the play/publish arguments. Players usually have a special way of setting connection string separate from the play/publish stream name. As an example, here’s how these arguments are set in JWPlayer FFplay (with librtmp) example
  • On_play- Sets HTTP plays callback. Each time a clients issues play command an HTTP request is issued asynchronously and command processing is suspended until it returns a result code. The HTTP result code is then analyzed. Http request receives a number of arguments. POST method is used with application/x-www-form-urlencoded MIME type. In addition to the above-mentioned items, all arguments passed explicitly to play command are also sent with the callback. For example, if stream is accessed with the URL rtmp://localhost/app/movie?a=100&b=face&foo=bar then a, b & foo are also sent with callback.
  • On_publish- The same as on_play above with the only difference that this directive sets callback on publish command. Instead of a remote pull-push is performed in this case.
  • On_done- Sets play/publish terminate callback. All the above applies here. However, the Http status code is not checked for this callback.
  • On_play_done- Same behavior as on_done but only for play end event.
  • On_publish_done- Same behavior as on_done but only r publish end event.
  • On_record_done- Set record_done callback.
  • On_update- Set update callback. This callback is called with a period of notify_update_timeout. If a request returns HTTP result other than the 2xx connection is terminated. This can be used to synchronize expired sessions.
  • Notify_update_timeout- Sets timeout between on_update callbacks. The default is 30 seconds.
  • Notify_update_strict- Toggles strict mode for on_update callbacks. The default is off. When turned on all connection errors, timeouts, as well as HTTP parse errors and empty responses, are treated as update failures and lead to connection termination. When off only valid HTTP response codes other than 2xx lead to failure.
  • Notify_relay_redirect- Enables local stream redirect for on_play and on_publish remote redirects. The new stream name is an MD5 hash of RTMP URL used for the remote redirect. The default is off.
  • Notify_method- Sets HTTP method for notifications. Default is POST with application/x-www-form-urlencodedcontent type. In certain cases GET is preferable, for example, if you plan to handle the call in http{}section. In this case, you can use arg_* variables to access arguments.
  • HLS– HLS Toggles HLS on the application.
  • HLS_path- Sets HLS playlist and fragment directory. If the directory does not exist it will be created.
  • HLS_fragment- Sets HLS fragment length. Defaults to 5 seconds.
  • HLS_playlist_length- Sets HLS playlist length. Defaults to 30 seconds.
  • HLS_sync- Sets HLS timestamp synchronization threshold. The default is 2ms. This feature prevents crackling noises after conversion from low-resolution RTMP (1KHz) to high-resolution MPEG-TS (90KHz).
  • HLS_continuous- Toggles HLS continuous mode. In this mode, the HLS sequence number is started from where it stopped last time. Old fragments are kept. The default is off.
  • HLS_nested- Toggles HLS nested mode. In this mode, a subdirectory of hls_path is created for each stream. Playlist and fragments are created in that subdirectory. The default is off.
  • HLS_base_url- Sets base URL for HLS playlist items. When empty those items have no prefix and assumed to be at the same location as parent playlist or one level lower when hls_nested is used. This feature applies both to master (variant) and slave HLS playlists. It can let you download the playlist and play it locally since it contains full references to child playlists or fragments. Empty by default.
  • HLS_cleanup- Toggles HLS cleanup. By default, the feature is on. In this mode, the cache manager process removes old HLS fragments and playlists from HLS directory.
  • HLS_fragment_naming- Sets fragment naming mode.
  • HLS_fragment_naming_granularity- Sets granularity for HLS fragment ids. If above zero, changes ids to divide the provided value. The default is zero.
  • HLS_fragment_slicing- Sets fragment slicing mode.
  • HLS_variant- Adds HLS variant entry. When the suffix is matched on stream name then variant playlist is created for the current stream with all entries specified by hls_variant directives in the current application. A stripped name without a suffix is used as a variant stream name. The original stream is processed as usual. Optional parameters following the suffix are appended to EXT-X-STREAM-INF in the m3u8 playlist. See HLS spec. 3.3.10. EXT-X-STREAM-INF for the full list of supported parameters.
  • HLS_type- Sets HLS playlist type specified in X-PLAYLIST-TYPE playlist directive. Live HLS stream is usually played from the current live position which is several fragments to the end of the playlist. Event HLS stream is always played from the start of the playlist. When in event mode make sure playlist length is enough for the whole event. The default
  • HLS_keys- Enables HLS encryption. The AES-128 method is used to encrypt the whole HLS fragments. Off by default. Here’s the example configuration using the HLS encryption. This configuration requires that is built with –with-http_ssl_module for https support.
  • HLS_key_path- Sets the directory where auto-generated HLS keys are saved. Key files have .key extension and pseudo-random 16-byte content created with the OpenSSL RAND_bytes() routine. If the directory does not exist it’s created in runtime. By default, hls_path directory is used for key files. Remember however you should normally restrict access to key files which is easier when these files are stored separately from playlist and fragments.
  • HLS_key_url- Sets URL for HLS key file entries. When empty those items have no prefix and keys are assumed to be at the same location as the playlist. Empty by default.
  • HLS_fragments_per_key- Sets the number of HLS fragments encrypted with the same key. Zero means only one key is created at the publish start and all fragments within the session are encrypted with this key. The default is zero.
  • MPEG-DASH– Dash Toggles MPEG-DASH on the application.
  • Dash_path Sets MPEG-DASH playlist and fragment directory. If the directory does not exist it will be created.
  • Dash_fragment- Sets MPEG-DASH fragment length. Defaults to 5 seconds.
  • Dash_playlist_length- Sets MPEG-DASH playlist length. Defaults to 30 seconds.
  • Dash_nested- Toggles MPEG-DASH nested mode. In this mode, a subdirectory of dash_path is created for each stream. Playlist and fragments are created in that subdirectory. The default is off.
  • Dash_cleanup- Toggles MPEG-DASH cleanup. By default, the feature is on. In this mode, the cache manager process removes old MPEG-DASH fragments and manifests from the MPEG-DASH directory. Init fragments are deleted after stream manifest is deleted.
  • Access log– Access_log Sets access log parameters. Logging is turned on by default. To turn it off use access_log offdirective. By default, access logging is done to the same file as HTTP access logger (logs/access.log). You can specify another log file path in the access_log directive. The second argument is optional. It can be used to specify a logging format by name. See log_format directive for more details about formats.
  • Log_format- Creates named log format. Log formats look very much the same as HTTP log formats.
  • Limits– Max_connections Sets the maximum number of connections for the Rtmp engine. Off by default.
  • Statistics– Statistics The module is the HTTP module unlike all other modules listed here.
  • RTMP_stat- Sets RTMP statistics handler to the current HTTP location. RTMP statistics is a dynamic XML document. To watch this document in browser as XHTML page use rtmp_stat_stylesheet directive.
  • RTMP_stat_stylesheet- Adds XML stylesheet reference to statistics XML to make it viewable in a browser. See RTMP_stat description and example for more information.
  • Multi-worker live streaming– Multi-worker live streaming is implemented by pushing the stream to remain workers.
  • RTMP_auto_push- Toggles auto-push (multi-worker live streaming) mode. The default is off.
  • RTMP_auto_push_reconnect Sets auto-push reconnect timeout when a worker is killed. The default is 100 milliseconds.
  • RTMP_socket_dir- Sets directory for UNIX domains sockets used for stream pushing. The default is /tmp.
  • Control– The control module is the HTTP module and should be located within http{} block.
  • RTMP_control Sets RTMP control handler to the current HTTP location.