Справочник CLI

Бинарный файл speech — основная точка входа для всех задач обработки речи. Соберите с помощью make build, затем запускайте из .build/release/speech.

transcribe

Транскрибирует аудиофайлы в текст.

speech transcribe <file> [options]

Опция	По умолчанию	Описание
`<file>`		Аудиофайл для транскрипции (WAV, M4A, MP3, CAF)
`--engine`	`qwen3`	ASR-движок: `qwen3`, `qwen3-coreml`, `parakeet`, `nemotron` или `omnilingual`
`--model, -m`	`0.6B`	Вариант модели: `0.6B`, `1.7B`, или полный ID модели HuggingFace (только qwen3)
`--language`		Подсказка языка (опционально, игнорируется omnilingual)
`--window`	`10`	`[omnilingual]` Размер окна CoreML в секундах: `5` или `10`
`--backend`	`coreml`	`[omnilingual]` Бэкенд: `coreml` (Neural Engine) или `mlx` (Metal GPU)
`--variant`	`300M`	`[omnilingual mlx]` Размер: `300M`, `1B`, `3B` или `7B`
`--bits`	`4`	`[omnilingual mlx]` Биты квантизации: `4` или `8`
`--stream`		Включить потоковую транскрипцию с VAD
`--max-segment`	`10`	Максимальная длительность сегмента в секундах (потоковый режим)
`--partial`		Выдавать частичные результаты во время речи (потоковый режим)

Примеры:

# Basic transcription
speech transcribe recording.wav

# Use larger model
speech transcribe recording.wav --model 1.7B

# CoreML encoder (Neural Engine + MLX decoder)
speech transcribe recording.wav --engine qwen3-coreml

# Use Parakeet (CoreML) engine
speech transcribe recording.wav --engine parakeet

# Use Nemotron Streaming (CoreML, English with native punctuation)
speech transcribe recording.wav --engine nemotron                                 # batch
speech transcribe recording.wav --engine nemotron --stream --partial              # streaming

# Omnilingual (CoreML, 1,672 languages)
speech transcribe recording.wav --engine omnilingual                              # 10 s window
speech transcribe recording.wav --engine omnilingual --window 5                     # 5 s window

# Omnilingual (MLX, any length up to 40 s)
speech transcribe recording.wav --engine omnilingual --backend mlx                              # 300M @ 4-bit
speech transcribe recording.wav --engine omnilingual --backend mlx --variant 1B                  # 1B @ 4-bit
speech transcribe recording.wav --engine omnilingual --backend mlx --variant 3B --bits 8         # 3B @ 8-bit
speech transcribe recording.wav --engine omnilingual --backend mlx --variant 7B                  # 7B @ 4-bit

# Streaming with VAD
speech transcribe recording.wav --stream --partial

align

Выравнивание с форсированием на уровне слов — получите точные временные метки для каждого слова.

speech align <file> [options]

Опция	По умолчанию	Описание
`<file>`		Аудиофайл
`--text, -t`		Текст для выравнивания (если опущен, сначала транскрибирует)
`--model, -m`	`0.6B`	ASR-модель для транскрипции: `0.6B`, `1.7B`, или полный ID
`--aligner-model`		ID модели выравнивателя с форсированием
`--language`		Подсказка языка

Примеры:

# Auto-transcribe then align
speech align recording.wav

# Align with known text
speech align recording.wav --text "Can you guarantee that the replacement part will be shipped tomorrow?"

speak

Синтез речи из текста.

speech speak "<text>" [options]

Опция	По умолчанию	Описание
`<text>`		Текст для синтеза (опционально при использовании `--batch-file`)
`--engine`	`qwen3`	TTS-движок: `qwen3` или `cosyvoice`
`--output, -o`	`output.wav`	Путь выходного WAV-файла
`--language`	`english`	Язык. Опустите, чтобы использовать родной диалект спикера, когда задан `--speaker`.
`--stream`		Включить потоковый синтез
`--voice-sample`		Референсное аудио для клонирования голоса (работает с обоими движками `qwen3` и `cosyvoice`)
`--verbose`		Показать подробную информацию о времени выполнения

Опции Qwen3-TTS

Опция	По умолчанию	Описание
`--model`	`base`	Вариант модели: `base`, `customVoice` или полный ID HF
`--speaker`		Голос спикера (требуется `--model customVoice`)
`--instruct`		Инструкция стиля (модель CustomVoice)
`--list-speakers`		Показать доступных спикеров и выйти
`--temperature`	`0.3`	Температура сэмплирования
`--top-k`	`50`	Top-k сэмплирование
`--max-tokens`	`500`	Максимум токенов (500 = ~40 с аудио)
`--batch-file`		Файл с одним текстом на строку для пакетного синтеза
`--batch-size`	`4`	Максимальный размер пакета для параллельной генерации
`--first-chunk-frames`	`3`	Кодек-фреймы в первом потоковом чанке
`--chunk-frames`	`25`	Кодек-фреймы в каждом потоковом чанке

Опции CosyVoice3

