### Install NeuCodec Environment

Source: https://github.com/neuphonic/neucodec/blob/main/README.md

Instructions for setting up the Python environment using either Conda or uv to install the neucodec package.

```bash
conda create -n neucodec python>3.9
conda activate neucodec
pip install neucodec
```

```bash
uv venv neucodec --python 3.10
source neucodec/bin/activate
uv pip install neucodec
```

--------------------------------

### Load and Use ONNX Decoder

Source: https://context7.com/neuphonic/neucodec/llms.txt

Loads a pre-trained ONNX decoder for efficient audio decoding. This decoder is optimized for deployment, runs on CPU using ONNX Runtime, and requires `onnxruntime` to be installed. It takes encoded codes as input (NumPy array) and outputs reconstructed audio.

```python
import numpy as np
import torch
import torchaudio
from neucodec import NeuCodec, NeuCodecOnnxDecoder

# First, encode with the PyTorch model
pytorch_model = NeuCodec.from_pretrained("neuphonic/neucodec")
pytorch_model.eval()

with torch.no_grad():
    fsq_codes = pytorch_model.encode_code("/path/to/audio.wav")

# Load ONNX decoder (requires: pip install onnxruntime)
onnx_decoder = NeuCodecOnnxDecoder.from_pretrained("neuphonic/neucodec-onnx-decoder")

# Decode using ONNX (input must be numpy array)
codes_numpy = fsq_codes.numpy()  # Shape: [B, 1, F]
reconstructed = onnx_decoder.decode_code(codes_numpy)

print(f"ONNX output shape: {reconstructed.shape}")  # [B, 1, T] as np.float32
print(f"Sample rate: {onnx_decoder.sample_rate}Hz")  # 24000Hz

# Save to file
torchaudio.save("onnx_reconstructed.wav", torch.from_numpy(reconstructed[0]), 24000)
```

--------------------------------

### Audio Preparation Internals

Source: https://context7.com/neuphonic/neucodec/llms.txt

Explains the internal audio preparation steps performed by the `_prepare_audio` method, including resampling to 16kHz, ensuring the correct shape `[B, 1, T]`, and padding to a multiple of 320 samples for frame alignment. Understanding these steps is crucial for custom pipeline integration and troubleshooting.

```python
import torch
import torchaudio
from torchaudio import transforms as T
from neucodec import NeuCodec

model = NeuCodec.from_pretrained("neuphonic/neucodec")

# Manual audio preparation (what _prepare_audio does internally)
y, sr = torchaudio.load("/path/to/audio.wav")

# 1. Resample to 16kHz if needed
if sr != 16000:
    y = T.Resample(sr, 16000)(y)

# 2. Ensure correct shape [B, 1, T]
if y.dim() == 2:
    y = y.unsqueeze(0)  # Add batch dimension

# 3. Pad to multiple of 320 samples (frame alignment)
pad_amount = 320 - (y.shape[-1] % 320)
if pad_amount != 320:
    y = torch.nn.functional.pad(y, (0, pad_amount))

print(f"Prepared tensor shape: {y.shape}")  # [1, 1, padded_length]
print(f"Duration: {y.shape[-1] / 16000:.3f} seconds")

# Now ready for encoding
model.eval()
with torch.no_grad():
    codes = model.encode_code(y)
```

--------------------------------

### Initialize and Use CodecEncoder

Source: https://context7.com/neuphonic/neucodec/llms.txt

Initializes the CodecEncoder with specified parameters and processes raw audio to extract features. Input is raw audio, output is compressed features.

```python
from neucodec.codec_encoder import CodecEncoder
import torch

encoder = CodecEncoder(
    ngf=48,
    up_ratios=[2, 2, 4, 4, 5],
    dilations=(1, 3, 9),
    hidden_dim=1024,
)

audio = torch.randn(1, 1, 16000)

with torch.no_grad():
    features = encoder(audio)

print(f"Input shape: {audio.shape}")
print(f"Output shape: {features.shape}")
```

--------------------------------

### Encode and Decode Audio with NeuCodec

Source: https://github.com/neuphonic/neucodec/blob/main/README.md

Demonstrates loading a pre-trained NeuCodec model, encoding audio input into FSQ codes, and decoding them back into 24kHz audio.

