@streamcore/js-sdk

Framework-agnostic TypeScript SDK for connecting to a StreamCoreAI server via WebRTC + WHIP.

Installation

npm install @streamcore/js-sdk

Quick Start

import { StreamCoreAIClient } from "@streamcore/js-sdk";

const agent = new StreamCoreAIClient(
  { whipUrl: "http://localhost:8080/whip" },
  {
    onStatusChange: (status) => console.log("Status:", status),
    onTranscript: (entry, all) => console.log("Transcript:", entry),
    onAudioLevel: (level) => console.log("Audio level:", level),
    onError: (err) => console.error("Error:", err),
  }
);

// Connect (requests microphone permission, establishes WebRTC session)
await agent.connect();

// Mute / unmute
agent.toggleMute();
console.log("Muted:", agent.isMuted);

// Disconnect
agent.disconnect();

API

new StreamCoreAIClient(config?, events?)

Creates a new client instance.

StreamCoreAIConfig

Property	Type	Default	Description
whipUrl	string	"http://localhost:8080/whip"	WHIP signaling endpoint URL
iceServers	RTCIceServer[]	[{ urls: "stun:stun.l.google.com:19302" }]	ICE server configuration
audioConstraints	MediaTrackConstraints	{ echoCancellation: true, noiseSuppression: true, autoGainControl: true }	Microphone constraints

StreamCoreAIEvents

Event	Signature	Description
onStatusChange	(status: ConnectionStatus) => void	Fired when connection status changes
onTranscript	(entry: TranscriptEntry, all: TranscriptEntry[]) => void	Fired on new or updated transcript
onAudioLevel	(level: number) => void	Fired every animation frame with mic level (0–1)
onError	(error: Error) => void	Fired on connection or server errors
onTiming	(event: TimingEvent) => void	Fired with server-side pipeline timing info

Instance Methods

Method	Returns	Description
connect()	Promise<void>	Request mic, establish WebRTC + WHIP session
disconnect()	void	Tear down connection, stop mic, free resources
toggleMute()	void	Toggle microphone mute
on(event, fn)	void	Register an event listener after construction

Instance Properties (read-only)

Property	Type	Description
status	ConnectionStatus	"idle" | "connecting" | "connected" | "error" | "disconnected"
transcript	TranscriptEntry[]	Full conversation history
audioLevel	number	Current mic audio level (0–1)
isMuted	boolean	Whether the mic is muted
localStream	MediaStream | null	Local microphone stream (after connect)
remoteStream	MediaStream | null	Remote agent audio stream (after connect)

Types

type ConnectionStatus = "idle" | "connecting" | "connected" | "error" | "disconnected";

interface TranscriptEntry {
  role: "user" | "assistant";
  text: string;
  partial?: boolean;
}

interface TimingEvent {
  stage: string;
  ms: number;
}

Building from Source

cd typescript-sdk
npm install
npm run build

The compiled output is written to dist/.

Usage with Bundlers

The SDK ships as ES modules with TypeScript declarations. It works out of the box with Vite, webpack, Next.js, esbuild, and other modern bundlers.

License

Apache2.0