Install & Compatibility
Where this runs
tested against v0.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 77.6s
py 3.11
✕ build_error
✓ 71.03s
py 3.12
✕ build_error
✓ 67.68s
py 3.13
✕ build_error
✓ 61s
py 3.9
✕ build_error
✕ timeout
4890MB installed
● package 4890MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EncodecModel
✓ from encodec import EncodecModel
For direct use of the core library components.
EncodecModel (via transformers)
✓ from transformers import EncodecModel, AutoProcessor
Recommended for using pre-trained models and easy integration with Hugging Face ecosystem.
This quickstart demonstrates how to use the `encodec` library for audio compression and decompression, leveraging its integration with Hugging Face Transformers. It loads a dummy audio sample, encodes it using a pre-trained Encodec model, and then decodes it. You need to install `datasets` and `transformers` (from source) for this example to work correctly.
import torch
from datasets import load_dataset, Audio
from transformers import EncodecModel, AutoProcessor
# NOTE: For a real application, you would load your own audio file.
# For quickstart, using a dummy dataset from Hugging Face.
librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
sample_audio = librispeech_dummy[0]["audio"]['array']
sample_rate = librispeech_dummy[0]["audio"]['sampling_rate']
# Load pre-trained Encodec model and processor (24khz monophonic model example)
model = EncodecModel.from_pretrained("facebook/encodec_24khz")
processor = AutoProcessor.from_pretrained("facebook/encodec_24khz")
# Pre-process the audio
inputs = processor(
raw_audio=sample_audio,
sampling_rate=sample_rate,
return_tensors="pt"
)
# Encode the audio. You can specify a bandwidth (e.g., 1.5, 3.0, 6.0, 12.0, 24.0 kbps).
# Default is 1.5 kbps if not specified. Example: encoded_frames = model.encode(inputs["input_values"], bandwidth=3.0)
encoded_frames = model.encode(inputs["input_values"])
# Decode the audio
decoded_audio = model.decode(encoded_frames)
print(f"Original audio shape: {inputs['input_values'].shape}")
print(f"Decoded audio shape: {decoded_audio.shape}")
print("Audio encoded and decoded successfully!")
Debug
Known issues
gotchaThe original `encodec` library does not handle very long audio files gracefully. It processes the entire file at once, which can lead to high memory consumption and Out-of-Memory (OOM) errors. The developers have stated they do not currently support this use case.fixManually chunk long audio files into smaller segments before processing with `encodec`.
affects: All versions
breakingTo use `encodec` via Hugging Face Transformers (as often recommended), the `transformers` library must be installed from its `main` GitHub branch, not the PyPI stable release, because `encodec` integration might be newer than the latest `transformers` release.fixInstall `transformers` directly from GitHub: `pip install -U datasets git+https://github.com/huggingface/transformers.git@main`
affects: All versions where Encodec is a recent addition to `transformers`.
gotchaThe 48 kHz stereo Encodec model processes audio in 1-second chunks with a 1% overlap and renormalizes the audio to unit scale. When extracting discrete representations, `model.encode(wav)` will return a list of `(codes, scale)` tuples, one for each 1-second frame. This behavior differs from the 24 kHz model.fixBe aware of the output format and chunking when using the 48 kHz model for encoding, especially for extracting discrete representations.
affects: All versions implementing the 48 kHz model.
gotchaEnsure a reasonably recent version of PyTorch (ideally 1.11.0 or newer) is installed. Older PyTorch versions (e.g., <1.8) may have compatibility issues, such as different default values for `torch.stft(return_complex)` within `encodec`'s internal audio processing.fixUpgrade PyTorch to version 1.11.0 or newer: `pip install -U torch torchaudio`
affects: < 0.1.1 (potentially affecting older PyTorch versions)
Upgrade
Version history
0.1.1latest on PyPI · released Oct 25, 2022
Audit
Dependencies
numpyrequiredCore numerical operations.
torchrequiredUnderlying deep learning framework (PyTorch 1.11.0+ recommended).
torchaudiorequiredAudio I/O and processing utilities.
einopsrequiredFlexible tensor operations.
datasetsoptionalRecommended for loading and managing audio datasets (when using Hugging Face Transformers integration).
transformersoptionalRequired for using EnCodec models via Hugging Face Transformers API.