Skip to main content

Configuration File Explanation

ZLMediaKitAbout 11 min

#!!!! This configuration file is an example configuration file intended to inform the reader about the specific meanings and functions of each configuration item.
#!!!! When executing cmake, this configuration file will be copied to the release/${operating_system_type}/${build_type} (e.g., release/linux/Debug) folder.
#!!!! This folder (release/${operating_system_type}/${build_type}) is also the target path for generating executable programs. When executing the MediaServer process, it will default to load the config.ini file in the same directory as the configuration file.
#!!!! If you modify this example configuration file (conf/config.ini), it will not be loaded by the MediaServer process because the MediaServer process defaults to loading release/${operating_system_type}/${build_type}/config.ini.
#!!!! Of course, every time you execute cmake, this file will indeed be copied to release/${operating_system_type}/${build_type}/config.ini,
#!!!! but it is generally recommended that you directly modify the release/${operating_system_type}/${build_type}/config.ini file. Modifying this file generally does not take effect unless you use the -c parameter to specify this file when running MediaServer.

# Whether to debug the HTTP API. When enabled, it will print the content and response of each HTTP request.
# Some sensitive HTTP APIs require a secret for access. If accessing through, the secret can be omitted.
# Root directory for saving screenshots generated and obtained through the HTTP API (/index/api/getSnap).
# Default snapshot image. When FFmpeg is started for screenshotting but the screenshot has not been generated yet, the default preset image can be returned.

# Path to the FFmpeg executable program, supports relative or absolute paths.
# Command template for pulling and pushing streams with FFmpeg. This template allows setting some parameters for re-encoding.
cmd=%s -re -i %s -c:a aac -strict -2 -ar 44100 -ab 48k -c:v libx264 -f flv %s
# Command for generating snapshots with FFmpeg. The configuration can be modified to change the resolution or quality of the snapshots.
snap=%s -i %s -y -f mjpeg -frames:v 1 %s
# Path for FFmpeg logs. Leaving it empty will disable FFmpeg logging.
# It can be a relative path (relative to the executable program directory) or an absolute path.
# Automatic restart time (in seconds), default is 0, which means no automatic restart. It is mainly used to avoid synchronization issues caused by long-term FFmpeg pulling of streams.

# Switches related to protocol conversion; if the addStreamProxy API and on_publish hook response do not specify the protocol conversion parameters, these configuration items will be used.
# When converting protocols, whether to enable frame-level timestamp overlay.
# 0: Use the absolute timestamp of the source video stream without any changes.
# 1: Use the system timestamp when receiving data in ZLMediaKit (smoothed processing).
# 2: Use the relative timestamp (increment) of the source video stream, with timestamp jump and rollback correction.
# Whether to enable audio during protocol conversion.
# Add silent audio (ACC) when audio is disabled. This switch is invalid when audio is closed.
# Whether to directly close when there are no viewers (instead of returning close through the on_none_reader hook).
# When this configuration is set to 1, if there are no viewers for this stream, the on_none_reader hook callback will not be triggered,
# but the stream will be closed directly.

# After a push is disconnected, it can reconnect and continue pushing within the timeout period, so that the player can continue playing.
# Set it to 0 to disable this feature (disconnection of the push will immediately disconnect the player).
# This parameter should not exceed the player's timeout period; unit: milliseconds.

# Whether to enable conversion to HLS (MPEG-TS).
# Whether to enable conversion to HLS (fMP4).
# Whether to enable MP4 recording.
# Whether to enable conversion to RTSP/WebRTC.
# Whether to enable conversion to RTMP/FLV.
# Whether to enable conversion to HTTP-TS/WS-TS.
# Whether to enable conversion to HTTP-fMP4/WS-fMP4

# Whether to treat mp4 recording as a player
# Maximum duration of mp4 segments in seconds
# Path to save mp4 recordings

# Path to save hls recordings

###### The following are protocol conversion switches. When testing the receiving and streaming performance of ZLMediaKit, please set the switches below to 1.
###### If you don't need a certain protocol, you can set the corresponding switch to 1 to save resources (but it can still be played, although the experience for the first player may be slightly worse),
###### If you want the best user experience for a certain protocol, please set the switch to 0 (the first player can start instantly without screen flickering).
# Whether to generate hls protocol on-demand. If hls.segNum is configured as 0 (meaning hls recording), hls will always be generated regardless of this switch.
# Whether to generate rtsp[s] protocol on-demand
# Whether to generate rtmp[s], http[s]-flv, ws[s]-flv protocols on-demand
# Whether to generate http[s]-ts protocol on-demand
# Whether to generate http[s]-fmp4, ws[s]-fmp4 protocols on-demand

