wav_info.py

r"""
Inspect reference audio files and flag anything OmniVoice would not like.

Reads the header only -- the files are never modified.

Run from the project root (omnivoice_lab):
    uv run --project OmniVoice python utils/wav_info.py
    uv run --project OmniVoice python utils/wav_info.py path\to\other.wav

Also prints the matching transcript, if one is found next to the audio.
"""

import glob
import os
import sys

import soundfile as sf

AUDIO_DIR = os.path.join("data", "audio_ref")

# The README recommends 3-10 s of reference audio: shorter carries too little
# voice information, longer slows inference down and can hurt clone quality.
MIN_SECONDS = 3.0
MAX_SECONDS = 10.0

# OmniVoice generates at 24 kHz. Reference audio below that was upsampled from
# something lossier, so the high end that carries timbre is simply missing.
TARGET_RATE = 24000


def find_transcript(audio_path):
    """Return the transcript next to an audio file, or None.

    Two layouts are accepted: the reference_txt_<name>.txt convention already
    used in data/audio_ref, and a plain <name>.txt sitting beside the audio.
    """
    folder, filename = os.path.split(audio_path)
    stem = os.path.splitext(filename)[0]

    candidates = [
        os.path.join(folder, f"reference_txt_{stem}.txt"),
        os.path.join(folder, f"{stem}.txt"),
    ]
    for candidate in candidates:
        if os.path.isfile(candidate):
            with open(candidate, encoding="utf-8") as handle:
                return candidate, handle.read().strip()
    return None


def inspect(path):
    try:
        info = sf.info(path)
    except Exception as error:
        print(f"{path}\n  could not be read: {error}\n")
        return

    duration = info.frames / info.samplerate

    print(os.path.basename(path))
    print(f"  format      : {info.format} / {info.subtype}")
    print(f"  sample rate : {info.samplerate} Hz")
    print(f"  channels    : {info.channels}")
    print(f"  duration    : {duration:.2f} s ({info.frames} frames)")
    print(f"  size        : {os.path.getsize(path) / 1024:.0f} KB")

    warnings = []
    if duration < MIN_SECONDS:
        warnings.append(f"shorter than {MIN_SECONDS:.0f} s - too little voice information")
    if duration > MAX_SECONDS:
        warnings.append(f"longer than {MAX_SECONDS:.0f} s - slower and can degrade cloning")
    if info.channels != 1:
        warnings.append(f"{info.channels} channels - will be mixed down to mono")
    if info.samplerate < TARGET_RATE:
        warnings.append(f"below {TARGET_RATE} Hz - high frequencies are missing")

    for warning in warnings:
        print(f"  WARNING     : {warning}")
    if not warnings:
        print("  looks good for voice cloning")

    found = find_transcript(path)
    if found:
        transcript_path, text = found
        print(f"  transcript  : {os.path.basename(transcript_path)}")
        print(f"                \"{text}\"")
    else:
        print("  WARNING     : no transcript found - Whisper would be pulled in")

    print()


def main():
    if len(sys.argv) > 1:
        paths = sys.argv[1:]
    else:
        paths = sorted(glob.glob(os.path.join(AUDIO_DIR, "*.wav")))

    if not paths:
        raise SystemExit(f"No wav files found in {AUDIO_DIR}")

    print(f"--- reference audio check ({len(paths)} file(s)) ---\n")
    for path in paths:
        inspect(path)


if __name__ == "__main__":
    main()