Skip to content
Registry

voice

v0.1.2

Speak to the console — bundled streaming speech-to-text for live dictation, optional host whisper.cpp for final-pass and file transcription, read-aloud, and remote speech providers, with a mic chip and a voice page.

license: Apache-2.0audiodictationspeechstttranscriptionttsvoice

Install

bash
iii trigger compose::add worker=voice@next

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions15

voice::configuration-id

Function

Returns this worker instance's effective configuration entry ID, without its value.

Request
Empty object
Response
  • idstringrequired

voice::dictation::list

Function

List the dictation sessions this worker currently holds open, with their age, audio duration and idle time.

Request
Empty object
Response
  • sessionsobject[]required
    • duration_secsnumber· floatrequired
    • idle_secsinteger· uint64requiredmin 0
    • modelstringrequired
    • segmentsinteger· uint32requiredmin 0
    • session_idstringrequired
    • started_at_msinteger· int64required

voice::dictation::push

Function

Feed one chunk of 16 kHz mono 16-bit PCM (base64, at most 64 KiB) to an open dictation session. Chunks carry a rising seq; ~100 ms per chunk keeps partial text prompt.

Request
  • pcm16_base64stringrequired

    Little-endian signed 16-bit PCM, 16 kHz mono, base64.

  • seqinteger· uint64requiredmin 0

    Rising per-session counter; a chunk not after the last accepted one is rejected.

  • session_idstringrequired
Response
  • acceptedbooleanrequired
  • queued_msinteger· uint32requiredmin 0

    Milliseconds of audio this chunk held.

  • seqinteger· uint64requiredmin 0

voice::dictation::start

Function

Open a dictation session. Transcript events (partial, final, closed) are delivered to output_function_id as audio arrives through voice::dictation::push; stop with voice::dictation::stop. Audio must be 16 kHz mono 16-bit PCM.

Request
  • output_function_idstringrequired

    Function that receives every transcript event of this session.

  • sample_rateinteger· uint32min 0

    Sample rate of the audio the caller will push. Only 16000 is accepted.

Response
  • modelstringrequired
  • sample_rateinteger· uint32requiredmin 0
  • session_idstringrequired

voice::dictation::stop

Function

Close a dictation session, flush the recognizer and return the whole transcript. discard=true throws the text away instead.

Request
  • discardboolean

    Drop the transcript instead of returning it.

  • session_idstringrequired
Response
  • duration_secsnumber· floatrequired
  • segmentsobject[]required
    • end_secsnumber· float
    • segmentinteger· uint32requiredmin 0
    • start_secsnumber· float
    • textstringrequired
  • session_idstringrequired
  • textstringrequired

voice::doctor

Function

Report the speech-to-text backend and whether its model is installed and loaded, the read-aloud backend and whether its command exists, and how many dictation sessions are open.

Request
Empty object
Response
  • sessionsinteger· uintrequiredmin 0
  • sttobjectrequired
    • backendstringrequired

      `local`, `whisper_cpp`, `router` or `openai`.

    • final_load_msinteger· uint64min 0
    • final_modelstringrequired

      The second-pass model that gives final text its punctuation and accuracy, and where it stands.

    • final_stateone ofrequired

      Where the second-pass model stands, for `voice::doctor`.

      one of (6)
      Variant 1
      valuestringenum off
      Variant 2
      valuestringenum missing
      Variant 3
      valuestringenum downloading
      Variant 4
      valuestringenum installed
      Variant 5
      valuestringenum loaded
      Variant 6
      valuestringenum unknown
    • installedbooleanrequired
    • live_installedbooleanrequired
    • live_loadedbooleanrequired
    • live_modelstringrequired

      The local streaming model that shows live words and finds sentence ends while dictating, whatever the engine.

    • load_msinteger· uint64min 0
    • loadedbooleanrequired
    • modelstringrequired

      The model that writes final text: bundled local, whisper.cpp GGML, router, or OpenAI-compatible endpoint model.

    • models_dirstringrequired
    • problemstring

      Set when the local model id is unknown or the selected host/remote backend is unavailable or incomplete.

  • ttsobjectrequired
    • availablebooleanrequired
    • backendstringrequired

      `host`, `openai`, or `off`.

    • commandstring
    • deviceany of

      Requested Piper policy only, not an assertion that GPU is available.

      any of (2)
      Variant 1
      one of (2)
      Variant 1
      valuestringenum auto
      Variant 2
      valuestringenum cpu
      Variant 2
      valuenull
    • modelstringrequired
    • playinginteger· uintrequiredmin 0

      Legacy field; browser playback is not tracked on the worker.

    • problemstring
  • versionstringrequired

voice::models::download

Function

Download a local speech model (the active one when id is omitted), verifying every file's checksum. Progress arrives on the voice::model-progress trigger.

Request
  • idstring

    Model id from voice::models::list; omit for the active one.

Response
  • bytesinteger· uint64requiredmin 0

    Bytes written by this call (0 when everything was already present).

  • idstringrequired
  • installedbooleanrequired

voice::models::list

Function

List the speech models the local backend can run, which one is active, and whether each is installed under models_dir.

