vllm-omni/.claude/skills/add-tts-model/references/optional-deps.md

Optional Dependency Handling

Models that rely on torchaudio, torchcodec, soundfile, or other optional packages must handle the missing-package case at import time, not at call time. Failing to do this causes cryptic errors only on environments without the optional package — after the model is already deployed.

Pattern (used in MOSS-TTS-Nano)

def _patch_torchaudio_load() -> None:
    """Fallback torchaudio.load/save to soundfile if torchcodec is unavailable."""
    try:
        import torchcodec  # noqa: F401
        return  # torchcodec present, torchaudio works as-is
    except ImportError:
        pass

    import soundfile as sf
    import torchaudio

    def _sf_load(path, **kwargs):
        data, sr = sf.read(str(path), dtype="float32", always_2d=True)
        return torch.from_numpy(data).T, sr

    torchaudio.load = _sf_load
    # patch .save similarly if needed

Rules

• Mirror the full signature of the replaced function. torchaudio.load accepts frame_offset, num_frames, normalize, channels_first, format — missing any of them causes TypeError from calling code.
• Catch except Exception, not just ImportError. import torchaudio itself can fail with non-ImportError errors on broken installs. Log the exception type and message (logger.warning("torchaudio probe failed: %s: %s", type(exc).__name__, exc)) before falling back, so unrelated errors are not silently swallowed.
• Call the patch function at the top of load_weights() before loading any audio assets. Do not call it at module import time.

Reference implementation

Any in-tree model that patches torchaudio.load in its load_weights() — e.g. MOSS-TTS-Nano's modeling_moss_tts_nano.py once that integration lands.