### Install AudioCodec-Hub

Source: https://github.com/ga642381/audiocodec-hub/blob/main/README.md

Install the library using pip. This command fetches the latest version from the GitHub repository.

```bash
pip install git+https://github.com/ga642381/AudioCodec-Hub.git
```

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

### Usage Example with Different Quality Levels

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

This example demonstrates how to use the AudioCodec class to encode audio files at different quality levels (bitrates) by varying the n_q parameter. It shows encoding for low, medium, and high bitrate outputs.

```python
from audiocodec import AudioCodec

codec = AudioCodec("encodec_24khz")

# Low bitrate (1.5 kbps) - intelligible speech
codec.encode_file("speech.wav", "speech_low.json", n_q=2)

# Medium bitrate (6 kbps) - good quality speech
codec.encode_file("speech.wav", "speech_med.json", n_q=8)

# High bitrate (24 kbps) - near-transparent quality
codec.encode_file("speech.wav", "speech_high.json", n_q=32)
```

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

### Full Encode-Decode Pipeline Example

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Demonstrates a complete encode-decode workflow for a directory of audio files. This includes encoding raw audio to compressed codes and then decoding those codes back to WAV format. Ensure `codebook_offset` is consistent between encoding and decoding.

```python
# Full encode-decode pipeline example
audio_codec.encode_dir(
    in_dir="raw_audio",
    out_dir="encoded_audio",
    n_q=8,
    batch_size=8,
    codebook_offset=True
)

audio_codec.decode_dir(
    in_dir="encoded_audio",
    out_dir="reconstructed_audio",
    codebook_offset=True
)
```

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

### Model Specification Reference

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

This section provides a reference for supported audio codec models, detailing their configuration options such as n_q, kbps, downsample rate, and codebook size. It serves as a guide for selecting appropriate settings.

```python
# Model Specification Reference
# =============================

# EnCodec (encodec_24khz)
# -----------------------
# | n_q   |  2  |  4  |  8  | 16  | 32  |
# | kbps  | 1.5 |  3  |  6  | 12  | 24  |
# Downsample rate: 320 (75 Hz code rate)
# Codebook size: 1024

# DAC (dac_24khz)
# ?---------------
# | n_q   |  2  |  4  |  8  | 16  | 32  |
# | kbps  | 1.5 |  3  |  6  | 12  | 24  |
# Downsample rate: 320 (75 Hz code rate)
# Codebook size: 1024

# AudioDec (audiodec_24khz)
# -------------------------
# | n_q   |  8  | 
# | kbps  | 6.4 | 
# Downsample rate: 300 (80 Hz code rate)
# Sample rate: 24kHz (libritts_v1 model)

# AudioDec (audiodec_48khz)
# -------------------------
# | n_q   |  8  | 
# | kbps  | 12.8| 
# Downsample rate: 300 (160 Hz code rate)
# Sample rate: 48kHz (vctk_v1 model)
```

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

### Test DAC and AudioDec Encoding/Decoding

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

This script demonstrates testing the DAC and AudioDec codecs by encoding and decoding a WAV file. It shows how to use the AudioCodec class with different model names and parameters like n_q and codebook_offset.

```python
print("Testing DAC...")
dac = AudioCodec("dac_24khz")
dac.encode_file("test.wav", "test_dac.json", n_q=NQ, codebook_offset=CODEBOOK_OFFSET)
dac.decode_file("test_dac.json", "test_dac_decoded.wav", codebook_offset=CODEBOOK_OFFSET)

# Test with AudioDec (fixed n_q=8)
print("Testing AudioDec...")
audiodec = AudioCodec("audiodec_24khz")
audiodec.encode_file("test.wav", "test_audiodec.json", n_q=8, codebook_offset=CODEBOOK_OFFSET)
audiodec.decode_file("test_audiodec.json", "test_audiodec_decoded.wav", codebook_offset=CODEBOOK_OFFSET)

print("All encoding/decoding completed successfully!")
```

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

### Run Unit Tests

Source: https://github.com/ga642381/audiocodec-hub/blob/main/README.md

Execute the unit tests for the audiocodec package using the provided command. Ensure your custom model is correctly integrated before running tests.

```bash
python -m unittest discover -s audiocodec/tests
```

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

### Complete Encoding/Decoding Pipeline with EnCodec

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Demonstrates the full workflow for encoding and decoding audio using the EnCodec model. This includes single file processing and directory processing. Key parameters like `n_q`, `codebook_offset`, and `batch_size` are configurable.

