User Guide¶

This page explains how to run VTC and read its output. The Technical Reference lists every command-line option. Complete Getting Started first.

Run VTC¶

Put your .wav files in one folder and run the following command, replacing the paths in angle brackets with your own:

uv run vtc-infer             \
    --wavs <audio_folder>    \
    --output <output_folder> \
    --device cpu

VTC processes every .wav file in the folder. The first run downloads the model and needs an internet connection (see Where the model comes from).

To avoid retyping the command, edit the variables at the top of run.sh, at the root of the repository:

• audios_path: the folder containing your .wav files, e.g. audios_path="/home/user/my_project/audio".
• output: the folder for the results, e.g. output="/home/user/my_project/output". By default, each run writes to a new timestamped folder inside out/.

Then run:

sh run.sh

Understanding the output¶

After a run, the output folder contains:

<output_folder>/
├── 📂 rttm/          # One .rttm file per audio recording
├── 📄 rttm.csv       # All detected segments combined into one CSV
└── 📄 f1.toml        # A copy of the thresholds used for this run

rttm/ and rttm.csv contain the same results. Use the CSV for analysis: it opens in Excel, Numbers or LibreOffice and loads directly into R or Python. RTTM is a standard format in speech processing, and other tools such as ALICE expect it.

The .toml file records which thresholds were used: f1.toml by default, hp.toml in high-precision mode, or your own file's name for custom thresholds.

What's in each row¶

Each row of the CSV, and each line of an RTTM file, is one detected speech segment:

For example, these rows from one recording correspond to the timeline below (the image is an illustration; VTC does not produce it):

uid,              start_time_s, duration_s, label
recording_jd7aks,         0.12,       1.20,   FEM
recording_jd7aks,         3.30,       0.34,   MAL
recording_jd7aks,         3.98,       1.98,   FEM
recording_jd7aks,         5.86,       2.10,   MAL
recording_jd7aks,         6.10,       1.90,  KCHI
recording_jd7aks,         8.24,       0.52,   OCH

Segments can overlap: here MAL and FEM overlap between 5.86 s and 5.96 s, and MAL and KCHI between 6.10 s and 7.96 s. VTC detects each category independently, so it can mark an adult and the child speaking at the same time.

SPEAKER <uid> 1 <start_time_s> <duration_s> <NA> <NA> <label> <NA> <NA>

How long will it take?¶

VTC is much faster on a GPU than on a CPU. The table shows measured processing times. The real-time factor is how many times faster than real time VTC runs: at 226×, one hour of audio takes about 16 seconds.

Use a GPU for large studies (hundreds of hours of recordings). If you don't have one, see HPC / SLURM setup for running VTC on a compute cluster.

If VTC fails with CUDA out of memory, lower the batch size (see Batch size and memory).

Technical Reference¶

Command Line Interface Arguments¶

Arguments accepted by vtc-infer (also listed by uv run vtc-infer --help):

Example commands¶

Process all .wav files in my_audio/ on the CPU and write the results to my_output/:

uv run vtc-infer \
    --wavs my_audio/ \
    --output my_output/ \
    --device cpu

Use a smaller batch size on a GPU with limited memory:

uv run vtc-infer \
    --wavs my_audio/ \
    --output my_output/ \
    --device cuda \
    --batch_size 64

Include .wav files in subfolders, for example one folder per participant:

uv run vtc-infer \
    --wavs my_audio/ \
    --output my_output/ \
    --device cuda \
    --recursive_search

Use the high-precision thresholds, which give fewer false detections but miss more speech (see Threshold selection):

uv run vtc-infer \
    --wavs my_audio/ \
    --output my_output/ \
    --device cuda \
    --high-precision

Also keep the RTTM files from before post-processing (see Raw model outputs):

uv run vtc-infer \
    --wavs my_audio/ \
    --output my_output/ \
    --device cuda \
    --keep_raw

Drop segments shorter than 0.2 s and merge same-speaker segments separated by less than 0.15 s:

uv run vtc-infer \
    --wavs my_audio/ \
    --output my_output/ \
    --device cuda \
    --min_duration_on_s 0.2 \
    --min_duration_off_s 0.15

Python API¶

run_vtc takes the same options as the command line, as keyword arguments: --batch_size 64 becomes batch_size=64, --high-precision becomes high_precision=True, and --thresholds-name becomes thresholds.

from vtc_inference import run_vtc

run_vtc(
    output="my_output/",
    wavs="my_audio/",
    config="2.2",
    checkpoint="2.2",
    device="cpu",
)

Batch size and memory¶

Larger batches are faster but use more GPU memory. Suggested starting points: 256 for an H100 or A100, 128 (the default) for an A40 or RTX 3090, 64 for an RTX 3060 or other 12 GB cards, and 32 or lower on CPU. Lower the batch size if you get CUDA out of memory. --batch_size sets the number of audio windows per forward pass, not the number of files processed in parallel.