config.lua

This is the main configuration file for the EMS. This file defines all of the startup parameters used by the server, including the location and names of all of the other configuration files. If you wish to change the name of any of the subsequent configuration files, you can do so here. This file is also just a command-line parameter to the EMS executable. The run-scripts provided with the EMS distribution use this file by default. If you want to change the location or name of this file you can simply modify the run scripts to use a different file.

The EMS configuration file, config.lua, is a hierarchical data structure of assignments (key names with values). It is sent as a parameter when running the EvoStream server. The format is as follows:

• <keyname>= <value>

  where value could be any of the following types:

  • string = series of alpha numeric characters (should be enclosed in double quotes)

    Example:	pushPullPersistenceFile="..\\config\\pushPullSetup.xml",
    

  • number = digits

    ​```
    Example:	streamsExpireTimer=10,
    ​```
    

  • array = list of values (separated by comma and is grouped by braces {}, each value enclosed in double quotes)

    Example:	aliases = {“flvplayback1”, “vod1”, “live”}
    

    ​

• <keyname>= <object>

  where objectis a list of assignments enclosed by braces {}

  configurations =
  {
      daemon = "true",
      pathSeparator = "/",
      logAppenders = {...},
      applications = {...}
  }
  

  Note:

  If you modify this file and the server then fails to start, you have made an error. You can either roll-back your changes or you can use the --use-implicit-console-appender command line parameter to get extra debug information about what failed during startup.

  • For Linux Package:

    cd /usr/bin/evostreamms –use-implicit-console-appender /etc/evostreamms/config.lua
    

    • For Linux Archive:

      cd EMS_INSTALL_DIRECTORY
      ./evostreamms --use-implicit-console-appender ../config/config.lua
      

    • For Windows:

      cd EMS_INSTALL_DIRECTORY
      evostreamms --use-implicit-console-appender config\config.lua
      

  Where:

  EMS_INSTALL_DIRECTORY is the bin directory within the EvoStream Media Server Archive directory.

  1. The “daemon” value is read. The server now will either fork to become daemon or continue as is in console mode.
  2. The “logAppenders” value is read. This is where all log appenders are configured and brought up to running state. Depending on the collection of your log appenders, you may (not) see further log messages.
  3. The “applications” value is taken into consideration. Up until now, the server doesn’t do much. After this stage completes, all the applications are fully functional and the server is online and ready to do stuff.

daemon

For Linux only. If true means the server will start in daemon mode. false means it will start in console mode (nice for development).

Type: Boolean

Mandatory: Yes

daemon = false,

instancesCount

For Linux only. The number of virtual instances of EMS server where load balancing will be performed. If this item is missing, it will be replaced by 0, disabling multiple instances. If its value is -1, it will be replaced by the number of CPUs, enabling one or more additional instances.

Type: Number

Mandatory: Yes

instancesCount=-1

Saying you have a 4-core machine:

instancesCount=0 : 1 origin + 0 edge
  2593 ?        00:00:00 evostreamms
  
instancesCount=1 : 1 origin + 0 edge
  2593 ?        00:00:00 evostreamms

instancesCount=2 : 1 origin + 1 edge 
  2593 ?        00:00:00 evostreamms
  2607 ?        00:00:00 evostreamms
  
instancesCount=3 : 1 origin + 2 edges
  2593 ?        00:00:00 evostreamms
  2607 ?        00:00:00 evostreamms
  2608 ?        00:00:00 evostreamms

instancesCount=4 : 1 origin + 3 edges
  2593 ?        00:00:00 evostreamms
  2607 ?        00:00:00 evostreamms
  2608 ?        00:00:00 evostreamms
  2609 ?        00:00:00 evostreamms

instancesCount=-1 : 1 origin + 3 edges
  2593 ?        00:00:00 evostreamms
  2607 ?        00:00:00 evostreamms
  2608 ?        00:00:00 evostreamms
  2609 ?        00:00:00 evostreamms

pathSeparator

This value will be used by the server to compose paths (like media files paths). Examples: on UNIX-like systems this is / while on windows is . Special care must be taken when you specify this value on windows because \ is an escape sequence for Lua so the value should be “\”.

Type: String

Mandatory: Yes

pathSeparator="/",

logAppenders

This section contains a list of log appenders. The entire collection of appenders listed in this section is loaded inside the logger at config-time. All log messages will be than passed to all these log appenders. Depending on the log level, an appender may (or may not) log the message. “Logging” a message means “saving” it on the specified “media” (in the example below we have a console appender and a file).

