### Install parakeet-mlx CLI with uv

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Install the parakeet-mlx command-line interface using uv. Ensure ffmpeg is installed.

```bash
uv tool install parakeet-mlx -U
```

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

### Install parakeet-mlx with uv

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Use uv to add the parakeet-mlx package to your project. Ensure ffmpeg is installed.

```bash
uv add parakeet-mlx -U
```

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

### Install parakeet-mlx with pip

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Install the parakeet-mlx package using pip. Ensure ffmpeg is installed.

```bash
pip install parakeet-mlx -U
```

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

### Install Parakeet MLX

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Install the Parakeet MLX library using uv or pip. Ensure ffmpeg is available on your PATH for audio loading.

```bash
# Recommended (uv)
uv add parakeet-mlx -U

# CLI tool only
uv tool install parakeet-mlx -U

# pip
pip install parakeet-mlx -U
```

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

### Parakeet MLX CLI Quick Start

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Basic command to start transcription using the parakeet-mlx CLI. Accepts one or more audio files.

```bash
parakeet-mlx <audio_files> [OPTIONS]
```

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

### Load and Decode Audio

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Use `load_audio` to load audio files in various formats supported by FFmpeg. It resamples to the target sample rate, converts to mono, and returns a normalized float32 mx.array. Ensure FFmpeg is installed.

```python
import mlx.core as mx
from parakeet_mlx.audio import load_audio
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")
sr = model.preprocessor_config.sample_rate  # typically 16000

# Load WAV
audio_wav = load_audio("speech.wav", sr)
print(audio_wav.shape)   # e.g. (48000,) for 3 s at 16 kHz
print(audio_wav.dtype)   # mlx.core.bfloat16

# Load MP3 with explicit dtype
audio_mp3 = load_audio("podcast.mp3", sr, dtype=mx.float32)

# Load a video file (audio track extracted by FFmpeg)
audio_mp4 = load_audio("recording.mp4", sr)
```

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

### from_pretrained

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Load a pre-trained model from Hugging Face. Models are downloaded and cached locally.

```APIDOC
## from_pretrained

Loads a pre-trained model from the Hugging Face Hub. The downloaded model is stored in the Hugging Face cache directory. You can specify a custom cache directory using the `cache_dir` argument.

### Method
`from_pretrained(model_name_or_path, cache_dir=None)`

### Parameters
- `model_name_or_path` (string) - The name or path of the pre-trained model on Hugging Face Hub (e.g., `"mlx-community/parakeet-tdt-0.6b-v3"`).
- `cache_dir` (string, optional) - Path to the directory where the model should be cached. Defaults to Hugging Face's default cache location.

### Returns
- An instance of a Parakeet model variant (e.g., `ParakeetTDT`, `ParakeetRNNT`, `ParakeetCTC`, `ParakeetTDTCTC`). For general use, `BaseParakeet` is often sufficient.

### Request Example
```python
from parakeet_mlx import from_pretrained

# Load a model with default cache directory
model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# Load a model with a specified cache directory
# model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3", cache_dir="./my_cache")
```
```

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

### CLI Transcription with All Output Formats

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Generate all available output formats (txt, srt, vtt, json) for a given audio file using the parakeet-mlx CLI.

```bash
parakeet-mlx audio.mp3 --output-format all
```

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

### Load and Preprocess Audio for Transcription

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Load an audio file and convert it to a log-mel spectrogram. This is a prerequisite for generating transcriptions. Ensure the audio file path and model are correctly specified.

```python
audio = load_audio("audio.wav", model.preprocessor_config.sample_rate)
mel = get_logmel(audio, model.preprocessor_config)
```

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

### CLI Transcription with VTT and Word Timestamps

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Transcribe multiple audio files, outputting in VTT format with word-level timestamps enabled.

```bash
parakeet-mlx *.mp3 --output-format vtt --highlight-words
```

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

### Load Parakeet Model with from_pretrained

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Load a Parakeet model from Hugging Face or a local path. Weights are cached by default. Specify dtype for precision or cache_dir for custom caching.

```python
import typing
from parakeet_mlx import from_pretrained
from parakeet_mlx.parakeet import ParakeetTDT
import mlx.core as mx

# Load from Hugging Face (weights cached in ~/.cache/huggingface by default)
model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# Load with fp32 precision
model_fp32 = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3", dtype=mx.float32)

# Load from a local directory
model_local = from_pretrained("/path/to/local/model")

# Use a custom HF cache directory
model_cached = from_pretrained(
    "mlx-community/parakeet-tdt-0.6b-v3",
    cache_dir="/tmp/hf_cache",
)

# Type-cast to a specific variant for linter-friendly access to variant methods
tdt_model = typing.cast(ParakeetTDT, model)
```

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

