Registry / ai-ml / s3tokenizer

s3tokenizer

JSON →
library0.3.0pypypiunverified

S3Tokenizer is a Python library that provides a reverse-engineered PyTorch implementation of the Supervised Semantic Speech Tokenizer (S3Tokenizer), originally proposed in CosyVoice. It enables high-throughput batch inference and online speech code extraction. The current version is 0.3.0, and the library demonstrates a rapid release cadence, frequently adding support for newer CosyVoice versions and improving audio processing capabilities.

pip install s3tokenizer
INSTALL
IMPORT
SIG · S3TOKENIZER
S
s3tokenizer
ai-mlpythonv0.3.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
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}.")
Debug
Known issues
gotchaAutomatic long audio processing introduced in v0.2.0 (and refined in v0.2.5/0.25) transparently handles audio longer than 30 seconds by segmenting it with a sliding window (30-second window, 4-second overlap). While this requires no explicit user action, advanced users should be aware of this internal behavior for specific use cases or debugging.
fix
No direct fix needed, but be aware of the internal long audio processing mechanism. Consult the GitHub README for details on windowing and overlap if fine-grained control is required.
affects: >=0.2.0
gotchaWhen upgrading to support CosyVoice3, ensure you are using the correct model identifier, such as `speech_tokenizer_v3_25hz`. While new models are supported, an open issue suggests potential differences in reconstruction quality compared to original CosyVoice tokens for `v3_25hz` models.
fix
Explicitly specify the desired model version (e.g., `s3tokenizer.load_model("speech_tokenizer_v3_25hz")`). If encountering reconstruction quality issues with `v3_25hz`, consider testing with previous model versions (`v1`, `v2`) or referring to GitHub issues for updates.
affects: >=0.2.5
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.
Agent activity
30 hits · last 30 days
node
26
Amazon
1
OpenAI (training)
1
Resources