useVoiceDictation

Hook for reactive roVoiceDictation events

import { useVoiceDictation } from "@roku-sdk/runtime/voice-dictation";

useVoiceDictation(): VoiceDictationHook

Description

Hook for reactive roVoiceDictation events.

roVoiceDictation is a control surface only (see getVoiceDictation); recognized text and lifecycle phases are delivered through the Input runtime API. This hook hides that wiring: it subscribes to useInput internally and exposes a single dictationParams signal filtered to command: "dictation" events.

Firmware routes recognized dictation through the voice input handler, so that is the channel this hook watches.

Each dictation event — every phase, start / text / end — is acknowledged with updateVoiceInputStatus({ status: "success" }) as soon as it arrives; firmware blocks up to 5s per event until the app responds (equivalent to roInput.EventResponse). The ack goes out first and dictationParams is published on a microtask, so no app code reacting to the signal can eat into that budget. Voice events for other commands are left alone for whoever owns them to answer.

After an end event is published the signal returns to null, so a consumer that mounts or re-runs later sees "no session" rather than a stale end.

Return values

VoiceDictationHook with a reactive dictationParams accessor.

Example

const { dictationParams } = useVoiceDictation();

createEffect(() => {
    const params = dictationParams();
    if (!params) return;
    switch (params.dictation_event) {
        case DictationEvent.Start: // listening started
        case DictationEvent.Text:  // params.text has recognized text
        case DictationEvent.End:   // dictation ended
    }
});

Types

VoiceDictationHook

Return type for the useVoiceDictation hook.

type VoiceDictationHook = {
    dictationParams: Accessor<DictationInputParams | null>;
};