```python
import librosa
import torch
import torchaudio
from torchaudio import transforms as T
from neucodec import NeuCodec

model = NeuCodec.from_pretrained("neuphonic/neucodec")
model.eval().cuda()

y, sr = torchaudio.load(librosa.ex("libri1"))
if sr != 16_000:
    y = T.Resample(sr, 16_000)(y)[None, ...]

with torch.no_grad():
    fsq_codes = model.encode_code(y)
    print(f"Codes shape: {fsq_codes.shape}")
    recon = model.decode_code(fsq_codes).cpu()

torchaudio.save("reconstructed.wav", recon[0, :, :], 24_000)
```

--------------------------------

### Load NeuCodec Pre-trained Model

Source: https://context7.com/neuphonic/neucodec/llms.txt

Initializes the NeuCodec model from HuggingFace Hub. This process automatically downloads weights and sets up the semantic and acoustic encoder components.

```python
import torch
from neucodec import NeuCodec

# Load the full NeuCodec model from HuggingFace
model = NeuCodec.from_pretrained("neuphonic/neucodec")
model.eval()

# Move to GPU for faster inference
if torch.cuda.is_available():
    model = model.cuda()

print(f"Model sample rate: {model.sample_rate}Hz")
print(f"Model hop length: {model.hop_length}")
```

--------------------------------

### Initialize and Use CodecDecoderVocos

Source: https://context7.com/neuphonic/neucodec/llms.txt

Initializes the CodecDecoderVocos for reconstructing audio from quantized features. It supports both quantization (vq=True) and decoding to audio (vq=False).

```python
from neucodec.codec_decoder_vocos import CodecDecoderVocos
import torch

decoder = CodecDecoderVocos(
    hidden_dim=1024,
    depth=12,
    heads=16,
    hop_length=480,
    vq_dim=2048,
    vq_num_quantizers=1,
)

features = torch.randn(1, 2048, 100)
quantized, codes, _ = decoder(features, vq=True)
print(f"Codes shape: {codes.shape}")

decoded_features = torch.randn(1, 100, 1024)
audio, _ = decoder(decoded_features, vq=False)
print(f"Audio shape: {audio.shape}")
```

--------------------------------

### Initialize CodecEncoder

Source: https://context7.com/neuphonic/neucodec/llms.txt

Shows how to initialize the `CodecEncoder` component of NeuCodec. This encoder is responsible for processing raw audio waveforms into dense feature representations using a convolutional architecture.

```python
import torch
from neucodec.codec_encoder import CodecEncoder

# Initialize the CodecEncoder
encoder = CodecEncoder()

# The encoder is now ready to process audio.
# Example usage would involve passing audio tensors to its forward method.
```

--------------------------------

### Batch Processing with NeuCodec

Source: https://context7.com/neuphonic/neucodec/llms.txt

Demonstrates how to process multiple audio files simultaneously using batching. This method stacks audio tensors along the batch dimension for both encoding and decoding, significantly improving throughput for bulk processing tasks. Ensure audio files are padded to the same length before stacking.

```python
import torch
import torchaudio
from torchaudio import transforms as T
from neucodec import NeuCodec

model = NeuCodec.from_pretrained("neuphonic/neucodec")
model.eval().cuda()

# Load and prepare multiple audio files
audio_files = ["audio1.wav", "audio2.wav", "audio3.wav"]
audio_tensors = []

for filepath in audio_files:
    y, sr = torchaudio.load(filepath)
    if sr != 16000:
        y = T.Resample(sr, 16000)(y)
    audio_tensors.append(y)

# Stack into batch (pad to same length first if needed)
max_len = max(t.shape[-1] for t in audio_tensors)
padded = [torch.nn.functional.pad(t, (0, max_len - t.shape[-1])) for t in audio_tensors]
batch = torch.stack(padded, dim=0)  # Shape: [B, 1, T]

# Batch encode and decode
with torch.no_grad():
    batch_codes = model.encode_code(batch.cuda())
    batch_reconstructed = model.decode_code(batch_codes)

print(f"Batch input shape: {batch.shape}")
print(f"Batch codes shape: {batch_codes.shape}")
print(f"Batch output shape: {batch_reconstructed.shape}")

# Save individual files
for i, filepath in enumerate(audio_files):
    torchaudio.save(f"recon_{i}.wav", batch_reconstructed[i:i+1].cpu(), 24000)
```

--------------------------------

### NeuCodec.from_pretrained

Source: https://context7.com/neuphonic/neucodec/llms.txt

Loads a pre-trained NeuCodec model from the HuggingFace Hub, initializing both semantic and acoustic encoders.

