microsoft/VibeVoice · error · ImportError

soundfile is required to save audio files. Install it with:

Error message

soundfile is required to save audio files. Install it with: pip install soundfile

What it means

VibeVoice's tokenizer processor lazily imports `soundfile` inside `save_audio()`; if the import fails, it re-raises an ImportError telling you soundfile is required. The dependency is optional, so a base install of the package does not include it, and the failure only surfaces at save time, not at package import time. The error is purely environmental — the audio data itself is fine.

Source

Thrown at vibevoice/processor/vibevoice_tokenizer_processor.py:313

                - torch.Tensor: PyTorch tensor with shape (B, C, T) or (B, T) or (T)
                - np.ndarray: NumPy array with shape (B, C, T) or (B, T) or (T)
                - List of tensors or arrays
            output_path: Path where to save the audio. If saving multiple files,
                this is treated as a directory and individual files will be saved inside.
            sampling_rate: Sampling rate for the saved audio. Defaults to the processor's rate.
            normalize: Whether to normalize audio before saving.
            batch_prefix: Prefix for batch files when saving multiple audios.
                
        Returns:
            List[str]: Paths to the saved audio files.
        """
        if sampling_rate is None:
            sampling_rate = self.sampling_rate
        
        try:
            import soundfile as sf
        except ImportError:
            raise ImportError(
                "soundfile is required to save audio files. "
                "Install it with: pip install soundfile"
            )
        
        # Ensure audio is in the right format
        if isinstance(audio, torch.Tensor):
            # Convert PyTorch tensor to numpy
            audio_np = audio.float().detach().cpu().numpy()
        elif isinstance(audio, np.ndarray):
            audio_np = audio
        elif isinstance(audio, list):
            # Handle list of tensors or arrays
            if all(isinstance(a, torch.Tensor) for a in audio):
                audio_np = [a.float().detach().cpu().numpy() for a in audio]
            else:
                audio_np = audio
        else:
            raise ValueError(f"Unsupported audio type: {type(audio)}")

View on GitHub (pinned to 94da20d98b)

Solutions

1. Install the dependency: `pip install soundfile` (add it to requirements.txt or the project's audio extra).
2. If libsndfile is missing at the OS level, install it: `apt-get install libsndfile1` (Debian/Ubuntu) or `apk add libsndfile` (Alpine), then retry.
3. If you cannot install soundfile, convert the tensor yourself and write the WAV with `torchaudio.save`/`scipy.io.wavfile.write` instead of calling `save_audio`.

Example fix

# before (ImportError in slim environments)
processor.save_audio(wav, "out.wav")

# after: ensure the optional dep is present
# pip install soundfile
processor.save_audio(wav, "out.wav")

import importlib.util

if importlib.util.find_spec("soundfile") is None:
    raise RuntimeError(
        "soundfile is not installed; run `pip install soundfile` before saving audio"
    )
processor.save_audio(wav, "out.wav")

try:
    processor.save_audio(wav, "out.wav")
except ImportError as e:
    if "soundfile" in str(e):
        logger.error("Optional dependency missing: %s", e)
        raise SystemExit("Install with: pip install soundfile") from e
    raise

When it happens

Trigger: Calling `processor.save_audio(audio, "out.wav")` (or any batch/list variant) in an environment where `pip install soundfile` was never run or where libsndfile (the C library soundfile wraps) is missing, making `import soundfile` raise ImportError.

Common situations: Running inference in a slim Docker/CI image, a fresh venv where vibevoice was installed without the `[audio]`/soundfile extra, or on a system without libsndfile installed (Alpine/minimal images) so the soundfile wheel cannot load.

Related errors

• Unsupported audio type: {type(audio)}
• Voices directory not found: {voices_dir}
• MODEL_PATH not set in environment
• Sample index {sample_idx} exceeds batch size {self.batch_siz
• load_audio_bytes_use_ffmpeg requires resample=True

AI-assisted analysis of microsoft/VibeVoice@94da20d98b (2026-08-15). Data as JSON: /api/errors/d9b1ba05bbce6474. Report an issue: GitHub.