### Verify Installation and Run Tests

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/CONTRIBUTING.md

Verify the successful installation of the package by running a simple Python command and then execute the full test suite.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline; print('Success!')
```

```bash
pytest
```

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

### Full Data Preparation Example

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Run the full data preparation example with MLS and a FLEURS subset, which takes approximately 90 minutes. You can specify a name and version for the processed data.

```bash
python workflows/dataprep/hf_dataset_ingestion_example.py run_full /path/to/output/dir \
    --name my_asr_data \
    --version 1
```

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

### Install omnilingual-asr with data dependencies

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Install the omnilingual-asr package with the necessary data libraries using pip or uv.

```bash
pip install omnilingual-asr[data]
```

```bash
uv add "omnilingual-asr[data]"
```

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

### Quick Start ASR Inference

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/inference/README.md

Initialize the ASRInferencePipeline with a model card and transcribe a single audio file.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline
pipeline = ASRInferencePipeline(model_card="omniASR_CTC_1B_v2")
transcriptions = pipeline.transcribe(["/path/to/audio1.flac"], batch_size=1)
print(transcriptions[0])
```

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

### Wav2Vec2 ASR Training Configuration Example

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/recipes/wav2vec2/asr/README.md

Example configuration snippet for Wav2Vec2 ASR training, focusing on dataset and optimizer settings. Adjust gradient accumulation if encountering Out-of-Memory errors.

```yaml
dataset:
  (...) 
  asr_task_config:
    max_audio_len: 960_000      # 60s at 16kHz
    max_num_elements: 7_680_000 # maximum of eight 60s samples, or more samples at lower lengths

optimizer:
  config:
    lr: 1e-05

trainer:
  grad_accumulation:
    num_batches: 4 # Increase gradient accumulation if running OOM during training, we use 32 GPUs for 300M, 64 GPUs for 1B and 96 GPUs for 3B

regime:
  num_steps: 5_000
```

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

### Install Omnilingual ASR with Data Support

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/README.md

Installs the omnilingual-asr package with the necessary dependencies for handling datasets.

```bash
pip install "omnilingual-asr[data]"
```

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

### Install omnilingual-asr using pip or uv

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/README.md

Install the omnilingual-asr package using either pip or uv. Ensure you have libsndfile installed for audio support.

```bash
pip install omnilingual-asr
```

```bash
uv add omnilingual-asr
```

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

### Run Full Dataset Ingestion Example

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Performs a comprehensive data ingestion using a subset of MLS and FLEURS languages. This process takes approximately 90 minutes.

```bash
python hf_dataset_ingestion_example.py run_full /path/to/output/dir
```

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

### Install omnilingual-asr Package

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Install the omnilingual-asr package using pip or uv. Use the '[data]' extra for data preparation dependencies.

```bash
# Basic installation
pip install omnilingual-asr
```

```bash
# With data preparation dependencies
pip install "omnilingual-asr[data]"
```

```bash
# Using uv
uv add omnilingual-asr
```

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

### Example Parquet Dataset Directory Structure

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Illustrates the partitioned directory structure for ASR datasets stored in parquet files, organized by corpus, split, and language.

```bash
dataset_root_dir/version=0/
├── corpus=mls/
│   ├── split=train/
│   │   ├── language=deu_Latn/
│   │   │   └── part-*.parquet
│   │   └── language=fra_Latn/
│   │       └── part-*.parquet
│   └── split=dev/
│       └── ...
└── corpus=fleurs/
    └── ...

```

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

### Run Short Dataset Ingestion Example

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Executes a quick data ingestion test using only English and French from FLEURS. Expect completion in approximately 5-10 minutes.

```bash
python hf_dataset_ingestion_example.py run_short /path/to/output/dir
```

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

### transcribe_with_context (Zero-Shot Inference)

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Explains how to perform zero-shot transcription for unseen languages using context examples with the `omniASR_LLM_7B_ZS` model.

```APIDOC
## transcribe_with_context (Zero-Shot Inference)

### Description
The `transcribe_with_context` method enables zero-shot transcription for unseen languages by providing audio-text context examples. This is designed for the `omniASR_LLM_7B_ZS` model, which learns transcription patterns from provided examples.

### Method
`ASRInferencePipeline.transcribe_with_context(inp: Union[List[str], List[Dict], List[bytes]], context_examples: List[List[ContextExample]], batch_size: int = 1)`

### Parameters
#### transcribe_with_context Method Parameters
- **inp** (Union[List[str], List[Dict], List[bytes]]) - Required - A list of audio inputs to transcribe.
- **context_examples** (List[List[ContextExample]]) - Required - A list where each element is a list of `ContextExample` objects for the corresponding input audio. Each `ContextExample` should contain an audio path and its transcription.
- **batch_size** (int) - Optional - The batch size for inference. Recommended to be 1 for zero-shot due to memory requirements.

### Request Example (Initialization)
```python
from omnilingual_asr.models.inference.pipeline import (
    ASRInferencePipeline,
    ContextExample
)

# Initialize zero-shot pipeline
pipeline = ASRInferencePipeline(model_card="omniASR_LLM_7B_ZS")
```

### Request Example (Zero-Shot Transcription)
```python
# Define context examples
context_examples = [
    ContextExample("/path/to/context1.wav", "transcription of context audio 1"),
    ContextExample("/path/to/context2.wav", "transcription of context audio 2"),
    ContextExample("/path/to/context3.flac", "transcription of context audio 3")
]

# Transcribe new audio using context examples
test_audio = ["/path/to/test_audio1.wav", "/path/to/test_audio2.wav"]
transcriptions = pipeline.transcribe_with_context(
    inp=test_audio,
    context_examples=[context_examples, context_examples],  # One list of examples per input audio
    batch_size=1
)

print(f"Zero-shot transcription: {transcriptions[0]}")
```

### Response Example (Zero-Shot Transcription)
```json
["transcribed text following context patterns"]
```
```

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

### Verify Dataloader Functionality

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Verify the dataloader functionality by running the dataloader example. Specify the dataset path, split, and number of iterations.

```bash
python -m workflows.dataprep.dataloader_example \
    --dataset_path="/path/to/dataset/version=0" \
    --split="train" \
    --num_iterations=10
```

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

### Install Package in Development Mode

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/CONTRIBUTING.md

Install the package in editable mode with development and data dependencies. This allows for direct code modifications and testing.

```bash
pip install -e ".[dev,data]"
```

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

### Check Supported Languages

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Demonstrates how to get the total count of supported languages and check if a specific language code is present in the list.

```python
print(f"Total supported languages: {len(supported_langs)}")
```

```python
language = "eng_Latn"
if language in supported_langs:
    print(f"{language} is supported!")
```

```python
sample_langs = [
    "eng_Latn",    # English (Latin)
    "cmn_Hans",    # Mandarin Chinese (Simplified)
    "cmn_Hant",    # Mandarin Chinese (Traditional)
    "deu_Latn",    # German (Latin)
    "fra_Latn",    # French (Latin)
    "spa_Latn",    # Spanish (Latin)
    "arb_Arab",    # Arabic (Arabic script)
    "hin_Deva",    # Hindi (Devanagari)
    "jpn_Jpan",    # Japanese
    "rus_Cyrl",    # Russian (Cyrillic)
]
print(f"Sample languages: {sample_langs}")
```

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

### Zero-Shot LLM Inference with Context

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/inference/README.md

Perform zero-shot inference on unseen languages using the omniASR_LLM_7B_ZS model with in-context audio/transcription pairs. Provide 1-10 examples; more examples generally improve performance. Maximum audio length is 60 seconds.

```python
from omnilingual_asr.models.inference.pipeline import (
    ASRInferencePipeline,
    ContextExample
)

pipeline = ASRInferencePipeline(model_card="omniASR_LLM_7B_ZS")

context_examples = [
    ContextExample("/path/to/context_audio1.wav", "Hello world"),
    ContextExample("/path/to/context_audio2.wav", "How are you today"),
    ContextExample("/path/to/context_audio3.flac", "Nice to meet you")
]

transcriptions = pipeline.transcribe_with_context(
    ["/path/to/test_audio.wav"],
    context_examples=[context_examples],
    batch_size=1
)

print(f"Transcription: {transcriptions[0]}")
```

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

### Initialize Zero-Shot ASR Inference Pipeline

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Initialize an ASRInferencePipeline for the Zero-Shot model, which supports few-shot learning for unseen languages. Best for low-resource languages with few examples. Available model is omniASR_LLM_7B_ZS.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

# Zero-Shot Model: Few-shot learning for unseen languages
# Best for: Low-resource languages with few examples
# Available: omniASR_LLM_7B_ZS
pipeline_zeroshot = ASRInferencePipeline(model_card="omniASR_LLM_7B_ZS")
```

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

### Zero-Shot Transcription with transcribe_with_context

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Enable zero-shot transcription for unseen languages using the `transcribe_with_context` method. Provide audio-text context examples to the `omniASR_LLM_7B_ZS` model. Context audio should be less than 30 seconds.

```python
from omnilingual_asr.models.inference.pipeline import (
    ASRInferencePipeline,
    ContextExample
)

# Initialize zero-shot pipeline
pipeline = ASRInferencePipeline(model_card="omniASR_LLM_7B_ZS")

# Define context examples (audio-text pairs from target language)
# Provide 1-10 examples; more examples generally improve performance
context_examples = [
    ContextExample("/path/to/context1.wav", "transcription of context audio 1"),
    ContextExample("/path/to/context2.wav", "transcription of context audio 2"),
    ContextExample("/path/to/context3.flac", "transcription of context audio 3"),
    # Context audio should be < 30 seconds for optimal performance
]

# Transcribe new audio using context examples
# Each input audio needs its own list of context examples
transcriptions = pipeline.transcribe_with_context(
    inp=["/path/to/test_audio1.wav", "/path/to/test_audio2.wav"],
    context_examples=[context_examples, context_examples],  # One per input
    batch_size=1  # Recommended for zero-shot due to memory requirements
)

