This is the multi-page printable view of this section. Click here to print.
Features
- 1: Encoder
- 1.1: Encoder Audio Routing
- 1.2: Encoder Status Screen Object
- 1.3: Encoder Configuration
- 1.4: Encoder Connections
- 1.5: Encoder Regionalization
- 2: Voice Tracking
- 3: Sound Processing
- 4: Stream Monitor
- 5: Aircheck Recorder
- 6: File Recorder
- 7: Scripting
- 8: Network Sync
- 9: Matrix Mixer
- 10: Regionalization
- 11: MusicMaster Integration
1 - Encoder
mAirList includes a streaming encoder, which sends the program directly to one or more streaming servers (Icecast, Shoutcast, and others), without any additional software.
The encoder has its own internal mixing engine. The players of mAirList can play directly into the encoder through virtual playback devices, so no physical sound card is needed for streaming; this even works on servers in a data center. Additionally, live inputs (e.g. a microphone or the output of a mixing console) can be mixed into the stream.
Getting Started
To set up a stream, follow these steps:
- Add a server connection on the Connections tab of the Encoder configuration page, and enter the server address, credentials, and stream format. See Connections.
- Route the on-air playback of the players to the Encoder playback device in the Audio Routing configuration, or set up a live input. See Audio Routing.
- Add the Encoder Status screen object to the playout window, so you can connect to the server and monitor the stream. See Screen Object.
Chapter Overview
- Audio Routing: The internal mixing engine of the encoder, its inputs and outputs, and common usage scenarios.
- Screen Object: The Encoder Status screen object, which controls the encoder from the playout window.
- Configuration: General encoder settings and options.
- Connections: The supported connection types and their settings.
- Regionalization: Streaming different regional variants of the program.
1.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.
Inputs
Player Inputs
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.
Live Inputs
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.
1.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.
MIC and LINE Buttons
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).
Connect/Disconnect Button
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”.
1.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
GetSilenceDurationscripting 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.
1.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
sourcewil 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.
Stream Format
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).
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 viaSTDOUT. - 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.
Metadata
The settings on the second tab control the transmission of metadata to the streaming server.
Stream Metadata
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.
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
1.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.
2 - Voice Tracking
Voice tracking lets you pre-record the moderation (“voice tracks”) between two items of a playlist, so that the program sounds live even when it is played out automatically.
The Voice Track Recorder plays the end of the previous item and the beginning of the next item, while you record your voice in between, just like you would do in a live show. The result is a new voice track item that is inserted into the playlist, with the fade and start markers of the surrounding items adjusted to match your recording.
Opening the Voice Track Recorder
The Voice Track Recorder can be opened from the following places:
- In the playout, select the item after which the voice track should be inserted,
and click the VT button in the toolbar (or execute the
VT OPENcommand). - In the Database app, click the VT button in the toolbar of the playlist editor at the desired position.
The selected item becomes item A (the item before the voice track), and the next item in the playlist becomes item B (the item after the voice track). If the selected item is the last one in the playlist, there is no item B, and the voice track is simply appended.
Recording a Voice Track
The Voice Track Recorder window contains three rows:
- A: The player for item A, with Start, Fade Out and Stop buttons, a progress bar, and a volume slider. The player is positioned 10 seconds before the end of the item, so you can hear its outro before you start talking.
- M: The microphone recording, with Record, Stop and Cancel buttons, and a live waveform of the recording.
- B: The player for item B, with Start, Fade Out and Stop buttons, a progress bar, and a volume slider.
A typical recording works like this:
- Click Record in the M row. Player A starts playing, and the recording begins.
- Start talking whenever you like, e.g. over the outro of item A. Use the volume slider of player A to lower its volume while you talk, and Fade Out or Stop to end it early.
- Click Start in the B row when item B should begin, e.g. to talk over its intro. Again, you can adjust its volume while talking.
- Click Stop in the M row to finish the recording.
Each recording is added to the list of takes at the bottom of the window. You can record as many takes as you like, and then select the best one. Before saving, you can listen to the selected take in context, and fine-tune it in the Mix Editor, by clicking EDIT (or double-clicking the take).
Enter a Title for the voice track, and click SAVE to insert the selected take into the playlist. CANCEL closes the recorder without changes.
When the voice track is saved, mAirList automatically:
- sets the Start Next marker of item A to the point where the recording started, and the Fade Out and Cue Out markers to the points where you faded out or stopped player A,
- stores the volume changes you made for items A and B as volume envelopes of the items,
- encodes the recording into the configured audio format, and saves it in the configured folder (see Configuration below),
- inserts the voice track item between item A and item B.
Using the Cartwall
If the Use cartwall option is enabled, the cartwall switches to VT mode while the Voice Track Recorder is open. Any cart players you start during the recording (e.g. jingles or sound effects) become part of the voice track: Instead of a plain voice track, a multi-track container item is created, which contains the microphone recording and all cart items at the exact positions at which they were played.
Remote Control
The Voice Track Recorder can be operated with the following remote control commands, e.g. from a mixing console or a MIDI controller:
VT OPEN– open the Voice Track Recorder (playout only)VT PLAYER A START,VT PLAYER A FADEOUT,VT PLAYER A STOPVT PLAYER B START,VT PLAYER B FADEOUT,VT PLAYER B STOPVT PLAYER A VOLUME <dB>,VT PLAYER B VOLUME <dB>– set the volume of a player in dB, e.g.VT PLAYER A VOLUME -10VT PLAYER A VOLUME <x>/<y>,VT PLAYER B VOLUME <x>/<y>– set the volume as a fraction of the full fader scale, e.g.VT PLAYER A VOLUME 64/127for a MIDI faderVT RECORD START,VT RECORD STOP,VT RECORD CANCELVT EDIT,VT SAVE,VT CANCEL
Many mixing console interfaces (e.g. SAS or DHD) can also be configured to start the voice tracking players and the recording through fader start.
Audio Devices
The microphone input and the outputs of players A and B are configured in the Audio Routing configuration.
Configuration
The settings of the Voice Track Recorder are found on the Voice Tracking page of the configuration.
General
- Save to folder:
The folder in which recorded voice tracks are saved. The default is the
VoiceTracksfolder inside the mAirList data folder. When voice tracks are recorded for use on other computers, this should be a shared network folder. - Format: The audio format of the recorded voice tracks. Click the … button to select the format and its settings.
Options
- Show artist and title of item A and B: Displays the artist and title of the items in the A and B rows.
- Adjust player volume: Applies the volume sliders of players A and B to the actual playback volume while recording. If disabled, volume changes are only recorded into the volume envelopes of the items.
- Auto fadeout player A at Fade Out: Player A fades out automatically when it reaches the Fade Out marker of item A, and the marker is kept in the saved item. If this option is disabled, player A plays to the end, and the Fade Out marker is cleared (unless you fade out player A manually during the recording).
- Use cartwall: Switches the cartwall to VT mode during recording (see above).
- Automatically stop cart players at the end of recording: Stops all cart players when the recording is stopped.
- Show save confirmation / Show cancel confirmation: Asks for confirmation before saving or cancelling.
Progress Bar
The display options of the progress bars of players A and B. See Common Settings for details.
Effects
Effects that are applied automatically to every recorded voice track, e.g. a compressor or an equalizer for the microphone. Additional effects can be applied manually to a take in the Mix Editor.
Database Integration
When a database is used, voice tracks can be imported into the database library automatically, rather than being kept as external files. This is controlled by the options Import new voice tracks recorded in the playlist editor and Import new voice tracks recorded in the playout window in the database connection settings. The library folder for imported voice tracks is set in the administrative settings of the database.
3 - Sound Processing
mAirList can process audio signals with DSP (digital signal processing) plugins, e.g. to apply compression, automatic gain control, or a complete broadcast processing chain. Several plugins can be combined into a DSP chain, in which the plugins are applied one after the other.
Where Sound Processing Can Be Applied
DSP chains are available in the following places:
- Audio devices: Each playback and recording device can have its own DSP chain, which is configured on the Sound Processing page of the Audio Settings. Select Playback or Recording, choose the device from the list, and add the desired plugins. The DSP chain of a playback device is applied to everything that is played on that device; the DSP chain of a recording device is applied to everything recorded from it.
- Encoder: The encoder has a central DSP chain, separate chains for each of its inputs and outputs, and a DSP chain for each encoder connection. See the encoder configuration and encoder connections for details.
- Voice tracking: Effects that are applied to every recorded voice track, see Voice Tracking.
Managing the DSP Chain
All DSP chains are managed in the same way:
- Click Add to add a new plugin. Select the plugin type from the menu, and adjust its settings in the configuration dialog.
- Select a plugin and click Configure (or double-click it) to change its settings.
- Click Remove to remove the selected plugin.
- Drag and drop the plugins to change their order. The plugins are applied from top to bottom.
- Use Export and Import to save the selected plugins to an
.inifile, and to add plugins from such a file, e.g. to copy a DSP chain to another device or computer.
The In and Out level meters next to the list display the signal level before and after the processing, so you can check the effect of the plugins in real time.
All plugins share the following settings:
- Enable (uncheck to bypass): Uncheck this option to temporarily disable a plugin without removing it from the chain.
- Channels (Advanced tab):
For multi-channel devices, enter the channels the plugin should be applied to (e.g.
1,2). Leave empty to apply the plugin to all channels.
Built-in Plugins
Amplification
Changes the volume of the signal by a fixed amount.
- Volume: The amplification in dB (negative values reduce the volume).
Compressor
A simple compressor, which reduces the volume of signals above the threshold.
- Threshold: The level above which compression starts, in dB (default -15 dB).
- Attack: How quickly the compressor reacts to a rising level, in milliseconds (default 10 ms).
- Release: How quickly the compressor returns to normal gain after the level has dropped, in milliseconds (default 50 ms).
Advanced Compressor
A compressor with adjustable ratio and make-up gain.
- Gain: The make-up gain applied after compression, in dB (default 0 dB).
- Threshold: The level above which compression starts, in dB (default -15 dB).
- Ratio: The compression ratio, e.g. 3 for 3:1 (default 3).
- Attack, Release: As above, in milliseconds (defaults 10 ms and 50 ms).
DirectX Compressor
The compressor effect from DirectX, with the parameters Gain, Attack, Release, Threshold, Ratio, and Predelay (in milliseconds).
Dynamic Amplification (AGC)
An automatic gain control, which slowly adjusts the volume so that the signal stays at a constant level, e.g. to even out recordings with different loudness.
- Target level: The level the AGC tries to reach, in dB (default -0.5 dB).
- Quiet level: Signals below this level are not amplified, so that silence and noise are not boosted, in dB (default -30 dB).
- Adjustment rate: How quickly the gain is adjusted (default 0.01).
- Amplification level: An additional fixed gain, in dB (default 0 dB).
- Delay: The look-ahead delay, in seconds (default 0.35 s).
This plugin is only available for real-time processing, not for files.
Echo/Delay
Adds an echo to the signal.
- Dry mix, Wet mix: The volume of the original and the delayed signal.
- Feedback: How much of the delayed signal is fed back into the delay, creating multiple echoes.
- Delay: The delay time, in seconds.
- Stereo: Whether the echo alternates between the left and right channel.
Downmix Plugins
- Stereo to mono (left + right): Mixes both channels into a mono signal, which is played on both channels.
- Stereo to mono (left channel only) / (right channel only): Plays one channel of the input on both channels.
- Custom downmix/remap: Freely maps the input channels to the output channels, using a matrix in which you select which input channels are mixed into which output channels.
Normalize Plugins
The Normalize (Peak), Normalize (True Peak) and Normalize (R128 Loudness) plugins adjust the volume of a whole file, so that its peak level, true peak level, or EBU R128 loudness reaches the specified Target level. As they need to analyze the complete file, they are only available where files are processed (e.g. the voice tracking effects), not for real-time processing.
Silence Detector
The Silence Detector does not change the audio signal, but monitors it and executes actions when the signal is silent for a certain time, e.g. to raise an alarm, send an e-mail, or switch to a backup source.
- Threshold (dBFS): The signal is considered silent when its level is below this threshold (default -20 dBFS).
- Duration (seconds): How long the signal must be silent before the silence actions are executed (default 10 seconds).
- Actions on Silence: The actions to execute when silence is detected.
- Actions on Recovery: The actions to execute when the signal is back.
Add the Silence Detector to the DSP chain of the device you want to monitor, e.g. the recording device that receives the program output of the mixing console.
External Plugins
VST Plugins
mAirList supports VST 2 effect plugins (.dll files). When adding a VST Plugin, select
the plugin file, and adjust its settings in the editor of the plugin, which is displayed
in the configuration dialog.
You can also display the plugin editor permanently in the playout window, e.g. to adjust the processing during a show: Add a VST Plugin GUI screen object in the GUI configuration, and enter the same Remote Control ID both in the screen object and on the Screen Object tab of the plugin configuration.
Winamp DSP Plugins
Winamp DSP plugins (dsp_*.dll) are supported for real-time processing. When adding a
Winamp DSP Plugin, select the plugin file. Click Show Plugin Configuration to open
the plugin’s own configuration window.
Stereo Tool
Stereo Tool is a professional broadcast audio processor by Thimeo, which is integrated directly into mAirList.
- Download Plugin: Click Download to download the most recent version of the Stereo Tool plugin.
- Stereo Tool License Key: Enter your Stereo Tool license key. Without a key, Stereo Tool runs in demo mode. Changes require a restart of mAirList.
- Presets: Check Load a specific preset at startup to load either one of the
built-in presets, or a settings file (
.sts) saved from Stereo Tool, when mAirList starts. For a settings file, select which parts of the settings should be loaded (Settings to load). - Use FM output (MPX): Use the FM/MPX output of Stereo Tool, e.g. to feed an FM transmitter directly from a suitable sound card. Adjust the Buffer size if necessary.
The remaining settings of Stereo Tool are adjusted in its own user interface, which is available from the plugin configuration dialog.
4 - Stream Monitor
The Stream Monitor continuously checks one or more Internet audio streams, and plays them as soon as they become available. A typical use case is a remote DJ who broadcasts live from home: The DJ sends a stream to a streaming server, mAirList detects it, and the live show automatically goes on air instead of the regular program. When the DJ stops streaming, mAirList automatically returns to the regular program.
How It Works
For each configured stream, the Stream Monitor regularly tries to connect to the stream URL. Each stream has one of the following states:
- disabled: The stream is not being monitored (e.g. because the Stream Monitor is not running in this application).
- offline: The stream is currently not available.
- available: The stream is available, but not on air, because another stream with a higher priority is on air.
- on air: The stream is being played.
If more than one stream is available, only the one with the lowest Priority value is played. If two or more streams with the same priority are available, all of them are played at the same time.
The streams are played on the Stream Monitor playback device, which is configured in the Audio Routing. Usually, this device is connected to the High Priority Input of the encoder, which automatically fades out all other signals while the stream is on air. Alternatively, you can route it to a sound card output and feed it into your mixing console.
Title updates (metadata) received from the stream are logged like the titles of any other item, and can be forwarded to the encoder connections (see the option Forward song title updates of relayed streams in the encoder connection settings).
Every change of a stream’s state is recorded in the System Log.
Configuration
The Stream Monitor is configured on the Stream Monitor page of the configuration. This page is also available in the live configuration (mAirList Control Panel).
Streams
The list contains all monitored streams. Use the toolbar to add, configure, or remove streams. Each stream has the following settings:
- Stream URL:
The URL of the stream, e.g.
https://stream.example.com/live. - Description: An optional name for the stream, which is displayed in the status display and the System Log.
- Priority: Determines which stream goes on air if more than one stream is available. Lower values have higher priority. The default is 1.
- Check interval (seconds): How often mAirList tries to connect to the stream while it is offline. The default is 5 seconds.
Actions
On the Actions tab, you can configure actions that are executed when the Stream Monitor goes on air (i.e. the first stream becomes available), and when it goes off air again (i.e. no stream is available anymore). Select When on air or When off air to edit the respective action list.
For example, you could disable automation while a remote show is running, or insert a jingle when the program returns to the studio.
Status Display
To display the state of the monitored streams in the playout window, add a Stream Monitor Status screen object in the GUI configuration. It shows the list of streams, along with their priority and current state.
The status of the Stream Monitor can also be retrieved from the
REST API (/streammonitor/summary).
5 - Aircheck Recorder
The Aircheck Recorder is a recording facility for live shows. It is placed into the playout window as a screen object, and records an audio input (typically the program output of the mixing console) into a file, e.g. to archive the show or to send it to the presenter as an aircheck.
The recording can be paused and resumed at any time, e.g. to skip music and only record the talk parts of the show. All parts end up in the same file.
Setup
The Aircheck Recorder is added to the playout window as a screen object in the GUI configuration. Double-click it in the configuration to open its settings.
The audio input that is recorded is set up in the Audio Routing configuration, on the Recording tab (Aircheck Input 1 to 8).
General
- File Format: The audio format of the recording. Click Change… to select the format and its settings.
- Audio input: Which of the eight Aircheck Recorder inputs to record from.
- Separation:
When the recording is paused (with the Pause button or the
OFFcommand), this number of seconds of silence is inserted into the file, so that the individual parts of the recording are clearly separated. Set to 0 to disable. - Output folder: The default folder for new recordings.
- Filename format:
The name of new recording files, without the extension, which is added automatically.
Logging variables can be used, e.g. for the date and
time. The default is
%Y%M%D-%h%m%s, e.g.20261031-180000.
Cue Sheet
Check Create a cue sheet file including the following item types to create a
.cue file alongside the recording. Each item that is started while the recording is
running (and not paused) is written to the cue sheet as a track, with its title, artist,
and position in the recording. Select which item types should be included, e.g. only
music.
Cue sheets are supported by many audio players and editors, which display the tracks and allow you to jump to them.
Usage
The Aircheck Recorder has four buttons:
- Open: Creates a new recording file. A file dialog is displayed, pre-filled with the output folder and filename format from the configuration. After opening the file, the recorder is paused.
- Record: Starts or resumes the recording.
- Pause: Pauses the recording (and inserts the configured separation).
- Close: Closes the recording file. The recording must be paused first.
The elapsed recording time and the filename are displayed next to the buttons, and a peakmeter shows the input level while recording.
Remote Control
The Aircheck Recorder can be controlled with the following
remote control commands, assuming the default Remote ID
AIRCHECK:
AIRCHECK OPEN– open a new file, using the configured folder and filename format (without a file dialog)AIRCHECK OPEN <filename>– open a new file with the specified nameAIRCHECK ON– start or resume the recordingAIRCHECK OFF– pause the recordingAIRCHECK CLOSE– close the file
The same functions are available as actions, e.g. to open a new file and start recording automatically at the beginning of a show from the event scheduler. If you place more than one Aircheck Recorder in the GUI, give each of them a different Remote ID.
6 - File Recorder
The File Recorder records audio inputs into files in the background, without any user interface in the playout window. Recordings are started and stopped by actions, so they can be triggered by the event scheduler, a cartwall button, a remote control, or a script. Typical uses are recording a show for a podcast, recording a feed at a fixed time for later playback, or logging the program output.
Any number of recordings can run at the same time, from the same or from different inputs.
Audio Inputs
The File Recorder has eight inputs, which are set up in the Audio Routing configuration, on the Recording tab (File Recorder Input 1 to 8).
Starting and Stopping Recordings
Recordings are started with the File Recorder → Start recording action, and stopped with the File Recorder → Stop recording action, e.g. in the event scheduler. See below for the settings of a recording, and the actions reference for details on the actions.
For example, to record a show from 18:00 to 20:00, add an event at 18:00 with a Start recording action, and either set its duration to 7200 seconds, or add another event at 20:00 with a Stop recording action.
Recording Settings
- Audio input: The File Recorder input to record from.
- Output filename:
The file to record into, including the extension matching the file format.
Logging variables can be used, e.g.
D:\Recordings\Show-%Y%M%D-%h%m.mp3, so that each recording gets a unique name. - Duration (seconds): If set, the recording is stopped automatically after this time. Leave empty to record until the recording is stopped by a Stop recording action.
- Recording ID: An optional ID, which can be used to stop this particular recording later.
- File Format: Either Use default file format, which is set in the Audio Settings, or select a specific format for this recording.
- After Recording: Optionally, enter a filename under Save copy as, to copy the file to another location (e.g. a network share or an upload folder) after the recording has finished. Check Delete original file after copying to move the file instead.
- Cue Sheet:
Optionally create a
.cuefile alongside the recording, which lists all items played during the recording, with their positions. Select which item types should be included.
The Stop recording action stops all running recordings with the specified Recording ID and/or from the selected input (Filter by input).
File Recorder Window
The File Recorder window, found in the Windows section of the About menu, displays a list of all recordings, with their state, current level, start time, duration, recording ID, and filename.
From this window, you can also start a recording manually (Add), stop the selected recording (Stop), and remove finished recordings from the list (Clean Up).
7 - Scripting
mAirList has a built-in scripting engine that allows you to automate tasks, react to events, and integrate mAirList with other systems, beyond what is possible with the regular configuration options.
Scripts are written in a Pascal dialect (based on
Pascal Script), and are stored as plain text
files with the extension .mls. They have access to most of the internal objects of
mAirList, e.g. the playlists, players, cartwall, and database, as well as a number of
helper functions.
There are two kinds of scripts, which differ in how and when they are executed: one-shot scripts and background scripts.
One-Shot Scripts
A one-shot script is loaded, executed once, and unloaded again. Execution starts with
the main begin ... end. block at the end of the script:
begin
ExecuteCommand('PLAYER 1-1 START');
SystemLog('Player 1-1 started by script');
end.
One-shot scripts can be run in the following ways:
- Manually, from the About menu of the main window (Run Script…).
- Through the Run script action (Miscellaneous category), e.g. from the event scheduler, a cartwall action, or any other place where actions can be configured.
- Through the remote control command
RUNSCRIPT <filename>, e.g. from a hotkey, a MIDI controller, or a network remote control.
As the script is unloaded after execution, global variables do not keep their values
between two runs. Use runtime data (SetRuntimeData/GetRuntimeData) to store values
that must survive, or to share them with other scripts.
Background Scripts
A background script is loaded when mAirList starts, and remains active until mAirList is shut down. Instead of a main block, it contains event handlers (hooks): procedures with predefined names and parameters, which are called by mAirList whenever the respective event occurs, e.g. when a player starts, an item is logged, or a MIDI message is received.
procedure OnPlayerStart(PlaylistIndex: integer; PlayerIndex: integer; Item: IPlaylistItem);
begin
SystemLog('Now playing: ' + Item.GetTitle);
end;
Background scripts are set up in the configuration, on the Background Scripts page: Add a new entry, select the script file, and optionally check Automatically reload when changed on disk, so that changes to the script are applied immediately, without restarting mAirList.
Note the following differences to one-shot scripts:
- A background script does not need a main
begin ... end.block. mAirList adds an empty one automatically so that the script compiles. If the script contains a main block anyway, it is never executed. Use theOnLoadevent handler for initialization code instead. - Global variables keep their values for as long as the script is loaded.
- Each background script processes its events in its own thread, so a slow event handler does not block the user interface or the playback. Still, event handlers should return as quickly as possible, so that subsequent events are not delayed.
- Only implement the event handlers you actually need. Event handlers that are not present in the script are simply not called.
Errors that occur while loading the script or executing an event handler are reported in the System Log.
Template
A template that contains all available event handlers (with empty bodies) is included in
the mAirList installation folder as Background Script Template.mls. Copy the handlers you
need into your own script.
Event Handlers
This section lists all event handlers that are available in background scripts, along with their exact syntax and parameters. Event handlers are identified by their name only, so the parameter list must match exactly as shown here; a different parameter list will lead to errors when the handler is called. Copying the handlers from the template is the safest way to get them right.
A few general notes on the parameters:
- Playlist and player indexes (
PlaylistIndex,PlayerIndex) are counted from 0, i.e. playlist 1 has index 0, and player 1-1 isPlaylistIndex = 0, PlayerIndex = 0. - Cart player indexes are counted from 1, i.e. they match the numbers displayed in the cartwall.
- Durations (
TTimeValue) are given in seconds, as a floating point number. - Items (
IPlaylistItem) give access to the item’s properties, e.g.Item.GetTitle,Item.GetArtist, orItem.GetDuration. The item may benilin some cases, so check it withAssigned(Item)before use. - Player states (
TPlayerState) are values such aspsEmpty,psLoaded,psPlaying,psFading,psPaused,psStopped,psPFL,psEOFandpsError.
Script and Application Lifecycle
procedure OnLoad;
procedure OnUnload;
Called when the script is loaded (i.e. when mAirList starts, or when the script is
reloaded after a change), and when it is unloaded (when mAirList shuts down, or before the
script is reloaded). Use OnLoad for initialization, e.g. to start timers, and OnUnload
for cleanup.
procedure OnOnAir;
procedure OnOffAir;
Called when mAirList is switched to ON AIR or OFF AIR mode.
procedure OnSystemLog(Category: TLogCategory; Message: string);
Called when a message is added to the System Log.
Category: The type of message:lcInfo,lcWarning,lcError,lcStatus,lcPlaylist(items started and stopped), orlcDebug.Message: The text of the message.
Be careful what you do in this handler: Do not write to the System Log yourself, and avoid raising exceptions, as this may result in an endless loop.
Timers and Runtime Data
procedure OnTimer;
Called periodically after the timer has been started with EnableTimer(Interval), where
Interval is given in milliseconds, e.g. EnableTimer(1000) in OnLoad.
Stop the timer with DisableTimer.
procedure OnTimerEx(ID: string);
Same as OnTimer, but supports multiple timers with different intervals. Start each timer
with EnableTimerEx(ID, Interval), and stop it with DisableTimerEx(ID).
ID: The ID of the timer that has elapsed, as passed toEnableTimerEx.
procedure OnRuntimeDataChange(Key, Value: string);
Called when a runtime data value is set, e.g. with SetRuntimeData from any script.
Runtime data are global variables that can be shared between scripts.
Key: The name of the value.Value: The new value.
Remote Control Commands
procedure OnExecuteCommand(Command: string);
Called whenever a remote control command is executed, regardless of its origin (remote control interface, action, script etc.). This also allows you to implement custom commands, by checking for your own command names.
Command: The command text, e.g.PLAYER 1-1 START.
Windows
procedure OnCartwallShow;
procedure OnCartwallHide;
procedure OnMixEditorShow;
procedure OnMixEditorHide;
procedure OnCueEditorShow;
procedure OnCueEditorHide;
Called when the cartwall window, the Mix Editor, or a Cue Editor window is shown or hidden.
Playlists
procedure OnAutomationOn(PlaylistIndex: integer);
procedure OnAutomationOff(PlaylistIndex: integer);
Called when automation is switched on or off for a playlist.
PlaylistIndex: The playlist, counted from 0.
procedure OnPlaylistEmpty(PlaylistIndex: integer);
Called when a playlist runs empty while in automation mode, i.e. there are no more items left to play.
PlaylistIndex: The playlist, counted from 0.
procedure OnPlaylistChange(PlaylistIndex: integer);
Called when the content of a playlist changes, e.g. when items are added, removed, or moved.
PlaylistIndex: The playlist, counted from 0.
procedure OnAfterEditPlaylistItem(Item: IPlaylistItem);
Called after an item has been edited in the Properties dialog, and the changes have been saved.
Item: The edited item.
Playlist Players
procedure OnPlayerStart(PlaylistIndex: integer; PlayerIndex: integer; Item: IPlaylistItem);
Called when a playlist player is started.
PlaylistIndex,PlayerIndex: The player, both counted from 0.Item: The item loaded in the player.
procedure OnPlayerStop(PlaylistIndex: integer; PlayerIndex: integer; Duration: TTimeValue; Item: IPlaylistItem);
Called when a playlist player is stopped.
PlaylistIndex,PlayerIndex: The player, both counted from 0.Duration: How long the item was playing, in seconds.Item: The item loaded in the player.
procedure OnPlayerEOFWarning(PlaylistIndex: integer; PlayerIndex: integer);
Called when a playlist player reaches the EOF warning point (by default, 10 seconds before the end of the item).
PlaylistIndex,PlayerIndex: The player, both counted from 0.
procedure OnPlayerStateChange(PlaylistIndex: integer; PlayerIndex: integer; OldState: TPlayerState; NewState: TPlayerState; Item: IPlaylistItem);
Called whenever a playlist player changes its state, e.g. from psLoaded to psPlaying.
PlaylistIndex,PlayerIndex: The player, both counted from 0.OldState,NewState: The previous and the new state of the player.Item: The item loaded in the player (may benil, e.g. when the player is empty).
procedure OnPlayerPFLOn(PlaylistIndex: integer; PlayerIndex: integer; PFLCount: integer);
procedure OnPlayerPFLOff(PlaylistIndex: integer; PlayerIndex: integer; PFLCount: integer);
Called when a playlist player enters or leaves PFL.
PlaylistIndex,PlayerIndex: The player, both counted from 0.PFLCount: The number of PFL sources (players, editors etc.) that are active after the change. For example,PFLCount = 0inOnPlayerPFLOffmeans that no PFL is active anymore.
Cartwall
procedure OnCartwallOnAirModeChange(OldMode, NewMode: TCartwallOnAirMode);
Called when the cartwall changes its mode.
OldMode,NewMode: The previous and the new mode:oamOnAir,oamOffAir,oamPFL, oroamVT(voice tracking).
procedure OnCartwallActivePageChange(OldPage: ICartwallPageControl; NewPage: ICartwallPageControl);
Called when the user switches to another page (tab) of the cartwall.
OldPage,NewPage: The previous and the new page. Either can benil, if no page was or is open.
procedure OnCartwallPlayerStateChange(PlayerIndex: integer;
OldState: TPlayerState; NewState: TPlayerState;
Item: IAudioCartwallItem; PlaylistItem: IPlaylistItem;
OnAirMode: TCartwallOnAirMode);
procedure OnCartwallPlayerStateChangeEx(PlayerIndex: integer;
OldState: TPlayerState; NewState: TPlayerState;
Item: IAudioCartwallItem; PlaylistItem: IPlaylistItem;
OnAirMode: TCartwallOnAirMode; Selected: boolean);
Called when the state of a cart player on the current page changes, and for all cart players when the user switches to another page. This is useful to mirror the cartwall on external hardware, e.g. button LEDs.
PlayerIndex: The cart player, counted from 1.OldState,NewState: The previous and the new state of the cart player.Item: The cartwall item (button), ornilif the cart player is empty.PlaylistItem: The item loaded in the cart player, ornil.OnAirMode: The current mode of the cartwall (see above).Selected(Exversion only): Whether the cart player is currently selected.
procedure OnCartwallPlayerStart(PlayerIndex: integer; Item: IAudioCartwallItem; PlaylistItem: IPlaylistItem);
procedure OnCartwallPlayerStop(PlayerIndex: integer; Item: IAudioCartwallItem; PlaylistItem: IPlaylistItem; Duration: TTimeValue);
procedure OnCartwallPlayerEOFWarning(PlayerIndex: integer; Item: IAudioCartwallItem; PlaylistItem: IPlaylistItem);
Called when a cart player is started, stopped, or reaches its EOF warning point.
PlayerIndex: The cart player, counted from 1.Item: The cartwall item (button).PlaylistItem: The item loaded in the cart player.Duration(OnCartwallPlayerStoponly): How long the item was playing, in seconds.
Items
procedure OnItemStart(Item: IPlaylistItem; Region: byte; OnAir: boolean; UniqueID: string);
procedure OnItemStop(Item: IPlaylistItem; Region: byte; OnAir: boolean; UniqueID: string; Duration: TTimeValue);
Called when the playback of an item begins or ends, in any player (playlist, cartwall, etc.). These are the same events that are passed to the logging interfaces, so they are the best choice for “now playing” information or as-run logs.
Item: The item.Region: The region the item is played in, when regionalization is used.OnAir: Whether mAirList was in ON AIR mode when the item was played.UniqueID: A unique ID for this playback, which is identical inOnItemStartand the correspondingOnItemStop, so the two events can be matched.Duration(OnItemStoponly): How long the item was playing, in seconds.
procedure OnItemCueMarker(Item: IPlaylistItem; MarkerType: TCuePositionType);
Called when the playback of an on-air item passes a cue marker.
Item: The item.MarkerType: The type of the cue marker, e.g.ptRamp1,ptHookIn,ptOutro,ptStartNext,ptFadeOut, orptCueOut.
procedure OnItemMetadata(Item: IPlaylistItem; Metadata: string);
Called when metadata (e.g. the current title) is received from a stream that is played or relayed.
Item: The stream item.Metadata: The received metadata, e.g.Artist - Title.
PFL
procedure OnPFLOn(Item: IPlaylistItem; PFLCount: integer);
procedure OnPFLOff(Item: IPlaylistItem; PFLCount: integer);
Called when any PFL source (player, cart player, Cue Editor, Mix Editor, etc.) starts or stops PFL playback.
Item: The item played in PFL.PFLCount: The number of active PFL sources after the change.
procedure OnExtPFLOn(Item: IPlaylistItem; ExtPFLCount: integer);
procedure OnExtPFLOff(Item: IPlaylistItem; ExtPFLCount: integer);
Same as above, but only for “external” PFL sources, i.e. editors such as the Cue Editor or Mix Editor, not players.
Item: The item played in PFL.ExtPFLCount: The number of active external PFL sources after the change.
Serial Ports and MIDI
procedure OnSerialData(Port: string; Data: AnsiString);
Called when data is received from a serial port. The port must be opened first, either from
the script (using the ComPort function), or by adding a
Serial Port remote control interface for
that port.
Port: The name of the port, e.g.COM1.Data: The received data. Data may arrive in arbitrary chunks, so you may have to buffer it until a complete message has been received.
procedure OnMidiMessage(Device: integer; Status, Data1, Data2: byte);
procedure OnMidiSysex(Device: integer; Data: string);
Called when a MIDI message or a SYSEX message is received from a MIDI input device that is opened, e.g. by a MIDI remote control interface.
Device: The number of the MIDI input device.Status,Data1,Data2: The status byte (message type and channel) and the two data bytes of the message.Data: The SYSEX data.
Voice Tracking
procedure OnVTOn;
procedure OnVTOff;
Called when the Voice Track Recorder is opened or closed.
procedure OnVTVolume(Player: string; Volume: single; Source: string);
Called when a volume slider is moved in the Voice Track Recorder.
Player: The player whose volume was changed,AorB.Volume: The new volume in dB.Source: Where the change originated from:GUI(moved with the mouse) orREMOTE(changed through a remote control).
Encoder
procedure OnEncoderInputToggle(Input: TEncoderInput; NewState: boolean);
Called when an input of the encoder is switched on or off.
Input: The encoder input, e.g.eiPlayer,eiMic,eiLine, oreiAux.NewState:trueif the input was switched on,falseif it was switched off.
procedure OnEncoderConnectionStateChange(Connection: IEncoderConnection; OldState, NewState: TEncoderConnectionState);
Called when the state of an encoder connection (e.g. to a streaming server) changes.
Connection: The encoder connection.OldState,NewState: The previous and the new state:ecsDisconnected,ecsConnecting,ecsConnected, orecsError.
Remote Control Interfaces
The following event handlers are related to particular remote control interfaces. In the template, they are commented out, as the script would otherwise fail to compile when the respective module is not available.
In all of these handlers, the Remote parameter is the remote control interface that
triggered the event, so you can distinguish between multiple interfaces of the same type.
SAS
procedure OnSASCommand(Remote: ISASRemote; Command: byte; Data: string);
Called for every message received from the SAS interface.
Command: The SAS command code.Data: The raw data bytes of the message.
procedure OnSASGPIOn(Remote: ISASRemote; GPI: byte);
procedure OnSASGPIOff(Remote: ISASRemote; GPI: byte);
Called when a GPI of the console goes on or off.
GPI: The number of the GPI, counted from 1.
procedure OnSASPFLOn(Remote: ISASRemote; SourceName: string);
procedure OnSASPFLOff(Remote: ISASRemote; SourceName: string);
Called when the PFL of a console source is switched on or off.
SourceName: The name of the source.
DHD
procedure OnDHDCommand(Remote: IDHDRemote; ID: cardinal; Len: integer;
Data0, Data1, Data2, Data3, Data4, Data5, Data6, Data7: byte);
Called for every message received from a DHD ECP interface.
ID: The message ID.Len: The number of data bytes in the message (0 to 8).Data0toData7: The data bytes of the message (unused bytes are 0).
procedure OnDHDLogic(Remote: IDHDRemote; LogicNo: integer; State: boolean);
Called when a logic of the DHD core changes its state.
LogicNo: The logic ID.State: The new state of the logic.
procedure OnDHDFaderOn(Remote: IDHDRemote; FaderNo: integer; State: boolean);
procedure OnDHDFaderPFL(Remote: IDHDRemote; FaderNo: integer; State: boolean);
procedure OnDHDFaderLevel(Remote: IDHDRemote; FaderNo: integer; Level: SmallInt);
Intended to be called when a fader is switched on or off, its PFL is switched, or its level changes.
OnDHDFaderOn, OnDHDFaderPFL and OnDHDFaderLevel are currently not called.
procedure OnDHDControlAPIConnected(Remote: IDHDControlAPIRemote);
procedure OnDHDControlAPIDisconnected(Remote: IDHDControlAPIRemote);
Called when the connection of a DHD Control API interface to the core is established or lost.
procedure OnDHDControlAPILogic(Remote: IDHDControlAPIRemote; LogicNo: integer; State: boolean);
Called when a logic changes its state (DHD Control API).
LogicNo: The logic ID.State: The new state of the logic.
procedure OnDHDControlAPIChannelOn(Remote: IDHDControlAPIRemote; ChannelNo: integer; State: boolean);
Called when the fader start of a channel changes (DHD Control API).
ChannelNo: The fader channel number.State: The new fader start state.
WheatNet-IP
procedure OnWheatNetBladeSLIOEvent(Remote: IWheatNetBladeRemote; SLIO: integer; State: boolean);
Called when an SLIO of a WheatNet-IP BLADE changes its state.
SLIO: The number of the SLIO.State: The new state.
procedure OnWheatNetBladeSLIOState(Remote: IWheatNetBladeRemote; SLIO: integer; State: boolean);
Called when the reply to a QuerySLIO request is received. The parameters are the same
as above.
Telos VX (LWCP)
procedure OnLWCPCommand(Remote: IBaseLWCPRemote; Command: string; ObjectName: string; Data: IPersistentObject);
Called for every LWCP message received from a Telos VX interface.
Command: The LWCP operation, e.g.eventorack.ObjectName: The object the message refers to, e.g.studio.line#1.Data: The properties of the message, as name/value pairs.
procedure OnVXLineEvent(Remote: IVXLWCPRemote; Line, Hybrid: integer;
Comment, State, CallState: string; Time, Cause: integer;
Busy: boolean; RemoteNumber, CallerID, Direction: string);
Called when the state of a phone line changes. The parameters correspond to the properties of the line, as reported by the VX engine:
Line: The line number.Hybrid: The hybrid the line is assigned to.Comment: The comment entered for the call (e.g. by the call screener).State,CallState: The state of the line and of the call.Time: The duration of the call.Cause: The cause code (e.g. when a call is dropped).Busy: Whether the line is busy.RemoteNumber,CallerID: The number and caller ID of the remote party.Direction: The direction of the call (incoming or outgoing).
REST and WebSocket
procedure OnRESTRequest(Request: TRESTRequest; var Response: IPersistentStorage);
procedure OnRESTRequestUnauthenticated(Request: TRESTRequest; var Response: IPersistentStorage);
Called when a request is made to the REST server. This lets you implement your own JSON endpoints. Use paths that do not collide with the built-in endpoints. For authenticated requests, the user must have the Scripting permission in the REST user management.
Request: The request, with the fieldsMethod(e.g.GETorPOST),Document(the path, e.g./myendpoint),Parameters(query or form parameters) andUploadDocument(the JSON body of the request, if any).Response: Set this to the JSON result to handle the request. Leave it unassigned (nil) to pass the request on to the next handler.
OnRESTRequest is only called for authenticated requests. OnRESTRequestUnauthenticated
is called before authentication is checked, so it is also called for requests without
valid credentials. Be careful not to expose any sensitive functions there.
procedure OnRESTRequestRaw(Request: TRawRESTRequest; var Response: TRawRESTResponse);
procedure OnRESTRequestRawUnauthenticated(Request: TRawRESTRequest; var Response: TRawRESTResponse);
Same as above, but for non-JSON responses, e.g. HTML pages or files.
Request: The request, with the fieldsMethod,DocumentandParameters.Response: To handle the request, setResponse.Handled := true, and fill inResponseNo(the HTTP status code, e.g. 200),ContentType,CharSetandData. Alternatively, setSendFile := trueandFilenameto send a file.
procedure OnWebSocketServerNewConnection(Event: TRESTWSNewConnectionEvent);
procedure OnWebSocketServerConnectionClosed(Event: TRESTWSConnectionClosedEvent);
procedure OnWebSocketServerTextData(Event: TRESTWSTextDataEvent);
Called when a WebSocket client connects to or disconnects from the REST server, or sends text data.
Event.Remote: The REST remote control interface.Event.Document: The path of the WebSocket connection.Event.ConnectionInfo: Information about the client connection:ID(unique connection ID),IP,Port,UserIDandUserName(of the authenticated user).Event.Data(OnWebSocketServerTextDataonly): The received text.
JSON Server and JSON Client
procedure OnJSONServerRemoteClientConnect(Remote: IJSONServerRemote; ClientID: cardinal);
procedure OnJSONServerRemoteClientDisconnect(Remote: IJSONServerRemote; ClientID: cardinal);
Called when a client connects to or disconnects from a JSON Server interface.
ClientID: A unique ID of the client connection, which can be used withSendTo.
procedure OnJSONServerRemoteClientData(Remote: IJSONServerRemote; ClientID: cardinal; Data: IPersistentStorage);
procedure OnJSONServerRemoteClientDataObject(Remote: IJSONServerRemote; ClientID: cardinal; Data: IPersistentObject);
Called when a JSON document is received from a client. OnJSONServerRemoteClientDataObject
is only called if the document is a JSON object, which saves you the type check.
ClientID: The ID of the client connection.Data: The received JSON document.
procedure OnJSONClientRemoteConnect(Remote: IJSONClientRemote; ClientID: cardinal);
procedure OnJSONClientRemoteDisconnect(Remote: IJSONClientRemote; ClientID: cardinal);
Called when the connection of a JSON Client interface to its server is (re-)established or lost.
ClientID: Always 0; only present for compatibility with the JSON Server handlers.
procedure OnJSONClientRemoteData(Remote: IJSONClientRemote; Data: IPersistentStorage);
procedure OnJSONClientRemoteDataObject(Remote: IJSONClientRemote; Data: IPersistentObject);
Called when a JSON document is received from the server. OnJSONClientRemoteDataObject is
only called if the document is a JSON object.
Data: The received JSON document.
8 - Network Sync
Network Sync lets several mAirList instances in the same local network exchange status information and commands. Its main uses are:
- ON AIR synchronization: In a setup with several studios (or a studio and an automation PC), only one instance should be ON AIR at a time. When one instance goes ON AIR, all other instances of the same group automatically go OFF AIR.
- Command forwarding: Remote control commands can be sent from one instance to the others, e.g. to start a player in another studio from a cartwall button.
The instances communicate via UDP broadcasts, so no central server is required. All instances must be in the same network segment, and use the same UDP port.
Configuration
Network Sync is configured on the Advanced → Network Sync page of the configuration. This page is also available in the live configuration (mAirList Control Panel).
Transports
- UDP Broadcast: Check Enable to send and receive Network Sync messages via UDP broadcast (enabled by default). Enter the UDP Port (default 9393), and optionally the Bind IP, i.e. the local IP address(es) to use, separated by commas. Leave empty to use all network interfaces.
ON AIR Sync
Check Enable ON AIR synchronization to enable this feature, and set up the identification of this instance:
- Client ID: The name of this instance in the network. Leave empty to use the computer name.
- Group ID: Only instances with the same group ID are synchronized with each other. Use different group IDs if you run several independent setups (e.g. for different stations) in the same network.
- Default Client: The client ID of the instance that should go ON AIR automatically when another instance of the group is switched OFF AIR, e.g. the automation PC that takes over when the live studio goes off air. Leave empty to disable this behavior.
When ON AIR synchronization is enabled:
- Whenever this instance goes ON AIR, all other instances of the same group go OFF AIR.
- When this instance is switched OFF AIR (manually, by a command etc., but not by Network Sync itself), and a default client is configured, the default client is switched ON AIR, so that the program is never left without an ON AIR instance.
Commands
- Prefix for commands to be forwarded to network:
Commands that start with this prefix (followed by a space) are not executed locally,
but sent to all other instances, with the prefix removed. The default prefix is
NETWORK. - Prefixes for commands received from network: Enter one prefix per line. A command received from the network is only executed if it starts with one of these prefixes (followed by a space); the prefix is removed before the command is executed. All other commands are ignored.
For example, to address the instance in studio 2, enter STUDIO2 as an incoming prefix
on that instance. Then, on any other instance, execute:
NETWORK STUDIO2 PLAYER 1-1 START
The command STUDIO2 PLAYER 1-1 START is broadcast to the network, and the instance in
studio 2 executes PLAYER 1-1 START. You can configure several incoming prefixes per
instance, e.g. an individual prefix and a common one such as ALL, to address all
instances at once.
9 - Matrix Mixer
The Matrix Mixer routes audio from recording devices (inputs) to playback devices (outputs) inside mAirList, e.g. to monitor a live input on a sound card output, to feed a sound card input into the encoder, or to pass a signal from one device to another without a hardware mixer.
Usage
The Matrix Mixer window is found in the Windows section of the About menu.
The window displays a matrix, with the recording devices as rows, and the playback devices as columns. Click a cell to connect the respective input to the output (a mix point); click it again to remove the connection. An input can be routed to several outputs, and an output can receive several inputs, which are mixed together.
Mix points take effect immediately. Note that they are not saved in the configuration, and are lost when mAirList is closed.
Saving and Loading
Use the Save button to save the current mix points into a text file, and Load to restore them from such a file. Loading a file replaces all current mix points.
The same can be done with the following remote control commands, e.g. to switch between different routings with the event scheduler:
MATRIXMIXER LOAD <filename>– load the mix points from the fileMATRIXMIXER SAVE <filename>– save the current mix points to the file
10 - Regionalization
Regionalization allows a single mAirList playout to broadcast several regional variants of the program at the same time. Most of the program is common to all regions, but at certain times, e.g. during advertising breaks, regional news, or traffic reports, each region plays its own content.
A typical example is a station with several transmitters, each covering a different area: the music and moderation are the same for everyone, but each area gets its own local advertising.
How It Works
With regionalization enabled, mAirList handles one common signal, plus one separate signal for each region:
- Regular playlist items are played on the common signal.
- At the points where the program splits into regions, a Region Container item is placed in the playlist. It contains a separate list of items for each region. When the container is played, the content of each region is played at the same time, each on the signal of its region.
- When all regions have finished, playback continues with the next item of the playlist, again on the common signal.
The complete program for a particular region is therefore the common signal plus the signal of that region. These two signals are mixed by the encoder (for streaming) or by an external mixer (e.g. for each transmitter feed).
Configuration
Regionalization is set up on the Regionalization page of the configuration.
- Number of regions to be used in playout: The number of regions you want to use. The maximum is the number of regions included in your license, which is displayed above. Set to 0 to disable regionalization.
- Region Names:
Click Edit… to enter a code and a name for each region, e.g. code
Nand nameNorth. The names are displayed throughout the user interface, e.g. in the audio routing and in the Region Container properties. The codes and names can also be used in logging variables (%N{CODE},%N{NAME}), e.g. for log file names or playlist import filenames. - Custom mapping (Advanced):
Changes which region content is played on which signal. This is only required in
special setups; leave empty for the normal 1:1 mapping. Two forms are supported:
- A single region number, e.g.
2: Only the content of region 2 is played, and it is played on the common signal instead of a separate region signal. This is useful for an additional playout PC that only feeds one particular region, and has no regional outputs at all. - A comma-separated list, e.g.
1,1,2: For each region, the number of the region whose content should be played on it. In this example, regions 1 and 2 both play the content of region 1, and region 3 plays the content of region 2.
- A single region number, e.g.
Audio Routing
When regionalization is enabled, each playback function in the Audio Routing configuration has a sub-node for each region. Assign the output device for the common signal to the main node, and the output devices for the region signals to the region sub-nodes. If no device is assigned to a region sub-node, the region content is played on the device of the main node.
When the players play into the encoder, the encoder takes care of the regions automatically, and each encoder connection can include the common signal and the signal of a particular region.
Region Containers
A Region Container is a playlist item that holds separate content for each region.
Creating Region Containers
Region Containers can be created in the following ways:
- In the playout, use the Insert menu in the main toolbar, and select Region Container.
- In the database, region containers can be stored in the library, or generated automatically by the scheduler (e.g. with the Region Container template item), and by the advertising module for blocks with regional content.
Editing Region Containers
Open the properties of the Region Container (double-click it in the playlist). The Region Content page contains one tab for each region. Add the items for each region to its tab, e.g. by drag & drop from the browser.
In the Options section, you configure what happens when the content of the regions has different durations. The container always plays until the longest region has finished; the Auto fill setting determines what is played in the other regions in the meantime:
- None: Nothing; the shorter regions simply end early.
- Silence: The remaining time is distributed evenly as short pauses between the items of the shorter regions, so that all regions end at the same time (default). This requires at least two items in the region.
- Use filler (fade out at end): The Filler item (e.g. an instrumental bed or a short jingle) is added after the regional content as often as it fits completely. The remaining time is filled with one more copy of the filler, which is faded out when the longest region ends.
- Use filler (fade in and play until end): Same as above, but the last copy of the filler is faded in (starting somewhere in the middle of the filler), so that it ends exactly when the longest region ends.
Use Edit… to select the filler item, and Clear to remove it.
Where Else Regionalization Is Used
Besides Region Containers and the audio routing, regions are supported in the following places:
- Encoder: Separate streams for each region, see Encoder Regionalization.
- Logging: Each played item is logged together with the region it was played in. In
the configuration of each logging interface, you can select on the Regions tab which
regions should be logged, e.g. to create a separate as-run log per region. The region is
also available in logging variables (
%N). - Advertising: Campaigns can be limited to particular regions, and advertising blocks with regional content are created as Region Containers, see Advertising.
- Scheduling: Scheduler templates can create Region Containers, and map sub-playlists to regions, see Scheduling.
- Playlist import: Import filenames can contain the region number or code, so that separate files per region can be imported, see Logging Variables.
- MusicMaster: Region suffixes for content imported from MusicMaster, see the database configuration.
- Scripting: The
OnItemStartandOnItemStopevent handlers receive the region of the item, see Scripting.
11 - MusicMaster Integration
MusicMaster is a professional music scheduling software, used by many radio stations worldwide. It can be used in place of the built-in music scheduler of mAirListDB, which is well suited for smaller setups, but has fewer options.
mAirList can work together with MusicMaster in three different ways, which differ in how the music library is kept in sync, and how the scheduled music gets into the mAirList playlist:
| Library | Music schedule | Primary database | |
|---|---|---|---|
| 1. Sync via files | CSV export from mAirListDB | TPI files, imported by music templates | mAirListDB |
| 2. Sync via Nexus API | Sync via Nexus | Imported via Nexus by music templates | mAirListDB |
| 3. Nexus database connection | Managed in MusicMaster | Loaded directly from MusicMaster | MusicMaster |
In the first two approaches, mAirListDB remains the primary database: It holds the library, the playlists, advertising, voice tracks etc. New songs are always added to mAirListDB first, and then transferred to MusicMaster. The scheduler of mAirListDB generates the playlists from hour templates as usual; only the music is scheduled by MusicMaster, and imported into the playlists through the music templates. This way, you can keep using the hour templates for fixed elements such as news, jingles and advertising, and let MusicMaster schedule the music only.
In the third approach, there is no mAirListDB at all: The playout connects directly to MusicMaster, and all library maintenance and scheduling is done in MusicMaster. This is particularly suited for 24/7 automated music channels, as no synchronization is required.
Common Setup: Hour and Music Templates
For approaches 1 and 2, the scheduled music is imported by the mAirListDB scheduler. The simplest setup is:
- An hour template containing a Start of hour marker, one large Fill with music section, and an End of hour marker. Use Music block instead of Fill with music to import the entire log that MusicMaster generated for that hour, including any overplanning.
- A music template, in which the source of Block 1 is set to External scheduler (or Hybrid, to fall back to the internal scheduler if the import fails), with the import configured as described below.
- The music template assigned to all hours of the week in the Template Assignments grid.
Then generate the playlists as usual, e.g. with the Generate button in the playlist editor of the Database app. See the Scheduling chapter for details.
1. Sync via Files (CSV and TPI)
This approach exchanges text files between the two systems. It is recommended to create a
set of folders for the files, e.g. C:\MM_Sync\Library for the library export and
C:\MM_Sync\Schedule for the schedule export.
Library Synchronization
- In the Database app, use Database → Export to export the entire library (or the current
view or selection), and choose the CSV file format. Always use the same filename, e.g.
C:\MM_Sync\Library\LibraryExport.csv, and overwrite it with each export. See Library Export for details on the CSV format. - In MusicMaster, import the file using a library synchronization definition (
.deffile), placed in the same folder as the MusicMaster database. The definition specifies the source file (SourceType=AsciiD,SourcePath,SourceSpec) and maps the CSV columns (e.g.ID,ExternalID,Filename,Title,Artist) to the MusicMaster fields, separately for new songs and for updates of existing songs. A template for this file is available from MusicMaster support or mAirList support; adjusting it to your database with the help of MusicMaster support is recommended. - Run the synchronization in MusicMaster with Dataset → Library → Synchronize.
It is essential that the mAirListDB database ID is imported into a MusicMaster field, as this is how the songs in the MusicMaster schedule are identified in mAirListDB later.
Repeat the export and synchronization whenever new songs have been added to mAirListDB.
Schedule Export
- In MusicMaster, create an export definition for mAirList in the Export File Designer
(again, MusicMaster support can provide a template). For the song elements (music,
non-music and control items), the 4th column must contain the field with the mAirListDB
database ID. Set the Output filename pattern to
@y1@m1@d1.TPI(one file per day, namedYYYYMMDD.TPI), and the Default output path to the schedule folder. - Export the schedule with Dataset → Schedule → Export → Export to Automation, selecting the mAirList export definition and the date range.
Schedule Import
In the music template, click Configure… next to the block source, and set up the import:
- File format: TPI Text Playlist Import File
- File style: One file per day
- Split hour by / Split block by: Automatic, which uses the start times and block markers in the file.
- Source folder: The schedule folder, e.g.
C:\MM_Sync\Schedule. - Filename format:
%Y%M%D.TPI
When the scheduler generates a playlist, the songs of the respective hour are imported from the TPI file.
The TPI Format
A TPI file is a text file (UTF-8), with one line per entry. The columns are separated by commas or tabs:
- Start time (optional):
hh:mmorhh:mm:ss. This also determines the hour the line belongs to. - Timing (optional):
N(normal),H(hard fixed time),S(soft fixed time),B(backtimed),E(excluded), orF(fixed).HandSrequire a start time. - Line type:
I– an item from the database, identified by its database ID (column 4)E– an item from the database, identified by its External ID (column 4)F– an audio file (column 4), optionally followed by title, artist and item typeD– a dummy item with the title in column 4B– start of a new block, with the block number in column 4 (optional)R– a remark, which is ignoredO– an option, e.g.ItemType(default item type forFlines)
- Data: Depending on the line type, see above.
See TPI Format for the full specification.
A typical file exported from MusicMaster looks like this:
08:00:00,N,I,4711
08:03:25,N,I,4712
08:07:10,N,I,4713
If the 4th column is missing or empty, check that the correct field is used in the export definition, and that the IDs were imported correctly during library synchronization.
2. Sync via Nexus API
MusicMaster Nexus is a server component that provides access to the MusicMaster database over the network. With the Nexus API, mAirListDB exchanges data with MusicMaster directly, without exporting and importing files. Otherwise, this approach works just like the file synchronization.
First, set up the connection to the Nexus server on the Databases → MusicMaster Nexus page of the configuration: Enter the URL and credentials of the Nexus server, the MusicMaster database, and the field mapping. In particular, map the ID field to a MusicMaster field: mAirList stores the database IDs there during library synchronization, and uses them to identify the songs when importing the schedule. See MusicMaster Nexus in the configuration chapter.
Library Synchronization
In the Database app, use Database → Export (entire library, current view, or selection), and choose one of the following formats:
- MusicMaster Nexus (new items only): Only songs that do not exist in MusicMaster yet are created. Existing songs are not changed.
- MusicMaster Nexus (new items and updates): Additionally, existing songs (identified by the database ID in the MusicMaster ID field) are updated with the current data from mAirListDB.
If more than one Nexus API is configured, you are asked which one to use.
Schedule Import
No schedule export is required in MusicMaster: mAirList retrieves the schedule directly through the Nexus API.
In the music template, set the source of the block to External scheduler (or Hybrid), click Configure…, and select MusicMaster Nexus as the Import source. The file-related settings of the playlist import are not used. Click Configure… next to the import source to set up the Nexus import:
- Nexus API: Select one of the Nexus APIs from the local configuration, or configure the connection globally for this template.
- Automatically split blocks at lognotes that contain the following string: If checked, the hour is split into blocks at MusicMaster lognotes. Enter a string to only split at lognotes that contain it, or leave it empty to split at any lognote.
- Raise error on unscheduled items: Treat unscheduled positions in the MusicMaster schedule as an error, instead of skipping them.
- Remove/filter lognotes: Do not import lognotes into the playlist.
- Remove/filter items marked as “No Export”: Skip items that are marked as “No Export” in MusicMaster.
The scheduled songs are then retrieved from MusicMaster whenever the mAirListDB scheduler generates a playlist.
3. Nexus Database Connection
In this approach, mAirListDB is not used at all. Instead, the playout is connected directly to MusicMaster, through a database connection of type MusicMaster Nexus Server.
Prerequisites
- A MusicMaster database, with a Nexus server (or a MusicMaster client/server database that implements the Nexus API). Its HTTP port must be reachable from the playout computer.
- An audio folder that is accessible from the playout computer (via a Windows share or HTTP). The filenames of the songs (without folder) must be stored in a MusicMaster field.
Setup
- Set up the Nexus API on the Databases → MusicMaster Nexus page of the configuration, including the audio folder and the field mapping. At least Artist, Title, Filename, and XML Metadata (in which mAirList stores additional metadata, e.g. cue markers) should be mapped.
- On the Databases page, click Add and select MusicMaster Nexus Server. Select the Nexus API, and adjust the settings of the connection. See MusicMaster Nexus Server for a description of all settings.
Playout
With this connection:
- The playout loads the hourly playlists directly from the MusicMaster schedule, e.g. with the usual hourly event in the event scheduler.
- Songs are played from the audio folder, using the filename stored in MusicMaster.
- Lognotes can be replaced by advertising blocks or external content (e.g. news), see the Content tab of the database connection.
- With Reconciliation enabled, mAirList reports the start and stop of each song back to MusicMaster in real time, so that the actual playback is recorded in MusicMaster.
The following actions are available to keep the playlist in sync with changes made in MusicMaster after the playlist has been loaded:
- MusicMaster → Synchronize Playlist: Synchronizes the playlist with the current schedule in MusicMaster.
- MusicMaster → Update unscheduled positions: Updates the unscheduled positions of the playlist from MusicMaster.
Adding Music
New songs can be added to the MusicMaster library in two ways:
- Manually in MusicMaster. The exact filename must be entered into the filename field.
- With the Nexus Importer (
mAirList.exe -mode nexusimporter), which is also available from the Windows Start Menu. It retrieves the list of songs from MusicMaster, scans the audio folder for audio files that are not in MusicMaster yet, and lets you select which of them to import as new songs. The tags of the files (e.g. ID3 tags) are transferred into the MusicMaster fields.
Editing Music
Library maintenance should generally be done in MusicMaster. The main exception are the cue
markers, as MusicMaster does not provide an editor for them. They can be edited with the
Nexus Editor (mAirList.exe -mode nexuseditor -songid <id>), which opens the mAirList
item properties dialog for a particular MusicMaster song, and saves the changes back to
MusicMaster.
MusicMaster User Buttons
Both tools can be launched directly from MusicMaster with User Buttons, which are defined
in MusicMaster.ini. Adjust the paths to your installation:
[UserButton1]
Tooltip=Look for New Files in mAirList
App=C:\Program Files\mAirList\mAirList.exe
CommandScript="-mode nexusimporter"
[UserButton2]
Tooltip=Edit song in mAirList
App=C:\Program Files\mAirList\mAirList.exe
CommandScript="-mode nexuseditor -songid " & mm.GetField(1)
If more than one MusicMaster database is configured, add the database to the command line,
e.g. "-mode nexuseditor -database """ & mm.DatasetLogo & """ -songid " & mm.GetField(1).
The value of -database is matched against the database ID and the alias of the Nexus APIs
configured in mAirList.
Regionalization
With regionalization, mAirList can create Region Containers automatically from the MusicMaster schedule:
- On the Content tab of the database connection, enter a filename suffix for each region,
e.g.
-ATOWN,-BTOWN,-CTOWN. - Create the regional versions of an item with these suffixes, e.g.
jingle1-ATOWN.mp3,jingle1-BTOWN.mp3andjingle1-CTOWN.mp3. They should have the same duration, and must be stored in the same folder. - In MusicMaster, create a Yes/No field (e.g. “Regionalized”), check it for these items, and map it to Regionalized in the Nexus API field mapping.
- Schedule one of the versions (e.g.
jingle1-ATOWN.mp3) in MusicMaster.
When mAirList encounters a regionalized item in the schedule, it collects the versions for the other regions by their suffixes, and creates a Region Container from them.