Select a Microphone

With Headless Web SDK v0.3.1, you can pass an optional microphone deviceId so ambient recording uses the mic your user picks. Your app lists devices, builds the picker UI, and keeps the selected id in app state. Pass that deviceId through config.audio.deviceId on useAmbientSession, or through the same audio option on Platform Client start and resume. The Headless Web SDK opens capture on that device when you call start() or resume(), and does not list microphones, remember the last choice, or switch mics for you. When a session is paused, pass the same deviceId again on resume so capture continues on that microphone.

When you omit deviceId, recording uses the browser default microphone.

When you pass a deviceId

The selected microphone is applied only when audio capture starts:

Action	Behavior
`start()`	Uses the provided `deviceId`, or the browser default if omitted
`resume()`	Uses the provided `deviceId`. On Platform Client, omitting options reuses the last successful selection for that live session instance
Change `deviceId` while recording	Does not change the microphone already in use. Takes effect on the next `pause()` → `resume()`, or the next `start()`

There is no option to switch the microphone mid-session. Pause, then resume with the new deviceId.

To change microphones during a visit:

Update your app state with the new deviceId so config.audio.deviceId is current.
Call pause()
Call resume()

Expect a short capture gap between pause and resume when you change the microphone. Flowchart: Select deviceId in host app, start or resume, Recording active, User changes mic?, Update app state deviceId, pause, resume with new deviceId.

Flowchart: Select deviceId in host app, start or resume, Recording active, User changes mic?, Update app state deviceId, pause, resume with new deviceId.

Pass `deviceId` to the hook

const { start, pause, resume, submit, sessionStatus } = useAmbientSession({
  ambientSessionId,
  config: selectedMicrophoneId // New in v0.3.1
    ? { audio: { deviceId: selectedMicrophoneId } }
    : undefined,
});

Types

The following types show the options you can pass to the hook:

type AmbientMicrophoneOptions = {
  /** MediaDeviceInfo.deviceId for an audioinput device */
  deviceId?: string; // New in v0.3.1
};

type AmbientRecordingOptions = {
  audio?: AmbientMicrophoneOptions;
};

When deviceId is set, the recording uses getUserMedia with:

{
  audio: {
    deviceId: { exact: deviceId } // New in v0.3.1
  }
}

When deviceId is omitted, the browser default microphone is used.

Enumerate devices and select a microphone

You own device enumeration and how you design and implement the microphone picker UI. Request microphone permission before you enumerate if you need readable device labels in Chromium. Changing the microphone while recording is active does not switch the microphone in use. First pause, then resume so the new device is applied. The following code example shows how to enumerate devices and select a microphone while using the Headless Web SDK.

import { useCallback, useEffect, useState } from "react";
import { useAmbientSession } from "@suki-sdk/platform-react";

type AudioInputDevice = {
  deviceId: string;
  label: string;
};

export function AmbientRecorderWithMicPicker({
  ambientSessionId,
}: {
  ambientSessionId: string;
}) {
  const [microphones, setMicrophones] = useState<AudioInputDevice[]>([]);
  const [selectedDeviceId, setSelectedDeviceId] = useState<string>("");
  const [error, setError] = useState<string | null>(null);

  const refreshMicrophones = useCallback(async () => {
    setError(null);

    try {
      // Permission unlocks readable device labels in Chromium.
      const permissionStream = await navigator.mediaDevices.getUserMedia({
        audio: true,
        video: false,
      });
      permissionStream.getTracks().forEach((track) => track.stop());

      const devices = await navigator.mediaDevices.enumerateDevices();
      const inputs = devices
        .filter((device) => device.kind === "audioinput")
        .map((device, index) => ({
          deviceId: device.deviceId,
          label: device.label || `Microphone ${index + 1}`,
        }));

      setMicrophones(inputs);
      setSelectedDeviceId((current) => current || inputs[0]?.deviceId || "");
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err));
    }
  }, []);

  useEffect(() => {
    void refreshMicrophones();
  }, [refreshMicrophones]);

  const { start, pause, resume, submit, sessionStatus } = useAmbientSession({
    ambientSessionId,
    config: selectedDeviceId // New in v0.3.1
      ? {
          audio: { deviceId: selectedDeviceId },
        }
      : undefined,
  });

  const changeMicrophoneDuringRecording = async (nextDeviceId: string) => {
    setSelectedDeviceId(nextDeviceId);

    // Changing deviceId while recording does not switch the microphone in use.
    // Pause, then resume so the new device is applied.
    await pause();
    await resume();
  };

  return (
    <div>
      <label>
        Microphone
        <select
          value={selectedDeviceId}
          onChange={(event) => {
            const nextDeviceId = event.target.value;
            void changeMicrophoneDuringRecording(nextDeviceId);
          }}
        >
          {microphones.map((mic) => (
            <option key={mic.deviceId} value={mic.deviceId}>
              {mic.label}
            </option>
          ))}
        </select>
      </label>

      <button type="button" onClick={() => void refreshMicrophones()}>
        Refresh devices
      </button>

      {error ? <p>{error}</p> : null}

      <p>Status: {sessionStatus}</p>
      <button type="button" onClick={() => void start()}>
        Start
      </button>
      <button type="button" onClick={() => void pause()}>
        Pause
      </button>
      <button type="button" onClick={() => void resume()}>
        Resume
      </button>
      <button type="button" onClick={() => void submit()}>
        Submit
      </button>
    </div>
  );
}