Type: Object

Mandatory: Yes

logAppenders=
	{
		{
			name="console appender",
			type="coloredConsole",
			level=6
		},
		{
			name="file appender",
			type="file",
			level=6,
			fileName="..\\logs\\evostream",
			newLineCharacters="\n",
			fileHistorySize=100,
			fileLength=1024*1024,
			singleLine=true,
			clearLogsOnStart=false
		},
	},

Log Appenders Structure Table

Note: When daemon mode is set to true, all console appenders will be ignored..

applications

This section is where all the applications inside the server are placed. It holds the attributes of each application that the server will use to launch them. Each application may have specific attributes that it requires to execute its own functionality.

Below are the objects inside applications:

rootDirectory

The folder containing applications subfolders. If this path begins with a “/” or “” (depending on the OS), then is treated as an absolute path. Otherwise is treated as a path relative to the run-time directory (the place where you started the server).

Type: String

Mandatory: Yes

In Windows:

rootDirectory=".\\",

In Linux:

rootDirectory="./",

appDir

Combined with rootDirectory to form a default base directory for non-absolute paths.

Type: String

Mandatory: Yes

In Windows:

appDir=".\\",

In Linux:

appDir="./",

Note: Be mindful of the application directory when using relative paths. You may misplace your files if you overlooked this setting

name

The name of the server. Could be the name of the company, organization etc.

Type: String

Mandatory: No

name="evostreamms",

description

The description of the “name”.

Type: String

Mandatory: No

description="EVOSTREAM MEDIA SERVER",

default

Selects default application

Type: Boolean

Mandatory: Yes

default=true,

pushPullPersistenceFile

The path of the pushPull configuration file.

Type: String

Mandatory: Yes

pushPullPersistenceFile="..\\config\\pushPullSetup.xml",

authPersistenceFile

The path of the authentication file

Type: String

Mandatory: Yes

authPersistenceFile="..\\config\\auth.xml",

connectionsLimitPersistenceFile

The path of the connection limit file

Type: String

Mandatory: Yes

connectionsLimitPersistenceFile="..\\config\\connlimits.xml",

bandwidthLimitPersistenceFile

The path of the bandwidth limit file

Type: String

Mandatory: Yes

bandwidthLimitPersistenceFile="..\\config\\bandwidthlimits.xml",

ingestPointsPersistenceFile

The path of the ingest points file

Type: String

Mandatory: Yes

ingestPointsPersistenceFile="..\\config\\ingestpoints.xml",

streamsExpireTimer

The number of seconds the EMS will wait for audio/video data from a connected stream before timing out

Type: Number

Mandatory: Yes

streamsExpireTimer=10,

rtcpDetectionInterval

The number of seconds the EMS will wait for RTCP streams in an RTSP session before continuing without them

Type: Number

Mandatory: Yes

rtcpDetectionInterval=15,

hasStreamAliases

Enables or disables stream name aliases

Type: Boolean

Mandatory: Yes

hasStreamAliases=false,

See addStreamAlias

hasIngestPoints

The configuration of the ingest point

Type: Boolean

Mandatory: Yes

hasIngestPoints=false

See createIngestPoint

validateHandshake

Set to false for old Flash players with no RTMP validation handshake

Type: Boolean

Mandatory: Yes

validateHandshake=false,

aliases

The extension of the stream where alias can be added

Type: Array

Mandatory: Yes

aliases={"er", "live", "vod"},

maxRtmpOutBuffer

The maximum amount of bytes the EMS will store in the output RTMP buffer

Type: String

Mandatory: Yes

maxRtmpOutBuffer=512*1024,

maxRtspOutBuffer

The maximum amount of bytes the EMS will store in the output RTSP buffer. Only used for RTSP when the final transport is RTP over TCP

Type: String

Mandatory: Yes

maxRtspOutBuffer=512*1024,

hlsVersion

The HLS version to be used. User should make sure of the version before creating HLS files.

Type: Number

Mandatory: Yes

hlsVersion=6,

Supported versions:

• HLS version 3
• HLS version 4
• HLS version 5
• HLS version 6

For more information about HLS click here.

useSourcePts

If set to true, the outbound stream will use the PTS of the source stream. Otherwise, the pushed stream will start at 0

Type: Boolean

Mandatory: Yes

useSourcePts=false,

enableCheckBandwidth

Reads the bandwidth.xml if set to true

Type: Boolean

Mandatory: Yes

enableCheckBandwidth=true,

See bandwidths.xml

