Triggered Audio Recorder (in Spectrum Lab)

Contents
Introduction
Example 1
The Trigger
Interpreter commands for the triggered audio recorder

Introduction

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:
Recording
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.

Note:
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 .


How to use the Triggered Audio Recorder - example 1

Let's assume you want to record the call of bats in a certain frequency range. Five 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 ten 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 checkmark 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. Click on the blue link (in the control panel) to open the circuit window, on which the "universal trigger" can be configured.
    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 required, because it may eat up 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 .
  • 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. The filename itself is defined on the "Filenames" tab. It 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 can also contain the date and time of recording, by using the 'template' option on the 'filenames and directories' tab.

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".

Note:
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.

Examples:
rec.trigger = 1  : REM set the recorder's trigger-flag
rec.trigger = 0  : REM clear the recorder's trigger flag
rec.trigger = (peak_a( 1000,1200) > -30) : REM trigger on a strong signal between 1000 and 1200 Hertz (above -30 dB)

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:
"rec.trigger="+((rec.trigger)?"ON":"off")
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 as 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.

rec.file_index

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 .

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, with the option "use as template" set. If the 'template' checkmark is set, the program will use the filename (entered in the config dialog) as a template, aka format string, for the real filename. In combination with the template option, use something like RecordedAudio_YMMDD_hhmmss.wav as the template in the configuration. A reference about formatting date and time (into strings) is here .
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 result in the fact that the triggered audio recorder doesn't 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)

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

back to top


Last modified: 2010-06-21