### Clone Repository and Install Dependencies

Source: https://github.com/salute-developers/gigaam/blob/main/colab_example.ipynb

Clones the GigaAM repository and installs the package with testing dependencies. This is the initial setup step.

```python
! git clone https://github.com/salute-developers/GigaAM.git
%cd GigaAM
```

```python
! pip install -e .[tests]
```

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

### Install Training Dependencies

Source: https://github.com/salute-developers/gigaam/blob/main/train_utils/README.md

Install the necessary training dependencies from the repository root. This command installs the package in editable mode with training extras.

```bash
pip install -e ".[train]"

cd train_utils
```

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

### Install GigaAM with PyTorch

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

Install GigaAM with PyTorch support. Use this for standard installations.

```bash
pip install -e " BASH_CODE_ESCAPED_QUOTES.[torch]"
```

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

### Install GigaAM Package

Source: https://github.com/salute-developers/gigaam/blob/main/README.md

Clone the repository and install the package with its requirements. Optionally, install test dependencies and run tests to verify the installation.

```bash
git clone https://github.com/salute-developers/GigaAM.git
cd GigaAM

pip install -e .[torch]

# (optionally) Verify the installation:
pip install -e ".[tests]"
pytest -v tests/test_loading.py -m partial  # or `-m full` to test all models
```

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

### Download Example Audio Files

Source: https://github.com/salute-developers/gigaam/blob/main/colab_example.ipynb

Downloads example audio files ('example.wav' and 'long_example.wav') from a remote URL for use with the GigaAM model.

```bash
! wget https://cdn.chatwm.opensmodel.sberdevices.ru/GigaAM/example.wav
! wget https://cdn.chatwm.opensmodel.sberdevices.ru/GigaAM/long_example.wav
```

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

### Install GigaAM with ONNX Runtime

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

Install GigaAM with ONNX Runtime support. Use this for ONNX-compatible deployments.

```bash
pip install -e " BASH_CODE_ESCAPED_QUOTES.[onnx]"
```

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

### Install GigaAM with PyTorch and Longform

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

Install GigaAM with PyTorch and longform support. Required for processing extended audio files.

```bash
pip install -e " BASH_CODE_ESCAPED_QUOTES.[torch,longform]"
```

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

### Load Model and Prepare WAV

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/model.md

Example of loading a GigaAM model and preparing an audio file using the `prepare_wav` method.

```python
import gigaam
model = gigaam.load_model("v3_ssl")
wav, length = model.prepare_wav("audio.wav")
```

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

### Client Inference Example: RNNT ONNX

Source: https://github.com/salute-developers/gigaam/blob/main/triton_scripts/README.md

Example of running the client for RNNT model with ONNX backend using a single WAV file.

```bash
python run_client.py rnnt onnx example.wav
```

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

### Navigate to Triton Scripts Directory

Source: https://github.com/salute-developers/gigaam/blob/main/triton_scripts/README.md

Change the current directory to the triton_scripts folder to begin the setup process.

```bash
cd triton_scripts
```

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

### Install FFmpeg on Linux, macOS, or Windows

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

FFmpeg is a required dependency for audio processing. Install it using the appropriate package manager for your operating system.

```bash
# Linux
apt-get install ffmpeg

# macOS
brew install ffmpeg

# Windows
choco install ffmpeg
# Then add to PATH
```

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

### Tokenizer Usage Examples

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/decoding.md

Demonstrates initializing and using the Tokenizer in both character-wise and SentencePiece modes, including decoding token IDs.

```python
from gigaam.decoding import Tokenizer

# Character-wise tokenizer
vocab = ['a', 'b', 'c', ' ', '[blank]']
tok = Tokenizer(vocab)
text = tok.decode([0, 1, 2])  # "abc"
print(len(tok))  # 5

# SentencePiece tokenizer
sp_tok = Tokenizer(vocab, model_path="tokenizer.model")
text = sp_tok.decode([42, 156, 203])
```

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

### Load GigaAM Model with Default Parameters

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/configuration.md

Loads a GigaAM model using default settings, including FP16 encoder and automatic device selection. This is the simplest way to get started.

```python
gigaam.load_model(
    model_name: str,
    fp16_encoder: bool = True,
    use_flash: Optional[bool] = False,
    device: Optional[Union[str, torch.device]] = None,
    download_root: Optional[str] = None,
)
```

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

### Iterable of Paths Input Format

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/audio_dataset.md

Example of initializing AudioDataset with a list of audio file paths.

```python
AudioDataset(["audio1.wav", "audio2.wav"])
```

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

### Install Dependencies for GigaAM

Source: https://github.com/salute-developers/gigaam/blob/main/colab_example.ipynb

Installs necessary libraries including numpy, torch, torchaudio, transformers, pyannote.audio, and others. A force reinstall of numpy is included to ensure compatibility with transformers.

```python
! pip install numpy==2.* torch==2.8.* torchaudio==2.8.* transformers==4.57.* \
    pyannote.audio==4.0 torchcodec==0.7 numba>=0.62 \
    onnx==1.19.* onnxruntime==1.23.* \
    hydra-core==1.3.* omegaconf==2.3.* \
    sentencepiece tqdm
```