vodRedirectRtmpIp

The IP of the other server where EMS can get the source VOD file.

How it works? The local server will look for video1. When that lookup fails it will get the configuration details set to vodRedirectRtmpIp parameter. If there’s a valid value, the local server makes a pullStream request on the server (vodRedirectRtmpIP value) for video1. The local server then uses that new stream resulting from the pullStream to serve the initial client request.

Type: String

Mandatory: No

vodRedirectRtmpIp="",

Note: This will only access the mediaFolder. Make sure that the VOD files are inside the mediaFolder or else, searching for the source is on loop.

forceRtmpDatarate

Hardcodes videodatarate and audiodatarate to satisfy the requirements for some configurations.

Type: Boolean

Mandatory: Yes

forceRtmpDatarate=false,

sendRtspRangeHeaders

Required for axis camera configuration

Type: Boolean

Mandatory: Yes

sendRtspRangeHeaders=false,

serverNameStreamPrefix

Server name used as prefix for stream name

Type: String

Mandatory: No

serverNameStreamPrefix="",

runWebServer

Enables EMS Web Server on startup

Type: Boolean

Mandatory: Yes

runWebServer=true,

runWebUI

Enables EMS Web UI on startup

Type: Boolean

Mandatory: Yes

runWebUI=true,

mediaStorage

The configuration for the media storage

Type: Object

Mandatory: Yes

mediaStorage = {
				recordedStreamsStorage="../media",
				{
					description="Default media storage",
					mediaFolder="../media",
				},
			},

There are several uses of the media folder:

• Storage of VOD file that is used for pullStream
• Location of the created file using generateLazyPull command
• Storage of recorded streams using record command

Media Structure Table

Other optional parameters:

See addStorage

acceptors

The “acceptors” block is found within the “applications” section named “evostreamms” in the configuration file. Each acceptor protocol used by applications is defined here. Some protocols may require additional parameters.

Type: Object

Mandatory: Yes

-- CLI acceptors
				{
					ip="0.0.0.0",
					port=1112,
					protocol="inboundJsonCli",
					useLengthPadding=true
				},
				{
					ip="0.0.0.0",
					port=7777,
					protocol="inboundHttpJsonCli"
				},
				{
					ip="0.0.0.0",
					port=9999,
					protocol="inboundHttpFmp4" 
				},
				{
					ip="0.0.0.0",
					port=1222,
					protocol="inboundAsciiCli",
					useLengthPadding=true
				},

-- RTMP and clustering
				{
					ip="0.0.0.0",
					port=1935,
					protocol="inboundRtmp",
				},
				{
					ip="127.0.0.1",
					port=1936,
					protocol="inboundRtmp",
					clustering=true
				},
				{
					ip="127.0.0.1",
					port=1113,
					protocol="inboundBinVariant",
					clustering=true
				},

-- RTSP
				{
					ip="0.0.0.0",
					port=5544,
					protocol="inboundRtsp",
					--[[
					multicast=
					{
						ip="224.2.1.39",
						ttl=127,
					}
					]]--
				},

-- LiveFLV ingest
				{
					ip="0.0.0.0",
					port=6666,
					protocol="inboundLiveFlv",
					waitForMetadata=true,
				},

-- Inbound TCP TS
				{
					ip="0.0.0.0",
					port=9998,
					localStreamName="testTcp",
					protocol="inboundTcpTs",
				},

-- Inbound UDP TS
				{
					ip="0.0.0.0",
					port=9898,
					localStreamName="testUdp",
					protocol="inboundUdpTs",
				},

--RTMPS
				{
					ip="0.0.0.0",
					port=4443,
					protocol="inboundRtmp",
					sslKey="/path/to/some/key",
					sslCert="/path/to/some/cert",
				},

-- JSONMETA
				{
					ip="0.0.0.0",
					port=8100,
					--streamname="test",
					protocol="inboundJsonMeta",
				},

-- WebSockets JSON Metadata
				{
					ip="0.0.0.0",
					port=8210,
					protocol="wsJsonMeta",
					-- streamname="~0~0~0~"
				},

-- WebSockets JSON Metadata over SSL
				{
					ip="0.0.0.0",
					port=8433,
					protocol="wssJsonMeta",
					-- streamname="~0~0~0~"
					sslKey="/path/to/some/key",
					sslCert="/path/to/some/cert",
				},

-- WebSockets FMP4 Fetch
				{
					ip="0.0.0.0",
					port=8410,
					protocol="inboundWSFMP4"
				},

