ownvoice-cli 0.1.1__py3-none-any.whl

ownvoice/__init__.py

@@ -0,0 +1,10 @@
+"""OwnVoice: train a LoRA voice adapter for pocket-tts, own the resulting model.
+
+OwnVoice wraps kyutai-labs/pocket-tts (MIT-licensed, CPU-capable local
+text-to-speech) with a LoRA fine-tuning workflow. The output is an adapter
+file you keep and run yourself, not an API subscription.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

ownvoice/cli.py

@@ -0,0 +1,216 @@
+"""OwnVoice CLI: `check`, `train`, `infer` subcommands.
+
+Every subcommand supports `--json` for a structured, machine-parseable
+output mode alongside the default human-readable text, so a script or an
+agent invoking `ownvoice` programmatically can parse the result reliably.
+"""
+
+from __future__ import annotations
+
+import json as json_module
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from ownvoice import __version__
+from ownvoice.infer import infer as run_infer
+from ownvoice.train import (
+    DEFAULT_EPOCHS,
+    DEFAULT_EVAL_TEXT,
+    DEFAULT_LEARNING_RATE,
+    DEFAULT_LORA_ALPHA,
+    DEFAULT_LORA_DROPOUT,
+    DEFAULT_LORA_RANK,
+    DEFAULT_OUT_DIR,
+    TrainingConfig,
+    check_compatibility,
+)
+from ownvoice.train import train as run_train
+
+app = typer.Typer(
+    name="ownvoice",
+    help="Train a LoRA voice adapter for pocket-tts and own the resulting model. No API lock-in.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"ownvoice {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Print the OwnVoice version and exit.",
+    ),
+) -> None:
+    """OwnVoice: own your voice model, no API lock-in."""
+
+
+@app.command()
+def check(
+    json_output: bool = typer.Option(
+        False, "--json", help="Print machine-readable JSON instead of human-readable text."
+    ),
+) -> None:
+    """Free, CPU-only compatibility check: load pocket-tts and dry-run the LoRA injection.
+
+    No GPU and no training required. Run this before renting a GPU for
+    `ownvoice train` -- it is the Day-0 compatibility spike, exposed as a
+    command.
+
+    Example:
+        ownvoice check
+    """
+    result = check_compatibility()
+
+    if json_output:
+        typer.echo(
+            json_module.dumps(
+                {
+                    "success": result.success,
+                    "message": result.message,
+                    "module_tree": result.module_tree,
+                }
+            )
+        )
+    else:
+        if result.success:
+            typer.secho(f"[ownvoice check] PASS: {result.message}", fg=typer.colors.GREEN)
+        else:
+            typer.secho(f"[ownvoice check] FAIL: {result.message}", fg=typer.colors.RED)
+            if result.module_tree:
+                typer.echo("\nModule tree (for debugging / for the issue #30 blocker post):")
+                typer.echo(result.module_tree)
+
+    raise typer.Exit(code=0 if result.success else 1)
+
+
+@app.command()
+def train(
+    voice_clips: Path = typer.Option(
+        ...,
+        "--voice-clips",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        help="Directory of .wav voice-clip recordings to train from. Required.",
+    ),
+    out: Path = typer.Option(
+        DEFAULT_OUT_DIR, "--out", help="Directory to write adapter.safetensors + metadata.json to."
+    ),
+    epochs: int = typer.Option(DEFAULT_EPOCHS, "--epochs", min=1, help="Number of training epochs."),
+    lora_rank: int = typer.Option(DEFAULT_LORA_RANK, "--lora-rank", min=1, help="LoRA rank."),
+    lora_alpha: int = typer.Option(DEFAULT_LORA_ALPHA, "--lora-alpha", min=1, help="LoRA alpha."),
+    lora_dropout: float = typer.Option(
+        DEFAULT_LORA_DROPOUT, "--lora-dropout", min=0.0, max=1.0, help="LoRA dropout."
+    ),
+    learning_rate: float = typer.Option(
+        DEFAULT_LEARNING_RATE, "--learning-rate", help="Optimizer learning rate."
+    ),
+    eval_text: str = typer.Option(
+        DEFAULT_EVAL_TEXT,
+        "--eval-text",
+        help="Sentence synthesized after training to score against the reference voice.",
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Print machine-readable JSON instead of human-readable text."
+    ),
+) -> None:
+    """Train a LoRA voice adapter from a directory of .wav voice clips.
+
+    Only --voice-clips is required; every other flag has a sensible default.
+    Exits 0 on a successful run whether or not the similarity score clears
+    the usable threshold (0.75) -- a below-threshold result is a labeled
+    outcome with a next step, not a crash. Only a data-loading failure or a
+    caught PEFT-injection failure exits non-zero.
+
+    Example:
+        ownvoice train --voice-clips ./my-voice-clips
+    """
+    config = TrainingConfig(
+        voice_clips_dir=voice_clips,
+        out_dir=out,
+        epochs=epochs,
+        lora_rank=lora_rank,
+        lora_alpha=lora_alpha,
+        lora_dropout=lora_dropout,
+        learning_rate=learning_rate,
+        eval_text=eval_text,
+    )
+    result = run_train(config)
+
+    if json_output:
+        typer.echo(
+            json_module.dumps(
+                {
+                    "success": result.success,
+                    "out_dir": str(result.out_dir) if result.out_dir else None,
+                    "similarity_score": result.similarity_score,
+                    "usable": result.usable,
+                    "message": result.message,
+                    "infer_command": result.infer_command,
+                }
+            )
+        )
+    else:
+        if result.success:
+            label = "USABLE ADAPTER" if result.usable else "BELOW THRESHOLD"
+            color = typer.colors.GREEN if result.usable else typer.colors.YELLOW
+            typer.secho(f"[ownvoice train] {label}", fg=color, bold=True)
+            typer.echo(result.message)
+        else:
+            typer.secho("[ownvoice train] FAILED", fg=typer.colors.RED, bold=True)
+            typer.echo(result.message)
+
+    raise typer.Exit(code=0 if result.success else 1)
+
+
+@app.command()
+def infer(
+    adapter: Path = typer.Option(
+        ..., "--adapter", exists=True, help="Path to a trained adapter.safetensors file. Required."
+    ),
+    text: str = typer.Option(..., "--text", help="Text to synthesize in the trained voice. Required."),
+    out: Path = typer.Option(Path("./ownvoice-output.wav"), "--out", help="Output .wav file path."),
+    reference_audio: Optional[Path] = typer.Option(
+        None,
+        "--reference-audio",
+        help="Override the reference clip OwnVoice recorded in metadata.json at train time.",
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Print machine-readable JSON instead of human-readable text."
+    ),
+) -> None:
+    """Generate speech in the trained voice from a saved adapter, and save it to a .wav file.
+
+    Example:
+        ownvoice infer --adapter ./ownvoice-adapter/adapter.safetensors --text "Hello, this is my own voice."
+    """
+    try:
+        out_path = run_infer(adapter, text, out_path=out, reference_audio_override=reference_audio)
+    except Exception as exc:  # noqa: BLE001
+        if json_output:
+            typer.echo(json_module.dumps({"success": False, "error": str(exc)}))
+        else:
+            typer.secho(f"[ownvoice infer] FAILED: {exc}", fg=typer.colors.RED, bold=True)
+        raise typer.Exit(code=1) from exc
+
+    if json_output:
+        typer.echo(json_module.dumps({"success": True, "out_path": str(out_path)}))
+    else:
+        typer.secho(f"[ownvoice infer] Wrote {out_path}", fg=typer.colors.GREEN)
+
+    raise typer.Exit(code=0)
+
+
+if __name__ == "__main__":
+    app()

ownvoice/data.py

@@ -0,0 +1,139 @@
+"""Voice-clip loading and validation for OwnVoice training data.
+
+pocket-tts's own sample rate is read from the loaded model at train time
+(`TTSModel.sample_rate`); this module only validates raw input files and
+normalizes them to whatever target rate the caller asks for.
+
+Audio I/O uses `soundfile` directly rather than `torchaudio.load`/
+`torchaudio.info`: as of the torchaudio version this project pins against
+(2.9+), both of those now route through an optional `torchcodec`/ffmpeg
+backend and raise `ImportError` without it installed. `soundfile` (libsndfile)
+reads plain .wav files with no extra runtime dependency. Resampling still
+goes through `torchaudio.transforms.Resample` per the locked design decision,
+since that's a pure-tensor operation with no I/O backend involved.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from pathlib import Path
+
+import soundfile as sf
+import torch
+import torchaudio
+
+MIN_CLIP_SECONDS = 1.0
+MAX_CLIP_SECONDS = 30.0
+SUPPORTED_SUFFIXES = {".wav"}
+
+
+class VoiceClipError(Exception):
+    """Raised when a voice-clip directory or file fails validation."""
+
+
+@dataclasses.dataclass(frozen=True)
+class VoiceClip:
+    """Metadata for one validated voice-clip file, not yet loaded into memory."""
+
+    path: Path
+    sample_rate: int
+    num_frames: int
+    num_channels: int
+
+    @property
+    def duration_seconds(self) -> float:
+        return self.num_frames / self.sample_rate
+
+
+def _iter_candidate_files(voice_clips_dir: Path) -> list[Path]:
+    if not voice_clips_dir.exists():
+        raise VoiceClipError(f"Voice clips directory does not exist: {voice_clips_dir}")
+    if not voice_clips_dir.is_dir():
+        raise VoiceClipError(f"Voice clips path is not a directory: {voice_clips_dir}")
+    return sorted(
+        p
+        for p in voice_clips_dir.iterdir()
+        if p.is_file() and p.suffix.lower() in SUPPORTED_SUFFIXES
+    )
+
+
+def load_voice_clips(
+    voice_clips_dir: Path | str,
+    *,
+    min_seconds: float = MIN_CLIP_SECONDS,
+    max_seconds: float = MAX_CLIP_SECONDS,
+) -> list[VoiceClip]:
+    """Validate every .wav file in `voice_clips_dir` and return clip metadata.
+
+    A file that individually fails to decode, is empty, or falls outside the
+    duration bounds is skipped (not fatal on its own) -- only an empty result
+    set raises. Raises VoiceClipError with an actionable message either way
+    the directory itself doesn't exist/isn't a directory, has no .wav files
+    at all, or every candidate file was skipped.
+    """
+    voice_clips_dir = Path(voice_clips_dir)
+    candidates = _iter_candidate_files(voice_clips_dir)
+    if not candidates:
+        raise VoiceClipError(
+            f"No .wav files found in {voice_clips_dir}. OwnVoice needs at least one "
+            "clean .wav recording of the target voice to train from."
+        )
+
+    clips: list[VoiceClip] = []
+    skipped: list[str] = []
+    for path in candidates:
+        try:
+            info = sf.info(str(path))
+        except Exception as exc:  # noqa: BLE001 - soundfile raises backend-specific errors
+            skipped.append(f"{path.name}: could not read audio ({exc})")
+            continue
+
+        if info.frames <= 0:
+            skipped.append(f"{path.name}: empty audio (0 frames)")
+            continue
+
+        duration = info.frames / info.samplerate
+        if duration < min_seconds:
+            skipped.append(f"{path.name}: too short ({duration:.2f}s, minimum is {min_seconds}s)")
+            continue
+        if duration > max_seconds:
+            skipped.append(f"{path.name}: too long ({duration:.2f}s, maximum is {max_seconds}s per clip)")
+            continue
+
+        clips.append(
+            VoiceClip(
+                path=path,
+                sample_rate=info.samplerate,
+                num_frames=info.frames,
+                num_channels=info.channels,
+            )
+        )
+
+    if not clips:
+        detail = "; ".join(skipped) if skipped else "no readable clips"
+        raise VoiceClipError(
+            f"No usable voice clips found in {voice_clips_dir} ({detail}). "
+            f"Each clip must be a valid mono or stereo .wav file between "
+            f"{min_seconds}s and {max_seconds}s."
+        )
+
+    return clips
+
+
+def load_waveform(clip: VoiceClip, target_sample_rate: int) -> torch.Tensor:
+    """Load a clip's waveform, downmix to mono, and resample to `target_sample_rate`.
+
+    Returns a 1D float32 tensor. This is the shared normalization path used
+    both by the training data pipeline and (via score.py) by evaluation, so
+    every clip reaches the model or the scorer in a consistent format
+    regardless of its original sample rate or channel count.
+    """
+    audio, sample_rate = sf.read(str(clip.path), dtype="float32", always_2d=True)
+    # soundfile returns (frames, channels); torchaudio's convention is (channels, frames).
+    waveform = torch.from_numpy(audio.T).to(torch.float32)
+    if waveform.shape[0] > 1:
+        waveform = waveform.mean(dim=0, keepdim=True)
+    if sample_rate != target_sample_rate:
+        resampler = torchaudio.transforms.Resample(orig_freq=sample_rate, new_freq=target_sample_rate)
+        waveform = resampler(waveform)
+    return waveform.squeeze(0).to(torch.float32)

ownvoice/infer.py

@@ -0,0 +1,227 @@
+"""Load a trained LoRA adapter and generate speech with it.
+
+Real-API note: pocket-tts's `TTSModel.generate_audio(model_state, text)`
+requires a `model_state` dict built by `get_state_for_audio_prompt(audio_
+conditioning, ...)`, and `audio_conditioning` has no default -- it must be a
+real path, URL, or tensor (confirmed against pocket_tts/models/tts_model.py,
+not assumed). OwnVoice's whole differentiation is that the *voice* comes
+from the trained LoRA weights, not a runtime reference clip, but pocket-tts's
+generation call still needs *some* audio prompt to build the initial
+conditioning state. OwnVoice resolves this by reusing the same reference
+clip that `ownvoice train` recorded in `metadata.json` (the first voice clip
+in the training set) by default, with an optional override.
+
+Verified for real this session (a real 2-epoch LoRA training run, followed
+by a real `ownvoice infer` call against the resulting adapter, produced a
+4.7s non-silent, finite, NaN-free .wav file): `load_adapter()` and
+`generate_speech()` below are exercised end to end against real loaded
+pocket-tts weights, not just reasoned about. Two things this session found
+that the original (structurally reasonable but unverified) approach in
+`generate_speech()` got wrong are documented on that function directly --
+in short, no `base_model.flow_lm` swap is needed or safe, and OwnVoice
+must pre-load and resample the reference clip itself rather than pass a
+raw path/URL, because the publicly downloadable pocket-tts weights are the
+non-voice-cloning checkpoint by default.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import torch
+
+from ownvoice.train import LORA_TARGET_MODULES, DEFAULT_LORA_ALPHA, DEFAULT_LORA_DROPOUT, DEFAULT_LORA_RANK
+
+
+class AdapterLoadError(Exception):
+    """Raised when an adapter file or its sibling metadata.json can't be loaded."""
+
+
+def _read_metadata(adapter_path: Path) -> dict[str, Any]:
+    metadata_path = adapter_path.parent / "metadata.json"
+    if not metadata_path.exists():
+        raise AdapterLoadError(
+            f"No metadata.json found next to {adapter_path}. OwnVoice adapters are always "
+            "saved with a sibling metadata.json (written by `ownvoice train`) -- if this "
+            "adapter was moved on its own, put metadata.json back alongside it."
+        )
+    return json.loads(metadata_path.read_text())
+
+
+def load_adapter(base_model: Any, adapter_path: Path | str):
+    """Load a saved LoRA adapter (`adapter.safetensors`) onto pocket-tts's `flow_lm`.
+
+    Reconstructs the same LoraConfig used at train time (rank/alpha/
+    dropout, read back from the adapter's sibling metadata.json) and loads
+    the saved state dict via PEFT's `set_peft_model_state_dict`. The
+    reload round trip is verified against a real trained adapter this
+    session: `ownvoice train` saved a real adapter.safetensors via
+    `get_peft_model_state_dict`, and this function loaded it back and used
+    it for real generation via `ownvoice infer` without error.
+    """
+    from peft import LoraConfig, get_peft_model, set_peft_model_state_dict
+    from safetensors.torch import load_file
+
+    adapter_path = Path(adapter_path)
+    metadata = _read_metadata(adapter_path)
+    train_config = metadata.get("config", {})
+
+    lora_config = LoraConfig(
+        r=train_config.get("lora_rank", DEFAULT_LORA_RANK),
+        lora_alpha=train_config.get("lora_alpha", DEFAULT_LORA_ALPHA),
+        lora_dropout=train_config.get("lora_dropout", DEFAULT_LORA_DROPOUT),
+        target_modules=LORA_TARGET_MODULES,
+        bias="none",
+    )
+    peft_model = get_peft_model(base_model.flow_lm, lora_config)
+    state_dict = load_file(str(adapter_path))
+    set_peft_model_state_dict(peft_model, state_dict)
+    peft_model.eval()
+    return peft_model
+
+
+def resolve_reference_audio(adapter_path: Path | str, override: Path | str | None = None) -> Path:
+    """Pick the audio-conditioning clip generate_speech() needs.
+
+    Uses `override` if given, otherwise falls back to the reference clip
+    OwnVoice recorded in the adapter's metadata.json at training time.
+    """
+    if override is not None:
+        return Path(override)
+
+    adapter_path = Path(adapter_path)
+    metadata = _read_metadata(adapter_path)
+    reference_clip = metadata.get("reference_clip")
+    if not reference_clip:
+        raise AdapterLoadError(
+            f"metadata.json next to {adapter_path} has no recorded reference_clip, and no "
+            "override was given. Pass one explicitly."
+        )
+    reference_path = Path(reference_clip)
+    if reference_path.is_absolute():
+        raise AdapterLoadError(
+            f"Recorded reference clip {reference_path} in metadata.json is an absolute path, "
+            "which OwnVoice does not trust from a shared adapter's metadata.json. Pass an "
+            "override path to a voice clip explicitly."
+        )
+
+    adapter_dir = adapter_path.parent
+    resolved_path = adapter_dir / reference_path
+    real_adapter_dir = os.path.realpath(adapter_dir)
+    real_resolved_path = os.path.realpath(resolved_path)
+    if os.path.commonpath([real_adapter_dir, real_resolved_path]) != real_adapter_dir:
+        raise AdapterLoadError(
+            f"Recorded reference clip {reference_path} in metadata.json resolves outside of "
+            f"{adapter_dir}, which OwnVoice does not trust from a shared adapter's "
+            "metadata.json. Pass an override path to a voice clip explicitly."
+        )
+    if not resolved_path.exists():
+        raise AdapterLoadError(
+            f"Recorded reference clip {resolved_path} no longer exists. Pass an override "
+            "path to a voice clip explicitly."
+        )
+    return resolved_path
+
+
+def generate_speech(base_model: Any, peft_model: Any, text: str, reference_audio_path: Path | str) -> torch.Tensor:
+    """Generate speech audio for `text` using the base model wrapped with the LoRA adapter.
+
+    Verified against real loaded pocket-tts weights this session, and the
+    naive approach the previous TODO here anticipated turned out to be
+    wrong for two independent, real reasons:
+
+    1. No flow_lm swap is needed, and the previous
+       `base_model.flow_lm = peft_model` swap actively breaks generation.
+       PEFT's `get_peft_model()` replaces `base_model.flow_lm`'s targeted
+       `nn.Linear` submodules with LoRA layers IN PLACE -- it mutates the
+       same live module graph rather than returning a copy, so
+       `base_model.flow_lm` already carries the trained adapter's weights
+       by the time this function runs (confirmed: `id(base_model.flow_lm)`
+       is unchanged before/after `get_peft_model()`, and its Linear
+       submodules are already `peft.tuners.lora.layer.Linear` instances
+       afterward). Reassigning `base_model.flow_lm` to the outer
+       `PeftModel` wrapper instead breaks pocket-tts's own streaming state
+       machinery: `StatefulModule.get_state()` looks up KV-cache state by a
+       fixed `_module_absolute_name` string baked onto each submodule once
+       at `TTSModel.load_model()` time (e.g. "transformer.layers.0.
+       self_attn"), but `get_state_for_audio_prompt()` rebuilds the
+       `model_state` dict fresh via `init_states(base_model.flow_lm, ...)`,
+       which keys it off `named_modules()` on whatever module is currently
+       assigned to `base_model.flow_lm`. PEFT's `PeftModel`/`LoraModel`
+       wrapper inserts a "base_model.model." prefix into those paths, so
+       swapping to the wrapper produces a `model_state` dict whose keys no
+       longer match the fixed `_module_absolute_name` strings, and
+       generation fails with `KeyError: 'transformer.layers.0.self_attn'`
+       -- reproduced against real weights this session.
+    2. The publicly downloadable pocket-tts weights
+       (`kyutai/pocket-tts-without-voice-cloning`, the checkpoint
+       `TTSModel.load_model()` falls back to whenever the gated
+       `kyutai/pocket-tts` voice-cloning weights aren't accessible, which
+       is the common case since that repo requires manual approval on
+       Hugging Face) set `has_voice_cloning = False`. With that flag set,
+       `get_state_for_audio_prompt()` raises `ValueError` for ANY
+       `str`/`Path` audio-conditioning argument, including OwnVoice's own
+       reference clip -- reproduced against real weights this session.
+       Passing a pre-loaded, pre-resampled `torch.Tensor` instead is
+       pocket-tts's own documented input type for this argument (`audio_
+       conditioning: Path | str | torch.Tensor`) and is not gated -- it
+       reaches the exact same Mimi-encode-then-project conditioning path
+       either way. So OwnVoice loads and resamples the reference clip
+       itself here rather than depending on gated HF access most users of
+       OwnVoice won't have. Voice-cloning fidelity from the without-voice-
+       cloning checkpoint is a known limitation of the base model itself
+       (per pocket-tts's own `VOICE_CLONING_UNSUPPORTED` message), not an
+       OwnVoice bug -- users who want kyutai's best-quality cloning weights
+       can request gated access at https://huggingface.co/kyutai/pocket-tts
+       and run `hf auth login`; OwnVoice works either way.
+    """
+    from pocket_tts.data.audio import audio_read
+    from pocket_tts.data.audio_utils import convert_audio
+
+    del peft_model  # injection already mutated base_model.flow_lm in place; see docstring point 1
+
+    reference_audio_path = Path(reference_audio_path)
+    raw_audio, source_sample_rate = audio_read(reference_audio_path)
+    audio_conditioning = convert_audio(
+        raw_audio, source_sample_rate, base_model.config.mimi.sample_rate, 1
+    )
+
+    model_state = base_model.get_state_for_audio_prompt(audio_conditioning)
+    return base_model.generate_audio(model_state, text)
+
+
+def save_wav(waveform: torch.Tensor, sample_rate: int, out_path: Path | str) -> Path:
+    """Save a 1D (or (1, N)) PCM waveform tensor to a .wav file.
+
+    Uses `soundfile` directly rather than `torchaudio.save` so writing a wav
+    file doesn't pull in an ffmpeg/torchcodec dependency chain just to save
+    plain PCM audio.
+    """
+    import soundfile as sf
+
+    out_path = Path(out_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    if waveform.dim() == 2:
+        waveform = waveform.squeeze(0)
+    sf.write(str(out_path), waveform.to(torch.float32).cpu().numpy(), sample_rate)
+    return out_path
+
+
+def infer(
+    adapter_path: Path | str,
+    text: str,
+    out_path: Path | str = Path("./ownvoice-output.wav"),
+    reference_audio_override: Path | str | None = None,
+) -> Path:
+    """End-to-end infer flow used by `ownvoice infer`: load, generate, save."""
+    from ownvoice.train import load_base_model
+
+    adapter_path = Path(adapter_path)
+    base_model = load_base_model(device="cpu")
+    peft_model = load_adapter(base_model, adapter_path)
+    reference_audio_path = resolve_reference_audio(adapter_path, reference_audio_override)
+    waveform = generate_speech(base_model, peft_model, text, reference_audio_path)
+    return save_wav(waveform, base_model.sample_rate, out_path)

ownvoice/score.py

@@ -0,0 +1,90 @@
+"""Speaker-similarity scoring: resample to 16kHz mono, Resemblyzer cosine similarity.
+
+Per the locked design (Approach A), 0.75 cosine similarity between the
+reference clip's and the generated clip's Resemblyzer speaker embeddings is
+the provisional bar for "usable adapter." Clearing it or not is reported as
+a labeled result, never a crash -- see ownvoice/train.py's train() flow.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import soundfile as sf
+import torch
+import torchaudio
+
+RESEMBLYZER_SAMPLE_RATE = 16000
+USABLE_THRESHOLD = 0.75
+
+
+def resample_to_16k_mono(waveform: torch.Tensor, orig_sample_rate: int) -> torch.Tensor:
+    """Resample a waveform tensor to 16kHz mono for Resemblyzer's embedding model.
+
+    Accepts a 1D (samples,) or 2D (channels, samples) tensor. Returns a 1D
+    float32 tensor. A no-op resample (already 16kHz) still runs through
+    downmixing and dtype normalization for a consistent return shape.
+    """
+    if waveform.dim() == 1:
+        waveform = waveform.unsqueeze(0)
+    if waveform.shape[0] > 1:
+        waveform = waveform.mean(dim=0, keepdim=True)
+    if orig_sample_rate != RESEMBLYZER_SAMPLE_RATE:
+        resampler = torchaudio.transforms.Resample(
+            orig_freq=orig_sample_rate, new_freq=RESEMBLYZER_SAMPLE_RATE
+        )
+        waveform = resampler(waveform)
+    return waveform.squeeze(0).to(torch.float32)
+
+
+def load_and_resample(path: Path | str) -> torch.Tensor:
+    """Load a wav file from disk and return it as 16kHz mono float32.
+
+    Reads via `soundfile` (not `torchaudio.load`, see the note in
+    ownvoice/data.py for why), then resamples with
+    `torchaudio.transforms.Resample`.
+    """
+    audio, sample_rate = sf.read(str(path), dtype="float32", always_2d=True)
+    waveform = torch.from_numpy(audio.T).to(torch.float32)
+    return resample_to_16k_mono(waveform, sample_rate)
+
+
+def cosine_similarity(a, b) -> float:
+    """Cosine similarity between two 1D embedding vectors (numpy or list-like).
+
+    Pure math, no Resemblyzer/model dependency -- kept separate from
+    compute_similarity() so the threshold logic is unit-testable without
+    downloading Resemblyzer's pretrained encoder weights.
+    """
+    import numpy as np
+
+    a = np.asarray(a, dtype=np.float64)
+    b = np.asarray(b, dtype=np.float64)
+    denom = float(np.linalg.norm(a) * np.linalg.norm(b))
+    if denom == 0.0:
+        return 0.0
+    return float(np.dot(a, b) / denom)
+
+
+def compute_similarity(
+    reference_waveform_16k: torch.Tensor,
+    generated_waveform_16k: torch.Tensor,
+) -> float:
+    """Cosine similarity between the two waveforms' Resemblyzer speaker embeddings.
+
+    Both inputs must already be 16kHz mono float32 tensors (use
+    resample_to_16k_mono or load_and_resample first). Resemblyzer is
+    imported lazily here, not at module load, so importing ownvoice.score
+    doesn't require Resemblyzer's pretrained weights to be downloaded yet.
+    """
+    from resemblyzer import VoiceEncoder
+
+    encoder = VoiceEncoder()
+    ref_embed = encoder.embed_utterance(reference_waveform_16k.numpy())
+    gen_embed = encoder.embed_utterance(generated_waveform_16k.numpy())
+    return cosine_similarity(ref_embed, gen_embed)
+
+
+def is_usable(score: float, threshold: float = USABLE_THRESHOLD) -> bool:
+    """True if `score` clears the usable-adapter bar (>= threshold, default 0.75)."""
+    return score >= threshold