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

Instead of a fixed threshold, the threshold can be estimated from the input itself:

auditok audio.wav -e auto        # default estimation method (otsu)
auditok audio.wav -V percentile  # noise floor + margin, recall-oriented
auditok audio.wav -V p20         # noise floor read at the 20th percentile
auditok -e auto                  # microphone: calibrated on the first 3 s

For file input the whole file is used for estimation. For live input (microphone or standard input), the threshold is calibrated on the first seconds of the stream — buffered and replayed, so nothing is lost — and clamped to a lower bound so that background noise alone (PC fan, air conditioning) cannot produce a threshold inside the noise. Both are adjustable:

# calibrate on the first 5 s, don't accept a threshold below 45 dB
auditok -e auto -U 5 -y 45

If you already know a good threshold for your setup, skip estimation entirely and pass it with -e:

auditok -e 50                    # explicit threshold, no estimation

To detect speech specifically rather than any audio activity, use the WebRTC voice activity detector as the frame decider (requires pip install auditok[webrtcvad]; also works with microphone input):

auditok audio.wav -V webrtc      # aggressiveness mode 1
auditok -V webrtc:2              # microphone input, mode 2

As a frame validator, the WebRTC VAD may work better with a smaller max_silence value than the default 0.3 s — typically -s 0.1.

The WebRTC VAD requires a sampling rate of 8000, 16000, 32000 or 48000 Hz. For files with other rates, pass -r to have ffmpeg resample the audio on the fly:

auditok audio.mp3 -r 16000 -V webrtc

The resolved threshold is printed to standard error (suppress with -q). Both options also work with the trim and fix-pauses subcommands.

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.

Trailing silence vs. --max-silence#

-s/--max-silence controls when an event ends (the longest silence tolerated inside an event), while -g/--max-trailing-silence controls how much silence is kept at the end of each delivered event:

  • Omitted (default): keep all trailing silence accumulated up to --max-silence.

  • -g 0: drop all trailing silence.

  • -g <= --max-silence: trim trailing silence to that duration.

  • -g > --max-silence: after the event boundary is decided (at --max-silence), keep collecting silent frames past the boundary up to --max-trailing-silence. Collection stops as soon as a new valid frame appears, so separate events are not merged.

This is useful when you want short, tightly segmented events that still keep a natural fadeout, e.g. a small --max-silence for crisp boundaries combined with a larger --max-trailing-silence for padding:

auditok speech.wav -s 0.1 -g 0.4

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, a number or 'auto'
                           ('auto' uses the otsu method) [default: 50]
-V, --validator            Frame validation strategy: 'otsu',
                           'percentile', 'pXX' (auto threshold
                           estimation; 'percentile' == 'p10') or
                           'webrtc[:MODE]' (WebRTC VAD as frame
                           decider)
-U, --calibration-duration Seconds of audio used to calibrate the
                           auto threshold on live input [default: 3]
-y, --min-energy-threshold Lower bound for the auto threshold
                           calibrated on live input [default: 40]
-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