### load_audio

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Loads and decodes audio files using FFmpeg, resampling to the target sample rate and returning a normalized float32 mx.array.

```APIDOC
## `load_audio` — Load and decode audio via FFmpeg

Loads any audio format supported by FFmpeg, resamples to the target sample rate, converts to mono, and returns a normalized float32 `mx.array`. Raises `RuntimeError` if FFmpeg is not installed or the file cannot be decoded.

```python
import mlx.core as mx
from parakeet_mlx.audio import load_audio
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")
sr = model.preprocessor_config.sample_rate  # typically 16000

# Load WAV
audio_wav = load_audio("speech.wav", sr)
print(audio_wav.shape)   # e.g. (48000,) for 3 s at 16 kHz
print(audio_wav.dtype)   # mlx.core.bfloat16

# Load MP3 with explicit dtype
audio_mp3 = load_audio("podcast.mp3", sr, dtype=mx.float32)

# Load a video file (audio track extracted by FFmpeg)
audio_mp4 = load_audio("recording.mp4", sr)
```
```

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

### from_pretrained

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Loads and instantiates a Parakeet model from Hugging Face or a local path. It supports various model variants and allows specifying dtype and cache directory.

```APIDOC
## `from_pretrained` — Load a model from Hugging Face or local path

Downloads and instantiates a Parakeet model from a Hugging Face repository (or a local directory containing `config.json` + `model.safetensors`). Returns a `BaseParakeet` subclass (`ParakeetTDT`, `ParakeetRNNT`, `ParakeetCTC`, or `ParakeetTDTCTC`) depending on the model config. Weights are cast to the requested dtype (default `bfloat16`).

```python
import typing
from parakeet_mlx import from_pretrained
from parakeet_mlx.parakeet import ParakeetTDT
import mlx.core as mx

# Load from Hugging Face (weights cached in ~/.cache/huggingface by default)
model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# Load with fp32 precision
model_fp32 = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3", dtype=mx.float32)

# Load from a local directory
model_local = from_pretrained("/path/to/local/model")

# Use a custom HF cache directory
model_cached = from_pretrained(
    "mlx-community/parakeet-tdt-0.6b-v3",
    cache_dir="/tmp/hf_cache",
)

# Type-cast to a specific variant for linter-friendly access to variant methods
tdt_model = typing.cast(ParakeetTDT, model)
```
```

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

### Basic CLI Transcription

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Perform a basic audio transcription using the parakeet-mlx CLI.

```bash
parakeet-mlx audio.mp3
```

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

### Parakeet-MLX CLI Usage

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

The parakeet-mlx CLI wraps the Python API, supporting model and decoding options via flags. It can output in various formats (SRT, VTT, TXT, JSON) with configurable naming templates.

```bash
# Basic transcription (default: SRT output in current directory)
parakeet-mlx audio.mp3

# Multiple files, VTT format with word-level highlights
parakeet-mlx *.mp3 --output-format vtt --highlight-words

# Generate all output formats, save to a specific folder
parakeet-mlx interview.wav --output-format all --output-dir ./transcripts

# Beam decoding, chunked processing, verbose output
parakeet-mlx long_audio.mp3 \
  --decoding beam \
  --beam-size 5 \
  --length-penalty 0.013 \
  --patience 3.5 \
  --chunk-duration 120 \
  --overlap-duration 15 \
  --verbose

# Use a different model from Hugging Face
parakeet-mlx audio.wav --model mlx-community/parakeet-ctc-0.6b-v3

# FP32 precision, local attention to save memory
parakeet-mlx audio.wav --fp32 --local-attention --local-attention-context-size 128

# Sentence splitting by word count and silence gap
parakeet-mlx audio.wav --max-words 20 --silence-gap 1.5 --max-duration 30

# Filename templating: output named by date and index
parakeet-mlx *.mp3 --output-template "{date}_{index}_{filename}" --output-dir out/
```

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

### Python API Check Timestamps

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Load a pre-trained Parakeet model, transcribe an audio file, and print the detailed sentence timestamps using the Python API.

```python
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

result = model.transcribe("audio_file.wav")

print(result.sentences)
```

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

### Configure Environment Variables for Parakeet MLX

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Set environment variables to configure Parakeet MLX behavior, such as model selection, output format, and chunk duration. Useful for CI or Docker environments.

