Documentation
    Preparing search index...

    Interface HostMediaBridge

    Host-bridge contract for pluggable media backends.

    The browser reference implementation (createBrowserMediaBridge) mirrors napplet-reported metadata/state to navigator.mediaSession and installs setActionHandler callbacks that fan into the bridge's onAction subscribers. It satisfies this interface with all 5 fields implemented (setActiveSession switches the active session and optionally re-applies action-handler narrowing; destroySession tears down the silent-audio prime on last-session teardown).

    Host apps (Electron, Tauri) implement this interface in their own code and pass it via createMediaService({ hostBridge: myBridge }) — the service then delegates metadata/state mirroring + action routing to the bridge and remains browser-free. Session-ownership bookkeeping (which windowId owns which sessionId, which send callback routes media.command back to which napplet) stays in the service layer — that's wire-protocol concern, not a bridge concern.

    Reference implementations for Electron / Tauri are explicitly out of v1.4 scope and live in host-app examples / follow-up milestones (see REQUIREMENTS.md "Future Requirements").

    // Host-app pseudocode (Electron main-process relay):
    const electronBridge: HostMediaBridge = {
      setMetadata(sessionId, md) { mediaBridge.sendMetadata({ sessionId, md }); },
      setPlaybackState(sessionId, state) { mediaBridge.sendPlaybackState({ sessionId, state }); },
      onAction(cb) {
        const handler = (_: unknown, msg: { sessionId: string; action: MediaAction; value?: number }) =>
          cb(msg.sessionId, msg.action, msg.value);
        mediaBridge.onAction(handler);
        return () => mediaBridge.offAction(handler);
      },
    };
    const media = createMediaService({ hostBridge: electronBridge });
    runtime.registerService('media', media);
    interface HostMediaBridge {
        destroySession?(sessionId: string): void;
        onAction(
            callback: (
                sessionId: string,
                action: MediaAction,
                value?: number,
            ) => void,
        ): () => void;
        setActiveSession?(
            sessionId: string | null,
            actions?: readonly MediaAction[],
        ): void;
        setMetadata(sessionId: string, metadata: MediaMetadata): void;
        setPlaybackState(
            sessionId: string,
            state: "playing" | "paused" | "stopped" | "buffering",
        ): void;
    }
    Index

    Methods

    destroySession? onAction setActiveSession? setMetadata setPlaybackState

    Methods

    • Optional: tear down per-session resources. The browser reference impl uses this to remove the silent-audio prime element when the last session is destroyed. Bridges that need no per-session teardown may omit this field.

      Parameters

      • sessionId: string

      Returns void

    • Subscribe to OS-level action events (user clicks play/pause/seek/next/prev on the transport surface). Returns an unsubscribe handle.

      The callback receives (sessionId, action, value?). sessionId is the bridge's currently-active session (the browser impl tracks this internally via setActionHandler-at-fire-time; native impls track via setActiveSession). value is populated for action === 'seek' (seek target in seconds) and for action === 'volume' (0.0-1.0). The service dispatches the resulting media.command envelope to the owning napplet of that session.

      Parameters

      • callback: (sessionId: string, action: MediaAction, value?: number) => void

      Returns () => void

    • Optional: notify the bridge that the active session has changed. The browser reference impl uses this to switch which session's metadata/state is mirrored to the singleton navigator.mediaSession and to install (or clear) action handlers for the session's declared capabilities.

      The optional actions parameter carries the session's declared capability set so the bridge can narrow which OS transport buttons are active. When omitted, the bridge applies its default set. Native OS bridges that track active-session state internally may omit this field entirely.

      Parameters

      • sessionId: string | null
      • Optionalactions: readonly MediaAction[]

      Returns void

    • Set the metadata displayed on the OS transport surface for a session. Called on session.create (with initial metadata) and on session.update (with merged metadata) whenever the session is the active session. Implementations MUST be idempotent.

      Parameters

      • sessionId: string
      • metadata: MediaMetadata

      Returns void

    • Set the playback state for a session. Called on media.state reports whenever the session is the active session. State strings match nap-media MediaState.status exactly. Implementations MUST be idempotent.

      Parameters

      • sessionId: string
      • state: "playing" | "paused" | "stopped" | "buffering"

      Returns void

    Settings

    Member Visibility

    On This Page

    Methods