yapsnap

Models are downloaded on the first run and cached locally for offline use.

Cache Locations:

• macOS: ~/Library/Caches/yapsnap/
• Linux: $XDG_CACHE_HOME/yapsnap/ (or ~/.cache/yapsnap/)
• Windows: %LOCALAPPDATA%\yapsnap\

Custom Models: To use a custom streaming transducer, point --model to a directory containing:

• encoder(.int8).onnx
• decoder(.int8).onnx
• joiner(.int8).onnx
• tokens.txt

Alternatively, set the KROKO_MODEL environment variable.

yapsnap is optimized for CPU-only execution using ONNX. It automatically detects physical cores to balance parallel decoding processes (--workers) and ONNX threads (--threads).

To avoid performance degradation from oversubscription, ensure that workers * threads does not significantly exceed your physical core count.

Tuning Knobs:

• --workers N: Number of parallel decode processes (0 = autodetect, 1 = single stream, no chunking).
• --threads N: ONNX threads per worker (0 = autodetect).
• --speed N: Higher values speed up transcription at a potential cost to accuracy.

Environment Variables:

• YAPSNAP_THREADS: Overrides the detected core budget.
• KROKO_MODEL: Overrides the model directory.
• YAPSNAP_LID_MODEL_DIR: Path to a directory holding lid-encoder.int8.onnx and lid-decoder.int8.onnx to bypass language-ID download.

By default, yapsnap automatically detects the language. You can override this or specify a custom output path.

• Language: Use --lang <CODE> (e.g., fr, de, en) to skip detection or force a specific language. Use --lang auto for the default behavior.
• Output Path: Use -o or --output to specify where the .txt file should be saved.
• Speed: Use --speed N to change the pre-transcription speedup factor (default is 1.4). Use --speed 1.0 to disable speedup.

Example:

# Force French and save to a specific directory
yapsnap podcast.mp3 --lang fr -o ./notes/french_podcast.txt

# Transcribe at normal speed
yapsnap input.mp4 --speed 1.0

By default, yapsnap uses --lang auto to detect the spoken language using a lightweight model. It listens to two 5-second windows to determine the language and automatically downloads the matching Kroko model.

To improve speed or handle code-switching (multiple languages in one file), you can pin a specific language using the --lang flag. Note that if you provide an explicit --model, the --lang flag is ignored.

Available language codes:

• de: German
• en: English
• es: Spanish
• fr: French
• it: Italian
• iw: Hebrew
• nl: Dutch
• pt: Portuguese
• sv: Swedish
• tr: Turkish

yapsnap interview.mp3                     # Auto-detect (default)
yapsnap interview.mp3 --lang fr          # Pin to French
yapsnap podcast.mp3 --lang de            # Pin to German
yapsnap meeting.mp4 --lang es --timestamps  # Spanish with timestamps

If you want to use a specific model (e.g., a different Kroko variant or a custom sherpa-onnx streaming transducer), you can provide the path to the model folder. Providing a model via --model also skips the language detection step.

You can pass the path per-run or set the KROKO_MODEL environment variable to use it as a default for your session.

# Per-run
yapsnap interview.mp3 --model /path/to/kroko-french

# Set as session default
export KROKO_MODEL=/path/to/kroko-french
yapsnap interview.mp3

The yapsnap command (aliased to transcribe) converts audio from video URLs or local files into plaintext. It supports major platforms like YouTube, TikTok, X (Twitter), and Instagram, as well as local files like .mp3, .mp4, .wav, etc.

Basic usage:

# Transcribe a YouTube video
yapsnap "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Transcribe a local file
yapsnap meeting.mp4

To use yapsnap, you must first ensure ffmpeg is installed on your system, as it handles audio decoding. Then, install yapsnap via pip.

1. Install ffmpeg

• macOS: brew install ffmpeg
• Linux: sudo apt install ffmpeg or sudo dnf install ffmpeg
• Windows: winget install ffmpeg or choco install ffmpeg

2. Install yapsnap

From PyPI (recommended):

pip install yapsnap

Or from source:

git clone https://github.com/kouhxp/yapsnap
cd yapsnap
pip install .

Note: yt-dlp is installed as a dependency. If URL extraction fails, run pip install -U yt-dlp to update it.

You can enhance your transcripts with sentence-level timestamps or speaker labels.

• Timestamps: Use --timestamps to emit one sentence per line with [MM:SS] markers.
• Speaker Labels: Use --diarize to identify different speakers (e.g., SPEAKER_00, SPEAKER_01). This flag implies --timestamps.
• Known Speaker Count: For more reliable diarization, provide the number of speakers with --num-speakers N.

Example:

# Transcribe with timestamps
yapsnap meeting.mp4 --timestamps

# Transcribe with speaker labels and a known count
yapsnap interview.mp3 --diarize --num-speakers 2

Use the --diarize flag to add speaker labels (e.g., SPEAKER_00, SPEAKER_01) to the transcript. This automatically enables --timestamps.

Key details:

• Speaker Count: The number of speakers is detected automatically (reliable up to ~7 speakers). For better accuracy with known counts, use --num-speakers N.
• Limitations: Does not support overlapping speech (simultaneous talking). Labels are unique to the current run and do not persist across different files.
• Requirements: Requires a sherpa-onnx build that exposes timestamp data.

# Basic diarization
yapsnap interview.mp3 --diarize

# Diarization with a known speaker count
yapsnap call.mp3 --diarize --num-speakers 2

When using --lang auto or a specific language code, yapsnap automatically downloads the required Kroko streaming transducer models from HuggingFace to a local cache directory.

Security Policy: To prevent the use of corrupted or malicious models, yapsnap employs a strict SHA-256 verification policy for all auto-downloads. It compares downloaded files against a hardcoded manifest (model_checksums.sha256).

• Match: File is accepted.
• Mismatch: Hard failure (integrity error).
• Unlisted file: Hard failure (unrecognized file).
• Missing manifest: Hard failure.

Note: This security policy only applies to auto-downloads. If you provide a model directory manually via --model or the KROKO_MODEL environment variable, it is loaded directly from disk without checksum verification.

If you want to bypass auto-downloading diarization models, provide a path to a directory containing the necessary .onnx files. The directory must contain:

1. A segmentation model (either a subdirectory with model.onnx or a file containing segmentation or reverb in its name).
2. An embedding model (a file containing campplus, eres2net, or embedding in its name).

If exactly two .onnx files exist and one is identified, the other is automatically assigned the remaining role.