```python
from audiocodec import AudioCodec

# Configuration
NQ = 8                    # Number of quantizers (affects quality/bitrate)
CODEBOOK_OFFSET = True    # Apply offset to codebook indices
BATCH_SIZE = 8            # Batch size for directory encoding

# Test with EnCodec
print("Testing EnCodec...")
encodec = AudioCodec("encodec_24khz")

# Single file workflow
encodec.encode_file("test.wav", "test_encodec.json", n_q=NQ, codebook_offset=CODEBOOK_OFFSET)
encodec.decode_file("test_encodec.json", "test_encodec_decoded.wav", codebook_offset=CODEBOOK_OFFSET)

# Directory workflow
encodec.encode_dir("input_wavs/", "encodec_codes/", n_q=NQ, batch_size=BATCH_SIZE, codebook_offset=CODEBOOK_OFFSET)
encodec.decode_dir("encodec_codes/", "encodec_decoded/", codebook_offset=CODEBOOK_OFFSET)
```

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

### Initialize AudioCodec Models

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Initialize the AudioCodec class with a model specification ID. The library automatically uses CUDA if available, otherwise falls back to CPU.

```python
from audiocodec import AudioCodec

# Initialize with EnCodec model (24kHz)
audio_codec = AudioCodec("encodec_24khz")

# Initialize with Descript Audio Codec (24kHz)
audio_codec_dac = AudioCodec("dac_24khz")

# Initialize with AudioDec (24kHz for LibriTTS, 48kHz for VCTK)
audio_codec_audiodec = AudioCodec("audiodec_24khz")

# Model specifications:
# EnCodec/DAC: n_q values [2, 4, 8, 16, 32] -> bitrates [1.5, 3, 6, 12, 24] kbps
# AudioDec: n_q=8 fixed -> 6.4 kbps (24kHz) or 12.8 kbps (48kHz)
```

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

### AudioCodec Initialization

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Initialize the AudioCodec class with a model specification ID to load a neural audio codec model. Supports CUDA if available.

```APIDOC
## AudioCodec Class Initialization

### Description
Initialize the main entry point for the library with a model specification ID to load the corresponding neural audio codec model. The model automatically uses CUDA if available, otherwise falls back to CPU.

### Supported Models
- `encodec_24khz`
- `dac_24khz`
- `audiodec_24khz`
- `audiodec_48khz`

### Model Specifications
- **EnCodec/DAC**: `n_q` values [2, 4, 8, 16, 32] correspond to bitrates [1.5, 3, 6, 12, 24] kbps.
- **AudioDec**: `n_q=8` fixed, resulting in 6.4 kbps (24kHz) or 12.8 kbps (48kHz).

### Request Example
```python
from audiocodec import AudioCodec

# Initialize with EnCodec model (24kHz)
audio_codec = AudioCodec("encodec_24khz")

# Initialize with Descript Audio Codec (24kHz)
audio_codec_dac = AudioCodec("dac_24khz")

# Initialize with AudioDec (24kHz for LibriTTS, 48kHz for VCTK)
audio_codec_audiodec = AudioCodec("audiodec_24khz")
```
```

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

### Custom Audio Codec Model Implementation

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Implement custom audio codec models by inheriting from `CodecModel`. This involves defining `encode_tensor` and `decode_tensor` methods, along with properties for `codebook_size`, `sample_rate`, and `downsample_rate`. Load your custom model weights within the `load_model` method.

```python
from audiocodec.codec_models import CodecModel
import torch

class CustomAudioCodec(CodecModel):
    def __init__(self, device="cuda"):
        super().__init__()
        self.device = device
        self.load_model()

    def load_model(self):
        # Load your custom model weights here
        self.model = YourCustomModel().to(self.device)

    @torch.no_grad()
    def encode_tensor(self, x: torch.Tensor, padding_mask=None, n_q=None) -> torch.Tensor:
        """
        Encode audio waveform to discrete codes.

        Args:
            x: Input tensor [B x 1 x T_wav] - batch of mono audio
            padding_mask: Optional mask for variable length inputs
            n_q: Number of quantizers to use

        Returns:
            codes: Encoded tensor [B x n_q x T_code]
        """
        # Your encoding logic here
        codes = self.model.encode(x)
        if n_q is not None:
            codes = codes[:, :n_q, :]
        return codes

    @torch.no_grad()
    def decode_tensor(self, codes: torch.Tensor) -> torch.Tensor:
        """
        Decode discrete codes back to audio waveform.

        Args:
            codes: Encoded tensor [B x n_q x T_code]

        Returns:
            audio: Decoded waveform [B x 1 x T_wav]
        """
        return self.model.decode(codes)

    @property
    def codebook_size(self) -> int:
        """Size of each codebook (vocabulary size)."""
        return 1024  # Common default

    @property
    def sample_rate(self) -> int:
        """Audio sample rate in Hz."""
        return 24000

    @property
    def downsample_rate(self) -> int:
        """Ratio of audio samples to code frames (hop size)."""
        return 320  # T_audio = downsample_rate * T_code
```

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