-- WebSockets over SSL FMP4 Fetch
				--[[
				{
					ip="0.0.0.0",
					port=8420,
					protocol="inboundWSSFMP4",
					sslKey="/path/to/some/key",
					sslCert="/path/to/some/cert",
				},

Acceptor Structure Table:

The following acceptor types are supported by EMS:

Protocol Group Table:

deviceStreams

—insert definition here

Type: Object

Mandatory: No

deviceStreams=
{
	{
		name="camera01",
		video=
		{
			type="v4l2",
			path="/dev/video0",
		},
		audio=
		{
			type="v4l2",
			path="/dev/video1",
		},
	},
},

deviceStreams Structure Table

autoDASH/HLS/HDS/MSS

If enabled, will automatically create the HTTP streams from the ingested streams.

Type: Object

Mandatory: No

autoDASH=
			{
				targetFolder="path/to/evo-webroot",
			},
autoHLS=
			{
				targetFolder="path/to/evo-webroot",
			},
autoHDS=
			{
				targetFolder="path/to/evo-webroot",
			},
autoMSS=
			{
				targetFolder="path/to/evo-webroot",
			},

Note: You can add other parameters associated with the API. See createDASHStream,createHLSStream, createHDSStream, createMSSStream, for parameter lists but below are the parameters that cannot be modified using auto:

authentication

The authentication settings for RTMP and RTSP protocols. For RTMP, another file, auth.xml, is required to enable authentication. In addition, a users file, typically named users.lua, provides the user names and passwords.

Type: Object

Mandatory: No

authentication=
			{
				rtmp=
				{
					type="adobe",
					encoderAgents=
					{
						"FMLE/3.0 (compatible; FMSc/1.0)",
						"Wirecast/FM 1.0 (compatible; FMSc/1.0)",
						"EvoStream Media Server (www.evostream.com)"
					},
					usersFile="path/to/config/users.lua",
					--verifierUri="http://authserver/verifier.php",
					--token="secretstring",					
				},
				rtsp=
				{
					usersFile="path/to/config/users.lua",
					--authenticatePlay=false,
				}
				--ws=
				--{
				--	token="",
				--},
			},

Authentication Structure Table:

• FOR RTMP

  Key	Type	Mandatory	Description
  type	string	true	“adobe”
  encoderAgents	string	true	The encoder agent/s to be used
  usersFile	string	true	The path to users.lua configuration file
  verifierUri	string	false	The path of the verifier file to be used
  token	string	false	The token to be used for token based authentication. The token is calculated by hashing the secret string, the requested stream name and a unix time. The secret string should match the one in configuration. The unix time should be set in the future.

  RTMP URI with Token Format: rtmp://hostname/streamName?e=ValidUntilUnixTime&h=Token

  Where: Token = MD5 (SecretString + “/” + StreamName + “?e=” + ValidUntilUnixTime)

  Sample: rtmp://127.0.0.1/live/bunny?e=1508895239&h=3C23875455CACF2D44C3608C146D7C87
  

  ​

• FOR RTSP

  Key	Type	Mandatory	Description
  usersFile	string	true	The path to users.lua configuration file
  authenticatePlay	boolean	false	If enabled, the player will ask for a password in every stream request

  ​

• FOR WEBSOCKET

  Key	Type	Mandatory	Description
  token	string	true	The token to be used for token based authentication. The token is calculated by hashing the secret string, the requested stream name and a unix time. The secret string should match the one in configuration. The unix time should be set in the future.

  Where: Token = MD5 (SecretString + “/” + StreamName + “?e=” + ValidUntilUnixTime)

  ​

  Token Authentication The EMS accepts play requests that contains token authenticaion. Prior to serving the requested stream the EMS validates that the timestamp is for a time and date that is in the future. The EMS then recomputes the MD5 hash using the timestamp in the play request with the secret string and validates that the resultant hash value matches the value passed in on the play request. If any validation step fails, the EMS will not serve the requested stream. If all validation steps succeed, the EMS will serve the requested stream to the player.

Notes:

1. Authentication is disabled if the “authentication” block in the “config.lua” file is missing or incomplete. For RTMP protocol, authentication is disabled if the “auth.xml” file is missing or contains a “false” setting. For RTSP protocol, authentication is disabled if “authenticatePlay” in the “rtsp” block is omitted or set to “false”.
2. Scripts are available for creating certificates and keys for EMS. Please refer to our GitHub files here for details.
3. You can use this link for UNIX time conversion.
4. You can use this link for MD5 hash generation.

eventLogger

Settings for the server-wide event sinks. See Events Overview for more details.

Type: Object

Mandatory: No

EMS Events Sinks

A. File

eventLogger=
	{
		--customData=123,
		sinks=
		{
			--[=[
			{
				type="file",
				--[[
				customData=
				{
					some="string",
					number=123.456,
					array={1, 2.345, "Hello world", true, nil}
				},
				]]--
				filename="C:\\EvoStream\\logs\\events.txt",
				format="text",
				--format="xml",
				--format="json",
				--format="w3c",
				--[[
				timestamp=true,
				appendTimestamp=true,
				appendInstance=true,
				fileChunkLength=43200, -- 12 hours (in seconds)
				fileChunkTime="18:00:00",
				]]--
				enabledEvents=
				{	-- common events enabled by default for eventLogger type "file":
					"inStreamCreated",
					"outStreamCreated",
					-- NOTE: add more events by copying items from the sorted list of VALID EVENTS below
				},
			},

Notes:

1. This section is disabled by default.

2. You can add more events in the list of events below

3. The event log files will be stored in the path where EMS logs are configured

4. See list of events here

   ​

File Sink Structure Table:

B. RPC - EvoWebservices

{
		type="RPC",
		url="http://127.0.0.1:4000/evowebservices",
		serializerType="JSON",
		enabledEvents=
		{	-- common events enabled by default for eventLogger type "RPC":
			"inStreamCreated",
			"inStreamClosed",
			"outStreamCreated",
			"outStreamClosed",
			"timerTriggered",
			"hdsMasterPlaylistUpdated",
			"hdsChildPlaylistUpdated",
			"hdsChunkClosed",
			"hdsChunkDeleted",							
			"hlsMasterPlaylistUpdated",
			"hlsChunkClosed",
			"hlsChunkDeleted",									
			"dashPlaylistUpdated",
			"dashChunkClosed",
			"dashChunkDeleted",									
		},
},

Notes:

1. This section is enabled by default.
2. Replace URL depending on the evowebservices to be used (Node.js or PHP). See evowebservices userguide.
3. These are the events are used by EMS webservices, no need to make any changes on this configuration

C. RPC - WebUI

{
	type="RPC",
	url="http://127.0.0.1:4100/streams/update-list",
	serializerType="JSON",
	enabledEvents=
	{	-- common events enabled by default for eventLogger type "RPC":
		"inStreamCreated",
		"inStreamClosed",
		"outStreamCreated",
		"outStreamClosed",
		"processStarted",
		"processStopped",
		"recordChunkCreated",
		"recordChunkClosed",
		"webRtcServiceStarted",
		"webRtcServiceStopped",
	},
}	

Note:

• These events are used by EMS Web UI, no need to make any changes on this configuration

transcoder

Within the application section you can find the configuration for the EvoStream Transcoder. The default settings are generally going to be fine for all applications, but under certain circumstances they may need to be adjusted. The transcoder section looks like the following:

Type: Object

Mandatory: Yes

transcoder = {
				scriptPath="..\\emsTranscoder.bat",
				srcUriPrefix="rtsp://localhost:5544/",
				dstUriPrefix="-f flv tcp://localhost:6666/"
			},

The srcUriPrefix tells the transcoder how to get the stream from the EMS. The dstUriPrefix tells the transcoder how to push the stream back to the EMS. The ports used in these two values must match the acceptors the EMS is actively listening on. By default this is 5544 for RTSP and 6666 for liveFLV.

Transcoder Structure Table:

mp4BinPath

The path to the mp4 writer executable file

Type: String

Mandatory: Yes

mp4BinPath="..\\evo-mp4writer.exe",

webRTC

The security configuration for the webRTC.

Type: Object

Mandatory: Yes

webrtc = {
			sslKey="..\\config\\server.key",
			sslCert="..\\config\\server.cert",
		},

webRTC Structure Table:

drm

The DRM section provides the configuration values for any DRM that needs to be activated. This section is commented out by default (wrapped in “–[[” and “]]–”). It must be un-commented-out before DRM will be activated.

Type: Object

Mandatory: Yes, if HLS version 5 is used

drm={
			type="verimatrix",
			requestTimer=1,
			reserveKeys=10,
			reserveIds=10,
			-- urlPrefix="http://server1.evostream1.com:12684/CAB/keyfile"
			urlPrefix="http://vcas3multicas1.verimatrix.com:12684/CAB/keyfile"
	},

DRM Structure Table: