Triggered Audio Recorder (in Spectrum Lab)

  1. Introduction
  2. Use cases for the Triggered Audio Recorder - Examples and Settings
  3. The Trigger
  4. Interpreter commands for the triggered audio recorder
    1. rec.trigger = N
    2. rec.file_index
    3. rec.filename
  5. Events generated by the triggered audio recorder
    1. rec.started
    2. rec.stopped

Introduction into the Triggered Recorder

In addition to the 'normal' wave-file logging routine implemented in Spectrum Lab, there is the possibility to save audio streams in disk files triggered by certain events, such as ...
  • a certain signal level (threshold) is exceeded
  • an "interesting" signal has appeared in the spectrum
  • a certain time has elapsed since "something else" happened
  • you just noticed the sound of that certain bird / bat / meteor (etc), which you want to save after the event actually happened .

The last point is the reason why the "triggered audio recorder" is different from SpecLab's normal wave recording routine: Only the 'Triggered Audio Recoder' has its own, quite large buffer in RAM which is permanently filled with the last N seconds of audio, without keeping the hard disk busy. Only when this recorder is triggered, it begins to write the data from the buffer to disk.

The current status of the triggered recorder is displayed as a small symbol in the menu of SL's main window :

passive (gray)
The triggered audio recorder is not enabled (in the configuration), or turned off via interpreter command.
pre-trigger phase
The triggered audio recorder is collecting pre-trigger data in RAM, but not writing them to a disk file, because it is still waiting for a trigger event. When the trigger condition gets TRUE, the contents of the pre-trigger buffer are quickly written into a disk file, and the recorder enters the next state:
The trigger condition is TRUE, and the recorder is currently writing audio samples into a disk file. The recorder will remain in this state until the trigger condition gets FALSE. In that case, the post-trigger timer starts, and the recorder enters the next state:
post-trigger phase
The trigger condition is FALSE again, but the recorder still writes audio samples to a file (as long as the post-trigger timer has not run off). If, during this time, the trigger condition gets TRUE again, the recorder switches back to the 'Recording' state. After expiration of the post-trigger interval, the recorder switches back into the pre-trigger phase.

The triggered recorder was designed to operate entirely automatic, which means recording is controlled by a trigger signal. Additionally, the triggered recorder can be started and stopped manually: Click on the status indicator (in SpecLab's main menu) to open a popup where you can configure / start / stop the recorder, and see the current status of the recorder in plain text (like "waiting for trigger", "recording", etc).

Note: If the triggered audio recorder was started manually, it won't stop just because the (automatic) trigger condition is FALSE. When manually started, the recorder must be manually stopped. When automatically started (i.e. trigger condition became TRUE), it will stop when the trigger condition became FALSE again, *and* the post-trigger interval has expired.

In this document, we begin with a simple example demonstrating the basic usage of the triggered audio recorder.

Since SpecLab V2.71, it is also possible to listen to audio captured in the spectrum display buffer, using the inverse FFT, as an alternative to recording the audio in the time domain.

See also: Wave File Settings; normal wave file logging (started from the menu or via command); Spectrum Lab's main index .

Use cases for the Triggered Audio Recorder - Examples and Settings

Assume you want to record the call of bats in a certain frequency range. A few seconds of data shall be recorded before the event actually happened (let's call this the pre-trigger area). While the bats are loud enough, the recording shall continue. Then, if no sound exceeded the programmed threshold for another couple of seconds, the recording shall stop to avoid filling the harddisk with unimportant data (let's call those ten seconds the post-trigger area).

First configure the triggered recoder: Select Options..Wave File Settings in SpecLab's main menu, with the panel Triggered Audio Recorder (we'll configure the universal trigger later):