Request
Empty object
Response
  • activestringrequired

    The model the configuration names.

  • modelsobject[]required
    • authorstringrequired

      Who trained the model; CC-BY weights must carry this when redistributed.

    • idstringrequired
    • installedbooleanrequired
    • kindall ofrequired

      `streaming_transducer` (live partials), `offline_nemo_transducer` (second pass), `whisper_ggml` (whisper-cli weights), or `piper_onnx` (neural TTS).

      all of (1)
      Variant 1
      one of (4)
      Variant 1
      valuestringenum streaming_transducer
      Variant 2
      valuestringenum offline_nemo_transducer
      Variant 3
      valuestringenum whisper_ggml
      Variant 4
      valuestringenum piper_onnx
    • languagesstring[]required
    • licensestringrequired

      SPDX id of the model weights' license.

    • namestringrequired
    • size_bytesinteger· uint64requiredmin 0
    • sourcestringrequired

      Model card with the license text and the files' origin.

  • models_dirstringrequired

voice::models::remove

Function

Delete a downloaded local model from models_dir. Configured ONNX transcription models may download on use; Whisper and Piper models require an explicit download.

Request
  • idstringrequired

    Model id from voice::models::list.

Response
  • idstringrequired
  • removedbooleanrequired

voice::on-config-change

Function

Internal: hot-reload the voice worker from the authoritative configuration when it changes, swapping the per-call snapshot.

Request
  • idstring

    Configuration id that changed (advisory; the handler re-fetches).

Response
  • okbooleanrequired

voice::speak

Function

Synthesize text and return audio_base64 plus mime to the requesting caller. Every backend (host, piper, openai, router) returns audio for client-side playback; nothing plays on the worker machine. Markdown formatting is omitted by default; set text_format=plain for literal text. host uses say/espeak; piper uses a local neural voice.

Request
  • rate_wpminteger· uint32min 0

    Speaking rate in words per minute (host backend).

  • textstringrequired

    What to say. Markdown is converted to prose before tts.max_speak_chars is applied.

  • text_formatall of

    `markdown` (default) removes presentation syntax; `plain` keeps literal symbols.

    all of (1)
    Variant 1
    one of (2)
    Variant 1
    valuestringenum markdown
    Variant 2
    valuestringenum plain
  • voicestring

    Voice name for the backend; empty uses the configured default.

Response
  • audio_base64string

    Base64 audio for the requesting caller to play, on every enabled backend.

  • backendstringrequired

    `host`, `piper`, `openai`, or `router`.

  • mimestring

    MIME type of `audio_base64`.

  • playedbooleanrequired

    Legacy compatibility field; always false. Playback belongs to the caller.

  • speech_idstringrequired

    Unique id of this synthesis result.

voice::speak::stop

Function

Legacy server-playback stop (returns stopped=0). Audio is now returned to the caller; stop its local audio element to stop browser playback.

Request
  • speech_idstring

    Legacy playback id; no effect on client-side audio.

Response
  • stoppedinteger· uintrequiredmin 0

    Always zero: playback is now owned by each client.

voice::speech::prepare

Function

Prepare a growing Markdown message as plain speech text without synthesizing audio. Incomplete inline syntax is withheld until complete=true or more text arrives. Returns the configured per-request speech limit for client-side chunking; no state, downloads or playback.

Request
  • completeboolean

    Flush incomplete syntax only when the message is no longer growing.

  • textstringrequired
Response
  • max_chunk_charsinteger· uintrequiredmin 0
  • textstringrequired

voice::transcribe

Function

Transcribe a WAV file to text with timestamped segments. Pass a path on the worker's host or the file itself as base64 (up to max_audio_bytes). Any sample rate and channel count; the audio is downmixed and resampled.

Request
  • audio_base64string

    The WAV file itself, base64.

  • languagestring

    Language hint (ISO 639-1), used by the remote backend.

  • pathstring

    Path of a WAV file on the machine running the worker.

Response
  • backendstringrequired

    `local`, `whisper_cpp`, `openai`, or `router`.

  • duration_secsnumber· floatrequired
  • modelstringrequired
  • segmentsobject[]required
    • end_secsnumber· float
    • segmentinteger· uint32requiredmin 0
    • start_secsnumber· float
    • textstringrequired
  • textstringrequired

voice::ui-content

Function

Serve the voice worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).

Request
  • pathstringrequired

    The asset path from the trigger config (e.g. `state/page.js`).

Response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

Triggers5

voice::model-progress

Trigger

Bytes received while a speech model downloads, one event per megabyte and a final done event (with error when the download failed).

Invocation
  • session_idstring

    Only deliver events for this dictation session.

  • speech_idstring

    Only deliver the end of this playback (`voice::speech-ended`).

Return
valueunknown

voice::session-started

Trigger

A dictation session is ready for audio.

Invocation
  • session_idstring

    Only deliver events for this dictation session.

  • speech_idstring

    Only deliver the end of this playback (`voice::speech-ended`).

Return
valueunknown

voice::session-stopped

Trigger

A dictation session ended (stopped, discarded, idle, or worker shutdown).

Invocation
  • session_idstring

    Only deliver events for this dictation session.

  • speech_idstring

    Only deliver the end of this playback (`voice::speech-ended`).

Return
valueunknown

voice::speech-ended

Trigger

A host read-aloud started by voice::speak finished: reason ended, stopped or failed. Filter with speech_id.

Invocation
  • session_idstring

    Only deliver events for this dictation session.

  • speech_idstring

    Only deliver the end of this playback (`voice::speech-ended`).

Return
valueunknown

voice::transcript

Trigger

A dictation session produced text: a partial replaces the in-progress text, a final commits a segment, closed ends the session. Filter with session_id.

Invocation
  • session_idstring

    Only deliver events for this dictation session.

  • speech_idstring

    Only deliver the end of this playback (`voice::speech-ended`).

Return
valueunknown

Search the registry

Find workers, kits and executables, or jump to a page.