# Whether to enable virtual hosting
# The hook.on_flow_report event will be triggered when a player or pusher is disconnected, indicating the amount of traffic used.
# The flowThreshold parameter controls the threshold for triggering the hook.on_flow_report event. It will only be triggered when the traffic usage exceeds this threshold, in kilobytes.
# Maximum waiting time for playback, in milliseconds.
# When playing a stream, if the stream does not exist,
# ZLMediaKit will allow the player to wait for a maximum of maxStreamWaitMS milliseconds.
# If the stream is successfully registered within this time, playback will start immediately.
# Otherwise, the player will receive a response indicating that the stream was not found. This mechanism allows playback before pushing the stream.
# Maximum waiting time for triggering the hook.on_stream_none_reader event when a stream has no viewers, in milliseconds.
# In conjunction with the hook.on_stream_none_reader event, it can automatically stop pulling or receiving streams when there are no viewers.
# When replaying a stream agent, whether to delete the previous media stream data after successful reconnection.
# If deleted, the playback will start from the beginning;
# if not deleted, it will continue writing from where it left off (for HLS/MP4 recording, it will continue writing at the end of the previous file).
# Merge write buffer size in milliseconds. Merging write means that the server caches a certain amount of data before writing it to the socket at once, which can improve performance but increases latency.
# When enabled, TCP_NODELAY will be disabled and MSG_MORE will be enabled.
# Unique ID of the server, used to differentiate which server triggers the hook event.

# Maximum waiting time for uninitialized tracks, in milliseconds. After the timeout, uninitialized tracks will be ignored.
# If a stream has only one track, maximum waiting time in milliseconds. If no data from other tracks is received after the timeout, it will be considered a single-track stream.
# This waiting time is not applicable if the protocol metadata declares a specific number of tracks.
# If a track is not ready, we cache frame data, but with a maximum number of frames to prevent memory overflow.

# Buffer size for writing HLS files, adjusting this parameter can improve file I/O performance
# Maximum duration of HLS segments
# Number of retained segments in the m3u8 index (typically 2-3 segments more than actually retained)
# If set to 0, segments will not be deleted and will be saved for on-demand playback
# Number of segments retained on disk after being removed from the m3u8 file
# Whether to broadcast a notification when HLS segments (ts/fmp4) are completed (on_record_ts)
# Delay for deleting live HLS files, in seconds, issue: #913
# Whether to retain HLS files. This function is partially equivalent to segNum=0,
# but the retained files will not be reflected in the m3u8 file.
# 0 means not retaining, not effective
# 1 means retaining, HLS files will not be deleted. If this function is enabled, be aware of disk size or manually clean up HLS files regularly.

# Whether to enable hook events, when enabled, both pulling and pushing streams require authentication
# Traffic event used by player or streamer, leave blank to disable
# HTTP file access authentication event, leave blank to disable authentication
# Playback authentication event, leave blank to disable authentication
# Publishing authentication event, leave blank to disable authentication
# Recording of mp4 segments completed event
# Recording of hls ts (or fmp4) segments completed event
# RTSP playback authentication event, in this event, RTSP username and password are compared
# Whether to enable exclusive RTSP authentication event, leave blank to disable RTSP authentication.
# RTSP playback authentication also supports authentication through URL.
# It is recommended to use URL parameter authentication uniformly.
# After enabling exclusive RTSP authentication, on_play authentication event will no longer be triggered.
# Remote telnet debugging authentication event
# Live stream registration or deregistration event
# Filter the protocol types of on_stream_changed hook, you can choose to only listen to certain interested protocols; leave blank to not filter protocols
# Event for streams with no viewers, through this event, you can choose to close streams with no viewers. Use together with general.streamNoneReaderDelayMS option.
# Event for stream not found during playback, by combining with hook.on_stream_none_reader event, on-demand streaming can be achieved
# Server startup report, can be used to listen for server crash and restart events
# Server exit report, triggered when the server exits normally
# Server keep-alive report
# Callback when sending rtp (startSendRtp) is stopped passively
# RTP server timeout, no data received