```python
! pip install --force-reinstall numpy  # make transformers work fine
```

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

### Install pyannote.audio for Longform Transcription

Source: https://github.com/salute-developers/gigaam/blob/main/colab_example.ipynb

Installs a specific version of the `pyannote.audio` library, which is required for the `transcribe_longform` functionality that uses voice activity detection for audio segmentation.

```python
! pip install pyannote.audio==4.0
```

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

### Initialize AudioDataset with Custom Settings

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/configuration.md

Create an AudioDataset instance for loading and processing audio data. This example shows how to specify data sources, tokenizers, duration filters, and text normalization options.

```python
from gigaam.utils import AudioDataset

dataset = AudioDataset(
    "train.tsv",
    tokenizer=tokenizer,
    min_duration=0.5,
    max_duration=20.0,
    raw_text=True,
    return_tokens=True
)
```

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

### Client Inference Example: CTC TRT

Source: https://github.com/salute-developers/gigaam/blob/main/triton_scripts/README.md

Example of running the client for CTC model with TensorRT backend using multiple WAV files.

```bash
python run_client.py ctc trt audio1.wav audio2.wav audio3.wav
```

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

### download_short_audio

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/utilities.md

Downloads an example short audio file (up to 25 seconds) suitable for testing.

```APIDOC
## download_short_audio

### Description
Downloads an example short audio file (up to 25 seconds) for testing purposes. Returns the path to the downloaded WAV file.

### Function Signature
```python
def download_short_audio() -> str
```

### Return Type
`str` — Path to downloaded WAV file (`example.wav` in current directory)

### Example
```python
import gigaam

audio_path = gigaam.download_short_audio()
model = gigaam.load_model("v3_ctc")
result = model.transcribe(audio_path)
print(result.text)
```
```

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

### Infer ONNX with List of Audio Paths

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/onnx_inference.md

Example of calling infer_onnx with a list of audio file paths. Requires model_cfg and sessions to be pre-loaded.

```python
infer_onnx(["audio1.wav", "audio2.wav"], model_cfg, sessions)
```

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

### Start Triton Inference Server

Source: https://github.com/salute-developers/gigaam/blob/main/triton_scripts/README.md

Launch the Triton Inference Server using Docker. Mounts model repositories and the GigaAM repository, exposing necessary ports.

```bash
docker run --gpus all --ipc=host -p 8000:8000 -p 8001:8001 -p 8002:8002 \
  -v "$(pwd)/repos:/models" \
  -v "$(pwd)/..:/opt/gigaam_repo" \
  -e PYTHONPATH=/opt/gigaam_repo \
  gigaam-triton \
  tritonserver --model-repository=/models --exit-on-error=false
```

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

### Process Short Audio with GigaAM and PyTorch

Source: https://github.com/salute-developers/gigaam/blob/main/colab_example.ipynb

Load a short audio file, preprocess it, and perform inference using the GigaAM model. This example demonstrates handling audio arrays and comparing results from different loading methods.

```python
import librosa
import torch

from gigaam.utils import AudioDataset
from gigaam.preprocess import SAMPLE_RATE as SR

fname = gigaam.utils.download_short_audio()
wav = gigaam.load_audio(fname)
# arrays can be not equal after possible resampling, but close enough
wav_ = torch.from_numpy(librosa.load(fname, sr=SR, mono=True)[0])

wav_tns, lengths = AudioDataset.collate([wav, wav_])
with torch.no_grad():
    encoded, encoded_len = model(wav_tns.to(model._device).to(model._dtype), lengths.to(model._device))
    results = model.decoding.decode(model.head, encoded, encoded_len)
    for text, _, __ in results:
        print(text)

# outputs expected to be equal
```

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

### Run End-to-end CTC Training

Source: https://github.com/salute-developers/gigaam/blob/main/train_utils/example.ipynb

Use this command to start the training process. Ensure you have the necessary data manifests and model configuration. The `--devices 2` flag indicates training across two GPUs.

```bash
! python -u train.py \
    --train_manifest data/manifest_train.tsv \
    --val_manifest data/manifest_val.tsv \
    --model_name v3_e2e_ctc \
    --max_epochs 3 \
    --val_check_interval 0.5 \
    --batch_size 64 \
    --eval_batch_size 64 \
    --precision bf16 \
    --devices 2 \
    --lr 8e-5 \
    --disable_tqdm
```

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

### Install Longform Dependencies

Source: https://github.com/salute-developers/gigaam/blob/main/README.md

To enable long-form audio transcription, install additional dependencies including pyannote.audio. Ensure you have a Hugging Face API token and have accepted the conditions for pyannote/segmentation-3.0.

```bash
pip install -e "[longform]"
# optionally run longform testing
pip install -e "[tests]"
HF_TOKEN=<your hf token> pytest -v tests/test_longform.py
```

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

### RNNTGreedyDecoding Example

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/decoding.md

