Install & Compatibility
Where this runs
tested against v0.3.0 · 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
3/4 runs
py 3.11
✕ build_error
3/4 runs
py 3.12
✕ build_error
3/4 runs
py 3.13
✕ build_error
3/4 runs
py 3.9
✕ build_error
✕ timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
load_model
✓ import s3tokenizer
tokenizer = s3tokenizer.load_model("speech_tokenizer_v1")
Primary entry point for loading S3Tokenizer models.
load_audio
✓ import s3tokenizer
audio = s3tokenizer.load_audio("path/to/audio.wav")
Utility function for loading audio files into the correct format.
This quickstart demonstrates how to load an S3Tokenizer model, load an audio file, and extract discrete speech codes from it. The example prioritizes GPU usage if available and includes a fallback to CPU. It also includes code to generate a dummy WAV file for immediate execution.
import s3tokenizer
import os
# Ensure PyTorch is available and CUDA is configured if using GPU
# For demonstration, we'll try to use CUDA if available, otherwise CPU.
# In a real scenario, you might want to explicitly set device or handle errors.
# Assuming a dummy audio file for demonstration.
# In a real use case, replace with your .wav file path.
# You might need to create a dummy WAV file or download one from the S3Tokenizer repo assets.
# For example, by downloading from: https://github.com/xingchensong/S3Tokenizer/blob/main/s3tokenizer/assets/BAC009S0764W0121.wav
# Create a dummy .wav file if it doesn't exist for a runnable example
dummy_wav_path = "dummy_audio.wav"
if not os.path.exists(dummy_wav_path):
try:
import torchaudio
import torch
sample_rate = 16000
duration_seconds = 5
waveform = torch.randn(1, sample_rate * duration_seconds)
torchaudio.save(dummy_wav_path, waveform, sample_rate)
print(f"Created dummy audio file: {dummy_wav_path}")
except ImportError:
print("torchaudio or torch not found. Cannot create dummy audio. Please provide a real .wav file.")
exit()
# Load the tokenizer model, preferring CUDA if available
device = "cuda" if torch.cuda.is_available() else "cpu"
tokenizer = s3tokenizer.load_model("speech_tokenizer_v1").to(device)
print(f"Tokenizer model loaded on device: {device}")
# Load an audio file
# Replace `dummy_wav_path` with your actual audio file path if not using the dummy
if os.path.exists(dummy_wav_path):
audio = s3tokenizer.load_audio(dummy_wav_path)
audio = audio.to(device)
audio_len = torch.tensor([audio.shape[1]], device=device)
# Quantize the audio to get speech codes
speech_codes, speech_codes_lens = tokenizer.quantize(audio, audio_len)
print(f"Shape of extracted speech codes: {speech_codes.shape}")
print(f"Length of speech codes: {speech_codes_lens.item()}")
else:
print(f"Error: Audio file not found at {dummy_wav_path}.")
Upgrade
Version history
0.3.0latest on PyPI · released Dec 22, 2025
Audit
Dependencies
torchrequiredCore deep learning framework for model implementation.
torchaudiorequiredAudio processing functionalities, tightly integrated with PyTorch.
tqdmrequiredProgress bar for iterative processes (e.g., batch processing).
numpyrequiredFundamental package for numerical computing in Python.
einopsrequiredFlexible and powerful tensor operations for neural networks.
onnxruntimerequiredRuntime for ONNX models, used for converting original ONNX weights to PyTorch.
soundfilerequiredLibrary for reading and writing sound files.