Map device buttons

Follow along with the runnable example. This guide walks through the Device buttons example in corti-examples — bootstrap your build from it or use it as reference.

Handheld dictation microphones (Philips SpeechMike, SpeechOne, PowerMic, Foot Control) have physical buttons (Record, Stop, F1–F4, EOL/Prio, and more). This guide maps those buttons to recording control and commands directly in the browser over WebHID, with no native driver or browser extension.

This guide is about wiring a device’s buttons. For choosing the right microphone hardware for audio quality, see Recommended Microphones.

WebHID is Chromium-only (Chrome / Edge) and requires a secure context (localhost is fine). requestDevice() must be called from a user gesture, and granted devices reconnect automatically on later visits.

Connect a device

Use the dictation_support library, which decodes each device’s raw HID reports into semantic button events. Create a DictationDeviceManager, subscribe to button events via addButtonEventListener, and call requestDevice() from a user gesture (a Connect button click). See the device buttons example in corti-examples for the setup code.

From button reports to actions

dictation_support reports a bitmask of the buttons currently pressed — a level, not an edge. Holding Record keeps its bit set across successive reports. To get discrete presses and releases, diff the previous mask against the new one.

JavaScript

const rising  = (prev: number, next: number, bit: number) => (next & bit) !== 0 && (prev & bit) === 0;
const falling = (prev: number, next: number, bit: number) => (next & bit) === 0 && (prev & bit) !== 0;

Map each button bit to one of three actions, then resolve the effects on each transition:

JavaScript

type ButtonAction =
  | { type: "toggle" }                      // press flips recording on/off
  | { type: "push" }                        // hold to record, release to stop
  | { type: "command"; commandId: string }; // fire a command on press

function computeEffects(prev: number, next: number, mappings: Record<number, ButtonAction>) {
  const effects = [];
  for (const [bit, action] of Object.entries(mappings).map(([b, a]) => [Number(b), a] as const)) {
    if (action.type === "command" && rising(prev, next, bit)) {
      effects.push({ kind: "command", commandId: action.commandId });
    } else if (action.type === "push") {
      if (rising(prev, next, bit))  effects.push({ kind: "record", op: "start" });
      if (falling(prev, next, bit)) effects.push({ kind: "record", op: "stop" });
    } else if (action.type === "toggle" && rising(prev, next, bit)) {
      effects.push({ kind: "record", op: "toggle" });
    }
  }
  return effects;
}

Keeping this bitmask-diffing logic pure (no WebHID calls) makes it easy to unit-test button behavior without a physical device. Let users learn a mapping by pressing the button — capture the next-pressed bit — so only the buttons a device actually has appear in your UI.

Drive recording and commands

Route each resolved effect to its target. Recording effects call dictation.startRecording(), dictation.stopRecording(), or dictation.toggleRecording() on the Dictation Web Component; command effects dispatch client-side against your own registry, exactly as in the Commands guide.

The Corti API does not execute button-triggered commands — a command-mapped button fires locally against your own command handler. Only spoken command phrases are recognized server-side.

Activation model

Tie the buttons to the microphone you’re actually recording with: only let them drive a surface while that surface has the handheld device selected as its mic. Selecting a built-in mic leaves the buttons inert; selecting the handheld activates them. This mirrors how the Web Component’s keyboard push-to-talk / toggle keys drive the same startRecording / stopRecording / toggleRecording methods.

Persist button mappings per API client (e.g. keyed by clientId:tenant) so a user’s device setup follows them across sessions.

Next steps

Commands

Build the command handler that button-mapped commands dispatch to.

Recommended Microphones

Choose the right handheld or headset mic for dictation.

Example code

The complete, runnable Device buttons example in corti-examples.

Please contact us for help or questions.

Endpoints

Features

Best Practices

Guides

Resources

Connect a device

From button reports to actions

Drive recording and commands

Activation model

Next steps

Commands

Recommended Microphones

Example code

​Connect a device

​From button reports to actions

​Drive recording and commands

​Activation model

​Next steps

Commands

Recommended Microphones

Example code

Connect a device

From button reports to actions

Drive recording and commands

Activation model

Next steps