Example demonstrating how to use the RNNTGreedyDecoding class for decoding.

```APIDOC
## Example

```python
from gigaam.decoding import RNNTGreedyDecoding
import torch

vocab = ['a', 'b', 'c', 'd']
decoder = RNNTGreedyDecoding(vocab, max_symbols_per_step=10)

# After model inference
text, token_ids, frames = decoder.decode(head, encoded, enc_len)[0]
print(f"Text: {text}")
print(f"Frames: {frames}")
```
```

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

### Iterable of Arrays Input Format

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/audio_dataset.md

Example of initializing AudioDataset with a list of NumPy arrays representing audio data.

```python
import numpy as np
arrays = [np.random.randn(16000), np.random.randn(32000)]
AudioDataset(arrays)
```

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

### Segment Usage Example

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/types.md

Demonstrates how to create and use a Segment object, including its fields and word-level timestamps.

```python
from gigaam.types import Segment, Word

segment = Segment(
    text="hello world",
    start=0.0,
    end=2.5,
    words=[
        Word(text="hello", start=0.0, end=1.2),
        Word(text="world", start=1.3, end=2.5)
    ]
)

print(f"[{segment.start:.1f}s-{segment.end:.1f}s] {segment.text}")
```

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

### Embed Audio and Print Shape

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/model.md

Example demonstrating how to extract audio embeddings and print the shape of the resulting embedding tensor.

```python
embedding, lengths = model.embed_audio("audio.wav")
print(embedding.shape)  # torch.Size([1, T, 768])
```

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

### Example Usage of RNNTGreedyDecoding

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/decoding.md

Demonstrates how to initialize RNNTGreedyDecoding and use its decode method after model inference. Prints the decoded text and the corresponding encoder frames.

```python
from gigaam.decoding import RNNTGreedyDecoding
import torch

vocab = ['a', 'b', 'c', 'd']
decoder = RNNTGreedyDecoding(vocab, max_symbols_per_step=10)

# After model inference
text, token_ids, frames = decoder.decode(head, encoded, enc_len)[0]
print(f"Text: {text}")
print(f"Frames: {frames}")

```

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

### Load Audio and Transcribe with GigaAM

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/README.md

Demonstrates loading an audio file and performing transcription with optional word-level timestamps. The output includes the transcribed text and a list of words with their start and end times.

```python
# Input: Audio file path
wav = gigaam.load_audio("speech.wav")  # Tensor[num_samples]

# Output: Transcription with optional timestamps
result = model.transcribe("speech.wav", word_timestamps=True)
# TranscriptionResult {
#   text: str
#   words: List[Word] = [Word(text, start, end), ...]
# }
```

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

### Load Model with Flash Attention

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/load_model.md

Load a model and enable the use of flash attention for potential speed improvements. This requires the flash_attn library to be installed.

```python
model = gigaam.load_model(
    "v3_ctc",
    use_flash=True
)
```

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

### Load GigaAM Model with Automatic Device Selection

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/configuration.md

Loads the 'v3_ctc' model, automatically selecting the GPU if available, otherwise falling back to the CPU. This is a common starting point for most users.

```python
# Automatic device selection (GPU if available, else CPU)
model = gigaam.load_model("v3_ctc")
```

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

### Load and Resample Audio with GigaAM

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/preprocessing.md

Loads an audio file and resamples it to a specified sample rate (defaulting to 16 kHz). Requires ffmpeg to be installed.

```python
from gigaam import load_audio

# Load and resample to 16 kHz
wav = load_audio("speech.wav")
print(wav.dtype, wav.shape)  # torch.float32, torch.Size([352000])

# Load with custom sample rate
wav_22k = load_audio("audio.mp3", sample_rate=22050)

# Use in model
model = gigaam.load_model("v3_ssl")
wav = load_audio("audio.wav").unsqueeze(0)  # Add batch dimension
embedding, _ = model.embed_audio_tensor(wav)
```

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

### Load Model and Embed Audio

Source: https://github.com/salute-developers/gigaam/blob/main/README.md

Load a GigaAM model and use it to generate audio embeddings. This example demonstrates loading a model by name and processing a short audio file.

```python
import gigaam

# Load test audio
audio_path = gigaam.utils.download_short_audio()
long_audio_path = gigaam.utils.download_long_audio()

# Audio embeddings
model_name = "v3_ssl"       # Options: `v1_ssl`, `v2_ssl`, `v3_ssl`
model = gigaam.load_model(model_name)
embedding, _ = model.embed_audio(audio_path)
print(embedding)
```

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

### CPU Inference (No GPU)

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/README.md

Configure GigaAM for inference on CPU when a GPU is not available. This example uses a specific model variant and disables fp16 encoding.

```python
model = gigaam.load_model(
    "v3_ctc",
    device="cpu",
    fp16_encoder=False
)
```

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

### CTCGreedyDecoding Usage Example

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/decoding.md

Demonstrates how to use the CTCGreedyDecoding class. Instantiate the decoder with a vocabulary, then call the decode method with model outputs to get the transcribed text and token information.

