city voice

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

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

Usage

city 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

city voice models
city voice init
city voice on SenseVoiceSmall
city voice install whisper-large-v3-turbo --force
city voice use whisper-large-v3-turbo
city voice transcribe ./demo.ogg --language en
city 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.
• Voice config is written to console-global ~/.ship/ship.db (extensions_config.voice), not project ship.json.

This command group usually requires an active agent runtime:

city agent start

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

city voice init SenseVoiceSmall

Example Output (Based on Current Implementation)

The examples below are aligned with current command implementations in package/src (including default output mode and field structure). Placeholder values are used for environment-specific fields.

$ city voice status
{
  "success": true,
  "data": {
    "enabled": true,
    "activeModel": "<modelId>"
  }
}

$ city voice on SenseVoiceSmall
{
  "success": true,
  "data": {
    "changed": true
  },
  "message": "daemon not reachable, executed locally"
}