Interface IRealtimeMediaHost

Acquires the user's microphone, prompting for permission if the platform requires it.

The host owns the entire permission experience, including any pre-permission priming UI and the decision about what to do when permission is permanently denied.

OPTIONAL: creates the sampler that takes still frames from a camera or a screen share for the agent: from stream, at options.Rate frames per second (the rate the model's video track negotiated), each handed to options.OnFrame as a base64 image. The runtime creates one per capture, starts it once the device or share is open, and stops it when the capture stops; the stream's tracks belong to the capture, not the sampler.

A host without it gets FrameSampler from @memberjunction/ai-realtime-client/media, which draws through a hidden <video> and a <canvas>: what a browser host wants, so it can omit this. A host without a DOM (React Native, a native shell, a test harness) supplies its own here. When the sampler cannot start (Start() returns false, as the DOM default does without a DOM), the capture fails as unsupported and the agent is never told it can see it.

OPTIONAL: creates a controller for the user's camera and microphone, once per session.

When a host offers one, the runtime starts the microphone through it instead of AcquireMicrophone. The call then follows a device switch and survives a lost device: the controller swaps the new track into the same stream (falling back to the system default when a device goes away), and the runtime moves the driver and the recorder onto it. The runtime disposes the controller at teardown. Hosts without one keep AcquireMicrophone.

OPTIONAL: creates a recorder for this session's audio, when the platform can record and the user has consented.

Returning null — or omitting the member entirely — disables recording for the session. That is a fully supported configuration, not a degraded one: recording is consent-gated and many hosts will never offer it. The runtime's session clock is anchored independently of the recorder precisely so that unrecorded sessions still produce correct per-turn timings.

The returned recorder is unstarted — the runtime calls IRealtimeSessionRecorder.Start once it knows whether the agent's remote stream is already available.

OPTIONAL: returns the platform's audio state to what it was before AcquireMicrophone changed it.

Acquiring a microphone is not always a symmetric act. A browser hands back a stream and nothing else changes, so most hosts omit this. iOS is the counter-example: a voice call requires putting the shared audio session into a record-and-play category with the speaker route, and that setting outlives the call — every later sound in the app plays through the call route, at call volume, until something puts it back.

Called by the runtime once each time it asks for the microphone (through AcquireMicrophone or the session's controller), after the request returns, opened or failed, and the microphone tracks are stopped: when the session ends, on every exit path including a failed start, or, when the session ended while the request was pending, once the request returns, so the call undoes what the request did. When a newer session has asked for the microphone by then, that session's end makes the call instead. A session that ends before asking for the microphone gets no call. Best-effort: a rejection is logged and swallowed, because restoring audio state is never worth failing the end of a call over.

OPTIONAL: asks the user for a screen, window or browser tab to share (or one panel of the page), for the session's screen share. Always resolves: a cancelled picker or a refusal is a result.

A browser host passes it to RequestDisplayCapture from @memberjunction/ai-realtime-client/media. A host without it cannot share a screen; the runtime reports that instead of asking.