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 -V otsu        # splits the energy histogram (balanced)
auditok audio.wav -V percentile  # noise floor + margin, recall-oriented
auditok audio.wav -V p20         # noise floor read at the 20th percentile
auditok -V otsu                  # 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 -V otsu -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

With -e (or -V webrtc) detection starts at the first frame and events stream out while the input is still being read or decoded; estimation (-V otsu|percentile|pXX) instead reads the whole file before detection starts.

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, in dB; overlooked
                           when -V is given [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