```bash
export PARAKEET_MODEL=mlx-community/parakeet-tdt-0.6b-v3
export PARAKEET_OUTPUT_FORMAT=json
export PARAKEET_CHUNK_DURATION=120
```

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

### Transcribe Log-Mel Spectrum Directly

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Transcribe audio by directly providing the log-mel spectrum. This requires using `mlx.core` and `parakeet_mlx.audio` utilities.

```python
import mlx.core as mx
from parakeet_mlx.audio import get_logmel, load_audio
from parakeet_mlx import DecodingConfig
```

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

### Generate Transcription from Log-Mel Spectrogram

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Use this low-level entry point for transcription when you have a pre-computed log-mel spectrogram. It supports both single and batched inputs and is useful for external audio preprocessing or batch inference pipelines.

```python
import mlx.core as mx
from parakeet_mlx import from_pretrained, DecodingConfig
from parakeet_mlx.audio import get_logmel, load_audio

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# --- Single input ---
audio = load_audio("audio.wav", model.preprocessor_config.sample_rate)
mel = get_logmel(audio, model.preprocessor_config)  # shape: [1, seq, 80]

results = model.generate(mel, decoding_config=DecodingConfig())
print(results[0].text)

# --- Batched input (pad mel spectrograms to same length) ---
audio_a = load_audio("a.wav", model.preprocessor_config.sample_rate)
audio_b = load_audio("b.wav", model.preprocessor_config.sample_rate)
mel_a = get_logmel(audio_a, model.preprocessor_config)  # [1, T_a, 80]
mel_b = get_logmel(audio_b, model.preprocessor_config)  # [1, T_b, 80]

T = max(mel_a.shape[1], mel_b.shape[1])
mel_a_pad = mx.pad(mel_a, [(0,0),(0, T - mel_a.shape[1]),(0,0)])
mel_b_pad = mx.pad(mel_b, [(0,0),(0, T - mel_b.shape[1]),(0,0)])
batch_mel = mx.concatenate([mel_a_pad, mel_b_pad], axis=0)  # [2, T, 80]

batch_results = model.generate(batch_mel)
for i, r in enumerate(batch_results):
    print(f"File {i}: {r.text}")
```

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

### Python API Transcribe Audio

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Load a pre-trained Parakeet model and transcribe an audio file using the Python API. Prints the transcribed text.

```python
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

result = model.transcribe("audio_file.wav")

print(result.text)
```

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

### Real-time Streaming Transcription

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Utilize this context manager for real-time streaming transcription. It accepts incremental audio chunks and internally switches to local attention for causal processing, providing live updates on the transcript.

```python
from parakeet_mlx import from_pretrained
from parakeet_mlx.audio import load_audio

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

audio = load_audio("audio.wav", model.preprocessor_config.sample_rate)
chunk_size = model.preprocessor_config.sample_rate  # 1-second chunks

with model.transcribe_stream(
    context_size=(256, 256),   # (left_context_frames, right_context_frames)
    depth=2,                   # first 2 encoder layers match non-streaming exactly
    keep_original_attention=False,  # switch to local attention (recommended)
) as streamer:
    for start in range(0, len(audio), chunk_size):
        chunk = audio[start : start + chunk_size]
        streamer.add_audio(chunk)

        # Live transcript (finalized + draft tokens)
        print(f"\r{streamer.result.text}", end="", flush=True)

    # Final result after all audio is fed
    final = streamer.result
    print()
    for sentence in final.sentences:
        print(f"[{sentence.start:.2f}s – {sentence.end:.2f}s] {sentence.text}")

# Finalized (stable) tokens vs draft (may be revised) tokens
# streamer.finalized_tokens  -> list[AlignedToken]
# streamer.draft_tokens      -> list[AlignedToken]
```

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

### Streaming Transcription with Parakeet-MLX

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Perform real-time transcription using the `transcribe_stream` method. This involves creating a streaming context and adding audio chunks iteratively.

```python
from parakeet_mlx import from_pretrained
from parakeet_mlx.audio import load_audio
import numpy as np

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# Create a streaming context
with model.transcribe_stream(
    context_size=(256, 256),  # (left_context, right_context) frames
) as transcriber:
    # Simulate real-time audio chunks
    audio_data = load_audio("audio_file.wav", model.preprocessor_config.sample_rate)
    chunk_size = model.preprocessor_config.sample_rate  # 1 second chunks

    for i in range(0, len(audio_data), chunk_size):
        chunk = audio_data[i:i+chunk_size]
        transcriber.add_audio(chunk)

        # Access current transcription
        result = transcriber.result
        print(f"Current text: {result.text}")

        # Access finalized and draft tokens
        # transcriber.finalized_tokens
        # transcriber.draft_tokens
```

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