```APIDOC
## NeuCodec.from_pretrained

### Description
Loads a pre-trained NeuCodec model from HuggingFace Hub. This is the primary entry point for using NeuCodec, automatically downloading model weights and initializing all components.

### Method
Class Method

### Parameters
- **model_id** (string) - Required - The HuggingFace model repository ID (e.g., "neuphonic/neucodec").

### Request Example
```python
from neucodec import NeuCodec
model = NeuCodec.from_pretrained("neuphonic/neucodec")
```

### Response
- **model** (NeuCodec) - An initialized instance of the NeuCodec model.
```

--------------------------------

### DistillNeuCodec.from_pretrained

Source: https://context7.com/neuphonic/neucodec/llms.txt

Loads the distilled version of NeuCodec for faster inference.

```APIDOC
## DistillNeuCodec.from_pretrained

### Description
Loads a distilled model variant that uses DistilHuBERT for semantic encoding, offering reduced memory footprint and faster inference.

### Parameters
- **model_id** (string) - Required - The HuggingFace model repository ID (e.g., "neuphonic/distill-neucodec").

### Request Example
```python
from neucodec import DistillNeuCodec
model = DistillNeuCodec.from_pretrained("neuphonic/distill-neucodec")
```

### Response
- **model** (DistillNeuCodec) - An initialized instance of the distilled model.
```

--------------------------------

### Initialize and Use SemanticEncoder

Source: https://context7.com/neuphonic/neucodec/llms.txt

Initializes the SemanticEncoder to transform Wav2Vec2-BERT or HuBERT features into the codec's internal representation. It uses convolutional layers with residual connections.

```python
from neucodec.module import SemanticEncoder
import torch

semantic_enc = SemanticEncoder(
    input_channels=1024,
    code_dim=1024,
    encode_channels=1024,
    kernel_size=3,
)

semantic_features = torch.randn(1, 1024, 50)

with torch.no_grad():
    encoded = semantic_enc(semantic_features)

print(f"Input: {semantic_features.shape}")
print(f"Output: {encoded.shape}")

distill_semantic_enc = SemanticEncoder(
    input_channels=768,
    code_dim=1024,
    encode_channels=768,
)
```

--------------------------------

### Verify Audio Reconstruction Quality with NeuCodec

Source: https://context7.com/neuphonic/neucodec/llms.txt

Verifies the quality of audio reconstruction by calculating the Mean Squared Error (MSE) between the original and reconstructed audio signals. A low MSE indicates good reconstruction.

```python
import torch
import torch.nn.functional as F
import torchaudio
from torchaudio import transforms as T
from neucodec import NeuCodec

model = NeuCodec.from_pretrained("neuphonic/neucodec")
model.eval()

y, sr = torchaudio.load("/path/to/test.wav")
if sr != 16000:
    y = T.Resample(sr, 16000)(y)
y = y[None, :]

y_prepared = model._prepare_audio(y)

with torch.no_grad():
    codes = model.encode_code(y)
    recon = model.decode_code(codes)

    recon_16k = T.Resample(24000, 16000)(recon)

    min_len = min(y_prepared.shape[-1], recon_16k.shape[-1])
    mse = F.mse_loss(y_prepared[..., :min_len], recon_16k[..., :min_len])

print(f"Reconstruction MSE: {mse.item():.6f}")
print(f"Quality check: {'PASS' if mse < 0.02 else 'FAIL'}")
```

--------------------------------

### Decode FSQ Tokens to Audio

Source: https://context7.com/neuphonic/neucodec/llms.txt

Reconstructs a 24kHz audio waveform from discrete FSQ tokens. It utilizes a Vocos-based decoder to synthesize high-quality audio from the compressed representation.

```python
import torch
import torchaudio
from neucodec import NeuCodec

model = NeuCodec.from_pretrained("neuphonic/neucodec")
model.eval().cuda()

with torch.no_grad():
    fsq_codes = model.encode_code("/path/to/input.wav")
    reconstructed = model.decode_code(fsq_codes)

# Save reconstructed audio at 24kHz
torchaudio.save("reconstructed.wav", reconstructed[0].cpu(), sample_rate=24000)
```

--------------------------------

### NeuCodec Python Interface

Source: https://github.com/neuphonic/neucodec/blob/main/README.md

The primary Python interface for loading the pre-trained NeuCodec model, encoding raw audio into FSQ tokens, and decoding tokens back into 24kHz audio.

```APIDOC
## POST /model/encode_decode

### Description
Encodes an input audio signal into FSQ tokens and reconstructs the audio at a 24kHz sample rate.

### Method
POST

### Endpoint
/model/encode_decode

### Parameters
#### Request Body
- **audio_input** (tensor/file) - Required - The 16kHz audio input signal.

### Request Example
{
  "audio_path": "path/to/audio.wav"
}

### Response
#### Success Response (200)
- **reconstructed_audio** (tensor) - The decoded audio output at 24kHz.
- **fsq_codes** (tensor) - The generated FSQ tokens (50 tokens/sec).

#### Response Example
{
  "status": "success",
  "codes_shape": "[1, 1, 500]",
  "output_path": "reconstructed.wav"
}
```

