Command-line guide

auditok provides three subcommands: split (default, backward-compatible), trim, and fix-pauses. All three support file input and microphone recording.

For a summary of all options, type:

auditok -h
auditok split -h
auditok trim -h
auditok fix-pauses -h

Split audio into events

split is the default subcommand. Both forms are equivalent:

auditok audio.wav
auditok split audio.wav

To adjust detection parameters:

auditok audio.wav -e 55 -n 0.5 -m 10 -s 0.3

where:

  • -e, --energy-threshold: energy threshold for detection, default: 50

  • -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 continuous silence within a valid audio event in seconds, default: 0.3

Save detected events to individual files

Use -o or --save-detections-as with placeholders:

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

Available placeholders: {id} (sequential, starting from 1), {start}, {end}, and {duration} (all in seconds).

Save the full audio stream

Use -O or --save-stream to save the complete audio data (including silence) to disk. This is especially useful when reading from the microphone:

auditok --save-stream output.wav

Customize output format

The --printf option controls the format of printed detection information:

auditok audio.wav --printf "{id}: [{timestamp}] start:{start}, end:{end}, dur: {duration}"

output:

1: [2021/02/17 20:16:02] start:1.160, end:2.390, dur: 1.230
2: [2021/02/17 20:16:04] start:3.420, end:4.330, dur: 0.910
3: [2021/02/17 20:16:06] start:5.010, end:5.720, dur: 0.710

The format of {timestamp} is controlled by --timestamp-format (default: %Y/%m/%d %H:%M:%S) whereas that of {start}, {end} and {duration} is controlled by --time-format (default: %S, absolute number of seconds).

To completely disable printing detection information use -q.

Play back detections

Use -E (or --echo) to immediately play each detected audio event:

auditok -E

Alternatively, use -C to run an external command with each detection:

auditok audio.wav -C "play -q {file}"

The {file} placeholder is replaced with a temporary WAV file containing the detected event.

Plot detections

Use -p (or --plot) to display the audio signal and detections (requires matplotlib). Use --save-image to save the plot:

auditok audio.wav -p --save-image "plot.png"

Trim silence

Remove leading and trailing silence from audio:

auditok trim audio.wav -o trimmed.wav

The -o/--output option is required for trim.

Record from the microphone, trim, and save:

auditok trim -o trimmed.wav

When recording from the microphone, a blinking indicator shows elapsed time. Press Ctrl+C to stop recording. Use -q/--quiet to suppress the recording indicator.

Normalize pauses (fix-pauses)

Replace all pauses between detected events with a fixed duration of silence:

auditok fix-pauses audio.wav -o cleaned.wav -d 0.5

Both -o/--output and -d/--pause-duration are required.

Record from the microphone, normalize pauses, and save:

auditok fix-pauses -o cleaned.wav -d 0.5

Improving detection boundaries

Use -l/--max-leading-silence and -g/--max-trailing-silence to extend detection boundaries and capture the natural attack and fade-out of speech:

auditok audio.wav -l 0.2 -g 0.15

Values of 0.1 – 0.3 seconds typically work well. These options are available on all three subcommands.

Real-time microphone input

All subcommands read from the microphone when no input file is given:

# Stream detection from microphone
auditok

# Record, trim, and save
auditok trim -o trimmed.wav

# Record, normalize pauses, and save
auditok fix-pauses -o cleaned.wav -d 0.5

Reading from the microphone requires sounddevice.

Read audio from an external program

You can pipe audio from an external program such as sox:

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

When reading from standard input, the same audio parameters must be set for both the source program and auditok:

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

Common options reference

-e, --energy-threshold     Detection threshold [default: 50]
-n, --min-duration         Minimum event duration in seconds [default: 0.2]
-m, --max-duration         Maximum event duration (split only) [default: 5]
-s, --max-silence          Max silence within an event [default: 0.3]
-l, --max-leading-silence  Silence to retain before events [default: 0]
-g, --max-trailing-silence Trailing silence to keep [default: all]
-r, --rate                 Sampling rate [default: 16000]
-c, --channels             Number of channels [default: 1]
-w, --width                Bytes per sample [default: 2]
-q, --quiet                Suppress output
-D, --debug                Debug mode