### Transcribe Audio with Beam Decoding

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Perform transcription using beam decoding. Configure parameters like `beam_size`, `length_penalty`, `patience`, and `duration_reward` via `DecodingConfig`.

```python
from parakeet_mlx import from_pretrained, DecodingConfig, Beam

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

config = DecodingConfig(
    decoding = decoding(
        beam_size=5, length_penalty=0.013, patience=3.5, duration_reward=0.67
        # Refer to CLI options for each parameters 
    )
)

result = model.transcribe("audio_file.wav", decoding_config=config)

print(result.sentences)
```

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

### get_logmel

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Computes the log-mel spectrogram from a raw audio array using pre-emphasis, STFT, mel-filterbank, and log compression.

```APIDOC
## `get_logmel` — Compute log-mel spectrogram

Applies pre-emphasis, STFT, mel-filterbank, log compression, and per-feature normalization to a raw audio array. Accepts a `PreprocessArgs` config that is embedded in every loaded model. Returns a 3-D array of shape `[1, time_frames, n_mels]`.

```python
import mlx.core as mx
from parakeet_mlx.audio import get_logmel, load_audio
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")
cfg = model.preprocessor_config  # PreprocessArgs

audio = load_audio("speech.wav", cfg.sample_rate)
mel = get_logmel(audio, cfg)
print(mel.shape)   # e.g. (1, 312, 80)  -> [batch=1, time_frames, n_mels=80]
print(mel.dtype)   # mlx.core.bfloat16

# Use for direct model inference
results = model.generate(mel)
print(results[0].text)
```
```

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

### Transcribe Audio with BaseParakeet.transcribe

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Transcribe a single audio file using the BaseParakeet.transcribe method. Supports basic transcription, sentence/word-level timestamps, chunked processing for long audio, and custom decoding configurations.

```python
from parakeet_mlx import from_pretrained, DecodingConfig, SentenceConfig, Beam, Greedy
import mlx.core as mx

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# --- Basic transcription ---
result = model.transcribe("interview.mp3")
print(result.text)
# "Welcome to the show. Today we discuss machine learning on Apple Silicon."

# --- Access sentence-level timestamps ---
for sentence in result.sentences:
    print(f"[{sentence.start:.2f}s – {sentence.end:.2f}s] ({sentence.confidence:.0%}) {sentence.text}")
# [0.00s – 3.12s] (97%) Welcome to the show.
# [3.15s – 7.40s] (95%) Today we discuss machine learning on Apple Silicon.

# --- Access word-level timestamps ---
for token in result.tokens:
    print(f"  {token.text!r:12s}  start={token.start:.3f}s  end={token.end:.3f}s  conf={token.confidence:.2f}")

# --- Chunked transcription for long audio (2-minute chunks, 15-second overlap) ---
long_result = model.transcribe(
    "lecture_2h.wav",
    chunk_duration=120.0,
    overlap_duration=15.0,
    chunk_callback=lambda current, total: print(f"Progress: {current/total:.0%}"),
)
print(long_result.text)

# --- Beam decoding with custom sentence splitting ---
config = DecodingConfig(
    decoding=Beam(beam_size=5, length_penalty=0.013, patience=3.5, duration_reward=0.67),
    sentence=SentenceConfig(max_words=20, silence_gap=1.5, max_duration=30.0),
)
beam_result = model.transcribe("podcast.mp3", decoding_config=config)
print(beam_result.sentences)

# --- FP32 precision ---
fp32_result = model.transcribe("audio.wav", dtype=mx.float32)
```

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

### Specify Sentence Split Options

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Customize sentence splitting behavior during transcription by configuring `SentenceConfig` within `DecodingConfig`. Options include `max_words`, `silence_gap`, and `max_duration`.

```python
from parakeet_mlx import from_pretrained, DecodingConfig, SentenceConfig

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

config = DecodingConfig(
    sentence = SentenceConfig(
        # Refer to CLI Options to see what those options does
        max_words=30, silence_gap=5.0, max_duration=40.0
    )
)

result = model.transcribe("audio_file.wav", decoding_config=config)

print(result.sentences)
```

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

### Configure Decoding Strategy with DecodingConfig

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Use DecodingConfig to specify decoding algorithms (Greedy or Beam) and sentence segmentation rules. Beam search is recommended for TDT models for higher accuracy.