--------------------------------

### Encode Audio to FSQ Tokens

Source: https://context7.com/neuphonic/neucodec/llms.txt

Converts audio files or tensors into discrete FSQ tokens at 50Hz. The method handles resampling to 16kHz and produces compact representations suitable for speech language models.

```python
import torch
import torchaudio
from torchaudio import transforms as T
from neucodec import NeuCodec

model = NeuCodec.from_pretrained("neuphonic/neucodec")
model.eval().cuda()

# Option 1: Encode directly from file path
fsq_codes = model.encode_code("/path/to/audio.wav")

# Option 2: Encode from pre-loaded tensor
y, sr = torchaudio.load("/path/to/audio.wav")
if sr != 16000:
    y = T.Resample(sr, 16000)(y)
y = y[None, :]

with torch.no_grad():
    fsq_codes = model.encode_code(y.cuda())
```

--------------------------------

### Load and Use DistillNeuCodec

Source: https://context7.com/neuphonic/neucodec/llms.txt

Loads a distilled version of NeuCodec that uses DistilHuBERT for faster inference. The API is identical to the standard NeuCodec, making it a drop-in replacement for resource-constrained environments.

```python
import torch
import torchaudio
from neucodec import DistillNeuCodec

# Load the distilled model
model = DistillNeuCodec.from_pretrained("neuphonic/distill-neucodec")
model.eval().cuda()

with torch.no_grad():
    fsq_codes = model.encode_code("/path/to/audio.wav")
    reconstructed = model.decode_code(fsq_codes)

torchaudio.save("distill_reconstructed.wav", reconstructed[0].cpu(), 24000)
```

--------------------------------

### Export NeuCodec Decoder to ONNX

Source: https://context7.com/neuphonic/neucodec/llms.txt

Provides a script to export the NeuCodec decoder model to the ONNX format. This allows for deployment in environments where PyTorch is not available. The export process configures dynamic batch and sequence lengths for flexibility.

```python
import torch
import librosa
from neucodec import NeuCodec

# Load model and encode sample audio
model = NeuCodec.from_pretrained("neuphonic/neucodec")
model.eval()

# Get sample codes for tracing
with torch.no_grad():
    fsq_codes = model.encode_code(librosa.ex("libri1"))

# Export decoder to ONNX with dynamic shapes
torch.onnx.export(
    model,
    (fsq_codes,),
    "neucodec_decoder.onnx",
    input_names=["codes"],
    output_names=["audio"],
    dynamic_axes={
        "codes": {0: "batch_size", 2: "sequence_length"},
        "audio": {0: "batch_size", 2: "audio_length"}
    },
    opset_version=17
)

print("Exported ONNX decoder to neucodec_decoder.onnx")
print(f"Input codes shape: {fsq_codes.shape}")  # [B, 1, F]
```

--------------------------------

### NeuCodec.decode_code

Source: https://context7.com/neuphonic/neucodec/llms.txt

Reconstructs 24kHz audio waveform from discrete FSQ tokens.

```APIDOC
## NeuCodec.decode_code

### Description
Takes quantized codes and generates high-quality audio output using a Vocos-based decoder with ISTFT synthesis.

### Parameters
- **codes** (torch.Tensor) - Required - The discrete FSQ tokens generated by the encoder.

### Request Example
```python
reconstructed = model.decode_code(fsq_codes)
```

### Response
- **waveform** (torch.Tensor) - Reconstructed audio tensor at 24kHz with shape [B, 1, T_24kHz].
```

--------------------------------

### NeuCodec.encode_code

Source: https://context7.com/neuphonic/neucodec/llms.txt

Encodes audio input into discrete FSQ codes at 50Hz, suitable for training speech language models.

```APIDOC
## NeuCodec.encode_code

### Description
Processes audio through semantic and acoustic encoders to produce compact discrete representations.

### Parameters
- **input** (str/Path/torch.Tensor) - Required - Audio file path or a tensor of shape [B, 1, T] at 16kHz.

### Request Example
```python
fsq_codes = model.encode_code("/path/to/audio.wav")
```

### Response
- **fsq_codes** (torch.Tensor) - Discrete tokens with shape [B, 1, num_frames] at 50Hz.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.