# Maximum waiting time for hook API response, in seconds
# Interval for keepalive hook triggering, in seconds, float type
# Number of retries for failed hook notifications, positive integer. 0 means no retries, 1 means retry once, and so on
# Hook notification failure retry delay, in seconds, float type

# Set the template for the source stream URL, similar to printf format. The first %s specifies the app, and the second %s specifies the stream_id.
# The on_stream_not_found and on_stream_none_reader hooks will be invalid when the cluster mode is enabled.
# The following types are supported for source tracing:
# rtmp: rtmp://
# rtsp: rtsp://
# hls:
# http-ts:
# Multiple source URLs are supported, and different URLs are separated by semicolons (;)
# Total timeout duration for source tracing, in seconds, float type. If there are 3 source URLs, the timeout for each trace will be timeout_sec divided by 3.
# The timeout for each trace should not exceed the general.maxStreamWaitMS configuration.
# Number of retries for source tracing failure. Set to -1 for unlimited retries.

# HTTP server character encoding. Default is gb2312 on Windows.
# HTTP connection timeout
# Maximum number of bytes for the HTTP request body. If the POST body is too large, it is not suitable to cache the body in memory.
# 404 page content. Users can customize the 404 page.
# notFound = <html><head><title>404 Not Found</title></head><body bgcolor="white"><center><h1>The resource you requested does not exist!</h1></center><hr><center>ZLMediaKit-4.0</center></body></html>
# HTTP server listening port
# Root directory for the HTTP file server.
# It can be a relative path (relative to the executable program directory) or an absolute path.
# Read file cache size for the HTTP file server, in bytes. Adjusting this parameter can optimize file I/O performance.
# HTTPS server listening port
# Whether to display the folder menu. Enabling this allows browsing of folders.
# Virtual directories. Separate virtual directory names and file paths with commas (,). Separate multiple configurations with semicolons (;).
# For example, if assigned as app_a,/path/to/a;app_b,/path/to/b, then
# accessing corresponds to the file path /path/to/a/file_a
# accessing corresponds to the file path /path/to/b/file_b
# Accessing other HTTP paths will correspond to file paths within rootPath.
# Disable mmap caching for files with specified file extensions. Separate extensions with commas (,).
# For example, if assigned as .mp4,.flv, then files with .mp4 and .flv extensions will not be cached.
# You can put the real client IP before the HTTP proxy in the HTTP header:
# Do not expose this key, as it may cause client IP forgery.
# Allow all cross-origin requests by default
# IP address whitelist for accessing HTTP API and HTTP file indexing. Leave it empty for no restrictions.

# The maximum multicast IP address for RTP multicast
# The minimum multicast IP address for RTP multicast
# Multicast UDP TTL

# Application name for MP4 recording or MP4 on-demand. Restricting the application name can prevent arbitrary on-demand requests.
# On-demand files must be placed in this folder.
# MP4 recording file write buffer size in bytes. Adjusting this parameter can improve file I/O performance.
# Amount of data streamed per request for MP4 on-demand, in milliseconds.
# Reducing this value can make the streaming data smoother, while increasing it conserves CPU resources.
# Whether to write a secondary keyframe index into the header after MP4 recording is completed.
# Whether to loop play the MP4 file for MP4 on-demand (rtsp/rtmp/http-flv/ws-flv).

# The RTMP handshake must be completed within this time, otherwise the server will disconnect the connection. Measured in seconds.
# RTMP timeout. If no data is received from the client within this time,
# or if the TCP send buffer exceeds this time, the connection will be disconnected. Measured in seconds.
# RTMP server listening port.
# RTMPS server listening address.

# Audio Maximum Transmission Unit (MTU) size. This parameter limits the maximum number of bytes in RTP packets. It is recommended not to exceed 1400.
# Increasing this value will significantly increase the latency of the live stream.
# Video Maximum Transmission Unit (MTU) size. This parameter limits the maximum number of bytes in RTP packets. It is recommended not to exceed 1400.
# Maximum length limit of RTP packets, in kilobytes. It is mainly used to identify incorrect RTP packets when TCP context is disrupted.
# When packaging RTP, the low-latency switch. It is disabled by default (set to 0). In the case of H.264 where one frame contains multiple slices (NAL units), enabling this may cause screen flickering.
# Whether to use the stap-a mode for H.264 RTP packetization (for compatibility with older versions of browsers) or to use the Single NAL unit packet per H.264 mode.
# Some older RTSP devices do not support stap-a RTP. Setting this configuration to 0 can improve compatibility.