What your app handles

List microphones in your app with enumerateDevices(), and keep only audioinput devices. The SDK does not list them for you.
Ask for microphone permission before you list devices if you need the names to be readable.
Save the chosen deviceId in your app. The SDK keeps it in memory only and does not save it to IndexedDB. Pass config.audio again after a page reload, an SDK remount, or session recovery.
If the user picks a new microphone while recording, the current microphone stays in use until you call pause(), then resume(). The hook may log a warning until that resume() succeeds.

When the device is unavailable

When you pass an exact deviceId and that device is missing, disconnected, or otherwise unavailable, getUserMedia fails. The Headless Web SDK does not automatically fall back to the browser default microphone. Mic capture failures are not a top-level AudioRecorderFailure error. They are wrapped as session lifecycle errors:

Path	Partner-facing `code`	`reason`
Failed on `start()` / `startAmbientSession`	`StartSessionFailed`	`AudioRecorderFailure`
Failed on `resume()` / `resumeAmbientSession`	`ResumeSessionFailed`	`AudioRecorderFailure`

Platform Client

You receive a structured error with code, reason, and cause. cause is the browser microphone error from getUserMedia.

React Hook

start() and resume() throw a string, not an object with error.code and error.reason.

[AmbientSession] Code: StartSessionFailed | Reason: AudioRecorderFailure | Message: Failed to start audio recorder in startSession. ...

In your UI, ask the user to pick another microphone, refresh the device list, then call start() or resume() again. Starting a session and Resuming a session list the same code and reason. Example code: Handle start failure

try {
  await start();
} catch (err) {
  // Platform: check error.code === "StartSessionFailed" && error.reason === "AudioRecorderFailure"
  // React: err is often a string that includes Code: StartSessionFailed | Reason: AudioRecorderFailure
  console.error("Failed to start ambient recording", err);
  await refreshMicrophones();
}

Changing config.audio.deviceId while recording does not switch the microphone that is already in use. The React hook may log a diagnostic warning. The new device applies on the next successful start() or resume().

For Platform Client (startAmbientSession / resumeAmbientSession) option retention, including { audio: undefined } to clear a previous in-memory selection, refer to Platform client and provider.

Partner checklist

See all the checklist items

Enumerate audioinput devices in your app.
Store the selected deviceId in your app state.
Pass it through useAmbientSession config.audio or Platform start/resume options.
On mic change during an active recording, pause then resume.
Re-supply deviceId after remount or recovery.
Handle start/resume failures when the selected device is unavailable.
Do not expect the microphone to change while recording is active, and do not expect a switchMicrophone API in this release.

Microphone FAQs

Will the SDK Remember the Selected Mic After a Page Reload?

No. Selection is in-memory only. Persist the preference in your app if needed, then pass it again on start/resume after remount.

What Happens If the Selected Device Is Unplugged?

Start or resume fails. The SDK does not fall back to another microphone automatically. The error uses code: "StartSessionFailed" or code: "ResumeSessionFailed" with reason: "AudioRecorderFailure". On React, you may receive that information as a string from error.toString().

Is Form Filling Covered?

No. Form filling deviceId support is out of scope for this release.

Is There a switchMicrophone API?

Not in this release. Use pause → resume with the new deviceId.

Limitations

You cannot change the active microphone while recording is running. Pause, then resume with the new deviceId.
There is no public switchMicrophone(deviceId) API in this release.
The SDK does not enumerate microphones or persist the user’s last choice. Your app owns listing, picker UI, and storage.
When an exact deviceId is missing or unavailable, the SDK does not fall back to the browser default microphone.
You cannot pass an external MediaStream as the audio source.
Form filling microphone selection is out of scope for this release.

Next steps

Ambient session examples Configure ambient session Manage ambient session - Guide for start, pause, and resume use cases. Platform client and provider Error handling guide

Get Started

Concepts & Feature Guides

API Reference

Resources

Select a Microphone

When you pass a deviceId

Pass `deviceId` to the hook

Types

Enumerate devices and select a microphone

What your app handles

When the device is unavailable

Platform Client

React Hook

Partner checklist

Microphone FAQs

Limitations

Next steps

When you pass a deviceId

Pass deviceId to the hook

Types

Enumerate devices and select a microphone

What your app handles

When the device is unavailable

Platform Client

React Hook

Partner checklist

Microphone FAQs

Limitations

Next steps

Pass `deviceId` to the hook