Опция	По умолчанию	Описание
`--speakers`		Отображение спикеров для многоголосого диалога: `s1=alice.wav,s2=bob.wav`
`--cosy-instruct`		Инструкция стиля (переопределяет дефолт). Управляет стилем голоса для CosyVoice3.
`--turn-gap`	`0.2`	Пауза между репликами диалога в секундах
`--crossfade`	`0.0`	Перекрытие crossfade между репликами в секундах
`--model-id`		ID модели HuggingFace

Примеры:

# Basic TTS
speech speak "Hello, world!" --output hello.wav

# Voice cloning (Qwen3-TTS)
speech speak "Hello in your voice" --voice-sample reference.wav -o cloned.wav

# Voice cloning (CosyVoice)
speech speak "Hello in your voice" --engine cosyvoice --voice-sample reference.wav -o cloned.wav

# CosyVoice multilingual
speech speak "Hallo Welt" --engine cosyvoice --language german -o hallo.wav

# Multi-speaker dialogue
speech speak "[S1] Hello there! [S2] Hey, how are you?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o dialogue.wav

# Inline emotion/style tags
speech speak "(excited) Wow, amazing! (sad) But I have to go..." \
    --engine cosyvoice -o emotion.wav

# Combined: dialogue + emotions + voice cloning
speech speak "[S1] (happy) Great news! [S2] (surprised) Really?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o combined.wav

# Custom style instruction
speech speak "Hello world" --engine cosyvoice --cosy-instruct "Speak cheerfully" -o cheerful.wav

# Streaming synthesis
speech speak "Long text here..." --stream

# Batch synthesis from file
speech speak --batch-file texts.txt --batch-size 4

kokoro

Лёгкий синтез речи с помощью Kokoro-82M на Neural Engine (CoreML). Неавторегрессивная модель — один прямой проход, задержка ~45 мс.

speech kokoro "<text>" [options]

Опция	По умолчанию	Описание
`<text>`		Текст для синтеза
`--voice`	`af_heart`	Пресет голоса (50 доступных в 10 языках)
`--language`	`en`	Код языка: en, es, fr, hi, it, ja, pt, zh, ko, de
`--output, -o`	`kokoro_output.wav`	Путь выходного WAV-файла
`--list-voices`		Показать все доступные голоса и выйти
`--model, -m`		ID модели HuggingFace

Примеры:

# Basic Kokoro TTS
speech kokoro "Hello, world!" --voice af_heart -o hello.wav

# French voice
speech kokoro "Bonjour le monde" --voice ff_siwis --language fr -o bonjour.wav

# List all 50 voices
speech kokoro --list-voices

respond

Полнодуплексный диалог речь-в-речь с помощью PersonaPlex 7B.

speech respond [options]

Опция	По умолчанию	Описание
`--input, -i`		Входной WAV-файл аудио (24 кГц моно) (обязательно)
`--output, -o`	`response.wav`	Выходной WAV-файл ответа
`--voice`	`NATM0`	Пресет голоса (например NATM0, NATF1, VARF0)
`--system-prompt`	`assistant`	Пресет: `assistant`, `focused`, `customer-service`, `teacher`
`--system-prompt-text`		Произвольный текст system prompt (переопределяет пресет)
`--max-steps`	`200`	Макс. шагов генерации на 12.5 Гц (~16 с)
`--stream`		Выдавать аудио-чанки во время генерации
`--compile`		Включить скомпилированный трансформер (прогрев + слияние кернелов)
`--list-voices`		Показать доступные пресеты голоса
`--list-prompts`		Показать доступные пресеты system prompt
`--transcript`		Печатать текст внутреннего монолога модели
`--json`		Вывод в JSON (транскрипт, задержка, путь к аудио)
`--verbose`		Показать подробную информацию о времени выполнения

Переопределения сэмплирования

Опция	По умолчанию	Описание
`--audio-temp`	`0.8`	Температура сэмплирования аудио
`--text-temp`	`0.7`	Температура сэмплирования текста
`--audio-top-k`	`250`	Top-k кандидатов для аудио
`--repetition-penalty`	`1.2`	Штраф за повторы в аудио (1.0 = отключён)
`--text-repetition-penalty`	`1.2`	Штраф за повторы в тексте (1.0 = отключён)
`--repetition-window`	`30`	Окно штрафа за повторы в фреймах
`--silence-early-stop`	`15`	Фреймов тишины до ранней остановки (0 = отключено)
`--entropy-threshold`	`0`	Порог энтропии текста для ранней остановки (0 = отключено)
`--entropy-window`	`10`	Последовательных шагов с низкой энтропией перед ранней остановкой

Примеры:

# Basic speech-to-speech
speech respond --input question.wav

# Use a female voice with compiled transformer
speech respond -i question.wav --voice NATF1 --compile

# Stream response and show transcript
speech respond -i question.wav --stream --transcript --verbose

vad

Офлайн-детекция голосовой активности с помощью сегментации Pyannote.

speech vad <file> [options]