control panel for triggered audio recorder

  • Enabled : Select this option to enable the triggered recorder (without this option, it won't fill the pretrigger buffer to reduce CPU usage )
  • Use universal trigger : With this option, the trigger signal for the audio recorder is fed from the universal trigger function. Set the checkmark for 'use universal trigger', and click on the blue link (in the control panel) to open the circuit window, on which the "universal trigger" can be configured.
    Set the trigger level large enough for the bat calls (the bat call's peak level can be seen in SL's tiny oscilloscope aka 'monitor scope'), to avoid unintended 'firing'. Advanced users will tap the trigger after a bandpass filter, so only bats can trigger the recorder but no low-frequency signals.
    If you do not use the 'universal' trigger for the recorder (because you need it for something else), you can still trigger the recorder in the main menu (under "File"), or with an interpreter command .
  • Save input: If this radio button is checked, the recorder will save the input (before SL's processing chain)
  • Save output: If this radio button is checked, the recorder will save the output (after SL's processing chain)
  • PRE-trigger time: Defines how many seconds shall be recorded before the trigger event (i.e., before the trigger-condition becomes TRUE).
    Caution: The pre-trigger buffer uses RAM, not the harddisk. Don't make the pretrigger-time longer than necessary, because it consumes a large amount of memory ! With 96 kHz sampling in "stereo" , a pretrigger-buffer for 10 seconds will occupy about 10 * 96000 * 2 * 4 bytes = 7.7 MByte, because the buffer uses 32-bit floating point values. Furthermore, that amount of data must be flushed to disk in the moment the trigger fires, without interrupting the normal audio processing (too much for a "slow" PC) !
  • POST-trigger time: Defines how many seconds shall be recorded after the trigger-condition became FALSE .
    Note: If the post-trigger recording time is ZERO, the triggered audio recorder doesn't stop recording immediately when the trigger-condition becomes FALSE. Instead, with Post-Trigger = 0 seconds, a triggered recording continues forever until stopped manually (by clicking the 'Stop' button on the Triggered Audio Recorder panel), or stopped via script (interpreter command rec.trigger = 0).
  • File index : This index is incremented for every new audio file produced by the recorder. It can be used as a "serial number" in the filename. In that case, the filename's template should contain three or four lower-case "n"'s (like "BATSOUNDS_nnnn.WAV"), which will later be replaced with the sequence number (resulting in something like "BATSOUNDS_0001.WAV"). The file index can be accessed through the interpreter function rec.file_index .

    In addition, or as an alternative to the file index number, the filename (-template) can also contain placeholders for the date and time of recording, as explained in chapter about normal (non-triggered) audio file logging.
    Example (for the 'Name' field of the panel shown further above):
    creates a file with the current date and time (of the trigger event) in the filename.

See also:

back to top

The Trigger

The Triggered Audio Recorder can use SL's 'universal trigger module' to start (and stop) saving an audio stream to disk. Details about the trigger, how to select the trigger source, how to set the threshold and hysteresis etc can be found here. To configure the universal trigger, select "View/Windows" in SL's main menu, and select "Spectrum Lab Components (circuit window)". Locate the trigger box (it's near the lower right corner of the window), and click on it to open this popup menu:

screenshot of the "universal trigger" popup menu

After adjusting the trigger parameters (if necessary), select the trigger source. It will often be "L1", the left input channel from the soundcard aka "Line In".

For some applications, you may want to run the trigger signal through a digital filter (for example, to isolate the bat's "calling frequency" from low-frequency noise, etc). In that case, connect the trigger input to label L4 instead of L1. More details on that is in the document about the circuit window.

In addition to the "universal" trigger, you can start or stop the recorder by setting/clearing the trigger flag via command, or manually as explained in the introduction.

back to top

Interpreter commands for the triggered audio recorder

rec.trigger = N

Sets the trigger-flag for the recorder only (not for the "universal trigger module" in general). N can be any numeric expression. A NON-ZERO value of N sets the trigger (so the recorder starts recording, if enabled). N = 0 (zero) clears the trigger-flag, which will stop the recorder after the post-trigger time expires.

rec.trigger = 1  : REM set the recorder's trigger-flag. Recording starts, including the pre-trigger history.
rec.trigger = 0  : REM clear the recorder's trigger flag. Recording stops when post-trigger time expires.
rec.trigger = (peak_a( 1000,1200) > -30) : REM trigger on a strong signal between 1000 and 1200 Hertz (above -30 dBfs)

Note: If the universal trigger is also enabled for the triggered audio recorder, the actual trigger flag which starts the recorder will be a logic "OR"-combination of the trigger-flag from all sources. This also applies to the manual trigger flag, which you can set through SpecLab's main menu. In other words, if *ANY* of the trigger sources is "TRUE", the recorder will be started.

The command "rec.trigger" is most useful in the conditional action table (for example, if your script just detected a meteor, and you want to record the past few seconds before the meteor was detected, triggered by the script).

The current state of the trigger condition can be read with the "rec.trigger" function (in that context, it acts as a function, not a command). The next example demonstrates the use of this function for a programmable button (in SL's main menu) which shows the current trigger state, and toggles it when clicked:

Variable String Expression for button text:
Interpreter Command(s) to be executed on click:
rec.trigger = !rec.trigger

How does this work ? The function rec.trigger returns zero, if the trigger condition is FALSE, otherwise TRUE. The boolean negation (exclamation mark like the prefix operator in the C programming language) turns FALSE into TRUE, and TRUE into FALSE. The result (inverted trigger flag) is finally set as the new trigger flag when passed to the command rec.trigger, which then starts or stops the triggered audio recorder. The effect can also be seen in the recorder indicator in SL's main menu.


Allows to get and set the current file index for the audio recorder (accessable like a variable). If you want to use a custom filename for the triggered audio recorder (instead of the default name with the file index after the name), set the recorder's filename before triggering it (! - because after triggering, you cannot change the name of the file currently written to disk). See rec.filename .


Reads or sets the filename which the triggered audio recorder will use for the next file, which will be written at the next trigger event.
Note: Modifying the filename with this command only has an effect on the next file being written to disk. It has no effect for the file currently being written (if the trigger has already fired). To embed the date and time in the filename, without using an interpreter command as in the example below, you can enter a similar format string in the output wave file name in SL's settings, on the 'filenames and directories' tab, as a template. If the filename contains certain characters between right angle brackets (see exmples below), the program will use the filename from the config dialog as a template, aka format string, for the real filename.
For example, enter RecordedAudio_<YMMDD_hhmmss>.wav as the template in the configuration. When evaluating the template (to generate a real filename), everything between the right angle brackets will be replaced according to the following list (which, by the way, works similar as the command interpreter's format string for date and time):

Full year number
Year number, least significant digit only
Month number (1..12)
Day of month (1..31)
Hour number (0..23)
Minute of the hour (0..59)
Second of the minute (0..59)
Four-digit file sequence number (rec.file_index)
Here is an example to modify the name and start the trigger at the same time via interpreter command. It was only necessary for older SL versions, which didn't have the 'template' option for the filename yet. Some older sample configurations may still use this command to change the name of the saved audio file, just before beginning to record (Note the sequence... first change the filename, then start the trigger) :
rec.filename="rec"+str("YMMDD_hhmmss",now)+".wav"):rec.trigger=1 : REM change name and start trigger

Note: Modifiying the default filename (which is RecordedAudio_nnnn.WAV) this way may cause the triggered audio recorder not to use the file sequence number in the filename anymore. This is not a bug but a feature... if you want the file sequence number in the filename, specify a name with a few 'n's at the end of the name (just before the file extension), for example:

rec.filename="RecordedAudio_nnnn.wav" : REM back to the default filename with 'serial number' (nnnn)

Events generated by the triggered audio recorder

Event listed in this chapter are typically used in SL's Conditional Actions to perform certain operations after certain audio-recorder related events.


This flag will be set one time during the evaluation of the conditional actions in Spectrum Lab, whenever the audio recorder has just started recording a new file. The event is intended to do whatever you need to, after starting a new recorded audio file. Example for the table of 'conditional actions':

IF-column (condition) THEN-column (action)
rec.started timer3.start(5.0) : REM start a timer for 5 seconds
rec.started spectrum.print("Started recording"+rec.filename) : REM show 'start' in spectrogram
timer3.expired(1) capture : REM capture the spectrogram screen 5 seconds after audio recording started


This flag will be set one time during the evaluation of the conditional actions in Spectrum Lab, whenever the audio recorder has just stopped recording a file. The event is intended to do whatever you need to, after recording an audio file. Example for the table of 'conditional actions':

IF-column (condition) THEN-column (action)
rec.stopped spectrum.print("Stopped recording") : REM mark end of audio-recording in spectrogram

See also:
Overview of all interpreter commands
Overview of all interpreter functions
The "universal" trigger module

back to top

Last modified: 2015-01-19

Benötigen Sie eine deutsche Übersetzung ? Vielleicht hilft dieser Übersetzer - auch wenn das Resultat z.T. recht "drollig" ausfällt !
Avez-vous besoin d'une traduction en français ? Peut-être que ce traducteur vous aidera !