```python
from parakeet_mlx import DecodingConfig, Beam, Greedy, SentenceConfig, from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# Greedy decoding (default, fast)
greedy_config = DecodingConfig(decoding=Greedy())

# Beam search (TDT models only, higher accuracy)
beam_config = DecodingConfig(
    decoding=Beam(
        beam_size=5,          # number of beams
        length_penalty=0.013, # penalise short hypotheses
        patience=3.5,         # stop early factor
        duration_reward=0.67, # balance token vs duration logprobs
    ),
    sentence=SentenceConfig(
        max_words=25,         # split after N words
        silence_gap=1.0,      # split on 1-second silence
        max_duration=30.0,    # split sentences longer than 30 s
    ),
)

result = model.transcribe("audio.wav", decoding_config=beam_config)
for s in result.sentences:
    print(f"[{s.start:.1f}–{s.end:.1f}s] {s.text}")
```

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

### Compute Log-Mel Spectrogram

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

The `get_logmel` function computes a log-mel spectrogram from a raw audio array. It applies pre-emphasis, STFT, mel-filterbank, log compression, and normalization using provided preprocessing arguments. The output is a 3-D array suitable for direct model inference.

```python
import mlx.core as mx
from parakeet_mlx.audio import get_logmel, load_audio
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")
cfg = model.preprocessor_config  # PreprocessArgs

audio = load_audio("speech.wav", cfg.sample_rate)
mel = get_logmel(audio, cfg)
print(mel.shape)   # e.g. (1, 312, 80)  -> [batch=1, time_frames, n_mels=80]
print(mel.dtype)   # mlx.core.bfloat16

# Use for direct model inference
results = model.generate(mel)
print(results[0].text)
```

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

### Generate Transcription with Alignments

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Generate a transcription from the preprocessed audio (log-mel spectrogram) and obtain word-level alignments. This function accepts input in both batch and single-sequence formats. The `alignments` output is a list of `AlignedResult` objects.

```python
alignments = model.generate(mel, decoding_config=DecodingConfig())
```

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

### Sentence Splitting Options

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Customize how the transcription output is split into sentences using various configuration options.

```APIDOC
## Sentence Splitting Options

This example shows how to customize sentence splitting during transcription using `SentenceConfig` within `DecodingConfig`.

### Method
`model.transcribe()` with `decoding_config`

### Parameters
- `audio_file.wav` (string) - Path to the audio file.
- `decoding_config` (DecodingConfig) - Configuration object for decoding.
  - `sentence.max_words` (int) - The maximum number of words allowed in a single sentence. Default is 30.
  - `sentence.silence_gap` (float) - The duration of silence in seconds that triggers a sentence break. Default is 5.0 seconds.
  - `sentence.max_duration` (float) - The maximum duration in seconds for a sentence. Default is 40.0 seconds.

### Request Example
```python
from parakeet_mlx import from_pretrained, DecodingConfig, SentenceConfig

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

config = DecodingConfig(
    sentence = SentenceConfig(
        max_words=30, silence_gap=5.0, max_duration=40.0
    )
)

result = model.transcribe("audio_file.wav", decoding_config=config)

print(result.sentences)
```

### Response
- `result.sentences` (list) - A list of `AlignedSentence` objects, with sentence boundaries determined by the specified configuration.
```

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

### BaseParakeet.generate

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Transcribes audio from a pre-computed log-mel spectrogram. Supports single and batched inputs, returning a list of AlignedResult objects.

```APIDOC
## `BaseParakeet.generate` — Transcribe from a log-mel spectrogram

Low-level entry point that accepts a pre-computed log-mel spectrogram as an `mx.array`. Supports both single `[seq, feat]` and batched `[batch, seq, feat]` inputs and always returns a `list[AlignedResult]` (one per batch item). Useful when audio preprocessing is managed externally or for batch inference pipelines.

```python
import mlx.core as mx
from parakeet_mlx import from_pretrained, DecodingConfig
from parakeet_mlx.audio import get_logmel, load_audio

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# --- Single input ---
audio = load_audio("audio.wav", model.preprocessor_config.sample_rate)
mel = get_logmel(audio, model.preprocessor_config)  # shape: [1, seq, 80]

results = model.generate(mel, decoding_config=DecodingConfig())
print(results[0].text)