Опция	Описание
`<file>`	Аудиофайл для анализа
`--model, -m`	ID модели HuggingFace
`--onset`	Порог начала (начало речи)
`--offset`	Порог окончания (конец речи)
`--min-speech`	Минимальная длительность речи в секундах
`--min-silence`	Минимальная длительность тишины в секундах
`--json`	Вывод в JSON

vad-stream

Потоковая детекция голосовой активности с помощью Silero VAD v5. Обрабатывает аудио чанками по 32 мс.

speech vad-stream <file> [options]

Опция	Описание
`<file>`	Аудиофайл для анализа
`--engine`	VAD-движок: `mlx` (по умолчанию) или `coreml`
`--model, -m`	ID модели HuggingFace (выбирается автоматически по движку)
`--onset`	Порог начала
`--offset`	Порог окончания
`--min-speech`	Минимальная длительность речи в секундах
`--min-silence`	Минимальная длительность тишины в секундах
`--json`	Вывод в JSON

wake

Локальное распознавание ключевых слов с помощью KWS Zipformer (3,49M параметров, CoreML INT8, 26× реального времени, только английский).

speech wake <file> [options]

Опция	Описание
`<file>`	Аудиофайл для анализа
`--keywords`	Одно или несколько ключевых слов. Форматы: `"hey soniqo"`, `"hey soniqo:0.15:0.5"` или `"LIGHT UP\|▁ L IGHT ▁UP:0.25:2.0"` (стиль sherpa-onnx с явными BPE-фрагментами)
`--keywords-file`	Файл ключевых слов, одна запись на строку
`--model, -m`	ID модели HuggingFace. По умолчанию: `aufklarer/KWS-Zipformer-3M-CoreML-INT8`
`--json`	Вывод в JSON

diarize

Диаризация спикеров — определите, кто говорил и когда.

speech diarize <file> [options]

Опция	По умолчанию	Описание
`<file>`		Аудиофайл для анализа
`--engine`	`pyannote`	Движок диаризации: `pyannote` (сегментация + связывание спикеров) или `sortformer` (сквозной CoreML)
`--target-speaker`		Аудио для регистрации целевого спикера (только pyannote)
`--embedding-engine`	`mlx`	Движок эмбеддингов спикера: `mlx` или `coreml` (только pyannote)
`--vad-filter`		Предварительная фильтрация через Silero VAD (только pyannote)
`--rttm`		Вывод в формате RTTM
`--json`		Вывод в JSON
`--score-against`		Эталонный RTTM-файл для расчёта DER

Примеры:

# Basic diarization (pyannote, default)
speech diarize meeting.wav

# End-to-end Sortformer (CoreML, Neural Engine)
speech diarize meeting.wav --engine sortformer

# RTTM output for evaluation
speech diarize meeting.wav --rttm

# Target speaker extraction (pyannote only)
speech diarize meeting.wav --target-speaker enrollment.wav

# Score against reference
speech diarize meeting.wav --score-against reference.rttm

embed-speaker

Извлечение вектора эмбеддинга спикера из аудио.

speech embed-speaker <file> [options]

Опция	Описание
`<file>`	Аудиофайл с голосом спикера
`--engine`	Движок инференса: `mlx` (по умолчанию), `coreml` (WeSpeaker 256-мерные) или `camplusplus` (CAM++ CoreML 192-мерные)
`--json`	Вывод в JSON

denoise

Удаление фонового шума с помощью DeepFilterNet3 на Neural Engine.

speech denoise <file> [options]

Опция	По умолчанию	Описание
`<file>`		Входной аудиофайл
`--output, -o`	`input_clean.wav`	Путь выходного файла
`--model, -m`		ID модели HuggingFace

Пример:

speech denoise noisy-recording.wav -o clean.wav

compose

Generate 30 s of music from a text prompt using MAGNeT on MLX.

speech compose <prompt> [options]

Option	Default	Description
`<prompt>`		Text prompt describing the music to generate (e.g. "happy rock")
`--output, -o`	`magnet.wav`	Output WAV path (32 kHz mono)
`--variant`	`small-int4`	Model variant: `small-int4`, `small-int8`, `medium-int4`, or `medium-int8`. Resolves to `aufklarer/MAGNeT-{Small,Medium}-30secs-MLX-{4,8}bit`.
`--temperature`	`3.0`	Sampling temperature, annealed linearly per stage.
`--top-p`	`0.9`	Nucleus sampling threshold.
`--cfg-max`	`10.0`	Max classifier-free guidance coefficient.
`--cfg-min`	`1.0`	Min CFG coefficient (annealed alongside the mask schedule).
`--steps`	`20,10,10,10`	Comma-separated decoding iterations per codebook (4 values).
`--seed`		Random seed for reproducible output.

Examples:

# Default: small-int4, ~10 s wall on M-series for a 30 s clip
speech compose "happy rock" -o happy_rock.wav

# Larger model — better prompt following, slower
speech compose "lo-fi hip hop with mellow piano" --variant medium-int4 -o lofi.wav

# Reproducible
speech compose "energetic EDM with synth lead" --seed 42 -o edm.wav