### Install Project Dependencies

Source: https://github.com/liquid4all/liquid-audio/blob/main/README.md

Installs the necessary project dependencies using uv. This command should be run before any other setup or training steps.

```bash
uv sync
```

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

### Full Training Pipeline Setup

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-loader.md

Example demonstrating the complete data preparation and training pipeline. This includes initializing the processor and mapper, preprocessing the dataset, and setting up the data loader and trainer.

```python
from pathlib import Path
from liquid_audio import LFM2AudioProcessor, LFM2AudioModel
from liquid_audio.data.mapper import LFM2AudioChatMapper
from liquid_audio.data.preprocess import preprocess_dataset
from liquid_audio.data.dataloader import LFM2DataLoader, lfm2_collator
from liquid_audio.trainer import Trainer
from torch.utils.data import DataLoader
import torch

# Step 1: Prepare processor and mapper
processor = LFM2AudioProcessor.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
mapper = LFM2AudioChatMapper(processor, codebooks=8)

# Step 2: Preprocess dataset (one-time)
def my_data_generator():
    """Yields lists of ChatMessage"""
    # Load your raw data here
    for sample in load_my_dataset():
        messages = convert_to_chat_messages(sample)
        yield messages

preprocess_dataset(
    data=my_data_generator(),
    output_path="data/my_dataset/train",
    mapper=mapper,
    max_context_length=4096,
)
```

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

### Basic DataLoader Setup

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-loader.md

Standard setup for a DataLoader with LFM2DataLoader for single-GPU training. Ensure the dataset path and context length are correctly specified.

```python
train_dataset = LFM2DataLoader(
    "data/my_dataset/train",
    context_length=4096,
)

train_loader = DataLoader(
    train_dataset,
    batch_size=16,
    shuffle=True,
    collate_fn=lfm2_collator,
    num_workers=4,
    pin_memory=True,
)
```

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

### Launch Gradio Demo

Source: https://github.com/liquid4all/liquid-audio/blob/main/README.md

Install the demo dependencies and launch the Gradio interface using the command line. The demo will be accessible at http://localhost:7860.

```bash
pip install "liquid-audio [demo]"
liquid-audio-demo
```

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

### Distributed Training - Multi-Machine Configuration

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Configures distributed training for multiple machines. First, run `accelerate config` to set up the multi-machine environment. Then, use `accelerate launch` to start the training script, potentially with different batch sizes and max steps for the distributed setup.

```bash
accelerate config  # Configure for multi-machine
accelerate launch training_script.py --batch-size 64 --max-steps 50000
```

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

### Install Liquid Audio Package

Source: https://github.com/liquid4all/liquid-audio/blob/main/README.md

Install the liquid-audio package using pip. Optional dependencies for the demo and flash attention 2 can also be installed.

```bash
pip install liquid-audio
pip install "liquid-audio [demo]" # optional, to install demo dependencies
pip install flash-attn --no-build-isolation  # optional, to use flash attention 2. Will fallback to torch SDPA if not installed
```

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

### Example Model Configuration (config.json)

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/configuration.md

This is a sample structure for the main model configuration file loaded from model checkpoints. It defines the model's architecture and various training-related parameters.

```json
{
  "architectures": ["LFM2AudioModel"],
  "codebooks": 8,
  "tie_audio_embeddings": true,
  "semantic_codebook_factor": 4.0,
  "codebook_weight": "log",
  "text_loss_multiplier": 1.0,
  "audio_loss_multiplier": 1.0,
  "interleaved_n_text": 6,
  "interleaved_n_audio": 12,
  "preprocessor": { ... },
  "encoder": { ... },
  "lfm": { ... },
  "depthformer": { ... }
}
```

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

### Preprocess Dataset Example

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-mapper.md

Demonstrates how to preprocess a dataset of chat messages using LFM2AudioChatMapper and save it in Arrow format. Ensure the output directory does not already exist.

```python
from liquid_audio.data.types import ChatMessage, TextSegment
from liquid_audio import LFM2AudioProcessor
from liquid_audio.data.mapper import LFM2AudioChatMapper
from liquid_audio.data.preprocess import preprocess_dataset
import io

processor = LFM2AudioProcessor.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
mapper = LFM2AudioChatMapper(processor)

def message_generator():
    """Generator yielding lists of ChatMessage"""
    for i in range(100):
        yield [
            ChatMessage(
                role="system",
                content=[TextSegment(text="You are helpful.")]
            ),
            ChatMessage(
                role="user",
                content=[TextSegment(text=f"Example {i}")]
            ),
        ]

# Preprocess
preprocess_dataset(
    data=message_generator(),
    output_path="data/my_dataset/train",
    mapper=mapper,
    max_context_length=4096,
)

print("Preprocessing complete!")
```

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

### Custom Trainer with Short Warmup

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Configure the Trainer with a short warmup phase for fine-tuning. This example sets warmup_steps to 50 and decays the learning rate to 5% of the initial value.

```python
# Short warmup for fine-tuning
trainer = Trainer(
    train_data=train_dataset,
    lr=3e-5,
    warmup_steps=50,    # Short warmup
    max_steps=5000,
    min_ratio=0.05,     # Decay to 5% of initial LR
)
```

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

### Initialize LFM2-Audio Trainer

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Instantiate the Trainer class with model, data, and training parameters. Ensure train_data is provided to start the training process.