print(f"Zero-shot transcription: {transcriptions[0]}")
# Output: Zero-shot transcription: transcribed text following context patterns
```

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

### Custom Dataset Asset Card Configuration

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Example YAML configuration for creating a custom dataset asset card. This allows registering custom datasets with the fairseq2 asset system. Reference the created asset card in your training configurations.

```yaml
# Save as: src/omnilingual_asr/cards/datasets/my_custom_dataset.yaml
name: my_custom_dataset
dataset_family: mixture_parquet_asr_dataset
dataset_config:
  data: /path/to/my/parquet/dataset/version=0
tokenizer_ref: omniASR_tokenizer_v1  # Use v2 tokenizer for v2 models

# After creating the asset card, reference it in training configs:
# dataset:
#   name: my_custom_dataset
#   asr_task_config:
#     max_audio_len: 960_000
#     max_num_elements: 7_680_000
```

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

### Zero-Shot Context ASR Batch Format

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/inference/README.md

Defines the Seq2SeqBatch structure for zero-shot context ASR. Includes context audio and text sequences within the 'example' dictionary.

```python
batch = Seq2SeqBatch(
    source_seqs=audio_tensor,           # [BS, T_audio, D_audio] - target audio
    source_seq_lens=audio_lengths,      # [BS] - actual audio lengths
    target_seqs=text_tensor,            # [BS, T_text] - target text tokens
    target_seq_lens=text_lengths,       # [BS] - actual text lengths
    example={
        "context_audio": [
            {"seqs": context_audio_1, "seq_lens": [audio_len_1]},  # Context audio 1 # List[Dict] - N context examples
            ...
            {"seqs": context_audio_BS, "seq_lens": [audio_len_BS]},  # BS Context audio
        ],
        "context_text": [
            {"seqs": context_text_1, "seq_lens": [text_len_1]},
            ...
            {"seqs": context_text_BS, "seq_lens": [text_len_BS]},   # BS Context text
        ]
    }
)
```

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

### Train CTC Model from W2V Encoder

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Use this command to train a CTC model from a W2V encoder, recommended for compute-constrained setups. Ensure the OUTPUT_DIR and config-file paths are correctly set.

```bash
python -m workflows.recipes.wav2vec2.asr $OUTPUT_DIR \
    --config-file workflows/recipes/wav2vec2/asr/configs/ctc-from-encoder-recommendation.yaml
```

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

### Language-Aware ASR Batch Format

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/inference/README.md

Defines the Seq2SeqBatch structure for language-aware ASR. Includes language codes in the 'example' dictionary for each sample.

```python
batch = Seq2SeqBatch(
    source_seqs=audio_tensor,           # [BS, T_audio, D_audio] - target audio
    source_seq_lens=audio_lengths,      # [BS] - actual audio lengths
    target_seqs=text_tensor,            # [BS, T_text] - target text tokens
    target_seq_lens=text_lengths,       # [BS] - actual text lengths
    example={
        "lang": ['mxs_Latn', ...]  # [BS] - language codes per sample
    }
)
```

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

### CTC Model Inference

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/inference/README.md

Utilize CTC models for parallel generation, offering faster throughput. These models do not support language conditioning or context examples.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

pipeline = ASRInferencePipeline(model_card="omniASR_CTC_3B_v2", device=None)

audio_files = ["/path/to/audio1.flac", "/path/to/audio2.wav"]
transcriptions = pipeline.transcribe(audio_files, batch_size=2)

for file_path, text in zip(audio_files, transcriptions):
    print(f"CTC transcription - {file_path}: {text}")
```

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

### Language-Conditioned LLM Inference

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/inference/README.md

Use LLM models with an optional language code to guide transcription towards a target language and script. This improves transcription quality.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

pipeline = Wav2Vec2InferencePipeline(model_card="omniASR_LLM_Unlimited_1B_v2")

audio_files = ["/path/to/russian_audio.wav", "/path/to/english_audio.flac", "/path/to/german_audio.wav"]

transcriptions = pipeline.transcribe(audio_files, lang=["rus_Cyrl", "eng_Latn", "deu_Latn"], batch_size=3)
```

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

### CLI for Training Workflows

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Shows how to use the command-line interface to run pre-configured training workflows, specifically fine-tuning a CTC model from an existing checkpoint.

```bash
# Set output directory for checkpoints and artifacts
export OUTPUT_DIR="/path/to/output/directory"

# Fine-tune CTC model from existing checkpoint
python -m workflows.recipes.wav2vec2.asr $OUTPUT_DIR \
    --config-file workflows/recipes/wav2vec2/asr/configs/ctc-finetune.yaml