### Custom Audio Codec Template

Source: https://github.com/ga642381/audiocodec-hub/blob/main/README.md

Use this template to create your custom audio codec by inheriting from `CodecModel`. Implement `encode_tensor`, `decode_tensor`, and define properties for `codebook_size`, `sample_rate`, and `downsample_rate`.

```python
from audiocodechub import CodecModel
import torch

class CustomAudioCodec(CodecModel):
    def __init__(self):
        super().__init__()
        # Initialize your custom model here

    def load_model(self):
        # Load your custom model from a file or initialize it here
        pass

    @torch.no_grad()
    def encode_tensor(self, x):
        """
        Implement your encoding logic here.
        Args:
            x (Tensor): Input audio tensor [B x 1 x T_wav].

        Returns:
            codes (Tensor): Encoded codes [B x n_q x T_code].
        """
        pass

    @torch.no_grad()
    def decode_tensor(self, codes):
        """
        Implement your decoding logic here.
        Args:
            codes (Tensor): Encoded codes to be decoded.

        Returns:
            Tensor: Decoded audio waveform.
        """
        pass

    @property
    def codebook_size(self):
        """
        Define the size of your custom model's codebook.
        """
        pass

    @property
    def sample_rate(self):
        """
        Define the sample rate of your custom model.
        """
        pass

    @property
    def downsample_rate(self):
        """
        Define the downsampling rate of your custom model.
        """
        pass
```

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

### Encode and Decode Directory in Batch Mode

Source: https://github.com/ga642381/audiocodec-hub/blob/main/README.md

Process all audio files within a directory for encoding and decoding. The encoding supports batch mode, while decoding currently does not.

```python
from audiocodec import AudioCodec

NQ = 8
CODEBOOK_OFFSET = True
BATCH_SIZE = 8

# Initialize the audio codec with a specific model name
model_name = "encodec_24khz"
audio_codec = AudioCodec(model_name)

# Encode all audio files in a directory (Support batch mode)
dir_in_enc = "test_wavs"
dir_out_enc = "encoded_dir"
audio_codec.encode_dir(dir_in_enc, dir_out_enc, n_q=NQ, codebook_offset=CODEBOOK_OFFSET, batch_size=BATCH_SIZE)

# Decode all encoded audio files in a directory (Currently not supporting batch mode)
dir_out_dec = "decoded_dir"
audio_codec.decode_dir(dir_out_enc, dir_out_dec, codebook_offset=CODEBOOK_OFFSET)

print("Encoding and decoding completed successfully!")
```

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

### encode_dir

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Batch encode all audio files in a directory, supporting parallel processing. Encoded files are saved to an output directory with matching filenames.

```APIDOC
## encode_dir

### Description
Batch encode all audio files in a directory with support for parallel processing via configurable batch size. This is optimized for processing large datasets efficiently. The method automatically discovers all audio files in the input directory and saves encoded JSON files to the output directory with matching filenames.

### Method
`encode_dir` (method of AudioCodec class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **in_dir** (str) - Required - Path to the input directory containing audio files.
- **out_dir** (str) - Required - Path to the output directory where encoded JSON files will be saved.
- **n_q** (int) - Required - Number of quantizers (codebooks) to use. Affects bitrate and quality.
- **batch_size** (int) - Optional - Number of files to process in parallel. Defaults to a system-determined optimal value.
- **codebook_offset** (bool) - Optional - Whether to apply an offset to each codebook's indices. Defaults to `False`.

### Request Example
```python
from audiocodec import AudioCodec

audio_codec = AudioCodec("encodec_24khz")

# Batch encode entire directory with batch processing
audio_codec.encode_dir(
    in_dir="dataset/wavs",
    out_dir="dataset/codes",
    n_q=8,
    batch_size=16,          # Process 16 files at once for GPU efficiency
    codebook_offset=True
)

# Lower quality encoding for storage efficiency
audio_codec.encode_dir(
    in_dir="dataset/wavs",
    out_dir="dataset/codes_compact",
    n_q=2,                  # 1.5 kbps - minimal but intelligible
    batch_size=32,
    codebook_offset=False
)

# Using DAC model for batch processing
audio_codec_dac = AudioCodec("dac_24khz")
audio_codec_dac.encode_dir(
    in_dir="librispeech/train",
    out_dir="librispeech/train_codes",
    n_q=16,                 # 12 kbps
    batch_size=8,
    codebook_offset=True
)
```

### Response
#### Success Response (200)
None (Files are saved to `out_dir`)

#### Response Example
None
```

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

### Decode Directory of Encoded Files

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Decodes all JSON-encoded audio files in a specified directory to WAV format. The output directory is created if it does not exist. Ensure `codebook_offset` matches the encoding setting.

```python
from audiocodec import AudioCodec

audio_codec = AudioCodec("encodec_24khz")

# Decode all files in directory
audio_codec.decode_dir(
    in_dir="dataset/codes",
    out_dir="dataset/reconstructed_wavs",
    codebook_offset=True    # Must match encoding setting
)
```

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

### Batch Encode Directory

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Batch encode all audio files in a directory with parallel processing support. This method is optimized for large datasets, saving encoded JSON files to an output directory with matching filenames.

```python
from audiocodec import AudioCodec

audio_codec = AudioCodec("encodec_24khz")

# Batch encode entire directory with batch processing
audio_codec.encode_dir(
    in_dir="dataset/wavs",
    out_dir="dataset/codes",
    n_q=8,
    batch_size=16,          # Process 16 files at once for GPU efficiency
    codebook_offset=True
)

# Lower quality encoding for storage efficiency
audio_codec.encode_dir(
    in_dir="dataset/wavs",
    out_dir="dataset/codes_compact",
    n_q=2,                  # 1.5 kbps - minimal but intelligible
    batch_size=32,
    codebook_offset=False
)

# Using DAC model for batch processing
audio_codec_dac = AudioCodec("dac_24khz")
audio_codec_dac.encode_dir(
    in_dir="librispeech/train",
    out_dir="librispeech/train_codes",
    n_q=16,                 # 12 kbps
    batch_size=8,
    codebook_offset=True
)
```

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

### encode_file

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Encode a single audio file into discrete codes and save the result to a JSON file. Control bitrate and quality using `n_q` and optionally enable `codebook_offset`.

```APIDOC
## encode_file

### Description
Encode a single audio file into discrete codes and save the result to a JSON output file. The `n_q` parameter controls the number of quantizers (codebooks) to use, which directly affects the bitrate and quality. Enable `codebook_offset` to apply an offset to each codebook's indices, useful for certain downstream applications.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
`encode_file` (method of AudioCodec class)

### Parameters
- **in_file** (str) - Required - Path to the input audio file (e.g., WAV).
- **out_file** (str) - Required - Path to save the output JSON file containing encoded codes.
- **n_q** (int) - Required - Number of quantizers (codebooks) to use. Affects bitrate and quality.
- **codebook_offset** (bool) - Optional - Whether to apply an offset to each codebook's indices. Defaults to `False`.

### Request Example
```python
from audiocodec import AudioCodec

audio_codec = AudioCodec("encodec_24khz")

# Basic encoding with 8 quantizers (6 kbps)
audio_codec.encode_file(
    in_file="audio/speech.wav",
    out_file="encoded/speech.json",
    n_q=8,
    codebook_offset=False
)

# High quality encoding with 32 quantizers (24 kbps)
audio_codec.encode_file(
    in_file="audio/music.wav",
    out_file="encoded/music_hq.json",
    n_q=32,
    codebook_offset=False
)

# Encoding with codebook offset (shifts code indices per codebook)
audio_codec.encode_file(
    in_file="audio/speech.wav",
    out_file="encoded/speech_offset.json",
    n_q=8,
    codebook_offset=True
)
```

### Response
#### Success Response (200)
None (File is saved to `out_file`)

#### Response Example
```json
{
    "0": "234 512 128 ...",  # Codes for codebook 0
    "1": "89 401 256 ...",   # Codes for codebook 1
    ...
}
```
```

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

### decode_file

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Decode audio codes from a JSON file back into a WAV audio file. Ensure `codebook_offset` matches the encoding setting.

```APIDOC
## decode_file

### Description
Decode previously encoded audio codes from a JSON file back to a WAV audio file. The `codebook_offset` parameter must match the value used during encoding. The output is saved as 16-bit PCM WAV at the model's native sample rate.

### Method
`decode_file` (method of AudioCodec class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **in_file** (str) - Required - Path to the input JSON file containing encoded codes.
- **out_file** (str) - Required - Path to save the output WAV audio file.
- **codebook_offset** (bool) - Required - Must match the `codebook_offset` setting used during encoding.

### Request Example
```python
from audiocodec import AudioCodec

audio_codec = AudioCodec("encodec_24khz")