```python
from gigaam.decoding import CTCGreedyDecoding
import torch

vocab = ['a', 'b', 'c', 'd']
decoder = CTCGreedyDecoding(vocab)

# After model inference
text, token_ids, frames = decoder.decode(head, encoded, lengths)[0]
print(f"Text: {text}")
print(f"Frames: {frames}")  # Time indices where tokens were emitted
```

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

### Get Emotion Probabilities with GigaAM

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

Get the probability distribution of emotions for a given speech audio file. Returns a dictionary of emotion labels and their probabilities.

```python
model = gigaam.load_model("emo")
probs = model.get_probs("speech.wav")
print(probs)  # {"neutral": 0.45, "anger": 0.3, ...}
```

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

### Dataset Creation Exception Handling

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/errors.md

Demonstrates error handling for creating an AudioDataset, covering issues like invalid values, missing manifest files, and incorrect data formats.

```python
from gigaam.utils import AudioDataset

try:
    dataset = AudioDataset(
        "train.tsv",
        tokenizer=tokenizer,
        min_duration=0.5,
        max_duration=20.0
    )
except ValueError as e:
    print(f"Dataset error: {e}")
except FileNotFoundError:
    print("Manifest file not found")
except TypeError:
    print("Invalid data format")
```

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

### GigaAMEmo.get_probs()

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Gets the emotion probabilities from a WAV audio file.

```APIDOC
## GigaAMEmo.get_probs(wav_file: str)

### Description
Gets the emotion probabilities from a WAV audio file.

### Parameters
- **wav_file** (str) - The path to the WAV audio file.

### Returns
- A dictionary mapping emotion labels to their probabilities.
```

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

### Instantiating Model Components with Hydra

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/architecture.md

Demonstrates how to instantiate model components, such as the encoder, using Hydra's utility function based on the provided configuration.

```python
module = hydra.utils.instantiate(cfg.encoder)
```

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

### Get Word Timestamps

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Retrieves word-level timestamps during transcription when enabled.

```APIDOC
## transcribe(word_timestamps=True)

### Description
Transcribes audio and returns word-level timestamps.

### Method
`model.transcribe(word_timestamps=True)`

### Parameters
- `word_timestamps` (bool) - Required - Set to True to enable word timestamp extraction.
```

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

### Initialize AudioDataset with File Paths and Duration Filtering

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/audio_dataset.md

Loads audio data from a list of file paths and applies duration filtering. Prints the number of loaded samples after filtering.

```python
dataset = AudioDataset(
    ["audio1.wav", "audio2.wav", "audio3.wav"],
    min_duration=1.0,
    max_duration=10.0
)

print(f"Loaded {len(dataset)} samples")
```

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

### download_long_audio

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/utilities.md

Downloads an example long audio file for testing longform transcription capabilities.

```APIDOC
## download_long_audio

### Description
Downloads an example long audio file for testing longform transcription. Returns the path to the downloaded WAV file.

### Function Signature
```python
def download_long_audio() -> str
```

### Return Type
`str` — Path to downloaded WAV file (`long_example.wav` in current directory)

### Example
```python
import gigaam
import os

os.environ["HF_TOKEN"] = "your_token"
audio_path = gigaam.download_long_audio()
model = gigaam.load_model("v3_rnnt")
result = model.transcribe_longform(audio_path)
for seg in result:
    print(f"{seg.text} ({seg.start:.1f}s-{seg.end:.1f}s)")
```
```

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

### Import GigaAM Preprocessing and Decoding Utilities

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Import specific components from the gigaam.preprocess and gigaam.decoding submodules. This includes audio loading, feature extraction tools, and various decoding strategies for transcription.

```python
from gigaam.preprocess import load_audio, FeatureExtractor, SpecScaler, SAMPLE_RATE
from gigaam.decoding import Tokenizer, CTCGreedyDecoding, RNNTGreedyDecoding
```

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

### Create Audio Dataset with GigaAM

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/README.md

Create an audio dataset from a manifest file using GigaAM's AudioDataset utility. Requires a tokenizer. See api-reference/audio_dataset.md.

```python
from gigaam.utils import AudioDataset
dataset = AudioDataset("manifest.tsv", tokenizer=tok)
```

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

### Run Unit Tests with Coverage

Source: https://github.com/salute-developers/gigaam/blob/main/evaluation.md

Execute unit tests for the GigaAM project and generate a coverage report. Ensure you replace `<your hf token>` with your actual Hugging Face token. Note that `flash-attn` is not covered by this command as it requires GPU execution.

```bash
HF_TOKEN=<your hf token> pytest --cov=gigaam --cov-report=term-missing -v tests/
```

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

### AudioDataset __len__ Method Signature

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/audio_dataset.md

Signature for getting the total number of samples in the dataset after any applied filtering.

```python
def __len__(self) -> int
```

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

### Create Dataset

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Initializes an AudioDataset for processing audio files.

```APIDOC
## AudioDataset()

### Description
Constructor for the AudioDataset class.

### Method
`AudioDataset()`
```

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