```

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

### Run Wav2Vec2 ASR Training Recipe

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/recipes/wav2vec2/asr/README.md

Execute the Wav2Vec2 ASR training recipe. Ensure the output directory is set and specify the configuration file.

```bash
> cd omnilingual_asr
> export OUTPUT_DIR="/path/to/artifact/directory"
> python -m workflows.recipes.wav2vec2.asr $OUTPUT_DIR --config-file workflows/recipes/wav2vec2/asr/configs/ctc-finetune.yaml
```

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

### Initialize ASRInferencePipeline

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Initialize the ASRInferencePipeline for transcribing audio. The pipeline handles model loading, audio preprocessing, and inference. It supports automatic device detection (CUDA/CPU) and specified data types.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

# Initialize pipeline with a model card (auto-downloads on first use)
pipeline = ASRInferencePipeline(
    model_card="omniASR_LLM_Unlimited_7B_v2",
    device=None,  # Auto-detect CUDA or CPU
    dtype=torch.bfloat16
)
```

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

### ASRInferencePipeline Usage

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Demonstrates how to initialize and use the ASRInferencePipeline for transcribing audio files using different input formats and language conditioning.

```APIDOC
## ASRInferencePipeline Usage

### Description
The `ASRInferencePipeline` class is the primary interface for transcribing audio files. It handles model loading, audio preprocessing, and inference execution. The pipeline supports multiple audio input formats and automatic device selection.

### Method
`ASRInferencePipeline(model_card: str, device: Optional[str] = None, dtype: torch.dtype = torch.float32)`

### Parameters
#### Initialization Parameters
- **model_card** (str) - Required - The name of the model card to load (e.g., "omniASR_LLM_Unlimited_7B_v2").
- **device** (Optional[str]) - Optional - The device to use for inference (e.g., "cuda", "cpu"). If None, auto-detects CUDA.
- **dtype** (torch.dtype) - Optional - The data type for model weights (e.g., `torch.bfloat16`).

#### transcribe Method Parameters
- **audio_input** (Union[List[str], List[Dict], List[bytes]]) - Required - A list of audio inputs. Can be file paths, pre-decoded audio dictionaries, or raw audio bytes.
- **batch_size** (int) - Optional - The number of audio files to process in a batch. Defaults to 1.
- **lang** (Optional[List[str]]) - Optional - A list of language codes for language-conditioned transcription (e.g., ["eng_Latn", "deu_Latn"]).

### Request Example (Initialization)
```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline
import torch

pipeline = ASRInferencePipeline(
    model_card="omniASR_LLM_Unlimited_7B_v2",
    device=None,  # Auto-detect CUDA or CPU
    dtype=torch.bfloat16
)
```

### Request Example (Transcription)
```python
# Transcribe audio files
audio_files = ["/path/to/audio1.flac", "/path/to/audio2.wav"]
transcriptions = pipeline.transcribe(audio_files, batch_size=2)
print(transcriptions)

# Language-conditioned transcription
transcriptions_lang = pipeline.transcribe(
    audio_files,
    lang=["eng_Latn", "deu_Latn"],
    batch_size=2
)
print(transcriptions_lang)
```

### Response Example (Transcription)
```json
["transcribed text from audio 1", "transcribed text from audio 2"]
```
```

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

### Initialize LLM Unlimited ASR Inference Pipeline

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Initialize an ASRInferencePipeline for LLM Unlimited models, designed to transcribe audio of any length. Best for long-form audio like podcasts or lectures. Available models include omniASR_LLM_Unlimited_{300M,1B,3B,7B}_v2.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

# LLM Unlimited Models: Transcribe audio of any length
# Best for: Long-form audio (podcasts, meetings, lectures)
# Available: omniASR_LLM_Unlimited_{300M,1B,3B,7B}_v2
pipeline_unlimited = ASRInferencePipeline(model_card="omniASR_LLM_Unlimited_7B_v2")
```

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

### Quick Test Data Preparation

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Perform a quick test of the data preparation pipeline using 2 languages from FLEURS. This typically takes 5-10 minutes. Specify the output directory.

```bash
python workflows/dataprep/hf_dataset_ingestion_example.py run_short /path/to/output/dir
```

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

### Clone Omnilingual ASR Repository

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/CONTRIBUTING.md

Clone the project repository and navigate into the project directory. This is the first step for any contribution.

```bash
git clone https://github.com/facebookresearch/omnilingual-asr.git
cd omnilingual-asr
```

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

### Verify Dataloader with CLI

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Verifies dataset creation and dataloading using a command-line interface. This script scans files, organizes data, and iterates through batches.

```bash
python -m workflows.dataprep.dataloader_example \
--dataset_path="root_ds/all_asr/version=0" \
--split="train" \
--num_iterations=10
```

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

### Format Code and Lint

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/CONTRIBUTING.md

Format your code using isort and black, and then check for linting errors with mypy and flake8. This ensures code style consistency.

```bash
isort . && black .
mypy && flake8 .
```

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

### Initialize MixtureParquetAsrDataset and Reader

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Initializes the MixtureParquetAsrDataset from a path and creates a data reader for iterating over batches. Requires tokenizer, gangs, dtype, storage_config, and task_config.

```python
from omnilingual_asr.datasets.impl.mixture_parquet_asr_dataset import MixtureParquetAsrDataset

# Create dataset and reader
dataset = MixtureParquetAsrDataset.from_path(path=dataset_path, name="my_asr")
reader = dataset.create_reader(
    split="train",
    tokenizer=tokenizer,
    gangs=gangs,
    dtype=torch.float32,
    storage_config=storage_config,
    task_config=task_config,
)

