Getting Started¶

This page covers installing VTC and preparing your audio files. If something goes wrong, see Common errors at the bottom of this page or the Troubleshooting page.

Requirements¶

• Operating system: Linux or macOS. Windows is not supported. If you only have a Windows machine, the easiest workaround is to use Windows Subsystem for Linux (WSL).
• uv, which installs Python and the necessary libraries.
• ffmpeg version 4 to 8, which VTC uses to read audio files. FFmpeg 9 is not supported yet.
• An internet connection on the first run, to download the model (see Where the model comes from).

Installation¶

Run the block for your operating system in a terminal.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install ffmpeg (Ubuntu/Debian)
sudo apt install ffmpeg

# Clone the repo
git clone https://github.com/LAAC-LSCP/VTC.git
cd VTC

# Install Python dependencies
uv sync

# Verify everything is set up
./check_sys_dependencies.sh

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install brew (a package manager for macOS)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install ffmpeg 8 (Homebrew's default ffmpeg is version 9, which VTC cannot use)
brew install ffmpeg@8
echo 'export PATH="$(brew --prefix ffmpeg@8)/bin:$PATH"' >> ~/.zshrc
echo 'export DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix ffmpeg@8)/lib"' >> ~/.zshrc
source ~/.zshrc

# Clone the repo
git clone https://github.com/LAAC-LSCP/VTC.git
cd VTC

# Install Python dependencies
uv sync

# Verify everything is set up
./check_sys_dependencies.sh

Where the model comes from¶

The model is not stored in the repository. On the first run, VTC downloads the model weights, configuration and threshold files from the coml/VTC-2 repository on Hugging Face. Later runs use the downloaded copy.

export HF_HOME=/path/with/more/space/huggingface

Prepare your audio¶

Folder structure¶

Put all the recordings you want to process in one folder. VTC processes every .wav file in that folder and writes its results to a separate output folder:

my_project/
├── audio/               # Your WAV files go here
│   ├── child01_day1.wav
│   ├── child01_day2.wav
│   └── child02_day1.wav
└── output/              # VTC will write results here
    ├── rttm/
    │   ├── child01_day1.rttm
    │   └── ...
    └── rttm.csv

Audio format¶

Each recording must be:

• a WAV file (uncompressed audio),
• sampled at 16 kHz (16 000 samples per second),
• mono (a single channel).

To check a file, run ffprobe (installed with ffmpeg):

ffprobe your_recording.wav

Look for the line starting with Stream #0:0: Audio::

Stream #0:0: Audio: pcm_s16le ([1][0][0][0] / 0x0001), 16000 Hz, 1 channels, s16, 256 kb/s

• pcm_s16le means the file is uncompressed WAV.
• 16000 Hz is the sample rate. It must be exactly 16 kHz.
• 1 channels (or mono, depending on your ffprobe version) means the file has a single channel. stereo or 2 channels means it needs converting.

If any of these don't match, convert the file with one of the methods below. Both resample to 16 kHz and mix all channels into one. For other formats such as .mp3 or .flac, use FFmpeg: convert-audios only converts .wav files and ignores all others.

# Replace `raw_audio.mp3` with the name of your file (it can be `.mp3`, `.flac`, etc.),
# and `converted.wav` with whatever you'd like to name the output file.

ffmpeg -i raw_audio.mp3 -acodec pcm_s16le -ar 16000 -ac 1 converted.wav

# Replace `/path/to/raw_audio` with the folder containing the .wav files,
# and `/path/to/converted` with the name of the output folder

uv run convert-audios --wavs /path/to/raw_audio --output /path/to/converted

Common errors¶

See Troubleshooting for problems not listed here.