### Training and Validation Manifest Usage

Source: https://github.com/salute-developers/gigaam/blob/main/train_utils/example.ipynb

Command-line usage for training and evaluating models using manifest files. Ensure to replace placeholder paths with actual file locations.

```bash
python train.py \
    --train_manifest /path/to/train/manifest.tsv \
    --val_manifest /path/to/val/manifest.tsv \
    ...
```

```bash
python eval.py \
    --eval_manifest /path/to/eval/manifest.tsv \
    ...
```

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

### Import GigaAM General Utilities

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Import utility functions for audio datasets, time formatting, and downloading audio files from the gigaam.utils submodule. These provide helpful tools for data handling and preparation.

```python
from gigaam.utils import AudioDataset, format_time, download_short_audio, download_long_audio
```

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

### Create DataLoader for AudioDataset

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

Set up a PyTorch DataLoader for an AudioDataset. Ensure the correct collate function and number of workers are specified.

```python
from torch.utils.data import DataLoader

loader = DataLoader(
    dataset,
    batch_size=32,
    collate_fn=dataset.collate_fn,
    num_workers=4
)

for batch, lengths, *tokens in loader:
    # Training/inference
    pass
```

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

### Emotion Recognition with GigaAM

Source: https://github.com/salute-developers/gigaam/blob/main/README.md

Load an emotion recognition model and get probability distributions for different emotions in an audio file.

```python
model = gigaam.load_model("emo")
emotion2prob = model.get_probs(audio_path)
print(", ".join([f"{emotion}: {prob:.3f}" for emotion, prob in emotion2prob.items()]))
```

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

### Long-Form ASR with Timestamps

Source: https://github.com/salute-developers/gigaam/blob/main/README.md

Perform long-form ASR and get segment-level timestamps. Requires setting the HF_TOKEN environment variable.

```python
import os
os.environ["HF_TOKEN"] = <HF_TOKEN with read access to "pyannote/segmentation-3.0">
result = model.transcribe_longform(long_audio_path)
for segment in result:
   print(f"[{gigaam.format_time(segment.start)} - {gigaam.format_time(segment.end)}]: {segment.text}")
```

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

### GigaAM.__init__()

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Initializes the GigaAM base encoder model with a configuration object.

```APIDOC
## GigaAM.__init__(cfg: DictConfig)

### Description
Initializes the GigaAM base encoder model with a configuration object.

### Parameters
- **cfg** (DictConfig) - The configuration dictionary for the model.
```

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

### apply_masked_flash_attn

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/utilities.md

Applies Flash Attention with padding masks for efficient attention computation. This function requires the 'flash_attn' and 'einops' libraries to be installed.

```APIDOC
## apply_masked_flash_attn

### Description
Apply Flash Attention with padding masks for efficient attention computation.

### Function Signature
```python
def apply_masked_flash_attn(
    q: Tensor,
    k: Tensor,
    v: Tensor,
    mask: Tensor,
    h: int,
    d_k: int,
) -> Tensor
```

### Parameters
#### Parameters
- **q** (`Tensor`) - Required - Query tensor, shape `[batch, time, heads*d_k]`
- **k** (`Tensor`) - Required - Key tensor, same shape as q
- **v** (`Tensor`) - Required - Value tensor, same shape as q
- **mask** (`Tensor`) - Required - Attention mask, shape `[batch, 1, time]` (True = attend, False = mask)
- **h** (`int`) - Required - Number of attention heads
- **d_k** (`int`) - Required - Dimension per head

### Return Type
`Tensor` of attention output, shape `[batch, time, heads*d_k]`

### Requirements
- Requires `flash_attn` library installed: `pip install flash-attn`
- Requires `einops` library
```

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

### CTCHead

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Initializes a CTCHead instance for CTC head.

```APIDOC
## CTCHead

### Description
Initializes a CTCHead instance for CTC head.

### Signature
`CTCHead(feat_in: int, num_classes: int)`

### Returns
Instance
```

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

### Model Checksum Verification Error

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/configuration.md

An example of an AssertionError raised when a model's MD5 checksum fails verification. This indicates a corrupted checkpoint.

```python
AssertionError: Model checksum failed. Please run `rm ~/.cache/gigaam/v3_ctc.ckpt` and reload
```

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

### Initialize AudioDataset with Manifest for Training

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/audio_dataset.md

Loads audio data from a TSV manifest file for training. Configures the dataset to normalize text, tokenize transcriptions, and filter samples by duration. Uses a custom collate_fn for batching.

```python
from gigaam.utils import AudioDataset
from torch.utils.data import DataLoader
from gigaam.decoding import Tokenizer

# Create tokenizer
vocab = ['а', 'б', 'в']
tokenizer = Tokenizer(vocab)

# Create dataset with text normalization and tokenization
dataset = AudioDataset(
    "train_manifest.tsv",
    tokenizer=tokenizer,
    min_duration=0.5,
    max_duration=20.0,
    raw_text=True,
    return_tokens=True
)

# Create dataloader
loader = DataLoader(
    dataset,
    batch_size=32,
    collate_fn=dataset.collate_fn,
    num_workers=4
)

for audio, audio_lens, tokens, token_lens in loader:
    # Train model
    pass
```

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