# Iterate through batches
for batches in reader:
    for batch in batches:
        # batch.source_seqs: audio features [batch, time, features]
        # batch.target_seqs: text tokens [batch, seq_len]
        # batch.source_seq_lens: audio sequence lengths
        # batch.target_seq_lens: text sequence lengths
        pass
```

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

### Transcribe Audio from HuggingFace Dataset

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/inference/README.md

Load audio data from a HuggingFace dataset, format it for the pipeline, and transcribe using ASRInferencePipeline. Ensure correct dataset loading and column renaming.

```python
from datasets import load_dataset
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

# Load dataset
omni_dataset = load_dataset("facebook/omnilingual-asr-corpus", "lij_Latn", split="train", streaming=True)
batch = next(omni_dataset.iter(5))

# Renaming columns to match the pipeline's expected input
audio_data = [{"waveform": x["array"], "sample_rate": x["sampling_rate"]} 
              for x in batch["audio"]]

pipeline = ASRInferencePipeline(model_card="omniASR_LLM_1B_v2")
transcriptions = pipeline.transcribe(audio_data, batch_size=2)

for i, text in enumerate(transcriptions):
    print(f"Sample {i+1}: {text}")
```

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

### Run Test Suite

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/CONTRIBUTING.md

Execute the project's test suite to ensure all tests pass before submitting a pull request. This command runs tests specifically located in the 'tests/' directory.

```bash
pytest tests/
```

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

### Load Dataset and Run Inference

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/README.md

Loads a specific language subset from the omnilingual-asr-corpus dataset, processes audio data in batches, and performs speech-to-text transcription using the ASRInferencePipeline. Displays the ground truth and predicted transcriptions.

```python
from datasets import load_dataset
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

# Load dataset for a specific language (e.g., Ligurian)
omni_dataset = load_dataset("facebook/omnilingual-asr-corpus", "lij_Latn", split="train", streaming=True)
batch = next(omni_dataset.iter(5))

# Convert to pipeline input format
audio_data = [{"waveform": x["array"], "sample_rate": x["sampling_rate"]} 
              for x in batch["audio"]]

# Run inference
pipeline = ASRInferencePipeline(model_card="omniASR_LLM_7B_v2")
transcriptions = pipeline.transcribe(audio_data, batch_size=2)

# Display results
for i, (transcription, original_text) in enumerate(zip(transcriptions, batch["raw_text"]), 1):
    print(f"\n Sample {i}:")
    print(f"   Ground Truth: {original_text}")
    print(f"   Predicted:    {transcription}")
```

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

### Run Short Ingestion with Versioning

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Executes a quick data ingestion test with custom naming and versioning. This allows for tracking specific data generation runs.

```bash
python hf_dataset_ingestion_example.py run_short /path/to/output/dir --name my_asr_data --version 1
```

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

### Train LLM Model from W2V Encoder

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Command to train an LLM model from a W2V encoder. Specify the OUTPUT_DIR and the path to the LLM configuration file.

```bash
python -m workflows.recipes.wav2vec2.asr $OUTPUT_DIR \
    --config-file workflows/recipes/wav2vec2/asr/configs/llm-from-encoder.yaml
```

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

### MixtureParquetAsrDataset for Training

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Initializes and uses the MixtureParquetAsrDataset for efficient data loading from parquet files, supporting weighted sampling and streaming. It configures storage and task parameters, then creates a reader to iterate through batches of audio and text data.

```python
import torch
from fairseq2.data.tokenizers.hub import load_tokenizer
from fairseq2.gang import FakeGangs

from omnilingual_asr.datasets.impl.mixture_parquet_asr_dataset import MixtureParquetAsrDataset
from omnilingual_asr.datasets.storage.mixture_parquet_storage import MixtureParquetStorageConfig
from omnilingual_asr.datasets.tasks.asr_task import AsrTaskConfig

# Load tokenizer
tokenizer = load_tokenizer("omniASR_tokenizer_v1")

# Configure storage and task
storage_config = MixtureParquetStorageConfig(
    shuffle_window=1000,        # Shuffle buffer size
    sample_by="temperature",    # Sampling strategy: "uniform" or "temperature"
    temperature=0.5,            # Temperature for weighted sampling
)

task_config = AsrTaskConfig(
    max_audio_len=480_000,      # 30 seconds at 16kHz
    min_audio_len=16_000,       # 1 second minimum
    max_num_elements=3_840_000, # Maximum batch elements (audio samples)
    normalize_audio=True,       # Normalize audio waveforms
)

# Create dataset and reader
dataset = MixtureParquetAsrDataset.from_path(path="/path/to/parquet/dataset/version=0")
gangs = FakeGangs(device=torch.device("cuda"))

reader = dataset.create_reader(
    split="train",
    tokenizer=tokenizer,
    gangs=gangs,
    dtype=torch.float32,
    num_accumulate=1,
    storage_config=storage_config,
    task_config=task_config,
)