```python
from liquid_audio.data.dataloader import LFM2DataLoader
from liquid_audio.trainer import Trainer

# Prepare datasets
train_dataset = LFM2DataLoader("data/my_dataset/train", context_length=4096)
val_dataset = LFM2DataLoader("data/my_dataset/val", context_length=4096)

# Create trainer
trainer = Trainer(
    model_id="LiquidAI/LFM2.5-Audio-1.5B",
    train_data=train_dataset,
    val_data=val_dataset,
    lr=3e-5,
    batch_size=16,
    max_steps=10000,
    warmup_steps=500,
    output_dir="checkpoints/my_model",
)

# Start training
trainer.train()
```

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

### Example Usage of LFM2AudioModelInput.to()

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-types.md

Demonstrates how to create a batched input using `lfm2_collator`, move it to a CUDA device, and then pass it to the model. This is a typical workflow for training or inference.

```python
batch = lfm2_collator([row1, row2, row3])
batch = batch.to("cuda")
output = model(batch)
```

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

### Fine-tuning with Limited Data Configuration

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Configuration example for fine-tuning a model with a small dataset. It uses a higher learning rate, a small batch size, and less weight decay. The `output_dir` specifies where checkpoints and logs will be saved.

```python
trainer = Trainer(
    train_data=train_dataset,
    val_data=val_dataset,
    lr=1e-4,  # Higher learning rate for small datasets
    batch_size=4,  # Small batch
    max_steps=2000,
    warmup_steps=100,
    weight_decay=0.05,  # Less regularization
    output_dir="checkpoints/small_data_finetune",
)

trainer.train()
```

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

### Trainer.train()

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Starts the main training loop, iterating through the dataset for a specified number of steps with periodic logging, validation, and checkpointing.

```APIDOC
## Instance Methods

### train

```python
def train(self) -> None
```

Main training loop. Runs for `max_steps` with periodic validation and checkpointing.

**Behavior:**

1. Iterates through training data for up to `max_steps`
2. Every `logging_interval` steps: Prints loss and learning rate
3. Every `save_interval` steps: Saves checkpoint
4. Every `val_interval` steps: Runs validation if val_data provided
5. After final step: Saves final model and ends training

**Prints:**
- Elapsed time per update
- Training loss and learning rate
- Validation loss if applicable
- Training completion message

**Example:**
```python
trainer = Trainer(
    train_data=train_dataset,
    max_steps=10000,
    save_interval=500,
    logging_interval=10,
)

# This will run for 10000 steps, saving every 500 steps
trainer.train()

# Checkpoints saved to output_dir/checkpoint-*
# Final model saved to output_dir/final/
```
```

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

### Multi-turn Chat with Interleaved Generation

Source: https://github.com/liquid4all/liquid-audio/blob/main/README.md

Example demonstrating multi-turn, multi-modal chat using interleaved generation. It sets up a system prompt and adds user audio input to the chat state.

```python
import torch
import torchaudio
from liquid_audio import LFM2AudioModel, LFM2AudioProcessor, ChatState, LFMModality

# Load models
HF_REPO = "LiquidAI/LFM2.5-Audio-1.5B"

processor = LFM2AudioProcessor.from_pretrained(HF_REPO).eval()
model = LFM2AudioModel.from_pretrained(HF_REPO).eval()

# Set up inputs for the model
chat = ChatState(processor)

chat.new_turn("system")
chat.add_text("Respond with interleaved text and audio.")
chat.end_turn()

chat.new_turn("user")
wav, sampling_rate = torchaudio.load("assets/question.wav")
chat.add_audio(wav, sampling_rate)
chat.end_turn()

chat.new_turn("assistant")

```

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

### Detokenization Pipeline Example

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/detokenizer.md

Complete example showing audio code generation and detokenization using LFM2.AudioModel and LFM2AudioProcessor. The LFM2 detokenizer outputs 24kHz mono audio.

```python
import torch
import torchaudio
from liquid_audio import LFM2AudioModel, LFM2AudioProcessor, ChatState

# Load models
processor = LFM2AudioProcessor.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
model = LFM2AudioModel.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B").eval()

# Set up conversation
chat = ChatState(processor)
chat.new_turn("system")
chat.add_text("Perform TTS. Use the US male voice.")
chat.end_turn()

chat.new_turn("user")
chat.add_text("Hello, world!")
chat.end_turn()

chat.new_turn("assistant")

# Generate audio codes
audio_codes = []
for t in model.generate_sequential(**chat, max_new_tokens=512, audio_temperature=0.8, audio_top_k=64):
    if t.numel() > 1:  # Audio token
        audio_codes.append(t)

# Remove end-of-audio marker (last token)
audio_codes = audio_codes[:-1]

# Stack into (batch, codebooks, time) format
audio_codes_stacked = torch.stack(audio_codes, 1).unsqueeze(0)

# Detokenize
waveform = processor.decode(audio_codes_stacked)

# Save
torchaudio.save("tts_output.wav", waveform.cpu(), 24_000)
```

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

### Automatic Speech Recognition (ASR) Example

Source: https://github.com/liquid4all/liquid-audio/blob/main/README.md

Performs ASR using sequential generation with a fixed system prompt. The input audio is loaded from a file, and the model generates capitalized and punctuated text output.

```python
import torch
import torchaudio
from liquid_audio import LFM2AudioModel, LFM2AudioProcessor, ChatState, LFMModality

# Load models
HF_REPO = "LiquidAI/LFM2.5-Audio-1.5B"

processor = LFM2AudioProcessor.from_pretrained(HF_REPO).eval()
model = LFM2AudioModel.from_pretrained(HF_REPO).eval()

# Set up inputs for the model
chat = ChatState(processor)

chat.new_turn("system")
chat.add_text("Perform ASR.")
chat.end_turn()

chat.new_turn("user")
wav, sampling_rate = torchaudio.load("assets/asr.wav")
chat.add_audio(wav, sampling_rate)
chat.end_turn()

chat.new_turn("assistant")

# Generate text
for t in model.generate_sequential(**chat, max_new_tokens=512):
    if t.numel() == 1:
        print(processor.text.decode(t), end="", flush=True)
```

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

### LFM2AudioProcessor.from_pretrained

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/processor.md

Loads an LFM2AudioProcessor instance from a specified Hugging Face Hub repository ID or a local directory path. This class method simplifies the initialization process by handling the download and setup of necessary model components.

```APIDOC
## LFM2AudioProcessor.from_pretrained

### Description
Loads an LFM2AudioProcessor instance from a specified Hugging Face Hub repository ID or a local directory path. This class method simplifies the initialization process by handling the download and setup of necessary model components.

### Parameters
#### Path Parameters
- **repo_id** (str | Path) - Required - HF Hub model ID or local directory path
- **revision** (str | None) - Optional - Git revision to load from HF Hub
- **device** (torch.device | str) - Optional - Device to load audio components onto (default: "cuda")

### Returns
- **Self** - Initialized LFM2AudioProcessor
```

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

### Text-to-Speech (TTS) Example with UK Male Voice

Source: https://github.com/liquid4all/liquid-audio/blob/main/README.md

Performs TTS using sequential generation with a specified system prompt for the UK male voice. The input sentence is converted to speech and saved as an audio file.

```python
import torch
import torchaudio
from liquid_audio import LFM2AudioModel, LFM2AudioProcessor, ChatState, LFMModality

# Load models
HF_REPO = "LiquidAI/LFM2.5-Audio-1.5B"

processor = LFM2AudioProcessor.from_pretrained(HF_REPO).eval()
model = LFM2AudioModel.from_pretrained(HF_REPO).eval()

# Set up inputs for the model
chat = ChatState(processor)

chat.new_turn("system")
chat.add_text("Perform TTS. Use the UK male voice.")
chat.end_turn()

chat.new_turn("user")
chat.add_text("What is this obsession people have with books? They put them in their houses—like they're trophies. What do you need it for after you read it?")
chat.end_turn()

chat.new_turn("assistant")
```

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

### Usage Example for LFMModality

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/types.md

Demonstrates how to use the LFMModality enum to check the type of tokens within a ChatState's modality flag. Requires initialization of ChatState with a processor.

```python
from liquid_audio import LFMModality, ChatState

chat = ChatState(processor)
chat.new_turn("user")
chat.add_text("Hello")  # Adds TEXT tokens

# Check modality
for i, mod in enumerate(chat.modality_flag[0]):
    if mod == LFMModality.TEXT:
        print(f"Token {i} is text")
    elif mod == LFMModality.AUDIO_IN:
        print(f"Token {i} is input audio")
    elif mod == LFMModality.AUDIO_OUT:
        print(f"Token {i} is output audio")
```

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

### Get Sample from LFM2DataLoader

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-loader.md

Access a single sample from the LFM2DataLoader by its index. The sample is padded to the specified context length. Note that audio features are not padded in time dimension and are handled by the collator.

```python
dataset = LFM2DataLoader("data/preprocessed_train")
row = dataset[0]

print(f"Text shape: {row.text.shape}")           # (1, 4096)
print(f"Audio in shape: {row.audio_in.shape}")   # (128, variable)
print(f"Audio in lens: {row.audio_in_lens.shape}")  # (num_audio,)
print(f"Audio out shape: {row.audio_out.shape}") # (8, variable)
```

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

### LFM2DataLoader Instance Methods

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-loader.md

Provides methods to get the size of the dataset and load individual samples. __getitem__ loads and returns a single sample, padded to context_length, and can throw a ValueError if the sample exceeds context_length. Specific padding behaviors are defined for text tokens, modality flags, and supervision masks.

```APIDOC
## LFM2DataLoader Instance Methods

### __len__

#### Description
Get the number of samples in the dataset.

#### Returns
- `int` - Total number of samples

### __getitem__

#### Description
Load and return a single sample, padded to context_length.

#### Parameters
- **idx** (int) - Yes - Sample index

#### Returns
- `LFM2AudioRow` - Single padded sample

#### Throws
- `ValueError` if sample exceeds context_length

#### Padding Behavior:

- Text tokens are padded with 0s
- Modality flags are padded with `LFMModality.TEXT` (1)
- Supervision mask is padded with False
- Audio features (audio_in, audio_out) are NOT padded in time dimension (concatenated per-batch in collator)

#### Example:
```python
dataset = LFM2DataLoader("data/preprocessed_train")
row = dataset[0]

print(f"Text shape: {row.text.shape}")           # (1, 4096)
print(f"Audio in shape: {row.audio_in.shape}")   # (128, variable)
print(f"Audio in lens: {row.audio_in_lens.shape}")  # (num_audio,)
print(f"Audio out shape: {row.audio_out.shape}") # (8, variable)
```
```

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

### Example Usage of LFM2AudioModelOutput

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-types.md

Demonstrates how to access and print loss values from the LFM2AudioModelOutput object after a model forward pass. Assumes `lfm2_collator` and `model` are defined and `row1`, `row2` are sample data.

```python
batch = lfm2_collator([row1, row2])
output = model(batch)
print(f"Loss: {output.loss.item():.4f}")
print(f"Text loss: {output.text_loss.item():.4f}")
print(f"Audio loss: {output.audio_loss.item():.4f}")
```

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

### Instantiate LFM2AudioModel

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/lfm2-audio-model.md

Demonstrates how to instantiate the LFM2AudioModel, typically loaded via `from_pretrained`.

```python
from liquid_audio import LFM2AudioModel
from liquid_audio.model.lfm2_audio import LFM2AudioConfig

# Typically loaded via from_pretrained instead of direct instantiation
model = LFM2AudioModel.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
```

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

### Run Training Script

Source: https://github.com/liquid4all/liquid-audio/blob/main/README.md

Initiates the training process using a preprocessed dataset. This is used for finetuning models.

```bash
python -m examples.train
```

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

### new_turn

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/processor.md

Starts a new conversation turn, specifying the role (system, user, or assistant) for that turn.

```APIDOC
## new_turn

### Description
Starts a new conversation turn, specifying the role (system, user, or assistant) for that turn.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **role** (Literal["system", "user", "assistant"]) - Required - Role for the turn

### Request Example
```python
chat.new_turn("system")
chat.add_text("You are a helpful assistant.")
chat.end_turn()

chat.new_turn("user")
chat.add_text("What is 2+2?")
chat.end_turn()
```

### Response
None

#### Success Response (200)
None

#### Response Example
None
```

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

### Add Text to Chat Turn

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/processor.md

Add a text segment to the current turn in the conversation. Ensure a turn has been started with `new_turn` before adding text.

```python
chat.new_turn("user")
chat.add_text("What time is it?")
chat.end_turn()
```

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

### Initialize LFM2AudioProcessor from Pretrained

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/processor.md

Recommended way to load the processor. Loads from a Hugging Face Hub model ID and sets it to evaluation mode.

```python
from liquid_audio import LFM2AudioProcessor

# Load from pretrained (recommended)
processor = LFM2AudioProcessor.from_pretrained(
    "LiquidAI/LFM2.5-Audio-1.5B"
).eval()
```

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

### Data Preparation Workflow: Step 3 - Run Preprocessing

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-mapper.md

Execute the preprocessing step using the configured mapper and data generator. Specify the output path and maximum context length.

```python
from liquid_audio.data.preprocess import preprocess_dataset

preprocess_dataset(
    data=my_dataset_generator(),
    output_path="data/preprocessed_train",
    mapper=mapper,
    max_context_length=4096,
)
```

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

### Start New Chat Turn

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/processor.md

Initiates a new turn in the conversation, specifying the role (system, user, or assistant). Use this before adding content for a new participant or role.

```python
chat.new_turn("system")
chat.add_text("You are a helpful assistant.")
chat.end_turn()

chat.new_turn("user")
chat.add_text("What is 2+2?")
chat.end_turn()
```

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

### Prepare and Train Audio Model

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/README.md

This snippet demonstrates the initial steps of preparing data using LFM2AudioProcessor and LFM2AudioChatMapper, followed by training the model with LFM2DataLoader and Trainer. Ensure data is loaded and mapped correctly before initiating training.

```python
processor = LFM2AudioProcessor.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
mapper = LFM2AudioChatMapper(processor)

def my_dataset():
    for sample in load_my_data():
        yield [ChatMessage(role="user", content=[TextSegment(...)])]

preprocess_dataset(my_dataset(), "data/train", mapper)

train_data = LFM2DataLoader("data/train")
trainer = Trainer(train_data=train_data, max_steps=10000)
trainer.train()
```

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

### LFM2AudioModel Initialization

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/configuration.md

Initialize the LFM2AudioModel using `from_pretrained`. Specify the model repository ID, Git revision, data type, and device.

```python
model = LFM2AudioModel.from_pretrained(
    "LiquidAI/LFM2.5-Audio-1.5B",
    revision=None,             # Git revision
    dtype=torch.bfloat16,      # Model dtype
    device="cuda",             # Device
)
```

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

### LFM2AudioModel Constructor

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/lfm2-audio-model.md

Initializes the LFM2AudioModel. It's recommended to use `from_pretrained` for loading models.

```APIDOC
## LFM2AudioModel Constructor

### Description
Initializes the LFM2AudioModel with a configuration object.

### Method
__init__

### Parameters
#### Parameters
- **conf** (`LFM2AudioConfig`) - Required - Configuration dataclass containing all model hyperparameters

### Example
```python
from liquid_audio import LFM2AudioModel
from liquid_audio.model.lfm2_audio import LFM2AudioConfig

# Typically loaded via from_pretrained instead of direct instantiation
# model = LFM2AudioModel(LFM2AudioConfig(...))
```
```

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

### LFM2AudioProcessor Initialization

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/configuration.md

Initialize the LFM2AudioProcessor using `from_pretrained`. Specify the model repository ID, Git revision, and target device.

```python
processor = LFM2AudioProcessor.from_pretrained(
    "LiquidAI/LFM2.5-Audio-1.5B",
    revision="main",           # Git revision
    device="cuda",             # Device placement
)
```

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

### Distributed Training - Single Machine, Multiple GPUs (CLI)

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Launches distributed training on a single machine with multiple GPUs using the `accelerate launch` command. This requires specifying the training script and relevant arguments like batch size and max steps.

```bash
accelerate launch training_script.py --batch-size 32 --max-steps 10000
```

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

### Trainer Configuration

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/configuration.md

Configure the Trainer with model ID, datasets, optimizer parameters (learning rate, betas, weight decay), schedule (min ratio, max steps, warmup steps), data loading (batch size, workers), logging, saving, and validation intervals, and output directory.

```python
trainer = Trainer(
    model_id="LiquidAI/LFM2.5-Audio-1.5B",
    train_data=train_dataset,
    val_data=val_dataset,
    # Optimizer
    lr=3e-5,
    betas=(0.9, 0.95),
    weight_decay=0.1,
    # Schedule
    min_ratio=0.1,
    max_steps=10000,
    warmup_steps=100,
    # Data
    batch_size=16,
    dataloader_num_workers=0,
    # Logging
    logging_interval=10,
    save_interval=500,
    val_interval=100,
    output_dir="checkpoints",
)
```

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

### Resume Training from Checkpoint

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Resumes training from a previously saved checkpoint. It loads the optimizer and scheduler states using `accelerator.load_state` and then initializes the Trainer with the `max_steps` set to the desired end point. Training will automatically continue from the loaded step.

```python
from accelerate import Accelerator

accelerator = Accelerator()

# Load checkpoint state
accelerator.load_state("checkpoints/my_model/checkpoint-5000")

# Trainer will resume from step 5000
trainer = Trainer(
    train_data=train_dataset,
    max_steps=20000,  # Will train from step 5000 to 20000
    output_dir="checkpoints/my_model",
)

trainer.train()
```

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

### Data Preparation Workflow: Step 4 - Load in Training

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-mapper.md

Load the preprocessed data using LFM2DataLoader and prepare it for training with a DataLoader and collator.

```python
from liquid_audio.data.dataloader import LFM2DataLoader, lfm2_collator
from torch.utils.data import DataLoader

train_loader = DataLoader(
    LFM2DataLoader("data/preprocessed_train", context_length=4096),
    batch_size=16,
    collate_fn=lfm2_collator,
    num_workers=4,
)

for batch in train_loader:
    # batch is LFM2AudioModelInput ready for model
    output = model(batch)
```

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

### TensorBoard Integration for Monitoring

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Enables monitoring of training progress using TensorBoard. The trainer automatically logs metrics to the specified `output_dir`. You can launch TensorBoard from the command line to visualize these logs.

```bash
tensorboard --logdir=checkpoints/my_model
```

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

### Instantiate LFM2AudioDetokenizer Directly

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/detokenizer.md

Directly instantiate LFM2AudioDetokenizer with a configuration. This is an advanced usage; typically, it's accessed via the processor's audio_detokenizer property. Manual weight loading is required for direct instantiation.

```python
from transformers import Lfm2Config
from liquid_audio.detokenizer import LFM2AudioDetokenizer

# Usually accessed via processor instead:
# detokenizer = processor.audio_detokenizer

# Direct usage (advanced):
config = Lfm2Config.from_pretrained("path/to/config.json")
detokenizer = LFM2AudioDetokenizer(config)
```

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

### Initialize ChatState

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/processor.md

Initialize ChatState with a processor. Optionally configure the number of codebooks and data type for audio features.

```python
from liquid_audio import ChatState, LFM2AudioProcessor

processor = LFM2AudioProcessor.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
chat = ChatState(processor)
```

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

### Run LFM2-Audio Training Loop

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Initiate the main training loop using the train() method. This method manages the entire training process, including steps, logging, saving, and validation.

```python
trainer = Trainer(
    train_data=train_dataset,
    max_steps=10000,
    save_interval=500,
    logging_interval=10,
)

# This will run for 10000 steps, saving every 500 steps
trainer.train()

# Checkpoints saved to output_dir/checkpoint-*
# Final model saved to output_dir/final/
```

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

### Initialize LFM2DataLoader

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-loader.md

Instantiate the LFM2DataLoader to load preprocessed training samples. Specify the dataset path and optionally the context length for padding.

```python
from liquid_audio.data.dataloader import LFM2DataLoader

train_dataset = LFM2DataLoader(
    "data/preprocessed_train",
    context_length=4096
)

print(f"Dataset size: {len(train_dataset)}")
```

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

### Initialize LFM2AudioChatMapper

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-mapper.md

Instantiate the LFM2AudioChatMapper with a pre-trained processor and specify the number of audio codebooks.

```python
from liquid_audio import LFM2AudioProcessor
from liquid_audio.data.mapper import LFM2AudioChatMapper

processor = LFM2AudioProcessor.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
mapper = LFM2AudioChatMapper(processor, codebooks=8)
```

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

### Instantiate ISTFT with Custom Parameters

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/detokenizer.md

Create an ISTFT instance with specified FFT size, hop length, window length, and padding mode. The default configuration (n_fft=1280, hop_length=320, win_length=1280) is suitable for generating 24kHz audio.

```python
from liquid_audio.detokenizer import ISTFT

istft = ISTFT(n_fft=1280, hop_length=320, win_length=1280, padding="same")
spec = torch.randn(1, 641, 100, dtype=torch.complex64)  # complex spectrogram
waveform = istft(spec)
```

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

### Fine-tuning Imports

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/README.md

This snippet includes necessary imports for fine-tuning the liquid-audio model. It covers data types, data mapping, dataset preprocessing, data loading, and the trainer class.

```python
from liquid_audio.data.types import ChatMessage, TextSegment
from liquid_audio.data.mapper import LFM2AudioChatMapper
from liquid_audio.data.preprocess import preprocess_dataset
from liquid_audio.data.dataloader import LFM2DataLoader
from liquid_audio.trainer import Trainer
```

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

### ChatState Constructor

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/processor.md

Initializes a new ChatState instance. It requires an LFM2AudioProcessor and can be configured with the number of audio codebooks and the data type for audio features.

```APIDOC
## ChatState Constructor

### Description
Initializes a new ChatState instance. It requires an LFM2AudioProcessor and can be configured with the number of audio codebooks and the data type for audio features.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **processor** (LFM2AudioProcessor) - Required - Processor for text and audio handling
- **codebooks** (int) - Optional - Number of audio codebooks, defaults to `8`
- **dtype** (torch.dtype) - Optional - Data type for audio features, defaults to `torch.bfloat16`

### Request Example
```python
from liquid_audio import ChatState, LFM2AudioProcessor

processor = LFM2AudioProcessor.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
chat = ChatState(processor)
```

### Response
None

#### Success Response (200)
None

#### Response Example
None
```

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

### Create AudioSegment Instance

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-types.md

Instantiate an AudioSegment by loading raw audio bytes from a file. Ensure the audio format is supported by torchaudio.

```python
from liquid_audio.data.types import AudioSegment

# Load audio from file
with open("question.wav", "rb") as f:
    audio_bytes = f.read()

segment = AudioSegment(audio=audio_bytes)
```

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

### Load LFM2AudioProcessor from Pretrained with Device Specification

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/processor.md

Loads the processor from a Hugging Face Hub model ID or a local path, allowing specification of the target device.

```python
processor = LFM2AudioProcessor.from_pretrained(
    "LiquidAI/LFM2.5-Audio-1.5B",
    device="cuda"
)
```

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

### Load Pretrained LFM2AudioModel

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/lfm2-audio-model.md

Loads a pretrained LFM2-Audio model from Hugging Face Hub or a local path. Specify revision, dtype, and device as needed.

```python
from liquid_audio import LFM2AudioModel

# Load from Hugging Face Hub
model = LFM2AudioModel.from_pretrained(
    "LiquidAI/LFM2.5-Audio-1.5B",
    device="cuda",
    dtype=torch.bfloat16
).eval()
```

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

### Create ChatMessage Instances

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-types.md

Instantiate ChatMessage objects for different roles (system, user, assistant). Content can be text, audio, or interleaved segments.

```python
from liquid_audio.data.types import ChatMessage, TextSegment, AudioSegment

# System message
system_msg = ChatMessage(
    role="system",
    content=[TextSegment(text="You are a helpful assistant.")]
)

# User message with audio
user_msg = ChatMessage(
    role="user",
    content=[AudioSegment(audio=wav_bytes)]
)

# Assistant response
assistant_msg = ChatMessage(
    role="assistant",
    content=[TextSegment(text="Sure, let me help!")]
)
```

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

### Generation Configuration

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/configuration.md

Configure generation parameters for sequential and interleaved generation, including maximum new tokens and sampling temperatures/top-k values for text and audio.

```python
for token in model.generate_sequential(
    **chat,
    max_new_tokens=512,
    text_temperature=None,     # Sampling temperature
    text_top_k=None,           # Top-k filtering
    audio_temperature=1.0,
    audio_top_k=4,
):
    ...
```

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

### LFM2AudioProcessor Constructor

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/processor.md

Initializes the LFM2AudioProcessor with paths to tokenizers, audio processing configurations, and optional model weights. It manages the core components for handling both text and audio data within LFM2-Audio models.

```APIDOC
## LFM2AudioProcessor Constructor

### Description
Initializes the LFM2AudioProcessor with paths to tokenizers, audio processing configurations, and optional model weights. It manages the core components for handling both text and audio data within LFM2-Audio models.

### Parameters
#### Path Parameters
- **text_tokenizer_path** (str) - Required - Path to HF tokenizer directory
- **audio_processor_config** (PreprocessorConfig) - Required - Audio preprocessor configuration (log-mel spectrogram parameters)
- **mimi_weights_path** (str | None) - Optional - Path to Mimi codec weights for audio encoding
- **detokenizer_path** (str | None) - Optional - Path to LFM2 audio detokenizer weights
- **name** (str | None) - Optional - Name identifier for the processor (e.g., model ID)
```

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

### Data Preparation Workflow: Step 1 - Collect Raw Data

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-mapper.md

Organize your raw data into an iterable of conversation lists, where each list contains ChatMessage objects.

```python
def my_dataset_generator():
    # Load your data
    for sample in my_raw_dataset:
        messages = convert_sample_to_messages(sample)
        yield messages
```

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

### LFM2AudioModel.generate_sequential

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/lfm2-audio-model.md

Generates text and audio tokens sequentially. The model determines the modality switch.

```APIDOC
## LFM2AudioModel.generate_sequential

### Description
Generates text and audio tokens sequentially. The model decides when to switch from text to audio via `<|audio_start|>` token. Suitable for non-conversational tasks like ASR or TTS.

### Method
generate_sequential

### Parameters
#### Path Parameters
- **text** (`torch.Tensor`) - Required - Text token IDs, shape (1, L)
- **audio_in** (`torch.Tensor`) - Required - Log-mel spectrogram features, shape (128, T)
- **audio_in_lens** (`torch.Tensor`) - Required - Length of each audio input, shape (B,)
- **audio_out** (`torch.Tensor`) - Required - Previous audio output tokens, shape (codebooks, T)
- **modality_flag** (`torch.Tensor`) - Required - Modality indicator per token, shape (1, L)

#### Query Parameters
- **max_new_tokens** (`int`) - Optional - Maximum tokens to generate. Defaults to `20`.
- **text_temperature** (`float | None`) - Optional - Sampling temperature for text (None = greedy). Defaults to `None`.
- **text_top_k** (`int | None`) - Optional - Top-k sampling for text (None = disabled). Defaults to `None`.
- **audio_temperature** (`float | None`) - Optional - Sampling temperature for audio (None = greedy). Defaults to `None`.
- **audio_top_k** (`int | None`) - Optional - Top-k sampling for audio (None = disabled). Defaults to `None`.

### Yields
`torch.Tensor` - Individual text tokens (shape: [1]) or audio frame tokens (shape: [8])

### Example
```python
import torch
import torchaudio
from liquid_audio import LFM2AudioModel, LFM2AudioProcessor, ChatState

processor = LFM2AudioProcessor.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
model = LFM2AudioModel.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B").eval()

chat = ChatState(processor)
chat.new_turn("system")
chat.add_text("Perform ASR.")
chat.end_turn()

chat.new_turn("user")
wav, sr = torchaudio.load("audio.wav")
chat.add_audio(wav, sr)
chat.end_turn()

chat.new_turn("assistant")
for t in model.generate_sequential(**chat, max_new_tokens=512):
    if t.numel() == 1:
        print(processor.text.decode(t), end="", flush=True)
```
```

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

### Light-weight Fine-tuning Trainer Configuration

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/configuration.md

Configure the Trainer for light-weight fine-tuning with a higher learning rate, small batch size, fewer steps, less regularization, and fewer dataloader workers.

```python
trainer = Trainer(
    train_data=train_dataset,
    lr=1e-4,                # Higher LR for small data
    batch_size=4,
    max_steps=2000,
    warmup_steps=100,
    weight_decay=0.05,      # Less regularization
    dataloader_num_workers=2,
)
```

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

### LFM2AudioModel.from_pretrained

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/lfm2-audio-model.md

Loads a pretrained LFM2-Audio model from Hugging Face Hub or a local path.

```APIDOC
## LFM2AudioModel.from_pretrained

### Description
Loads a pretrained LFM2-Audio model from Hugging Face Hub or a local path.

### Method
from_pretrained

### Parameters
#### Path Parameters
- **repo_id** (`str | Path`) - Required - HF Hub model ID (e.g., "LiquidAI/LFM2.5-Audio-1.5B") or local path to checkpoint directory

#### Query Parameters
- **revision** (`str | None`) - Optional - Git revision (branch/tag) to load from HF Hub
- **dtype** (`torch.dtype`) - Optional - Target data type for model parameters. Defaults to `torch.bfloat16`.
- **device** (`torch.device | str`) - Optional - Device to load model onto ("cuda", "cpu", or torch.device). Defaults to `"cuda"`.

### Returns
`Self` - Initialized and loaded LFM2AudioModel instance

### Throws
`FileNotFoundError` - if config.json not found in repo

### Example
```python
from liquid_audio import LFM2AudioModel

# Load from Hugging Face Hub
model = LFM2AudioModel.from_pretrained(
    "LiquidAI/LFM2.5-Audio-1.5B",
    device="cuda",
    dtype=torch.bfloat16
).eval()
```
```

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

### Sequential Generation with LFM2AudioModel

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/lfm2-audio-model.md

Generates text and audio tokens sequentially using the `generate_sequential` method. The model switches between text and audio based on the `<|audio_start|>` token. Suitable for ASR or TTS tasks.

```python
import torch
import torchaudio
from liquid_audio import LFM2AudioModel, LFM2AudioProcessor, ChatState

processor = LFM2AudioProcessor.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
model = LFM2AudioModel.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B").eval()

chat = ChatState(processor)
chat.new_turn("system")
chat.add_text("Perform ASR.")
chat.end_turn()

chat.new_turn("user")
wav, sr = torchaudio.load("audio.wav")
chat.add_audio(wav, sr)
chat.end_turn()

chat.new_turn("assistant")
for t in model.generate_sequential(**chat, max_new_tokens=512):
    if t.numel() == 1:
        print(processor.text.decode(t), end="", flush=True)
```

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

### Multi-GPU Training with DataLoader

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-loader.md

Configure DataLoader for distributed training using DistributedSampler. This requires initializing the distributed process group and setting up the sampler with world size and rank.

```python
from torch.utils.data import DataLoader, DistributedSampler
from liquid_audio.data.dataloader import LFM2DataLoader, lfm2_collator
import torch.distributed as dist

# Initialize distributed training
dist.init_process_group("nccl")

dataset = LFM2DataLoader("data/my_dataset/train", context_length=4096)

sampler = DistributedSampler(
    dataset,
    num_replicas=dist.get_world_size(),
    rank=dist.get_rank(),
    shuffle=True,
)

train_loader = DataLoader(
    dataset,
    batch_size=16,
    sampler=sampler,
    collate_fn=lfm2_collator,
    num_workers=4,
    pin_memory=True,
)

# Training loop
model = LFM2AudioModel.from_pretrained("LiquidAI/LFM2.5-Audio-1.5B")
model.train()

for batch in train_loader:
    batch = batch.to("cuda")
    output = model(batch)
    loss = output.loss
    loss.backward()
    optimizer.step()
```

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

### Quick Validation Configuration

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Configuration for rapid testing and validation. It sets a moderate number of `max_steps`, saves checkpoints infrequently (`save_interval`), logs frequently (`logging_interval`), and validates often (`val_interval`).

```python
trainer = Trainer(
    train_data=train_dataset,
    val_data=val_dataset,
    max_steps=1000,
    save_interval=10000,  # Save rarely
    logging_interval=1,   # Log frequently
    val_interval=100,     # Validate often
    output_dir="checkpoints/quick_test",
)

trainer.train()
```

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

### LFM2DataLoader Constructor

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-loader.md

Initializes the LFM2DataLoader, which loads preprocessed training samples from disk and pads them to a fixed context length. It can throw a ValueError if any sample exceeds the specified context length.

```APIDOC
## LFM2DataLoader Constructor

### Description
Initializes the LFM2DataLoader, which loads preprocessed training samples from disk and pads them to a fixed context length. It can throw a ValueError if any sample exceeds the specified context length.

### Parameters
#### Path Parameters
- **dataset_path** (str) - Yes - Path to preprocessed dataset (from `preprocess_dataset`)
#### Query Parameters
- **context_length** (int) - No - `4096` - Fixed sequence length to pad/trim to

### Throws
- `ValueError` if any sample exceeds context_length

### Example
```python
from liquid_audio.data.dataloader import LFM2DataLoader

train_dataset = LFM2DataLoader(
    "data/preprocessed_train",
    context_length=4096
)

print(f"Dataset size: {len(train_dataset)}")
```
```

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

### Trainer Constructor

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Initializes the Trainer class with various configuration options for fine-tuning LFM2-Audio models.

```APIDOC
## Trainer

High-level trainer class for fine-tuning LFM2-Audio models with distributed training support, mixed precision, checkpointing, and validation.

### Constructor

```python
def __init__(
    self,
    model_id: str = "LiquidAI/LFM2.5-Audio-1.5B",
    train_data: LFM2DataLoader | None = None,
    val_data: LFM2DataLoader | None = None,
    lr: float = 3e-5,
    betas: tuple[float, float] = (0.9, 0.95),
    weight_decay: float = 0.1,
    min_ratio: float = 0.1,
    max_steps: int = 1000,
    warmup_steps: int = 100,
    batch_size: int = 16,
    dataloader_num_workers: int = 0,
    logging_interval: int = 10,
    save_interval: int = 500,
    val_interval: int = 100,
    output_dir: str = "tmp",
) -> None
```

#### Parameters

- **model_id** (`str`, Optional, Default: `
```

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

### PreprocessorConfig Configuration

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/types.md

Configuration for the audio preprocessor, defining parameters for log-mel spectrogram generation.

```python
from dataclasses import dataclass

@dataclass(kw_only=True)
class PreprocessorConfig:
    sample_rate: int
    normalize: str
    window_size: float
    window_stride: float
    window: str
    features: int
    n_fft: int
    log: bool
    frame_splicing: int
    dither: float
    pad_to: int
    pad_value: float
```

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

### Create InterleavedSegment Instance

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/data-types.md

Instantiate an InterleavedSegment with both text and raw audio bytes.

```python
from liquid_audio.data.types import InterleavedSegment

segment = InterleavedSegment(
    text="Here's a song I wrote.",
    audio=audio_bytes
)
```

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

### Data Loader Configuration

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/configuration.md

Configure the LFM2DataLoader with the dataset path and context length. Also configure the PyTorch DataLoader with batch size, collate function, number of workers, and memory pinning.

```python
dataset = LFM2DataLoader(
    "data/preprocessed",
    context_length=4096,    # Sequence length
)

loader = DataLoader(
    dataset,
    batch_size=16,
    collate_fn=lfm2_collator,
    num_workers=4,
    pin_memory=True,
)
```

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

### Distributed Training - Single Machine, Multiple GPUs (Programmatic)

Source: https://github.com/liquid4all/liquid-audio/blob/main/_autodocs/api-reference/trainer.md

Initiates distributed training programmatically on a single machine. The `Trainer` class, when used with `accelerate`, automatically handles the distribution across available GPUs. No explicit distribution configuration is needed in the script itself.

```python
from accelerate import Accelerator
from liquid_audio.trainer import Trainer

# Accelerate handles distribution automatically
trainer = Trainer(
    train_data=train_dataset,
    batch_size=32,
    max_steps=10000,
)

trainer.train()
```