### Create and Print a Word Object

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/types.md

Demonstrates how to instantiate the Word dataclass and format its output. Requires the Word class to be imported.

```python
from gigaam.types import Word

word = Word(text="привет", start=0.5, end=1.2)
print(f"[{word.start:.2f}s-{word.end:.2f}s] {word.text}")
```

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

### Get Audio Embeddings with GigaAM Model

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/README.md

Generate audio embeddings and their corresponding lengths using a GigaAM model. Refer to api-reference/model.md and quick-reference.md.

```python
embedding, length = model.embed_audio("audio.wav")
```

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

### Create AudioDataset from Audio Files

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

Initialize an AudioDataset directly from a list of audio file paths.

```python
from gigaam.utils import AudioDataset

# From audio files
dataset = AudioDataset(["audio1.wav", "audio2.wav"])
```

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

### Create AudioDataset from Manifest

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

Initialize an AudioDataset from a manifest file (e.g., TSV). Supports tokenization and duration filtering.

```python
from gigaam.utils import AudioDataset
from torch.utils.data import DataLoader

# From manifest file
dataset = AudioDataset(
    "train_manifest.tsv",
    tokenizer=tokenizer,
    min_duration=0.5,
    max_duration=20.0,
    raw_text=True,
    return_tokens=True
)
```

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

### Load and Use GigaAMEmo Model

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/model.md

Demonstrates how to load the GigaAMEmo model and calculate emotion probabilities for an audio file. Ensure you have a 'speech.wav' file available.

```python
model = gigaam.load_model("emo")
probs = model.get_probs("speech.wav")
print(probs)  # {"neutral": 0.45, "anger": 0.35, "sadness": 0.20}
```

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

### Segment Data Type

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/types.md

Represents a single segment of audio with its transcribed text and optional word-level timestamps. It includes the start and end times of the segment.

```APIDOC
## Segment

Single segment of audio with text and optional word-level timestamps.

### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| text | `str` | — | Segment transcription |
| start | `float` | — | Segment start time in seconds |
| end | `float` | — | Segment end time in seconds |
| words | `Optional[List[Word]]` | None | Word-level timestamps within segment |

### Usage

```python
from gigaam.types import Segment, Word

segment = Segment(
    text="hello world",
    start=0.0,
    end=2.5,
    words=[
        Word(text="hello", start=0.0, end=1.2),
        Word(text="world", start=1.3, end=2.5)
    ]
)

print(f"[{segment.start:.1f}s-{segment.end:.1f}s] {segment.text}")
```
```

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

### TSV Manifest Data Format

Source: https://github.com/salute-developers/gigaam/blob/main/train_utils/README.md

Example of a tab-separated values (TSV) manifest file used for data input. It includes path, duration, and optionally transcription.

```text
path	duration	transcription
audio/0001.wav	3.21	привет как дела
```

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

### Get Embeddings

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Generates audio embeddings for a given audio input. Embeddings can be used for various downstream tasks like speaker recognition or similarity analysis.

```APIDOC
## embed_audio()

### Description
Generates embeddings from audio data.

### Method
`model.embed_audio()`
```

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

### SpecScaler

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Initializes a SpecScaler instance for spectral scaling.

```APIDOC
## SpecScaler

### Description
Initializes a SpecScaler instance for spectral scaling.

### Signature
`SpecScaler()`

### Returns
Instance
```

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

### Load ONNX Model and Get Emotion Probabilities

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/onnx_inference.md

Loads an ONNX model for emotion recognition and performs inference on a single audio file to obtain emotion probabilities.

```python
# Get emotion probabilities
sessions, model_cfg = load_onnx("onnx_dir", "emo")
probs = infer_onnx(
    ["speech.wav"],
    model_cfg,
    sessions
)
print(probs[0].shape)  # (num_emotions,)
```

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

### Import GigaAM ONNX Utilities

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Import functions for loading and inferring ONNX models from the gigaam.onnx_utils submodule. Use these for integrating GigaAM with ONNX runtime.

```python
from gigaam.onnx_utils import load_onnx, infer_onnx
```

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

### Format Time for Longform Transcription Segments

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/utilities.md

Integrates `format_time` to display start and end times for segments in longform audio transcriptions. Ensure the `gigaam` library is imported.

```python
result = model.transcribe_longform("long_audio.wav")
for segment in result:
    start_str = gigaam.format_time(segment.start)
    end_str = gigaam.format_time(segment.end)
    print(f"[{start_str}-{end_str}] {segment.text}")
```

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

### Transcribe Long Audio with GigaAM

Source: https://github.com/salute-developers/gigaam/blob/main/colab_example.ipynb

Load a GigaAM model and transcribe a long audio file. The output is a list of segments with start and end times and their corresponding text.