# Iterate through batches
for batch_group in reader:
    for batch in batch_group:
        # batch.source_seqs: audio features [batch_size, time, features]
        # batch.target_seqs: text tokens [batch_size, seq_len]
        # batch.source_seq_lens: audio sequence lengths
        # batch.target_seq_lens: text sequence lengths
        print(f"Batch shape: {batch.source_seqs.shape}")
        print(f"Text tokens shape: {batch.target_seqs.shape}")
        break
    break
```

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

### Initialize LLM ASR Inference Pipeline

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Initialize an ASRInferencePipeline for LLM models. LLM models provide higher accuracy with autoregressive generation and optional language conditioning. Available models include omniASR_LLM_{300M,1B,3B,7B}_v2.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

# LLM Models: Autoregressive generation with optional language conditioning
# Best for: High accuracy transcription with known language
# Available: omniASR_LLM_{300M,1B,3B,7B}_v2
pipeline_llm = ASRInferencePipeline(model_card="omniASR_LLM_7B_v2")
```

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

### Define Dataset Asset Card for Finetuning

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Defines an asset card in YAML format for integrating a custom dataset into the finetuning recipe. This allows the dataset to be referenced by name.

```yaml
name: my_dataset
dataset_family: mixture_parquet_asr_dataset
dataset_config:
  data: /path/to/the/dataset
tokenizer_ref: omniASR_tokenizer_v1
```

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

### Configure Model Asset in Training Recipe

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/cards/README.md

Reference a model asset by its name within a training recipe configuration file, typically under the 'model' key.

```yaml
model:
  name: "omniASR_CTC_300M_v2"

trainer:
  (...)

optimizer:
  (...)
```

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

### Run Evaluation on Fleurs-MLS-Mini Test Set

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Execute model evaluation on the fleurs-mls-mini test set. Provide the OUTPUT_DIR and the path to the evaluation configuration file.

```bash
python -m workflows.recipes.wav2vec2.asr.eval $OUTPUT_DIR \
    --config-file workflows/recipes/wav2vec2/asr/eval/configs/fleurs-mls-mini.yaml
```

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

### Model Memory Requirements

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Approximate VRAM requirements for different model sizes when using batch_size=1 and 30s audio with BF16 precision. This information helps in selecting a model that fits your hardware constraints.

```python
# Model memory requirements (approximate VRAM for batch_size=1, 30s audio, BF16):
# 300M: ~2-5 GiB | 1B: ~3-6 GiB | 3B: ~8-10 GiB | 7B: ~15-17 GiB
```

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

### Transcribe Audio from Parquet Dataset

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/inference/README.md

Load audio data from a Parquet dataset and transcribe it using the ASRInferencePipeline. Ensure the dataset schema matches the expected format.

```python
import pyarrow.parquet as pq
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

ds = pq.ParquetDataset("/path/to/dataset/")
batch_data = ds._dataset.head(10).to_pandas()  # taking only few first samples
audio_bytes = batch_data["audio_bytes"].tolist()

pipeline = ASRInferencePipeline(model_card="omniASR_LLM_1B_v2")
transcriptions = pipeline.transcribe(audio_bytes, batch_size=4)

for i, text in enumerate(transcriptions):
    print(f"Sample {i+1}: {text}")
```

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

### Ingest Individual Datasets

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Commands to ingest individual datasets (MLS or FLEURS) into the specified output directory. Use these for targeted data preparation.

```bash
python workflows/dataprep/hf_dataset_ingestion_example.py ingest_mls /path/to/output/dir
```

```bash
python workflows/dataprep/hf_dataset_ingestion_example.py ingest_fleurs /path/to/output/dir
```

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

### Transcribe Audio Files with ASRInferencePipeline

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Transcribe audio files using the ASRInferencePipeline. Supports various input formats including file paths, pre-decoded audio dictionaries, and raw audio bytes. Batch processing is available.

```python
# Transcribe audio files - supports multiple input formats:
# 1. File paths (str or Path)
audio_files = ["/path/to/audio1.flac", "/path/to/audio2.wav"]

# 2. Pre-decoded audio dictionaries
audio_data = [
    {"waveform": numpy_array, "sample_rate": 16000},
    {"waveform": torch_tensor, "sample_rate": 48000}  # Auto-resampled to 16kHz
]

# 3. Raw audio bytes
audio_bytes = [open("audio.wav", "rb").read()]

# Basic transcription (CTC models)
transcriptions = pipeline.transcribe(audio_files, batch_size=2)
# Output: ['transcribed text from audio 1', 'transcribed text from audio 2']
```

```python
# Language-conditioned transcription (LLM models) - improves accuracy
transcriptions = pipeline.transcribe(
    audio_files,
    lang=["eng_Latn", "deu_Latn"],  # ISO code + script format
    batch_size=2
)
print(transcriptions)
# Output: ['hello world this is english audio', 'hallo welt das ist deutsches audio']
```

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

### HuggingFace Dataset Integration for ASR

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Loads the omnilingual-asr-corpus dataset from HuggingFace in streaming mode, processes audio data, runs ASR inference, and compares predictions with ground truth.

