auditok can also be used from the command-line. For more information about parameters and their description type:

auditok -h

In the following we’ll a few examples that covers most use-cases.

Read and split audio data online

To try auditok from the command line with you voice, you should either install pyaudio so that auditok can directly read data from the microphone, or record data with an external program (e.g., sox) and redirect its output to auditok.

Read data from the microphone (pyaudio installed):

auditok

This will print the id, start time and end time of each detected audio event. Note that we didn’t pass any additional arguments to the previous command, so auditok will use default values. The most important arguments are:

  • -n, --min-duration : minimum duration of a valid audio event in seconds, default: 0.2
  • -m, --max-duration : maximum duration of a valid audio event in seconds, default: 5
  • -s, --max-silence : maximum duration of a consecutive silence within a valid audio event in seconds, default: 0.3
  • -e, --energy-threshold : energy threshold for detection, default: 50

Read audio data with an external program

If you don’t have pyaudio, you can use sox for data acquisition (sudo apt-get install sox) and make auditok read data from standard input:

rec -q -t raw -r 16000 -c 1 -b 16 -e signed - | auditok - -r 16000 -w 2 -c 1

Note that when data is read from standard input, the same audio parameters must be used for both sox (or any other data generation/acquisition tool) and auditok. The following table summarizes audio parameters.

Audio parameter sox option auditok option auditok default
Sampling rate -r -r 16000
Sample width -b (bits) -w (bytes) 2
Channels -c -c 1
Encoding -e NA always a signed int

According to this table, the previous command can be run with the default parameters as:

rec -q -t raw -r 16000 -c 1 -b 16 -e signed - | auditok -i -

Play back audio detections

Use the -E option (for echo):

auditok -E
# or
rec -q -t raw -r 16000 -c 1 -b 16 -e signed - | auditok - -E

The second command works without further argument because data is recorded with auditok’s default audio parameters . If one of the parameters is not at the default value you should specify it alongside -E.

Using -E requires pyaudio, if it’s not installed you can use the -C (used to run an external command with detected audio event as argument):

rec -q -t raw -r 16000 -c 1 -b 16 -e signed - | auditok - -C "play -q {file}"

Using the -C option, auditok will save a detected event to a temporary wav file, fill the {file} placeholder with the temporary name and run the command. In the above example we used -C to play audio data with an external program but you can use it to run any other command.

Save detections

You can save audio events to disk as they’re detected using -o or --save-detections-as. To get a uniq file name for each event, you can use {id}, {start}, {end} and {duration} placeholders. Example:

auditok --save-detections-as "{id}_{start}_{end}.wav"

When using {start}, {end} and {duration} placeholders, it’s recommended that the number of decimals of the corresponding values be limited to 3. You can use something like:

auditok -o "{id}_{start:.3f}_{end:.3f}.wav"

Save whole audio stream

When reading audio data from the microphone, you most certainly want to save it to disk. For this you can use the -O or --save-stream option.

auditok --save-stream "stream.wav"

Note this will work even if you read data from another file on disk.

Plot detections

Audio signal and detections can be plotted using the -p or --plot option. You can also save plot to disk using --save-image. The following example does both:

auditok -p --save-image "plot.png" # can also be 'pdf' or another image format

output example:

_images/example_1.png

Plotting requires matplotlib.