# --- Batched input (pad mel spectrograms to same length) ---
audio_a = load_audio("a.wav", model.preprocessor_config.sample_rate)
audio_b = load_audio("b.wav", model.preprocessor_config.sample_rate)
mel_a = get_logmel(audio_a, model.preprocessor_config)  # [1, T_a, 80]
mel_b = get_logmel(audio_b, model.preprocessor_config)  # [1, T_b, 80]

T = max(mel_a.shape[1], mel_b.shape[1])
mel_a_pad = mx.pad(mel_a, [(0,0),(0, T - mel_a.shape[1]),(0,0)])
mel_b_pad = mx.pad(mel_b, [(0,0),(0, T - mel_b.shape[1]),(0,0)])
batch_mel = mx.concatenate([mel_a_pad, mel_b_pad], axis=0)  # [2, T, 80]

batch_results = model.generate(batch_mel)
for i, r in enumerate(batch_results):
    print(f"File {i}: {r.text}")
```
```

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

### Transcribe Audio with Chunking

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Transcribe audio files using chunking for longer audio. Specify `chunk_duration` and `overlap_duration` for processing.

```python
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

result = model.transcribe("audio_file.wav", chunk_duration=60 * 2.0, overlap_duration=15.0)

print(result.sentences)
```

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

### BaseParakeet.transcribe_stream

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Enables real-time streaming transcription using a context manager. Accepts incremental audio chunks and provides access to finalized and draft tokens.

```APIDOC
## `BaseParakeet.transcribe_stream` — Real-time streaming transcription

Returns a `StreamingParakeet` context manager that accepts incremental audio chunks via `add_audio()`. Internally switches the encoder to local (windowed) attention to enable causal chunk-by-chunk processing. Exposes `finalized_tokens`, `draft_tokens`, and a `result` property that returns the current full transcript at any point.

```python
from parakeet_mlx import from_pretrained
from parakeet_mlx.audio import load_audio

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

audio = load_audio("audio.wav", model.preprocessor_config.sample_rate)
chunk_size = model.preprocessor_config.sample_rate  # 1-second chunks

with model.transcribe_stream(
    context_size=(256, 256),   # (left_context_frames, right_context_frames)
    depth=2,                   # first 2 encoder layers match non-streaming exactly
    keep_original_attention=False,  # switch to local attention (recommended)
) as streamer:
    for start in range(0, len(audio), chunk_size):
        chunk = audio[start : start + chunk_size]
        streamer.add_audio(chunk)

        # Live transcript (finalized + draft tokens)
        print(f"\r{streamer.result.text}", end="", flush=True)

    # Final result after all audio is fed
    final = streamer.result
    print()
    for sentence in final.sentences:
        print(f"[{sentence.start:.2f}s – {sentence.end:.2f}s] {sentence.text}")

# Finalized (stable) tokens vs draft (may be revised) tokens
# streamer.finalized_tokens  -> list[AlignedToken]
# streamer.draft_tokens      -> list[AlignedToken]
```
```

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

### Local Attention

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Configure the model to use local attention for potentially faster inference, especially on longer sequences.

```APIDOC
## Local Attention

This example demonstrates how to enable local attention in the model's encoder. Local attention can improve efficiency by focusing on a subset of the input sequence.

### Method
`model.encoder.set_attention_model()`

### Parameters
- `attention_model_name` (string) - The name of the attention model to use. `"rel_pos_local_attn"` is a common choice, following NeMo's naming convention.
- `attention_window_size` (tuple of two ints) - Specifies the size of the local attention window. For example, `(256, 256)` indicates a window of 256 frames before and 256 frames after the current position.

### Request Example
```python
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

model.encoder.set_attention_model(
    "rel_pos_local_attn", 
    (256, 256),
)

result = model.transcribe("audio_file.wav")

print(result.sentences)
```

### Response
- `result.sentences` (list) - A list of `AlignedSentence` objects containing the transcription.
```

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

### Switch Attention Mechanism with set_attention_model

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Dynamically switch the encoder's attention mechanism between full relative-position attention and local windowed attention. Local attention reduces memory usage for long sequences.

```python
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# Switch to local attention with a 256-frame symmetric context window
model.encoder.set_attention_model(
    "rel_pos_local_attn",
    (256, 256),   # (left_context_frames, right_context_frames)
)

# Transcribe a very long file without chunking
result = model.transcribe("long_lecture.wav")
print(result.text)

# Restore full attention
model.encoder.set_attention_model("rel_pos")
```

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

### Enable Local Attention for Transcription

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Use local attention for transcription by setting the attention model in the encoder. This follows NeMo's naming convention.