# Export debug data (including rtp/ps/h264) to this directory, leave blank to disable data export
# UDP and TCP proxy servers, support rtp (must be ts or ps type) proxy
# rtp timeout in seconds
# Random port range, ensuring a minimum of 36 ports
# This range also limits the udp port range of the rtsp server
# pt for rtp h264 payload
# pt for rtp h265 payload
# pt for rtp ps payload
# pt for rtp opus payload
# Whether to enable RtpSender's gop cache optimization for instant play experience, enabled by default
# Set to 0 to save memory if startSendRtp related interfaces are not called

# rtc play and publish timeout in seconds
# The visible IP of this machine to rtc clients, usually the public IP when acting as a server, can have multiple IPs separated by ','
# Also supports environment variables starting with '$', such as "$EXTERN_IP"; please refer to:
# rtc udp server listening port, all rtc clients will transmit stun/dtls/srtp/srtcp data through this port
# This port is multi-threaded and supports connection migration due to client network switching
# Note that if the server is inside NAT and needs port mapping, the external mapped port must be consistent with this port
# rtc tcp server listening port, in case udp is not available, tcp will be used to transmit data
# This port is multi-threaded and supports connection migration due to client network switching
# Note that if the server is inside NAT and needs port mapping, the external mapped port must be consistent with this port
tcpPort = 8000
# Set the remb bit rate, when non-zero, twcc is turned off and remb is turned on. This setting is effective for rtc publishing and can control the streaming quality
# Currently, twcc automatic bitrate adjustment has been implemented and remb is closed to adjust the bitrate according to the real network conditions
# Supported audio codec types for rtc, higher priority in front
# The following example includes all supported audio codecs
# Supported video codec types for rtc, higher priority in front
# The following example includes all supported video codecs

# srt play and publish timeout in seconds
# srt udp server listening port, all srt clients will transmit srt data through this port
# This port is multi-threaded and supports connection migration due to client network switching
# Estimation parameter for latency cache in srt protocol, estimating rtt in handshake stage, then latencyMul*rtt becomes the maximum cache duration
# The larger this parameter, the longer the waiting time for retransmission
# Packet buffer size

# Whether to use base64 or md5 for rtsp specific authentication
# Whether the rtsp pull and push proxy is in direct proxy mode
# When in direct proxy mode, it supports any encoding format, but it will cause the GOP cache unable to locate the I frame, which may cause screen flickering when starting broadcasting
# And if it is pulling with tcp, if rtp is larger than mtu, it will not be able to use udp proxy
# Suppose your pull source address is not 264 or 265 or AAC, then you can use direct proxy mode to support rtsp proxy
# If you are doing rtsp push and pull, but playing with webrtc, it is also recommended to disable direct proxy mode,
# because when in direct proxy mode, there may be no sps pps in rtp, which will prevent webrtc from playing; in addition, webrtc does not support Single NAL Unit Packets type rtp
# Direct proxy mode for rtsp is enabled by default, rtmp is forced to enable direct proxy mode because it doesn't have these issues
# The rtsp handshake must be completed within this time, otherwise the server will disconnect the connection, in seconds
# rtsp timeout, if no data is received from the client within this time,
# or if the tcp send buffer exceeds this time, the connection will be disconnected, in seconds
# RTSP server listening address
# RTSPS server listening address
# Whether to use low latency mode for RTSP forwarding. When enabled, RTP packets will not be cached, improving concurrency and reducing the latency of one frame.
# Force negotiation of RTP transmission method (0: TCP, 1: UDP, 2: MULTICAST, -1: no restriction)
# When the client initiates an RTSP SETUP and the transport type is inconsistent with this configuration, return 461 Unsupported transport
# Force the client to re-SETUP and switch to the corresponding protocol. Currently supported by FFMPEG and VLC.
# Maximum buffer size for receiving requests from the telnet server in debug mode
# Telnet server listening port in debug mode

You can also refer to HTTP-HOOK-API Supported by MediaServer for configuration related to hooks.