```python
import os
import warnings
warnings.simplefilter("ignore")

import gigaam

os.environ["HF_TOKEN"] = "<HF_TOKEN with read access to `pyannote/segmentation-3.0`>"

long_audio_path = gigaam.utils.download_long_audio()
model = gigaam.load_model("v3_e2e_rnnt")

result = model.transcribe_longform(long_audio_path)
for segment in result:
   print(f"[{gigaam.format_time(segment.start)} - {gigaam.format_time(segment.end)}]: {segment.text}")
```

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

### Infer ONNX with NumPy and Torch Arrays

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/onnx_inference.md

Example of calling infer_onnx with a list containing NumPy and PyTorch tensors representing audio data. Requires model_cfg and sessions to be pre-loaded.

```python
import numpy as np
import torch

audio_arrays = [
    np.random.randn(16000),  # 1 second at 16 kHz
    torch.randn(32000),
]
infer_onnx(audio_arrays, model_cfg, sessions)
```

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

### __getitem__

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/audio_dataset.md

Retrieves an audio sample by its index from the dataset.

```APIDOC
## __getitem__

### Description
Get audio sample by index.

### Returns
- Without tokens: `Tensor` of audio waveform
- With tokens: `Tuple[Tensor, Tensor]` of (audio, token_ids)
```

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

### LongformTranscriptionResult Usage Example

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/types.md

Shows how to load a model, transcribe long audio, and access various attributes of the LongformTranscriptionResult, such as full text, individual segments, all words, and segment count.

```python
import gigaam
import os

os.environ["HF_TOKEN"] = "your_token"

model = gigaam.load_model("v3_rnnt")
result = model.transcribe_longform("long_speech.wav", word_timestamps=True)

# Access full text
print(result.text)

# Iterate segments
for segment in result:
    print(f"[{segment.start:.1f}s-{segment.end:.1f}s] {segment.text}")

# Get all words
all_words = result.words
for word in all_words:
    print(f"[{word.start:.2f}s] {word.text}")

# Check if word timestamps available
if result.has_word_timestamps:
    print("Word-level timestamps available")

# Get segment count
print(f"Total segments: {len(result)}")
```

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

### Configure Model for High Performance (GPU, FP16)

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

Load a model optimized for high performance using a GPU, FP16 precision for the encoder, and FlashAttention if available.

```python
model = gigaam.load_model(
    "v3_e2e_rnnt",
    device="cuda:0",
    fp16_encoder=True,
    use_flash=True
)
```

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

### Get PyAnnote VAD Pipeline

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/longform_vad.md

Retrieves a PyAnnote voice activity detection pipeline. The pipeline is loaded once and cached globally for reuse. Ensure the correct device (CPU or GPU) is specified.

```python
import torch
from gigaam.vad_utils import get_pipeline

# First call downloads and caches model
pipeline = get_pipeline(torch.device("cuda:0"))

# Subsequent calls return cached pipeline
pipeline = get_pipeline(torch.device("cuda:0"))  # Instant
```

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

### Download Short Audio for Testing

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/utilities.md

Downloads a short audio file (up to 25 seconds) for testing transcription. Returns the local path to the downloaded WAV file.

```python
import gigaam

audio_path = gigaam.download_short_audio()
model = gigaam.load_model("v3_ctc")
result = model.transcribe(audio_path)
print(result.text)
```

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

### Tokenizer

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Initializes a Tokenizer instance for text tokenization.

```APIDOC
## Tokenizer

### Description
Initializes a Tokenizer instance for text tokenization.

### Signature
`Tokenizer(vocab: List[str], model_path: Optional[str])`

### Returns
Instance
```

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

### Load GigaAM Models and Utilities

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Import and use top-level functions and classes from the gigaam library for model loading, audio processing, time formatting, and downloading audio files. This is the primary entry point for most GigaAM functionalities.

```python
import gigaam

gigaam.load_model(...)           # GigaAM, GigaAMASR, GigaAMEmo
gigaam.load_audio(...)           # Tensor
gigaam.format_time(...)          # str
gigaam.download_short_audio()    # str
gigaam.download_long_audio()     # str
gigaam.GigaAM                    # Class
gigaam.GigaAMASR                 # Class
gigaam.GigaAMEmo                 # Class
```

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

### frames_to_words

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/longform_vad.md

Converts token-level frame indices to word-level timestamps. It groups tokens into words, converts frame indices to seconds using the provided frame shift, and assigns start and end times for each word.

```APIDOC
## frames_to_words

### Description
Convert token-level frame indices to word-level timestamps.

### Function Signature
```python
def frames_to_words(
    tokenizer: Tokenizer,
    token_ids: List[int],
    token_frames: List[int],
    frame_shift: float,
) -> List[Word]
```

### Parameters
#### Path Parameters
- **tokenizer** (Tokenizer) - Required - Tokenizer for converting token IDs to characters.
- **token_ids** (List[int]) - Required - Token ID sequence from decoder.
- **token_frames** (List[int]) - Required - Frame index for each token.
- **frame_shift** (float) - Required - Frame duration in seconds.

### Return Type
`List[Word]` — A list of Word objects, each containing text, start, and end times.

### Algorithm
1. Group tokens into words at word boundaries (space or SentencePiece '▁')
2. Convert frame indices to seconds using frame_shift
3. Assign start/end times based on first/last frame of each word

### Example
```python
from gigaam.timestamps_utils import frames_to_words, compute_frame_shift