```python
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

model.encoder.set_attention_model(
    "rel_pos_local_attn", # Follows NeMo's naming convention
    (256, 256),
)

result = model.transcribe("audio_file.wav")

print(result.sentences)
```

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

### BaseParakeet.transcribe

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

Transcribes a single audio file, handling format conversions and resampling. Supports chunked transcription for long audio with configurable overlap and merging strategies, as well as advanced decoding options.

```APIDOC
## `BaseParakeet.transcribe` — Transcribe an audio file

Transcribes a single audio file at the given path. Handles mono/stereo conversion and resampling internally via FFmpeg. When `chunk_duration` is specified the audio is split into overlapping windows and merged using longest-contiguous or LCS overlap algorithms. Returns a single `AlignedResult`.

```python
from parakeet_mlx import from_pretrained, DecodingConfig, SentenceConfig, Beam, Greedy
import mlx.core as mx

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# --- Basic transcription ---
result = model.transcribe("interview.mp3")
print(result.text)
# "Welcome to the show. Today we discuss machine learning on Apple Silicon."

# --- Access sentence-level timestamps ---
for sentence in result.sentences:
    print(f"[{sentence.start:.2f}s – {sentence.end:.2f}s] ({sentence.confidence:.0%}) {sentence.text}")
# [0.00s – 3.12s] (97%) Welcome to the show.
# [3.15s – 7.40s] (95%) Today we discuss machine learning on Apple Silicon.

# --- Access word-level timestamps ---
for token in result.tokens:
    print(f"  {token.text!r:12s}  start={token.start:.3f}s  end={token.end:.3f}s  conf={token.confidence:.2f}")

# --- Chunked transcription for long audio (2-minute chunks, 15-second overlap) ---
long_result = model.transcribe(
    "lecture_2h.wav",
    chunk_duration=120.0,
    overlap_duration=15.0,
    chunk_callback=lambda current, total: print(f"Progress: {current/total:.0%}"),
)
print(long_result.text)

# --- Beam decoding with custom sentence splitting ---
config = DecodingConfig(
    decoding=Beam(beam_size=5, length_penalty=0.013, patience=3.5, duration_reward=0.67),
    sentence=SentenceConfig(max_words=20, silence_gap=1.5, max_duration=30.0),
)
beam_result = model.transcribe("podcast.mp3", decoding_config=config)
print(beam_result.sentences)

# --- FP32 precision ---
fp32_result = model.transcribe("audio.wav", dtype=mx.float32)
```
```

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

### Streaming Transcription

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Perform real-time transcription using the `transcribe_stream` method for continuous audio input.

```APIDOC
## Streaming Transcription

This example demonstrates how to perform real-time transcription using the `transcribe_stream` method. It processes audio in chunks and provides intermediate transcription results.

### Method
`model.transcribe_stream()`

### Parameters
- `context_size` (tuple of two ints) - `(left_context, right_context)` frames for attention windows. Controls the amount of past and future audio the model considers. Default: `(256, 256)`.
- `depth` (int) - Number of encoder layers that preserve exact computation across chunks. Higher values increase consistency with non-streaming mode but also computation. Default: 1.
- `keep_original_attention` (bool) - If `False`, switches to local attention for streaming (recommended). If `True`, keeps the original attention mechanism, which might be less suitable for streaming. Default: `False`.

### Request Example
```python
from parakeet_mlx import from_pretrained
from parakeet_mlx.audio import load_audio
import numpy as np

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

# Create a streaming context
with model.transcribe_stream(
    context_size=(256, 256),  # (left_context, right_context) frames
) as transcriber:
    # Simulate real-time audio chunks
    audio_data = load_audio("audio_file.wav", model.preprocessor_config.sample_rate)
    chunk_size = model.preprocessor_config.sample_rate  # 1 second chunks

    for i in range(0, len(audio_data), chunk_size):
        chunk = audio_data[i:i+chunk_size]
        transcriber.add_audio(chunk)

        # Access current transcription
        result = transcriber.result
        print(f"Current text: {result.text}")

        # Access finalized and draft tokens
        # transcriber.finalized_tokens
        # transcriber.draft_tokens
```

### Response
- `result.text` (string) - The current transcribed text.
- `transcriber.finalized_tokens` (list) - Tokens that have been finalized.
- `transcriber.draft_tokens` (list) - Tokens that are still being processed.
```

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

### Chunking Transcription

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Transcribe audio files by splitting them into chunks for processing. This is useful for handling long audio files efficiently.

