@odysseyml/odyssey package provides a TypeScript/JavaScript client for interacting with Odyssey’s audio-visual intelligence.
| Feature | Minimum Version |
|---|---|
| Core SDK | ^1.0.0 |
| Recordings | ^1.0.0 |
| Simulate API | ^1.0.0 |
| Broadcast | ^1.1.0 |
Installation
API Summary
Methods
| Signature | Description |
|---|---|
connect(handlers?): Promise<MediaStream> | Connect to a streaming session (returns MediaStream when ready) |
createClientCredentials(): Promise<ClientCredentials> | Mint short-lived credentials for client-side connections (v1.3.0+) |
connectWithCredentials(credentials, handlers?): Promise<MediaStream> | Connect with pre-minted credentials (no API key required) (v1.3.0+) |
disconnect(): void | Disconnect and clean up resources |
startStream(options?): Promise<string> | Start an interactive stream. Supports ‘broadcast: true’ to enable shared playback. |
interact(options): Promise<string> | Send a prompt to update the video |
endStream(): Promise<void> | End the current stream session |
attachToVideo(element): HTMLVideoElement | Attach stream to a video element |
getRecording(streamId): Promise<Recording> | Get recording URLs for a stream |
listStreamRecordings(options?): Promise<StreamRecordingsListResponse> | List user’s stream recordings |
simulate(options): Promise<SimulationJob> | Create an async simulation job |
getSimulateStatus(id): Promise<SimulationJobDetail> | Get simulation job status |
listSimulations(options?): Promise<SimulationJobsList> | List simulation jobs |
cancelSimulation(id): Promise<void> | Cancel a simulation job |
connectToStream(webrtcUrl: string, spectatorToken: string, options?: { signal?: AbortSignal }): Promise<SpectatorConnection> | Connect as a spectator to an existing broadcast stream (WebRTC/WHEP). |
Properties
| Property | Type | Description |
|---|---|---|
isConnected | boolean | Whether connected and ready |
currentStatus | ConnectionStatus | Current connection status |
currentSessionId | string | null | Current session ID |
mediaStream | MediaStream | null | Video stream from streamer |
connectionState | RTCPeerConnectionState | null | WebRTC connection state |
broadcastInfo | BroadcastInfo | null | Contains latest broadcast playback details |
Event Handlers
| Handler | Parameters | Description |
|---|---|---|
onConnected | mediaStream: MediaStream | Video stream established |
onDisconnected | - | Video stream closed |
onStreamStarted | streamId: string | Interactive stream ready (streamId can be used for recordings) |
onStreamEnded | - | Interactive stream ended |
onInteractAcknowledged | prompt: string | Interaction processed |
onStreamError | reason, message | Stream error occurred |
onError | error: Error, fatal: boolean | General error |
onStatusChange | status, message? | Connection status changed |
onBroadcastReady | info: BroadcastInfo | Fires when broadcast playback details are available. |
Next Steps
Odyssey Class
Main client class documentation
React Hook
useOdyssey hook for React apps
Recordings
Working with stream recordings
Simulate API
Async scripted video generation
Types
TypeScript types and interfaces
Examples
Complete usage examples