frame_shift = compute_frame_shift(
    audio_length_samples=32000,
    seq_len=100
)

words = frames_to_words(
    tokenizer,
    token_ids=[1, 2, 3, 4],
    token_frames=[0, 5, 10, 15],
    frame_shift=frame_shift
)

for word in words:
    print(f"[{word.start:.2f}-{word.end:.2f}] {word.text}")
```
```

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

### frames_to_words

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-index.md

Converts audio frames (represented by token IDs and their corresponding frame indices) into a list of words with start and end timestamps. It requires a tokenizer, token IDs, token frames, and the computed frame shift.

```APIDOC
## frames_to_words

### Description
Converts audio frames (represented by token IDs and their corresponding frame indices) into a list of words with start and end timestamps. It requires a tokenizer, token IDs, token frames, and the computed frame shift.

### Signature
`(tokenizer: Tokenizer, token_ids: List[int], token_frames: List[int], frame_shift: float)`

### Returns
`List[Word]`
```

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

### Configure Model with Custom Cache Location

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

Load a model and specify a custom directory for downloading and caching model weights.

```python
model = gigaam.load_model(
    "v3_ctc",
    download_root="/mnt/models"
)
```

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

### Build Triton Inference Server Docker Image

Source: https://github.com/salute-developers/gigaam/blob/main/triton_scripts/README.md

Build the Docker image for the Triton Inference Server, tagged as gigaam-triton.

```bash
docker build -t gigaam-triton .
```

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

### Transcribe Long Audio File

Source: https://github.com/salute-developers/gigaam/blob/main/colab_example.ipynb

Transcribes a long audio file using the GigaAM-v3 model. Requires setting the HF_TOKEN environment variable with read access to 'pyannote/segmentation-3.0'. The output is a list of segments with start and end times.

```python
import os
os.environ["HF_TOKEN"] = "<HF_TOKEN with read access to `pyannote/segmentation-3.0`>"

model = AutoModel.from_pretrained(repo_name, revision="e2e_rnnt", trust_remote_code=True)
result = model.transcribe_longform("long_example.wav")
print("Longform transcription:\n")
for segment in result:
   print(f"[{segment.start:.4f} - {segment.end:.4f}]: {segment.text}")
```

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

### AudioDataset Constructor

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/audio_dataset.md

Initializes the AudioDataset with data, tokenizer, and duration filters.

```APIDOC
## AudioDataset Constructor

### Description
Initializes the AudioDataset with data, tokenizer, and duration filters.

### Parameters
#### Path Parameters
- **data** (Union[str, Iterable]) - Required - TSV manifest file path or iterable of audio paths/arrays
- **tokenizer** (Optional[Tokenizer]) - Optional - Tokenizer for text-to-token conversion (required if `return_tokens=True`)
- **max_duration** (Optional[float]) - Optional - Filter samples longer than this (seconds); None = no limit
- **min_duration** (float) - Optional - Filter samples shorter than this (seconds); Default: 0.0
- **raw_text** (bool) - Optional - Normalize text (lowercase, replace ё→е, remove extra spaces); Default: False
- **return_tokens** (bool) - Optional - Return token IDs alongside audio; Default: False
```

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

### GigaAMEmo Constructor

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/model.md

Initializes the GigaAMEmo model with a given configuration.

```APIDOC
## GigaAMEmo Constructor

### Description
Initializes the GigaAMEmo model with a given configuration.

### Parameters
#### Path Parameters
- **cfg** (omegaconf.DictConfig) - Required - Configuration with encoder and emotion head specs
```

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

### Export PyTorch Model to ONNX

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/api-reference/onnx_inference.md

Export a loaded PyTorch model to ONNX format. FP16 is recommended for GPU deployment for better performance and reduced VRAM usage. Ensure you have the appropriate ONNX Runtime installed for GPU inference if using FP16.

```python
import torch
import gigaam

# Load model
model = gigaam.load_model("v3_ctc")

# Export to ONNX (FP16 recommended for GPU)
model.to_onnx(dir_path="onnx_models", dtype=torch.float16)

# Load and use
from gigaam.onnx_utils import load_onnx, infer_onnx
sessions, cfg = load_onnx("onnx_models", "v3_ctc")
result = infer_onnx("audio.wav", cfg, sessions)
```

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

### Create AudioDataset from NumPy Arrays

Source: https://github.com/salute-developers/gigaam/blob/main/_autodocs/quick-reference.md

Initialize an AudioDataset from raw audio data represented as NumPy arrays.

```python
from gigaam.utils import AudioDataset
import numpy as np

# From arrays
dataset = AudioDataset([np.random.randn(16000)])
```