> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.api.odyssey.ml/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Complete API reference for the Odyssey JavaScript client library.

The `@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

<CodeGroup>
  ```bash npm theme={null}
  npm install @odysseyml/odyssey
  ```

  ```bash yarn theme={null}
  yarn add @odysseyml/odyssey
  ```

  ```bash pnpm theme={null}
  pnpm add @odysseyml/odyssey
  ```
</CodeGroup>

## 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

<CardGroup cols={2}>
  <Card icon="cube" href="/sdk/javascript/odyssey-class" title="Odyssey Class">
    Main client class documentation
  </Card>

  <Card icon="react" href="/sdk/javascript/react-hook" title="React Hook">
    useOdyssey hook for React apps
  </Card>

  <Card icon="video" href="/sdk/javascript/recordings" title="Recordings">
    Working with stream recordings
  </Card>

  <Card icon="robot" href="/sdk/javascript/simulations" title="Simulate API">
    Async scripted video generation
  </Card>

  <Card icon="code" href="/sdk/javascript/types" title="Types">
    TypeScript types and interfaces
  </Card>

  <Card icon="file-code" href="/sdk/javascript/examples" title="Examples">
    Complete usage examples
  </Card>
</CardGroup>