```python
from datasets import load_dataset
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

# Load dataset for a specific language (streaming mode for efficiency)
language = "lij_Latn"  # Ligurian language
omni_dataset = load_dataset(
    "facebook/omnilingual-asr-corpus",
    language,
    split="train",
    streaming=True
)

# Get a batch of samples
batch = next(omni_dataset.iter(5))

# Convert HuggingFace audio format to pipeline input format
audio_data = [
    {"waveform": x["array"], "sample_rate": x["sampling_rate"]}
    for x in batch["audio"]
]

# Run inference
pipeline = ASRInferencePipeline(model_card="omniASR_LLM_7B_v2")
transcriptions = pipeline.transcribe(audio_data, batch_size=2)

# Compare predictions with ground truth
for i, (prediction, ground_truth) in enumerate(zip(transcriptions, batch["raw_text"])):
    print(f"\nSample {i + 1}:")
    print(f"  Ground Truth: {ground_truth}")
    print(f"  Predicted:    {prediction}")
```

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

### Parquet Binary Audio Processing for Inference

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Python script to load and process parquet datasets containing binary audio data for inference. This is useful for custom data pipelines. It extracts audio bytes, initializes the ASR pipeline, and transcribes the audio.

```python
import pyarrow.parquet as pq
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

# Load parquet dataset with audio bytes
ds = pq.ParquetDataset("/path/to/parquet/dataset/")
batch_data = ds._dataset.head(10).to_pandas()

# Extract audio bytes column (stored as list<int8>)
audio_bytes = batch_data["audio_bytes"].tolist()

# Initialize pipeline and transcribe
pipeline = ASRInferencePipeline(model_card="omniASR_LLM_1B_v2")
transcriptions = pipeline.transcribe(audio_bytes, batch_size=4)

# Display results with ground truth comparison
for i, (text, ground_truth) in enumerate(zip(transcriptions, batch_data["text"])):
    print(f"Sample {i + 1}:")
    print(f"  Ground Truth: {ground_truth}")
    print(f"  Predicted:    {text}")
```

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

### Load Model Asset in Python

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/cards/README.md

Load a pre-defined model asset using its name with the `load_model` function from `fairseq2.models.hub`.

```python
from fairseq2.models.hub import load_model

model = load_model("omniASR_CTC_300M_v2")
```

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

### Initialize CTC ASR Inference Pipeline

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Initialize an ASRInferencePipeline for CTC models. CTC models offer fast parallel decoding and are suitable for on-device applications. Available models include omniASR_CTC_{300M,1B,3B,7B}_v2.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

# CTC Models: Fast parallel decoding, no language conditioning
# Best for: On-device, low-latency applications
# Available: omniASR_CTC_{300M,1B,3B,7B}_v2
pipeline_ctc = ASRInferencePipeline(model_card="omniASR_CTC_1B_v2")
```

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

### Perform ASR inference with ASRInferencePipeline

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/README.md

Use the ASRInferencePipeline to transcribe audio files. Specify the model card, audio file paths, and optionally language codes and batch size. Note that currently only audio files shorter than 40 seconds are accepted.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

pipeline = ASRInferencePipeline(model_card="omniASR_LLM_Unlimited_7B_v2")
audio_files = ["/path/to/eng_audio1.flac", "/path/to/deu_audio2.wav"]
lang = ["eng_Latn", "deu_Latn"]
transcriptions = pipeline.transcribe(audio_files, lang=lang, batch_size=2)
```

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

### Basic ASR Batch Format

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/inference/README.md

Defines the Seq2SeqBatch structure for basic ASR tasks. Requires source audio sequences, lengths, and optionally target text sequences and lengths.

```python
batch = Seq2SeqBatch(
    source_seqs=audio_tensor,           # [BS, T_audio, D_audio] - target audio
    source_seq_lens=audio_lengths,      # [BS] - actual audio lengths
    target_seqs=text_tensor,            # [BS, T_text] - target text tokens
    target_seq_lens=text_lengths,       # [BS] - actual text lengths
    example={}
)
```

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

### Supported Languages

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Provides information on how to programmatically access the list of supported languages.

```APIDOC
## Supported Languages

### Description
Access the full list of 1,600+ supported languages programmatically. Language codes follow the `{iso_code}_{script}` format (e.g., `eng_Latn` for English Latin script, `cmn_Hans` for Mandarin Simplified Chinese).

### Method
`supported_langs()`

### Endpoint
`from omnilingual_asr.models.wav2vec2_llama.lang_ids import supported_langs`

### Usage Example
```python
from omnilingual_asr.models.wav2vec2_llama.lang_ids import supported_langs

# Get the list of supported languages
all_langs = supported_langs()

# Print a few examples
print(all_langs[:10])
# Example Output: ['afr_Latn', 'amh_Ethi', 'ara_Arab', 'asm_Beng', 'aze_Latn', 'bel_Cyrl', 'ben_Beng', 'bod_Tibt', 'bos_Latn', 'bul_Cyrl']
```
```

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

### Omnilingual ASR Architecture Overview

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/README.md

Visual representation of the hierarchical design for W2V, CTC, and LLM models built on Wav2Vec2.