# Decode without codebook offset
audio_codec.decode_file(
    in_file="encoded/speech.json",
    out_file="decoded/speech_reconstructed.wav",
    codebook_offset=False
)

# Decode with codebook offset (must match encoding setting)
audio_codec.decode_file(
    in_file="encoded/speech_offset.json",
    out_file="decoded/speech_offset_reconstructed.wav",
    codebook_offset=True
)
```

### Response
#### Success Response (200)
None (File is saved to `out_file`)

#### Response Example
None
```

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

### Encode and Decode Single Audio File

Source: https://github.com/ga642381/audiocodec-hub/blob/main/README.md

Encode a single audio file and then decode the resulting data. Ensure the input WAV file exists and specify output paths for encoded JSON and decoded WAV.

```python
from audiocodec import AudioCodec

NQ = 8
CODEBOOK_OFFSET = True

# Initialize the audio codec with a specific model name
model_name = "encodec_24khz"
audio_codec = AudioCodec(model_name)

# Encode an audio file
f_in_enc = "test_wavs/61_70970_000007_000001.wav"
f_out_enc = "encoded.json"
audio_codec.encode_file(f_in_enc, f_out_enc, n_q=NQ, codebook_offset=CODEBOOK_OFFSET)

# Decode the encoded audio data
f_out_dec = "decoded.wav"
audio_codec.decode_file(f_out_enc, f_out_dec, codebook_offset=CODEBOOK_OFFSET)

print("Encoding and decoding completed successfully!")
```

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

### Decode Audio File

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Decode audio codes from a JSON file back to a WAV audio file. Ensure the `codebook_offset` parameter matches the setting used during encoding. The output is a 16-bit PCM WAV file.

```python
from audiocodec import AudioCodec

audio_codec = AudioCodec("encodec_24khz")

# Decode without codebook offset
audio_codec.decode_file(
    in_file="encoded/speech.json",
    out_file="decoded/speech_reconstructed.wav",
    codebook_offset=False
)

# Decode with codebook offset (must match encoding setting)
audio_codec.decode_file(
    in_file="encoded/speech_offset.json",
    out_file="decoded/speech_offset_reconstructed.wav",
    codebook_offset=True
)
```

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

### Encode Audio File

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Encode a single audio file into discrete codes and save to a JSON file. The `n_q` parameter controls bitrate and quality, while `codebook_offset` can be enabled for specific applications.

```python
from audiocodec import AudioCodec

audio_codec = AudioCodec("encodec_24khz")

# Basic encoding with 8 quantizers (6 kbps)
audio_codec.encode_file(
    in_file="audio/speech.wav",
    out_file="encoded/speech.json",
    n_q=8,
    codebook_offset=False
)

# High quality encoding with 32 quantizers (24 kbps)
audio_codec.encode_file(
    in_file="audio/music.wav",
    out_file="encoded/music_hq.json",
    n_q=32,
    codebook_offset=False
)

# Encoding with codebook offset (shifts code indices per codebook)
audio_codec.encode_file(
    in_file="audio/speech.wav",
    out_file="encoded/speech_offset.json",
    n_q=8,
    codebook_offset=True
)

# Output JSON format example:
# {
#     "0": "234 512 128 ...",  # Codes for codebook 0
#     "1": "89 401 256 ...",   # Codes for codebook 1
#     ...
# }
```

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

### SpeechDataset for Batch Processing

Source: https://context7.com/ga642381/audiocodec-hub/llms.txt

Utilizes `SpeechDataset` for batch encoding of audio files. It handles audio loading, resampling to a target sample rate, and collation with padding masks for variable-length inputs. A `DataLoader` with a custom `collate_fn` is used for efficient batching.

```python
from audiocodec.dataset import SpeechDataset
from torch.utils.data import DataLoader
from pathlib import Path
import librosa

# Create dataset from list of audio file paths
wav_files = [Path(f) for f in librosa.util.find_files("audio_directory")]
dataset = SpeechDataset(
    file_paths=wav_files,
    target_sr=24000  # Resample all audio to target sample rate
)

# Create dataloader with custom collation
dataloader = DataLoader(
    dataset,
    batch_size=8,
    shuffle=False,
    collate_fn=dataset.collate_fn  # Handles padding and masking
)

# Iterate over batches
for input_values, padding_mask, file_paths in dataloader:
    # input_values: [B x 1 x T] - padded audio tensor
    # padding_mask: [B x T] - mask indicating valid samples
    # file_paths: List of source file paths
    print(f"Batch shape: {input_values.shape}")
    print(f"Files: {[p.name for p in file_paths]}")
```

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