Skip to content

README.md

Latest commit

 

History

History
131 lines (94 loc) · 6.21 KB

README.md

File metadata and controls

131 lines (94 loc) · 6.21 KB
Raw

Utilities and diagnostic tools

This directory contains diagnostic, verification, and model management tools for OmniVoice.

All utility scripts read configuration parameters dynamically from .env (such as OMNIVOICE_MODEL_DIR, HF_TOKEN, HF_HOME, and MODELS_DIR).

Environment check: check_env.py

Description

check_env.py performs an end-to-end environment diagnostic to verify that runtime dependencies, GPU acceleration, and model weights are properly installed before running synthesis.

Diagnostic checks

  • Python runtime: Reports Python version and CPU architecture (x86_64 / AMD64).
  • PyTorch and CUDA: Checks PyTorch version, CUDA runtime availability, CUDA driver version, detected GPU name (e.g. NVIDIA RTX 5070 Ti), and total available VRAM in GB.
  • OmniVoice package: Verifies that the omnivoice package can be imported and reports the installed package version.
  • Model weight verification: Reads OMNIVOICE_MODEL_DIR from .env, checks for required core weights (model.safetensors and audio_tokenizer/model.safetensors), and reports total on-disk model weight size in GB.

Exit codes

  • Exits with code 0 when all checks pass (All good.).
  • Exits with code 1 when any dependency, CUDA device, or model file is missing.

How to run

uv run --project OmniVoice python utils/check_env.py

Reference audio inspection: wav_info.py

Description

wav_info.py inspects reference audio files in data/audio_ref/ (or custom paths provided as arguments) against the acoustic requirements of OmniVoice's voice cloning pipeline.

The script only reads file headers via soundfile and never alters audio data on disk.

Validated criteria

  • Audio duration (3 to 10 seconds):
    • Warns if audio is shorter than 3 seconds (insufficient acoustic information for voice timbre extraction).
    • Warns if audio is longer than 10 seconds (increases inference latency and can degrade cloning quality).
  • Sample rate ($\ge 24\text{ kHz}$):
    • Compares sample rate against OmniVoice's native 24 kHz target.
    • Warns if lower sample rates are detected, indicating missing high frequencies and loss of voice clarity.
  • Channel layout (Mono):
    • Checks channel count. Warns if stereo/multi-channel audio will require automatic downmixing to mono.
  • Transcript pairing:
    • Checks for corresponding transcripts (reference_txt_<stem>.txt or <stem>.txt) next to each audio file.
    • Warns if no transcript is found, which would cause OmniVoice to download and run Whisper in the background.

How to run

Scan all reference files in data/audio_ref/:

uv run --project OmniVoice python utils/wav_info.py

Inspect a specific audio file:

uv run --project OmniVoice python utils/wav_info.py data/audio_ref/my_voice_berlin_k.wav

Model downloader: download_model.py

Description

download_model.py downloads full model repositories from Hugging Face to a local model storage directory (HF_HOME, MODELS_DIR, or F:/KI_Model/Huggingface/).

Key features

  • Windows symlink prevention: Uses local_dir instead of cache symlinks in snapshot_download, avoiding Windows WinError 1314 privilege errors.
  • Path normalization: Converts repository names with slashes (e.g. k2-fsa/OmniVoice) into safe directory names (e.g. k2-fsa--OmniVoice).
  • Parallel transfers: Uses max_workers=8 for multi-threaded downloads.
  • Authentication: Automatically loads HF_TOKEN from .env for gated models, while allowing public downloads without a token.
  • License and commit manifest (download_info.json): Queries HfApi().model_info() to capture the exact commit SHA, last modified timestamp, and repository license, saving a permanent download_info.json alongside the downloaded model files.

How to run

Pass repository ID directly:

uv run --project OmniVoice python utils/download_model.py k2-fsa/OmniVoice

Run interactively:

uv run --project OmniVoice python utils/download_model.py

Selective model file downloader: download_model_files.py

Description

download_model_files.py downloads specific files or pattern-matched subsets from a Hugging Face repository without pulling the entire repository.

Key features

  • Pattern filtering: Uses allow_patterns with fnmatch wildcard matching (e.g. "*.safetensors", "*.gguf", "config.json").
  • Targeted storage: Saves files directly to <cache_dir>/<repo--id> with symlink-free local file storage.
  • Audit trail: Generates the same download_info.json tracking manifest with commit SHA and license metadata.

How to run

Download specific files by name or pattern:

uv run python utils/download_model_files.py unsloth/gemma-4-E4B-it-GGUF "gemma-4-E4B-it-UD-Q8_K_XL.gguf" "mmproj-F32.gguf"

Download only configuration and tokenizer files:

uv run python utils/download_model_files.py k2-fsa/OmniVoice "*.json" "*.txt"

Utilities overview

Utility Script Primary Purpose Key Output / Artifact
check_env.py Verifies Python, PyTorch, CUDA, GPU VRAM, and model file integrity Terminal health check report with exit code 0 or 1
wav_info.py Inspects reference audio headers and transcript pairing Acoustic compatibility report with warning flags
download_model.py Downloads complete Hugging Face model repositories Local model folder + download_info.json audit manifest
download_model_files.py Selectively downloads matching files from Hugging Face Filtered model folder + download_info.json audit manifest

Best practices

  1. Run diagnostics before experiments: Execute check_env.py whenever switching environments or updating dependencies to confirm CUDA and model paths.
  2. Inspect voice recordings before cloning: Use wav_info.py to ensure recordings are mono, sampled at 24 kHz or higher, between 3 and 10 seconds long, and accompanied by transcript text.
  3. Preserve download manifests: Never delete download_info.json inside model folders, as it serves as the permanent record of the model commit SHA and license terms under which weights were retrieved.