```text
W2V:     [Audio 16kHz] → Wav2Vec2 Feature Extractor → Wav2Vec2 Encoder →   [Audio Embeddings]
                         (CNN downsampling ~320x)       (Transformer)      (1024/1280/2048-dim)

CTC:     [Audio 16kHz] → Wav2Vec2 Feature Extractor → Wav2Vec2 Encoder →    Linear Projection     → [Vocab Logits]
                         (CNN downsampling ~320x)       (Transformer)      (1024/1280/2048-dim)

LLM:     [Audio 16kHz] → Wav2Vec2 Feature Extractor → Wav2Vec2 Encoder →    Linear Projection     → LLama Decoder       → [Vocab Logits]
                         (CNN downsampling ~320x)       (Transformer)      (1024/1280/2048-dim)  (Transformer, 4096-dim)
```

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

### Print Supported Languages

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/README.md

Displays the total number of supported languages and lists them. Checks if a specific language code is present in the supported list.

```python
print(f"Total supported languages: {len(supported_langs)}")
print(supported_langs)

# Check if a specific language is supported
if "eng_Latn" in supported_langs:
    print("English (Latin script) is supported!")
```

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

### Create Feature Branch

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/CONTRIBUTING.md

Create a new branch for your feature development, branching off the main development branch.

```bash
git checkout -b feature_name
```

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

### Minimal PyArrow Schema for ASR Dataset

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Defines the minimal pyarrow schema for the ASR dataset, including text, audio bytes, audio size, corpus, split, and language.

```python
text: string

audio_bytes: list<element: int8>
  child 0, element: int8

audio_size: int64

corpus: dictionary<values=string, indices=int32, ordered=0>

split: dictionary<values=string, indices=int32, ordered=0>

language: dictionary<values=string, indices=int32, ordered=0>

```

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

### Ingest Multilingual LibriSpeech Datasets

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Processes only the Multilingual LibriSpeech (MLS) datasets. This command is useful for isolating MLS data ingestion.

```bash
python hf_dataset_ingestion_example.py ingest_mls /path/to/output/dir
```

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

### Batch Audio Transcription

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/models/inference/README.md

Transcribe multiple audio files in batches using the ASRInferencePipeline. Ensure audio files are shorter than 40 seconds.

```python
from omnilingual_asr.models.inference.pipeline import ASRInferencePipeline

pipeline = ASRInferencePipeline(model_card="omniASR_CTC_1B_v2")

audio_files = ["/path/to/audio1.flac", "/path/to/audio2.wav"]
transcriptions = pipeline.transcribe(audio_files, batch_size=2)

for file, trans in zip(audio_files, transcriptions):
    print(f"{file}: {trans}")
```

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

### Define Model Asset in YAML

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/src/omnilingual_asr/cards/README.md

Use this YAML structure to define a model asset, specifying its name, family, architecture, checkpoint location, and tokenizer reference.

```yaml
name: omniASR_CTC_300M_v2
model_family: wav2vec2_asr
model_arch: 300m
checkpoint: https://dl.fbaipublicfiles.com/mms/omniASR-CTC-300M.pt
tokenizer_ref: omniASR_tokenizer_written_v2
```

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

### Access supported languages programmatically

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/README.md

Retrieve the list of all supported languages by importing the 'supported_langs' variable from the lang_ids module.

```python
from omnilingual_asr.models.wav2vec2_llama.lang_ids import supported_langs
```

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

### Ingest FLEURS Datasets

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Processes only the FLEURS datasets. This command is useful for isolating FLEURS data ingestion.

```bash
python hf_dataset_ingestion_example.py ingest_fleurs /path/to/output/dir
```

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

### Convert Audio Bytes to Waveform Tensor

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Converts a numpy array of audio bytes to a waveform array. Allows specifying the target sample rate.

```python
bytes_to_tensor(audio_arr, target_sample_rate=16_000)
```

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

### Convert Binary Array to List Int8

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Efficiently converts PyArrow BinaryArray to ListArray of int8. This is a utility for audio data processing.

```python
binary_to_list_int8(binary_array)
```

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

### Compute Statistics from Processed Data

Source: https://context7.com/facebookresearch/omnilingual-asr/llms.txt

Generate statistics from the processed parquet dataset. Provide the path to the dataset and the desired output path for the statistics file.

```bash
python workflows/dataprep/hf_dataset_ingestion_example.py compute_stats \
    /path/to/parquet/dataset \
    /path/to/output/stats.tsv
```

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

### Compute Statistics from Processed Data

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Generates statistics from existing processed data in parquet format. This is useful for analyzing dataset characteristics.

```bash
python hf_dataset_ingestion_example.py compute_stats /path/to/parquet/dataset /path/to/output/stats.tsv
```

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

### Text Normalization Function

Source: https://github.com/facebookresearch/omnilingual-asr/blob/main/workflows/dataprep/README.md

Applies language-specific text normalization. Configurable options include lowercasing, number removal, and bracket removal.

```python
text_normalize(text, iso_code, lower_case=True, remove_numbers=True, remove_brackets=False)
```

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