```APIDOC
## Chunking Transcription

This example demonstrates how to transcribe an audio file by dividing it into manageable chunks.

### Method
`model.transcribe()`

### Parameters
- `audio_file.wav` (string) - Path to the audio file.
- `chunk_duration` (float) - The duration of each chunk in seconds. Default is 120.0 seconds.
- `overlap_duration` (float) - The duration of overlap between consecutive chunks in seconds. Default is 15.0 seconds.

### Request Example
```python
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

result = model.transcribe("audio_file.wav", chunk_duration=60 * 2.0, overlap_duration=15.0)

print(result.sentences)
```

### Response
- `result.sentences` (list) - A list of `AlignedSentence` objects containing the transcribed text and timestamps.
```

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

### Accessing Transcript Data with AlignedResult

Source: https://context7.com/senstella/parakeet-mlx/llms.txt

The AlignedResult, AlignedSentence, and AlignedToken dataclasses provide hierarchical access to transcription data, including text, timestamps, and confidence scores. Use dataclasses.asdict to export results.

```python
from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")
result = model.transcribe("speech.wav")

# Top-level result
print(result.text)          # "Hello world. How are you?"
print(len(result.sentences))  # 2
print(len(result.tokens))     # flat list of all AlignedToken across sentences

# Sentence level
for sentence in result.sentences:
    print(sentence.text)       # "Hello world."
    print(sentence.start)      # 0.32   (seconds)
    print(sentence.end)        # 1.84
    print(sentence.duration)   # 1.52
    print(sentence.confidence) # 0.973  (geometric mean of token confidences)

    # Token / word level
    for token in sentence.tokens:
        print(token.text)       # " Hello"
        print(token.id)         # vocabulary index
        print(token.start)      # 0.32
        print(token.end)        # 0.76
        print(token.duration)   # 0.44
        print(token.confidence) # 0.98

# Filter high-confidence sentences only
reliable = [s for s in result.sentences if s.confidence > 0.90]

# Export to dict
import dataclasses
sentence_dicts = [dataclasses.asdict(s) for s in result.sentences]
```

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

### Beam Decoding

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Utilize beam decoding for improved transcription accuracy by exploring multiple hypotheses.

```APIDOC
## Beam Decoding

This example shows how to use beam decoding to enhance transcription accuracy. Beam decoding explores multiple possible transcription paths to find the most likely one.

### Method
`model.transcribe()` with `decoding_config`

### Parameters
- `audio_file.wav` (string) - Path to the audio file.
- `decoding_config` (DecodingConfig) - Configuration object for decoding.
  - `decoding.beam_size` (int) - The number of beams to keep at each step. Higher values explore more possibilities but increase computation.
  - `decoding.length_penalty` (float) - Penalty applied to the length of the hypothesis. Helps balance shorter and longer sequences.
  - `decoding.patience` (float) - Used for early stopping during beam search. Stops if no improvement is seen for a certain number of steps.
  - `decoding.duration_reward` (float) - Reward applied based on the duration of the hypothesis. Can influence the model's preference for certain durations.

### Request Example
```python
from parakeet_mlx import from_pretrained, DecodingConfig, Beam

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

config = DecodingConfig(
    decoding = Beam(
        beam_size=5, length_penalty=0.013, patience=3.5, duration_reward=0.67
    )
)

result = model.transcribe("audio_file.wav", decoding_config=config)

print(result.sentences)
```

### Response
- `result.sentences` (list) - A list of `AlignedSentence` objects representing the transcription.
```

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

### Timestamp Result Structure

Source: https://github.com/senstella/parakeet-mlx/blob/master/README.md

Details the structure of the transcription results, including text, sentences, and token-level alignments with timestamps.

```APIDOC
## Timestamp Result Structure

This section describes the data structures returned by the transcription methods, providing detailed alignment information.

### `AlignedResult`
- `text` (string): The full transcribed text of the audio.
- `sentences` (list): A list of `AlignedSentence` objects, representing segmented sentences.

### `AlignedSentence`
- `text` (string): The text content of the sentence.
- `start` (float): The start time of the sentence in seconds.
- `end` (float): The end time of the sentence in seconds.
- `duration` (float): The duration of the sentence (`end` - `start`).
- `tokens` (list): A list of `AlignedToken` objects, representing word or token-level alignments within the sentence.

### `AlignedToken`
- `text` (string): The text of the token or word.
- `start` (float): The start time of the token in seconds.
- `end` (float): The end time of the token in seconds.
- `duration` (float): The duration of the token (`end` - `start`).
```

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