1 - Encoder Audio Routing
Internally, the encoder provides a mixing engine that combines various audio sources.
In this chapter, we give an overview about this mixing engine, and describe some
common usage scenarios.
Player inputs provide a (virtual) playback devices in the
Audio Routing configuration. When you assign
the on air playback of a player to one of these devices, the audio is routed
directly into the encoder module, not requiring any (physical or virtual) Windows
soundcard. This will even work on datacenter servers with no physical audio
hardware at all.
Each player input provides a separate DSP chain, accessible on the Soundprocessing
tab on the Encoder configuration page.
The following player inputs are available:
- Player Input:
This is the main player input for the encoder. It is simply labeled Encoder in
the Audio Routing playback device list.
- Player Input 2/3/4:
In addition to the main player input, the encoder offers three additional player
inputs, labeled as Encoder - Player Input 2(/3/4) in the Audio Routing configuration.
You can use these inputs when you need separate DSP processing for some players.
- High Priority Input:
This is a special input which mutes the audio from all other inputs (primary
player input, player input 2/3/4, live inputs) whenever audio is played into it.
The other signals are briefly faded; the duration of this fade can be adjusted
in the configuration. The High Priority Input is most frequently used for the
Stream Monitor.
The encoder provides three live inputs which can be used to pick up audio from
a physical sound card:
- MIC:
This input is meant to pick up a DJ microphone signal during live operation, in
situations where no physical mixing console is used. It can be toggled via the MIC
button in the Encoder Status screen object. According to the
settings on the Encoder configuration page, optional ducking of the player inputs
will take place when the MIC input is active.
- LINE:
This input is most frequently used to pick up the master signal coming from your
external mixing console. It is toggled via the LINE button in the
Encoder Status screen object.
- AUX:
This is an auxiliary input which can be used to pick up another line or microphone
signal. There is no button in the screen object to toggle it. The only way to
enable or disable it is through actions or scripts.
To assign a sound card to any of these inputs, go to the
Audio Routing configuration page, Recording
tab, and edit the assignment in the Encoder part of the device tree.
Just like the player inputs, each live input has a separate DSP chain accessible
through the Encoder configuration page.
Outputs
Main Output
The encoder has one main output, which can be assigned to a physical output
on the Audio Routing configuration page,
Playback tab.
The signal of this main output will usually be the master bus of the encoder,
but there are several options in the configuration to tweak
the actual signal, e.g. make it pre-DSP or mute it while the MIC input is active.
Additional Outputs
In addition to the main output, you can add (virtual) connections of
the type Additional local audio output
in order to send the master signal to (additional) sound card outputs.
As with any connection, you can create region submixes, and there is also a separate
DSP chain to add sound processing only for this particular output.
Best Practices
Audio can be routed freely to and from the encoder, but there are two common setups
described here: Internal audio routing (no mixing console used) and external audio
routing (recording master signal from external mixing console).
All audio settings described here refer to the
Audio Routing page in the configuration
app or mAirList Control Panel:
Internal Audio Routing
In this setup, the audio of all players is routed directly into the encoder, so it stays
“inside” mAirList rather than being sent to a soundcard. Optionally, you can listen to
the encoder master signal on any soundcard. You can also use the MIC button to toggle
the microphone input when you want to make an announcement.
Internal audio routing can also be used on server hardware with no physical soundcard.
All audio stays inside the application, no virtual soundcard etc. is required.
Steps to follow:
- Set the Playback device for all players (“Playback -> Playlist 1 -> Player 1” etc.)
and the cartwall to “Encoder”.
- Optionally, as a precaution: Set the PFL device for all players and the cartwall to
any other soundcard or “No audio output” so that it won’t be broadcasted on your
stream.
- Optionally: Set “Recording -> Encoder -> Mic input” to the soundcard input where
your microphone is connected
- Optionally: Set “Playback -> Encoder -> Playback device” to the soundcard on which
you would like to listen to your broadcast
- During your broadcast, use the MIC button to turn your microphone on and off.
Note that, due to the nature of digital audio on computers, there will most likely
be a delay between what you speak and what you hear on the playback soundcard.
With high quality audio cards and ASIO or WASAPI, the delay can be minimized
to a level that you don’t really notice. Alternatively, turn off Filter microphone
signal from local playback in the encoder options so that you don’t hear yourself
at all.
The LINE button is not used in this setup, you can disable it in the Encoder Status
screen object settings in the configuration app.
External Audio Routing
This setup is for people who own a physical mixing console and use that console to
mix the on air signal rather than using the encoder built-in mixer.
In essence, you connect all audio sources (mAirList players and cartwall, microphones,
CD players, etc.) to your mixing console, and then send the master signal back to your
PC via Line In.
Steps to follow:
- Set the Playback device for the players (“Playback -> Playlist 1 -> Player 1” etc.)
and the cartwall to the soundcard output that is connected to the respective channels
on your mixing console
- Set “Recording -> Encoder -> Line Input” to the soundcard input where your the
master signal from your console is connected
- Important: Set “Playback -> Encoder -> Playback device” to “No audio output”.
If you don’t, the encoder master signal is sent back to the soundcard,
and there is a good chance that it will loop through your console,
causing feedbacks and echoes.
- Now when you start mAirList, click the LINE button in the encoder status window to
enable recording from the Line input.
(Note: To automate this step, go to Actions in the configuration app,
select After startup in the list at the top, and add a new action of type
“Encoder -> Toggle Input”.)
The MIC button is not used in this setup, you can disable it in the Encoder Status
screen object settings in the configuration app.
2 - Encoder Status Screen Object
When setting up the streaming encoder, the first thing you should is to add up
the Encoder Status screen object.
It provides the following controls:
- Buttons to toggle the MIC and LINE inputs.
- A Connect/Disconnect button to establish or terminate the actual server
connections.
- A peakmeter showing the current output level of the (master) signal.
- A status label with information about the current connections and the number of
listeners.
Configuration
To add the Encoder Status screen object, open the
standalone configuration app,
navigate to the Screen Objects page,
click Add and select Streaming Encoder Status.
On the General tab, the following options are available:
- Show MIC button:
Enable to display the MIC button that toggles the microphone input.
- Show LINE button:
Enable to display the LINE button that toggles the line input.
- Show audio level when offline:
By default, the peakmeter will be disabled when the encoder is in “Disconnected”
master state. This is to provide visual feedback of the master state to the user.
By checking this option, the peakmeter will always display the current
audio level, regardless of the master state of the encoder.
The Advanced tab provides access to the
common settings of all screen objects,
in particular, the desired position in the GUI.
Usage
Once you have added the screen object to the configuration, restart the playout,
and the object will appear in the GUI.
These buttons, when enabled in the config, can be used to toggle the respective
live input of the encoder. When disabled (gray), the input will be muted.
If only the MIC or the LINE button is enabled in the config, that button
will span the entire width of the screen object. If neither button is enabled,
the height of the screen object will be reduced accordingly.
Connection Status
The label below the MIC and LINE buttons displays a brief summary of the
current connections. The following texts may be displayed:
- Offline: The master switch is set to “Disconnected”. Click the Connect button
to establish the server connections.
- No connections: The master switch is set to “Connected”, but no connections
are configured or enabled.
- Online (x/x) - Listeners: (number): The master switch is set to “Connected”, all
enabled connections are established successfully. The number of listeners displayed
is the total of all listeners on all connections.
- Connecting (x/y) - Listeners: (number): The master switch is set to “Connected”,
but some connections are not currently established. See the System Log for details
on the failing connections.
When you hover the mouse cursor over the label, a hint will be displayed that gives
you per-connection information on the current status.
Double-clicking the label will take you directly to the Encoder page in the
Live Configuration (mAirList Control Panel).
The Connect/Disconnect button toggles the encoder connection master switch:
- In “Connected” state, all (enabled) server connections will be established;
if a connection fails, or unexpectedly terminates, an automatic reconnection
attempt will be made, according to the settings in the configuration.
- In “Disconnected” state, all server connections will be terminated.
Peakmeter
At the bottom of the screen object, there is a peakmeter that displays the current
level of the audio sent to the encoder.
By default, the peakmeter will display the level of the stereo “Master” bus of the
encoder, but there are several other signals to choose from, which you can
access through the right-click menu.
If regionalization is enabled, the peakmeter will display a
separate stereo pair for the common signal as well as for each region
(1+n stereo pairs for n regions).
Depending on the Show audio level when offline option in the screen object
settings, the peakmeter will be disabled when the encoder master switch is set to
“Disconnected”.
3 - Encoder Configuration
Configuration of the encoder is done on the Encoder page in the configuration app,
which can be accessed through the either the standalone configuration or the live
configuration.
Connections
On the first tab, the server connections are managed.
See the Connections section for the list of supported connection
types and their configuration.
Options
The second tab contains general settings and options for the encoder.
The following settings can be made:
- Sample rate:
This is the sample rate that the internal mixer of the encoder component runs at.
All audio fed into the encoder module will be resampled to this rate.
It will also be used as the default sample rate for all outgoing streams, unless
a different sample rate is configured in the connection properties.
Note that you must restart the playout when you make any changes here.
- Ducking level and speed:
These options refer to the Duck player volume while microphone is active option below.
Specify the attenuation of the ducking, and the duration of the fade.
- High priority fade length:
When audio is played to the High Priority encoder input, all other inputs will be
faded out and then muted, and later faded in again. Specify the duration of those
fades here.
- Silence detection level:
This is the level below which the signal is regarded as “silence”. It is only used
for the
GetSilenceDuration scripting method.
For regular silence detection with configurable actions, use the
Silence Detector DSP plugin.
Moreover, the following options are available:
- Connect/disconnect encoder when switching ON AIR mode:
If enabled, the encoder master switch will be controlled by the system ON AIR status.
When the instance is switched to ON AIR mode, the encoder will be set to “Connected”.
When you switch back to OFF AIR, the encoder will be set to “Disconnected”. Note
that this is only unidirectional; for controlling the ON AIR status from the encoder
master switch, the option Switch ON AIR mode when connecting/disconnecting encoder
must be enabled as well.
- Switch ON AIR mode when connecting/disconnecting encoder:
This is the reverse of the Connect/disconnect encoder when switching ON AIR mode
option above. When enabled, toggling the encoder master switch will also toggle
the system ON AIR status.
- Duck player volume while microphone is active:
If enabled, the volume of all player inputs will be ducked while the MIC input is
enabled, according to the settings above.
- Line input is high priority:
If enabled, the LINE input will work similar to the High Priority player input,
i.e. it will mute all other inputs when it is active.
- Filter microphone signal from local playback:
If enabled, the signal sent to the main encoder output (Encoder Playback Device
in the Audio Routing) will not include the MIC signal, i.e. it will be a mix of
the player and LINE/AUX inputs only. Note: This signal will always be Pre-DSP.
- Local playback is pre-DSP:
If enabled, the signal sent to the main encoder output will be the master bus,
but before any of the sound processing takes place.
This option has no effect if Filter microphone signal from local playback is
turned on as well.
- Mute local output during PFL:
If enabled, the encoder main output will be muted while any PFL is active.
Sound Processing
The encoder provides several ways to add sound processing to the audio.
See the Sound Processing chapter for a list of supported
(built-in or external) DSP plugins and their configuration.
The following DSP chains are available:
- Master bus –
this is the place where you usually add DSPs that should be applied to your outgoing
on air signal.
- Player inputs
- Player Input
- Player Input 2
- Player Input 3
- Player Input 4
- High Priority Input
- Live inputs
- Mic Input
- Line Input
- Aux Input
Note that you can also add sound processing on
connection level. This can be used as an
alternative to the Master bus DSP chain, in situations where you only want to have
DSP on some but not all connections.
4 - Encoder Connections
This section explains how to add and configure server connections for the built-in
encoder.
Management of connections is done on the Connections tab of the Encoder configuration
page in either the standalone configuration app or the live configuration.
In addition to regular connections to Shoutcast or Icecast servers, mAirList supports
some additional (virtual) connection types, which are covered at the end of
this section.
Shoutcast/Icecast
To add a new connection to a Shoutcast or Icecast server, click Add and select
the appropriate type. The configuration dialog for the new connection will appear.
Server
On the first tab, we configure the server connection and stream format.
Connection Parameters
These are the general server connection parameters. You should have received this
information from your streaming provider; or enter your own values in case of
a self-hosted server.
- Host name or IP and Port:
Enter the correct host name or IP address (not a URL!), and port number,
for your server.
- User:
Some servers require you to specify a user name. Most of the time this field can
be left blank, in which case the default user
source wil be used. - Password:
Enter the source password as configured in your server.
- Stream ID: (Shoutcast V2 only)
When using a Shoutcast V2 server, enter the Stream ID, or leave this field blank
to use the default Stream ID (1).
- Mount Point: (Icecast only)
For Icecast servers, enter the mount point for your stream.
In the section of the Server tab, the format, bitrate and stereo mode
of your stream can be adjusted.
For Shoutcast servers, the only supported format is MP3.
For Icecast servers, the following formats are supported: MP3, Ogg Vorbis, Opus, FLAC.
The actual encoding is done with the help of a command line encoder.
The appropriate encoders (lame.exe, oggenc.exe, opusenc.exe, flac.exe)
are included in the distribution.
mAirList will call these encoders with the correct parameters to receive PCM data on
STDIN, encode it according to the bitrate/mode settings, and send back encoded data
on STDOUT.
For example, for MP3 (using lame.exe), 128kbit, joint stereo, and the encoder
running at a samplerate of 48000, the command line will be:
lame.exe -r -s 48000 -b 128 -m j - -
If you want to tweak this command line with additional parameters, you can enter
these into the Encoder options field. mAirList will insert the parameters
just before the - - part of the command line.
For example, if you want to force LAME to create a high quality stream,
enter -h into the Encoder options field, and the resulting command line will be:
lame.exe -r -s 48000 -b 128 -m j -h - -
The Encoder options field can also be used to use 3rd party command line encoders,
even for stream formats not supported out of the box (e.g. AAC, using the 3rd party
enc_aacplus.exe encoder).
Note
When using 3rd party encoders, please make sure that you check the legal requirements
in your country. Some encoders must not be used without obtaining a proper license
beforehand.
To use a custom 3rd part command line encoder, proceed as follows:
- In the Audio Format dropdown, select “Custom” from the list.
- An empty text field will appear next to the dropdown. Enter the correct MIME type
for your audio format, e.g.
audio/aacp. - In the Encoder options field, enter the full filename and parameters for your
command line options; the parameters must be set up in a way so that raw PCM data
(at 16bit, stereo, and the sample rate at which the encoder is running, see
the Advanced tab below) is received via
STDIN, and encoded data is returned
via STDOUT. - The Bit rate and Stereo mode fields will be ignored.
Settings
On the bottom of the Server page, the behavior of the server connection can be adjusted:
- Seconds between connect attempts and checks:
As soon as the encoder master switch is set to “Connected”, a loop will be started
that attempts to establish the server connection, retries if that fails (e.g. because
the server is unreachable or the stream is busy), and then periodically check if
the connection is still alive. The number entered here is the time between any of
these checks/attempts. Note that, due to the nature of TCP, a failed connection may
only be detected later than in the period specified here.
- Seconds before trying to re-establish a list connection:
When the server connection is lost, mAirList will wait for the specified number of
seconds before trying to reconnect. This setting can be tweaked to enlarge the
time window before an (unattended) mAirList process tries to reconnect after purposely
“kicking” it from the server.
- Retrieve listener count:
If enabled, mAirList will periodically request the current number of listeners,
and display it in the Encoder Status screen object.
These requests use the regular XML APIs from Shoutcast/Icecast, so they will only work
if the server supports them. This should be the case for the stock Shoutcast and Icecast
servers; however some providers use their own implementation of the Shoutcast/Icecast
protocols which may not support listener count retrieval.
- Do not stream, only count listeners:
If you are using a network of relayed servers, and you want to include listeners
numbers of the relay servers, you can add connections to these servers and check
this box – mAirList will not actually send a stream to these servers then, but
only use the XML API to retrieve the number of listeners.
The settings on the second tab control the transmission of metadata to the streaming
server.
Enter the stream title and optional other metadata (URL, description, etc.)
that should be displayed to the user and in optional directories.
Title Update
Whenever an audio item is started in mAirList, the encoder can update the stream title
with the artist, title etc. This is similar to the
Logging feature, but it is built into the encoder connection
and does not require setup of a separate logging interface.
Shoutcast and Icecast only support a single text field for the current stream title,
so you will want to merge the artist name and the song title into it.
This is specified in the Log Format which defaults to %a - %b (“artist - title”).
You can use any of the available logging variables.
If a Delay is set, mAirList will wait for the specified number of seconds before
sending the new title to the server. This can be used to synchronize the title update
with a possible delay due to buffering.
The Character Set will be determined automatically based on your connection type
and matches the default configuration of the server types:
- Shoutcast V1: latin1
- Shoutcast V2: UTF-8
- Icecast: latin1 for MP3, UTF-8 for Ogg Vorbis, Opus and FLAC
If, for any reason, your server is configured to expect metadata in a different
character set, you can set it manually in the dropdown.
The Item Type Filter determines which items, based on the type set in their
properties, should be transmitted at all. For example, you can choose only to
display “Music” items, but no jingles etc. Hint: Use the right-click menu to
select all or no entries at once.
If the Forward song title updates of relayed streams option is checked, and you
are playing a stream through a “Stream” playlist item, or the Stream Monitor, mAirList
will transmit all incoming title updates “as is” to the connection.
Regions
If Regionalization is enabled for the encoder, this tab provides control over the
downmix sent to this connection.
See the Encoder Regionalization chapter for more information.
Sound Processing
In addition to the
central sound processing of the encoder module,
each encoder connection provides its own DSP chain that you can add DSP plugins to.
See the Sound Processing chapter for a list of supported
(built-in or external) DSP plugins and their configuration.
The DSP plugins registered here will be applied after the central DSP plugins, and
after region downmix. The signal will always be stereo.
Advanced
The last tab contains the following settings:
- Custom caption:
Enter an optional caption under which this connection should appear in the configuration,
System Log, etc.
- Sample rate:
This setting provides optional sample rate conversion for this particular connection,
in case it needs to run at a different sample rate than the one specified
in the main encoder configuration.
The sample rate will both be used for the raw PCM data fed into the command line
encoder, as well as the DSP plugins.
To disable sample rate conversion and use the default sample rate, leave this
field empty.
Integrated Streaming Server
The Integrated Streaming Server provides a Shoutcast (V1) compatible streaming server.
Warning
The Integrated Streaming Server is running directly inside the playout process,
and it is not as versatile as a regular standalone Shoutcast/Icecast server.
It also does not support transmission of metadata.
You should never use it to stream to “real” listeners.
It is often only used to provide a quick monitoring facility for inside the LAN.
To set up a new server, click Add and select Integrated Streaming Server.
In the connection properties, specify an optional local IP address (if you want
have multiple network interfaces and only want the stream to be available on one of
them), and the port number. Note that in the Shoutcast V1 protocol, there can
only be one stream per port.
The Stream Format settings are similar to those of the regular Shoutcast/Icecast
connections, see above.
If Retrieve listener count is checked, the number of listeners will be displayed
in the Encoder Status screen object.
For the settings on the Regions, Sound Processing and Advanced tabs,
see the Shoutcast/Icecast section above.
Record to File
Additional Local Audio Output
5 - Encoder Regionalization
With regionalization, mAirList can play out different
content for different regions at the same time, e.g. regional advertising or news, while
the rest of the program is common to all regions. The encoder supports this by mixing a
separate signal for each region, so that each stream can carry the program of one
particular region.
How It Works
When regionalization is enabled for the encoder, the encoder mixes a separate signal for
the common program and for each region, and its inputs appear as the following playback
devices in the Audio Routing configuration:
- a multi-region device, named e.g. Encoder - all regions, which carries the common
signal and the signals of all regions. When the players play into this device,
mAirList automatically sends common content to the common signal, and regional
content to the signal of the respective region.
- one additional device per region, named e.g. Encoder - North, which feeds directly
into the signal of that region. Use these devices to route other sources to a single
region.
With regionalization enabled, each playback function in the Audio Routing configuration
has a sub-node for each region, so you can also assign the output for each region
explicitly.
Each encoder connection then decides which signals are included in its stream: Typically,
a connection includes the common signal plus the signal of exactly one region. This way,
you can set up one stream per region, all fed from the same mAirList instance.
Configuration
- Define the regions and their names in the
Regionalization configuration.
- On the Options tab of the Encoder configuration page, set the Region count to
the number of regions the encoder should handle. The maximum is the number of regions
covered by your license. Set to 0 to disable regionalization for the encoder.
- In the Audio Routing, assign the playback of the
players to the encoder’s devices (see above).
- In the configuration of each encoder connection, go to the
Regions tab, and check the signals that should be included in this stream under
Include the broadcast signal for the following regions: Common, and the
region(s) for this stream. By default, only Common is included.