This site requires javascript and cookie operation.

Streaming preset creation

guidelines

WARNING! The following guide is very technical.

The easiest place to start, when developing streaming presets is to look at the streams.cda file located in the \cfg directory.  As there are examples which cover most of the aspects, which are explained here in detail.

When reading this guide, it's worthwhile keeping streams.cda open in a text editor for easy reference.

Overview


The example streaming presets in MX light currently use VLC, FFMpeg or MX Light's included mini-programs, via thier command line interfaces.  As command line interfaces are used it is possible to use any program that supports command line operation.
The command lines are generated using a tokenised version of the command line stored in streams.cda (this will be explained in further detail below).

Each preset has a simple xml style structure which defines how the preset appears to the user in the GUI & optionally how the hardware encoder should be setup before streaming commences.

There are 2 types of preset:

Type 1: Template presets

To simplify setting up streaming across LANs, the concept of preset templates is used.  These presets do not specify IP addresses in thier command line but instead use the following tokens.

|IP-X|         = Network adapter IP address
|IP-X-name|    = Network adapter name

When MX Light loads a preset which uses the above tokens, it generates a version of the preset for each network adapter found, these generated presets are described as virtual presets & are indicated in the preset list by [v] text to the right.

Type 2 : Normal presets

These presets only contain direct references to either IP addresses or web addresses.  As such they are not expanded like template presets.  A preset is considered normal if it does not contain |IP-X| or |IP-X-name| tokens.

To simplify the user setup of these presets, user variables can be defined.  This will be covered later.

Syntax

The format of .cda files uses a nested structure similar to xml.  When modifying .cda files it is important to maintain matching opening & closing tags ('<','>') & follow the exact format shown in the examples (ie. use of spaces & quotations).

nb. .cda files are 8-bit ANSI encoded.  Indentation uses the tab character (ASCII #9).

A node has the form '<{name}.', where {name} is text. nb. This must not include a '.' as this is used to signify to end of a node or property name.

A property has the form '{name}.[{type}] = "{value}".
{value} is an escaped string.  This means that certain characters are replaced with 2 characters, this allows characters such a new line to be used.

a quick reference:

\\  =  \ character
\"  =  " character
\r  =  carrige return
\n  =  new line

nb. these are always used together eg. \r\n .  This should only be used when creating description text.

When creating presets {type} should always be [TSTR8].

Tokens

A token has the form '|*|' where * = some text.  Wherever these are found in a presets definition they are replaced with real information based on the current operating environement.

Default tokens:

|MXL|              = the current MX Light directory
|VLC|              = path to vlc.exe
|VLC-INstream|     = the input stream for VLC based commandlines
|VLC-RCI|          = remote control interface.  This allows the stream server to be turned off with the stream button (aswell as on)
|IP-X-name|        = Network adapter name(s)
|IP-X|             = Network adapter IP address(es)
|IP-local|         = Local host IP address (eg. 127.0.0.1)
|INstream-ip|      = Input stream IP address
|INstream-port|    = Input stream IP port
|INstream-fps|     = Input stream FPS (eg. 59.94)
|INstream-fpsFrac| = Input stream FPS as a fraction (eg. 59940/1000)
|INstream-V-bps|   = Video bits per second
|INstream-V-kbps|  = Video kilo-bits per second
|INstream-V-X|      = Video X-size
|INstream-V-X-mod16|= Video X-size mod 16
|INstream-V-X-crop| = Video X-size crop amount from mod 16 size
|INstream-V-Y|      = Video Y-size
|INstream-V-Y-mod16|= Video Y-size mod 16
|INstream-V-Y-crop| = Video Y-size crop amount from mod 16 size
|INstream-V-AR-X|   = Video aspect ratio X
|INstream-V-AR-Y|   = Video aspect ratio Y
|INstream-A-bps|    = Audio bits per second
|INstream-A-kbps|   = Audio kilo-bits per second
|INstream-A-SR|     = Audio sample rate (Hz)
|INstream-A-SR(k)|  = Audio sample rate (Khz)
|INstream-A-Bits|   = Audio bit-depth
|INstream-A-Ch|     = Audio channels
|FPE|               = Force Process Exit.  This is used for non-VLC commandlines such as FFMpeg, which require a manual exit & allows these processes to be synced with the Stream button.  This token should only be used at the start of the commandline.
|RUN PARALLEL|      = This is used to split a commandline, so that text after this token is effectively a new commandline which will be run in parallel.
|RUN PIPED|         = This is used to send data from one process to the next. This works like the pipe command '|' in dos. The STDOUT of the process before |RUN PIPED| is sent to the STDIN of the process after.  Examples of this can be seen in the default RTMP presets.
|(|                 = Defines the start of an expression.
|)|                 = Defines the end of an expression.

Expressions

Everything between a |(| and |)| pair define a mathematical expression, which is replaced in the command line by its result.

Expressions can also contain tokens eg.
|(|(|INstream-V-bps||)+(|INstream-V-kbps|*1000)|)|
|(||INstream-V-AR-X|/|INstream-V-AR-Y||)|
The tokens are replaced before the expression is evaluated.

Aswell as basic math operators ( ) + - * /  the following functions are also available for use in expressions :

Random, Int, Frac, Exp, Cos, Sin, Ln, ArcTan, Sqrt, Sqr, ArcCos, ArcSin, ArcTan2, Tan, Cotan, Secant, Cosecant, Hypot, RadToDeg, RadToGrad, RadToCycle, DegToRad, DegToGrad, DegToCycle, GradToRad, GradToDeg, GradToCycle, CycleToRad, CycleToDeg, CycleToGrad, Cot, Sec, Csc, Cosh, Sinh, Tanh, CotH, SecH, CscH, ArcCot, ArcSec, ArcCsc, ArcCosh, ArcSinh, ArcTanh, ArcCotH, ArcSecH, ArcCscH, LnXP1, Log10, Log2, LogN, Power, Ceil, Floor, Min, Max

User variables & Custom tokens:

User variables are properties that can be set by the user, using the preset setup GUI, allowing the less technical user easy access to important setup information.

nb. User variables are only usable in normal / non-template presets.

Please refer to streams.cda for an example of how user vars are integrated.

User variables are defined as a subsection in the preset, using the following format.

<user vars.
  Stream Key.[TSTR8] = "my stream key"
  --advanced property.[TSTR8] = ""
>

These user variables can then be used in command lines & descriptions, using the following token format: |UV:*| where *  = the user variable referenced.  eg. the token |UV:Stream Key| would be replaced with my stream key
If a user var has '--' at the start of its name, it is considered an advanced property & will only be visible in the GUI if the user selects 'Show Adv.'

User variable options

User variables can have preset values defined.  These user variables will act as switched options in the preset editor.

To specify options for a particular user variable, use the following format:

<user vars.
  a variable.[TSTR8] = "option 1 value"
  <opts.
    <
a variable.
      OPTION 1.[TSTR8] = "option 1 value"
      OPTION 2.[TSTR8] = "option 2 value"
    >
  >
>

Examples of this can be seen in the default presets.

User variable visibility

Only variables that are used in the final command line will be visible in the editor. 

As user variable values can also reference other user variables.  This allows options to be used to control what properties the user can see to edit.  Examples of this can also be seen in the default presets.

Further information

For specific command line options available for VLC & FFMpeg please see the following links:

FFMpeg Command line documentation
VLC command line documentation