`sma voice`

Manage local speech-to-text via the voice extension.

Hierarchy note: sma voice is an extension action command, not a top-level command. Top-level entry is sma extension.

Usage

sma voice <subcommand> [options]

Subcommands (current version)

models
status
on [models...]
init [models...]
off
install [models...]
use <modelId>
transcribe <audioPath>

`on` key options

--models-dir <path>: model directory (default ~/.ship/models/voice)
--active-model <modelId>: set active model
--no-install: write config only, skip download
--force: overwrite existing model files
--hf-token <token>: token for private/gated models

`init` key options

[models...]: model IDs (if omitted, interactive multi-select is shown in TTY)
--active-model <modelId>: active model (if omitted with multiple selected models, interactive select is shown)
--no-install-model: skip model download, only write config
--no-install-deps: skip Python dependency install
--python <bin>: Python executable path
--venv-dir <path>: fallback venv dir for PEP 668 environments
--no-pip-upgrade: install deps without pip -U
--pip-timeout-ms <ms>: pip install timeout in milliseconds

`install` key options

--models-dir <path>
--force
--hf-token <token>

`transcribe` key options

<audioPath>: local audio path
--language <code>: language hint (for example zh / en)

Examples

sma voice models
sma voice init
sma voice on SenseVoiceSmall
sma voice install whisper-large-v3-turbo --force
sma voice use whisper-large-v3-turbo
sma voice transcribe ./demo.ogg --language en
sma voice off

Notes

Install-related actions perform a local pre-check first:

If model files already exist, download is skipped by default (--force re-downloads).
During voice init, Python dependency install is skipped when packages are already present, with explicit skip logs.

This command group usually requires an active agent runtime:

sma agent on

In non-interactive environments (CI/scripts), pass models explicitly, for example:

sma voice init SenseVoiceSmall