audiocraft - Audio Generation

1.3.0 · active · verified Fri Apr 17

Audiocraft is a research library from Facebook AI for state-of-the-art audio generation, including models like MusicGen and AudioGen. It is built on PyTorch, providing tools for both model inference and training. Currently at version 1.3.0, it sees active development with new releases roughly every 1-3 months, often coinciding with new model research.

Common errors

```
torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate X GiB (GPU 0; Y GiB total capacity; Z GiB already allocated; W GiB free; P MiB reserved in total by PyTorch)
```
cause Attempting to generate audio that exceeds the available VRAM on your GPU.

fix Reduce the `duration` parameter in `model.set_generation_params()`. Use a smaller model (e.g., 'small'). If possible, upgrade to a GPU with more VRAM. Ensure no other processes are consuming GPU memory.
```
AttributeError: 'MusicGen' object has no attribute 'generate_unconditional'
```
cause You are using an older API call (`generate_unconditional`) that has been deprecated/removed in favor of a unified `generate` method.

fix Replace `model.generate_unconditional()` with `model.generate(descriptions=None)`. The `generate` method now handles both conditional and unconditional generation.
```
ImportError: cannot import name 'audio_write' from 'audiocraft.utils.audio' (...)
```
cause The `audio_write` utility function's import path changed in a recent version.

fix Update your import statement from `from audiocraft.utils.audio import audio_write` to `from audiocraft.data.audio import audio_write`.
```
RuntimeError: No module named '_C' or ImportError: cannot import name '_C' from 'torch_audiomentations.utils'
```
cause This often indicates a mismatch between your PyTorch version and your CUDA toolkit, or an issue with custom C++ extensions failing to compile/load.

fix Ensure your PyTorch installation is compatible with your CUDA version. It's often best to install PyTorch directly from their website with the correct CUDA version. Reinstalling `audiocraft` or `torchaudio` after verifying PyTorch/CUDA can help. For `torch_audiomentations`, ensure it's properly installed and compatible with your Python/PyTorch versions.

Warnings

gotcha Generating audio, especially longer clips or with larger models ('medium', 'large'), is extremely GPU memory intensive. Running out of VRAM is the most common issue.
Fix: Use a GPU with sufficient VRAM (e.g., 24GB+ for 'medium' models and longer generations). Reduce `duration` in `set_generation_params`. Try smaller models ('small'). Consider CPU inference as a last resort, but it will be very slow.
breaking The `model.generate_unconditional()` method has been removed/renamed.
Fix: Use `model.generate(descriptions=None)` for unconditional generation. The `generate` method now handles both conditional and unconditional generation.
gotcha Initial model loading requires downloading large weights (~2GB-3GB+). This can fail due to network issues or insufficient disk space.
Fix: Ensure you have a stable internet connection and at least 5GB of free disk space. On unstable networks, consider pre-downloading models or increasing connection timeout settings if possible.
gotcha On Linux, you might encounter `FileNotFoundError: libFLAC.so.8` or similar errors if audio processing dependencies are missing.
Fix: Install `libflac-dev` (Debian/Ubuntu) or `flac-libs` (Fedora/CentOS) or `libflac` (Arch Linux) using your system's package manager. For example: `sudo apt-get install libflac-dev`.

Install

pip install audiocraft Stable release
pip install -e '.[dev]' --no-deps From source (development)

Imports

MusicGen

wrong:

from audiocraft.models.musicgen import MusicGen

correct:

from audiocraft.models import MusicGen

Models are directly accessible from `audiocraft.models`.

AudioGen

wrong:

from audiocraft.models.audiogen import AudioGen

correct:

from audiocraft.models import AudioGen

Models are directly accessible from `audiocraft.models`.

audio_write
wrong:
```
from audiocraft.utils.audio import audio_write
```
correct:
```
from audiocraft.data.audio import audio_write
```
The utility for writing audio files moved from `utils` to `data.audio`.

Quickstart

This quickstart demonstrates how to load a pretrained MusicGen model, generate an 8-second audio clip based on a text description, and save it to a WAV file. Ensure you have sufficient disk space and a stable internet connection for the initial model download. GPU is highly recommended for faster generation.

from audiocraft.models import MusicGen
from audiocraft.data.audio import audio_write
import torch # For moving to CPU if needed

# Load a pretrained MusicGen model ('small' is generally recommended for quick tests)
# This will download model weights (~2GB for 'small'). Ensure stable internet and disk space.
# Specify device if needed: model = MusicGen.get_pretrained('small', device='cuda')
# Ensure you have a compatible PyTorch/CUDA setup for GPU usage.
model = MusicGen.get_pretrained('small')
model.set_generation_params(duration=8) # Generate 8 seconds of audio

# Define a description for the music
description = "a retro synthwave track with a driving beat"

print(f"Generating audio for: '{description}'...")
# The generate method takes a list of descriptions. For unconditional generation, pass descriptions=None.
samples = model.generate(descriptions=[description], progress=True)

# Save the generated audio to a WAV file
# `samples` is a torch.Tensor. It's good practice to move to CPU before saving if it's on GPU.
audio_write(
    'my_synthwave_track',
    samples[0].cpu(), # Take the first generated sample and move to CPU
    model.sample_rate,
    strategy="loudness",
    loudness_compressor=True # Recommended for better audio quality
)

print("Audio saved as 'my_synthwave_track.wav'")

view raw JSON →