Browser SDK - Gamilab

The Gamilab Browser SDK abstracts the usage of the Gamilab application over WebSockets. It handles retries and state management internally.

If a function fails, it is a definite failure. Do not retry -- it means the network conditions are insufficient or a required permission was not granted. In this case, a page reload is necessary to reinitialize the SDK.

The SDK is designed exclusively for the browser and relies on browser APIs (MediaRecorder, WebSocket, etc.). It will not work in Node.js or other JavaScript environments.

Installation

Add the SDK script tag to your HTML page:

<script defer src="https://gamilab.ch/js/sdk.js"></script>

Initialization

The SDK dispatches a gami:init custom event on window when it is ready. You must call evt.detail.Gami() inside the handler to complete initialization. If you do not call it, the event fires again until you do.

Gami() returns a singleton instance that you use for all subsequent SDK calls.

let gami = null;
window.addEventListener("gami:init", (evt) => {
    gami = evt.detail.Gami();
});

Events

The SDK fires events that you can subscribe to with the on method. Each call returns a reference you can pass to off to unsubscribe.

const ref = gami.on("audio", (state) => {
    console.log(state);
});

// later
gami.off(ref);

Supported events

Event	Callback signature	Description
`audio`	`(state: string)`	Audio status change. Values: `idle`, `initializing`, `paused`, `recording`.
`text_history`	`(history: string)`	Complete speech-to-text history.
`text_current`	`(current: string)`	Current live speech-to-text output.
`extraction_status`	`(status: string)`	Extraction status change. Values: `idle`, `running`.
`struct_current`	`(data: object)`	Structured data matching the portal model schema.
`silence`	`(is_silence: boolean)`	`true` if no audio detected for 5+ seconds.
`live_waveform`	`(data: ArrayBuffer)`	Waveform preview with averaged audio values as single bytes.

Usage

1. Connect

await gami.connect();

2. Select a portal

await gami.use_portal(portal_id);

3. Create or resume a thread

Both methods return {thread_id, token}.

const { thread_id } = await gami.create_thread();
const resumed = await gami.resume_thread(thread_id);

4. Start recording

await gami.start_recording();

5. Control recording

await gami.toggle_recording();

Full reference

See the Browser SDK API Reference for the complete API.