### Install Dependencies

Source: https://github.com/openai/openai-realtime-solar-system/blob/main/README.md

Install project dependencies using npm. Ensure you are in the project directory.

```bash
npm install
```

--------------------------------

### Run the Application

Source: https://github.com/openai/openai-realtime-solar-system/blob/main/README.md

Start the Next.js development server. The application will be accessible at http://localhost:3000.

```bash
npm run dev
```

--------------------------------

### startSession() — Establish a WebRTC Realtime session

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Fetches a client secret, creates a WebRTC peer connection, captures microphone audio, and establishes a data channel for Realtime events with the OpenAI API.

```APIDOC
## startSession() — Establish a WebRTC Realtime session

### Description
Fetches a client secret from `/api/session`, creates an `RTCPeerConnection`, captures microphone audio, creates the `oai-events` data channel, performs the SDP offer/answer exchange with `https://api.openai.com/v1/realtime/calls`, and wires up audio playback. On data channel open, immediately sends a `session.update` event to configure tools and instructions.

### Usage
```typescript
// Simplified usage inside a React component (see components/app.tsx)
async function startSession() {
  // 1. Fetch ephemeral token from the Next.js backend
  const sessionResponse = await fetch("/api/session");
  const session = await sessionResponse.json();
  const sessionToken = session.value; // e.g. "ek-abc123..."

  // 2. Create WebRTC peer connection
  const pc = new RTCPeerConnection();

  // 3. Play model audio output
  const audioEl = document.createElement("audio");
  audioEl.autoplay = true;
  pc.ontrack = (e) => { audioEl.srcObject = e.streams[0]; };

  // 4. Add microphone track
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  stream.getTracks().forEach((track) => pc.addTrack(track, stream));

  // 5. Create data channel for sending/receiving Realtime events
  const dc = pc.createDataChannel("oai-events");

  dc.addEventListener("open", () => {
    // Configure tools and instructions once connected
    dc.send(JSON.stringify({
      type: "session.update",
      session: {
        type: "realtime",
        tools: TOOLS,        // from lib/config.ts
        instructions: INSTRUCTIONS, // from lib/config.ts
      },
    }));
  });

  // 6. SDP negotiation
  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);

  const sdpResponse = await fetch("https://api.openai.com/v1/realtime/calls", {
    method: "POST",
    body: offer.sdp,
    headers: {
      Authorization: `Bearer ${sessionToken}`,
      "Content-Type": "application/sdp",
    },
  });

  await pc.setRemoteDescription({
    type: "answer",
    sdp: await sdpResponse.text(),
  });
  // Session is now active — audio streams bidirectionally
}
```
```

--------------------------------

### Establish WebRTC Realtime Session (TypeScript)

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Initiates a WebRTC Realtime session by fetching a token, setting up the peer connection, handling audio streams, and negotiating the SDP offer/answer. Configures tools and instructions upon connection.

```typescript
// Simplified usage inside a React component (see components/app.tsx)
async function startSession() {
  // 1. Fetch ephemeral token from the Next.js backend
  const sessionResponse = await fetch("/api/session");
  const session = await sessionResponse.json();
  const sessionToken = session.value; // e.g. "ek-abc123..."

  // 2. Create WebRTC peer connection
  const pc = new RTCPeerConnection();

  // 3. Play model audio output
  const audioEl = document.createElement("audio");
  audioEl.autoplay = true;
  pc.ontrack = (e) => { audioEl.srcObject = e.streams[0]; };

  // 4. Add microphone track
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  stream.getTracks().forEach((track) => pc.addTrack(track, stream));

  // 5. Create data channel for sending/receiving Realtime events
  const dc = pc.createDataChannel("oai-events");

  dc.addEventListener("open", () => {
    // Configure tools and instructions once connected
    dc.send(JSON.stringify({
      type: "session.update",
      session: {
        type: "realtime",
        tools: TOOLS,        // from lib/config.ts
        instructions: INSTRUCTIONS, // from lib/config.ts
      },
    }));
  });

  // 6. SDP negotiation
  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);

  const sdpResponse = await fetch("https://api.openai.com/v1/realtime/calls", {
    method: "POST",
    body: offer.sdp,
    headers: {
      Authorization: `Bearer ${sessionToken}`,
      "Content-Type": "application/sdp",
    },
  });

  await pc.setRemoteDescription({
    type: "answer",
    sdp: await sdpResponse.text(),
  });
  // Session is now active — audio streams bidirectionally
}
```

--------------------------------

### Configure AI Function-Calling Tools and Instructions

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Exports 'TOOLS' (OpenAI function-calling definitions) and 'INSTRUCTIONS' (system prompt) from 'lib/config.ts'. These are sent to the model via 'session.update' once the data channel opens. 'TOOLS' is an array of function definitions, and 'INSTRUCTIONS' governs model behavior.

```typescript
import { TOOLS, INSTRUCTIONS, VOICE } from "@/lib/config";
// VOICE = "coral"

// TOOLS array (sent in session.update):
// [
//   { type: "function", name: "focus_planet",   parameters: { planet: enum[...] } },
//   { type: "function", name: "display_data",   parameters: { chart, title, text, data[] } },
//   { type: "function", name: "reset_camera",   parameters: {} },
//   { type: "function", name: "show_orbit",     parameters: {} },
//   { type: "function", name: "show_moons",     parameters: { moons: array of enum[...] } },
//   { type: "function", name: "get_iss_position", parameters: {} },
// ]

// Session configuration sent on data channel open:
sendClientEvent({
  type: "session.update",
  session: {
    type: "realtime",
    tools: TOOLS,
    instructions: INSTRUCTIONS,
  },
});

// Model constants (lib/constants.ts):
// MODEL = "gpt-realtime-1.5"
// REALTIME_CALLS_URL = "https://api.openai.com/v1/realtime/calls"
// REALTIME_CLIENT_SECRETS_URL = "https://api.openai.com/v1/realtime/client_secrets"
```

--------------------------------

### TOOLS and INSTRUCTIONS

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

AI function-calling configuration exported from `lib/config.ts`. `TOOLS` is an array of tool definitions sent to the model, and `INSTRUCTIONS` is the system prompt governing model behavior.

```APIDOC
## TOOLS and INSTRUCTIONS

### Description
AI function-calling configuration. Exported from `lib/config.ts`, `TOOLS` is an array of OpenAI function-calling tool definitions sent to the model via `session.update`. `INSTRUCTIONS` is the system prompt that governs model behavior. Both are sent once when the data channel opens.

### `TOOLS` Array
An array of function definitions for the AI model.

Example:
```typescript
[
  { type: "function", name: "focus_planet",   parameters: { planet: enum[...] } },
  { type: "function", name: "display_data",   parameters: { chart, title, text, data[] } },
  { type: "function", name: "reset_camera",   parameters: {} },
  { type: "function", name: "show_orbit",     parameters: {} },
  { type: "function", name: "show_moons",     parameters: { moons: array of enum[...] } },
  { type: "function", name: "get_iss_position", parameters: {} },
]
```

### `INSTRUCTIONS`
The system prompt that governs the AI model's behavior.

### Usage
Both `TOOLS` and `INSTRUCTIONS` are sent to the model when the data channel opens via `session.update`.

```typescript
sendClientEvent({
  type: "session.update",
  session: {
    type: "realtime",
    tools: TOOLS,
    instructions: INSTRUCTIONS,
  },
});
```
```

--------------------------------

### Set API Key using .env file

Source: https://github.com/openai/openai-realtime-solar-system/blob/main/README.md

Configure your OpenAI API key by creating a .env file at the project root and adding the key.

```bash
OPENAI_API_KEY=<your_api_key>
```

--------------------------------

### Clone Repository

Source: https://github.com/openai/openai-realtime-solar-system/blob/main/README.md

Clone the project repository to your local machine.

```bash
git clone https://github.com/openai/openai-realtime-solar-system.git
```

--------------------------------

### startRecording() / stopRecording()

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Toggles microphone recording during an active session. `startRecording` acquires a new audio stream and replaces the current sender track. `stopRecording` stops the real mic tracks and replaces them with a silent placeholder track.

```APIDOC
## startRecording() / stopRecording()

### Description
Toggle microphone during an active session. `startRecording` acquires a new `getUserMedia` audio stream and replaces the current sender track on the peer connection. `stopRecording` stops the real mic tracks and replaces them with a silent placeholder track created via the Web Audio API — preserving the data channel and peer connection while muting the user.

### Methods
#### `startRecording()`
- **Description**: Unmutes the microphone by acquiring a live audio stream and replacing the current sender track with it.
- **Returns**: `Promise<void>`

#### `stopRecording()`
- **Description**: Mutes the microphone by stopping the current audio tracks and replacing the sender track with a silent placeholder.
- **Returns**: `void`

### Request Example
```typescript
// To start recording (unmute):
await startRecording();

// To stop recording (mute):
stopRecording();
```
```

--------------------------------

### Request Session Token (Bash)

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Use this command to request an ephemeral token from the /api/session endpoint. Ensure OPENAI_API_KEY is configured on the server.

```bash
# Request a session token
curl http://localhost:3000/api/session
```

```json
# Expected success response (200)
{
  "value": "ek-abc123...",
  "expires_at": 1712345678,
  "session": {
    "id": "sess_xyz789"
  }
}
```

```json
# Error response when OPENAI_API_KEY is missing (500)
{
  "error": "OPENAI_API_KEY is not configured"
}
```

--------------------------------

### showMoons(moons)

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Sequentially animates moons into view with a staggered effect. It iterates over an array of moon names and triggers each moon's appearance animation with a 100ms delay between each.

```APIDOC
## showMoons(moons)

### Description
Sequentially animate moons into view. Iterates over an array of moon names and triggers each moon's appearance animation with a 100ms delay between each for a staggered visual effect.

### Parameters
#### Path Parameters
- **moons** (string[]) - Required - An array of moon names to animate. Must be a subset of the MOONS enum: ["Io", "Europa", "Ganymede", "Callisto", "Kerberos", "Styx", "Nix", "Hydra", "Charon"]

### Request Example
```typescript
await showMoons(["Io", "Europa", "Ganymede", "Callisto"]);
await showMoons(["Kerberos", "Styx", "Nix", "Hydra", "Charon"]);
```
```

--------------------------------

### Toggle Microphone Recording

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Manages microphone input by acquiring a new audio stream for unmuting or replacing tracks with a silent placeholder for muting. 'startRecording' uses 'getUserMedia' and 'replaceTrack', while 'stopRecording' uses the Web Audio API to create a silent track.

```typescript
// Unmute: replace sender with a live mic track
async function startRecording() {
  const newStream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const micTrack = newStream.getAudioTracks()[0];
  tracks.current?.forEach((sender) => sender.replaceTrack(micTrack));
  setAudioStream(newStream);
  setIsListening(true);
}
```

```typescript
// Mute: replace sender with a silent placeholder track
function stopRecording() {
  audioStream?.getTracks().forEach((track) => track.stop());
  setAudioStream(null);

  const audioCtx = new AudioContext();
  const destination = audioCtx.createMediaStreamDestination();
  const silentTrack = destination.stream.getAudioTracks()[0];
  tracks.current?.forEach((sender) => sender.replaceTrack(silentTrack));

  setIsListening(false);
}
```

--------------------------------

### handleToolCall(output)

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Dispatches and responds to model function calls received from the `response.done` event. It processes tool calls, optionally fetches external data, and sends a `function_call_output` event back to the model. For specific tools, it also triggers a `response.create` to ensure a spoken follow-up.

```APIDOC
## handleToolCall(output)

### Description
Invoked when a `response.done` event contains a `function_call` output. Checks the tool name, optionally fetches external data (ISS position), then sends a `function_call_output` event back to the model. For `get_iss_position` and `display_data`, also triggers a `response.create` to force a spoken follow-up.

### Method
`async handleToolCall(output: any)`

### Parameters
- **output** (any) - The tool call output from the model, expected to have `name`, `arguments`, and `call_id` properties.

### Response
Sends events back to the model via `sendClientEvent`.

### Example
```typescript
// Assuming 'output' is received from a model response
await handleToolCall({
  call_id: "call_xyz789",
  name: "get_iss_position",
  arguments: "{}"
});
```
```

--------------------------------

### Session and Microphone Toggle Buttons in React

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

A stateless React component for session and microphone control. Ensure session is active for microphone interaction.

```tsx
import Controls from "@/components/controls";

<Controls
  isConnected={isSessionActive}   // true → WiFi icon green, session running
  isListening={isListening}       // true → Mic icon green, microphone active
  handleConnectClick={handleConnectClick}   // starts or stops the WebRTC session
  handleMicToggleClick={handleMicToggleClick} // mutes or unmutes during session
/>
```

--------------------------------

### Handle Model Tool Calls

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Dispatches and responds to model function calls. It checks the tool name, optionally fetches external data (like ISS position), and sends a `function_call_output` event back to the model. For specific tools, it also triggers a `response.create` to force a spoken follow-up.

```typescript
async function handleToolCall(output: any) {
  const toolCall = { name: output.name, arguments: output.arguments };

  const toolCallOutput: { response: string; [key: string]: any } = {
    response: `Tool call ${toolCall.name} executed successfully.`, 
  };

  // Special handling: fetch ISS position from /api/iss
  if (toolCall.name === "get_iss_position") {
    const issPosition = await fetch("/api/iss").then((r) => r.json());
    // issPosition = { latitude: "51.72", longitude: "-123.45" }
    toolCallOutput.issPosition = issPosition;
  }

  // Return the result to the model
  sendClientEvent({
    type: "conversation.item.create",
    item: {
      type: "function_call_output",
      call_id: output.call_id,
      output: JSON.stringify(toolCallOutput),
    },
  });

  // Force a spoken response after data-heavy tool calls
  if (toolCall.name === "get_iss_position" || toolCall.name === "display_data") {
    sendClientEvent({ type: "response.create" });
  }
}
```

--------------------------------

### Collapsible Real-time Event Console in React

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Renders a slide-in panel to display formatted JSON output from the Realtime API. Requires an array of response output objects.

```tsx
import Logs from "@/components/logs";

// messages is the array of Realtime API response output objects
<Logs messages={logs} />

// Example message shape (function_call output):
// {
//   "type": "function_call",
//   "name": "focus_planet",
//   "arguments": "{\"planet\":\"Mars\"}",
//   "call_id": "call_abc123"
// }
```

--------------------------------

### Fetch ISS Position (Bash)

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

This command fetches the current latitude and longitude of the International Space Station from the /api/iss endpoint. Handles upstream API failures.

```bash
# Fetch ISS position
curl http://localhost:3000/api/iss
```

```json
# Expected success response (200)
{
  "latitude": "51.7270",
  "longitude": "-123.4567"
}
```

```json
# Error response when upstream fails (500)
{
  "error": "Failed to fetch ISS position"
}
```

--------------------------------

### Sequentially Animate Moons with Staggered Delay

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Iterates over an array of moon names to trigger their appearance animations with a 100ms delay between each for a staggered visual effect. Ensure the input 'moons' array contains valid moon names.

```typescript
async function showMoons(moons: string[]) {
  // moons must be a subset of the MOONS enum: 
  // ["Io", "Europa", "Ganymede", "Callisto", "Kerberos", "Styx", "Nix", "Hydra", "Charon"]
  for (const moon of moons) {
    triggerAnimation(moon);
    await new Promise((resolve) => setTimeout(resolve, 100));
  }
}
```

```typescript
// Example: Show Jupiter's Galilean moons
await showMoons(["Io", "Europa", "Ganymede", "Callisto"]);
```

```typescript
// Example: Show Pluto's moons
await showMoons(["Kerberos", "Styx", "Nix", "Hydra", "Charon"]);
```

--------------------------------

### Spline 3D Scene with Tool Call Integration in React

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Embeds a Spline scene and integrates tool calls for animation and UI actions. Listens for 'd' keypress to clear data overlay and Space/M/Enter for camera shortcuts.

```tsx
import Scene from "@/components/scene";

// toolCall is set by the App component when a function_call event arrives
<Scene toolCall={toolCall} />

// toolCall shape:
// { name: "focus_planet", arguments: '{"planet":"Jupiter"}' }
// { name: "display_data", arguments: '{"chart":"bar","title":"...","data":[...] }' }
// { name: "show_moons",   arguments: '{"moons":["Io","Europa"]}' }
// { name: "get_iss_position", arguments: '{}' }
// { name: "reset_camera", arguments: '{}' }
// { name: "show_orbit",   arguments: '{}' }
```

--------------------------------

### getComponent(component)

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Renders a chart component from AI-supplied data. It maps an AI-generated `display_data` tool call payload to either a `PieChartComponent` or a Recharts `BarChart`. Returns a React node ready to be overlaid on the 3D scene, or `null` if the chart type is unrecognized.

```APIDOC
## getComponent(component)

### Description
Render a chart component from AI-supplied data. Maps an AI-generated `display_data` tool call payload to either a `PieChartComponent` (via chart.js) or a Recharts `BarChart`. Returns a React node ready to be overlaid on the 3D scene, or `null` if the chart type is unrecognized.

### Parameters
#### Path Parameters
- **component** (object) - Required - The component configuration object, expected to have properties like `chart`, `title`, `text`, and `data`.
  - **chart** (string) - Required - The type of chart to render ('pie' or 'bar').
  - **title** (string) - Required - The title of the chart.
  - **text** (string) - Optional - Descriptive text for the chart.
  - **data** (array) - Required - An array of objects, where each object has a `label` and a `value`.

### Request Example
```typescript
const node = getComponent({
  chart: "pie",
  title: "Earth Surface Distribution",
  text: "Approximate percentage of land vs. water",
  data: [
    { label: "Water", value: "71" },
    { label: "Land",  value: "29" },
  ],
});

const barNode = getComponent({
  chart: "bar",
  title: "Volcano Height Comparison (km)",
  data: [
    { label: "Olympus Mons", value: "21.9" },
    { label: "Mount Everest", value: "8.85" },
  ],
});
```

### Response
#### Success Response (React Node)
- Returns a React node representing the chart component, or `null` if the chart type is unrecognized.

#### Response Example
```jsx
// For pie chart:
<PieChartComponent title="Earth Surface Distribution" data={[...]} />

// For bar chart:
<div><h1>Volcano Height Comparison (km)</h1><ChartContainer>...</ChartContainer></div>
```
```

--------------------------------

### Render Chart Component from AI Data

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Maps AI-generated display data to either a PieChartComponent (chart.js) or a Recharts BarChart. Returns a React node for overlay on a 3D scene, or null for unrecognized chart types. Requires the 'getComponent' function from '@/lib/components-mapping'.

```typescript
import { getComponent } from "@/lib/components-mapping";

// Example: Render a pie chart for Earth's surface distribution
const node = getComponent({
  chart: "pie",
  title: "Earth Surface Distribution",
  text: "Approximate percentage of land vs. water",
  data: [
    { label: "Water", value: "71" },
    { label: "Land",  value: "29" },
  ],
});
// Returns: <PieChartComponent title="Earth Surface Distribution" data={[...]} />
```

```typescript
// Example: Render a bar chart for volcano height comparison
const barNode = getComponent({
  chart: "bar",
  title: "Volcano Height Comparison (km)",
  data: [
    { label: "Olympus Mons", value: "21.9" },
    { label: "Mount Everest", value: "8.85" },
  ],
});
// Returns: <div><h1>Volcano Height Comparison (km)</h1><ChartContainer>...</ChartContainer></div>
```

```typescript
// Both nodes can be rendered directly in JSX:
setDisplayComponent(node);
```

--------------------------------

### Fetch real-time ISS position

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Proxies a request to the public Open Notify API and returns the current latitude and longitude of the International Space Station.

```APIDOC
## GET /api/iss — Fetch real-time ISS position

### Description
Proxies a request to the public Open Notify API (`http://api.open-notify.org/iss-now.json`) and returns only the `iss_position` object containing the current latitude and longitude of the International Space Station.

### Method
GET

### Endpoint
`/api/iss`

### Request Example
```bash
# Fetch ISS position
curl http://localhost:3000/api/iss
```

### Response
#### Success Response (200)
- **latitude** (string) - The current latitude of the ISS.
- **longitude** (string) - The current longitude of the ISS.

#### Response Example
```json
{
  "latitude": "51.7270",
  "longitude": "-123.4567"
}
```

#### Error Response (500)
- **error** (string) - Description of the error, e.g., "Failed to fetch ISS position".

```json
{
  "error": "Failed to fetch ISS position"
}
```
```

--------------------------------

### Mint a short-lived Realtime client secret

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Calls the OpenAI POST /v1/realtime/client_secrets endpoint server-side and returns a short-lived ephemeral token to the browser for authentication.

```APIDOC
## GET /api/session — Mint a short-lived Realtime client secret

### Description
Calls the OpenAI `POST /v1/realtime/client_secrets` endpoint server-side using the `OPENAI_API_KEY` environment variable and returns a short-lived ephemeral token (valid 600 seconds) to the browser. The browser uses this token directly to authenticate its WebRTC SDP exchange — the real API key is never exposed to the client.

### Method
GET

### Endpoint
`/api/session`

### Request Example
```bash
# Request a session token
curl http://localhost:3000/api/session
```

### Response
#### Success Response (200)
- **value** (string) - The ephemeral client secret token.
- **expires_at** (integer) - The Unix timestamp when the token expires.
- **session** (object) - Information about the session.
  - **id** (string) - The session ID.

#### Response Example
```json
{
  "value": "ek-abc123...",
  "expires_at": 1712345678,
  "session": {
    "id": "sess_xyz789"
  }
}
```

#### Error Response (500)
- **error** (string) - Description of the error, e.g., "OPENAI_API_KEY is not configured".

```json
{
  "error": "OPENAI_API_KEY is not configured"
}
```
```

--------------------------------

### stopSession()

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Tears down the WebRTC session by closing the data channel and peer connection, stopping microphone tracks, and resetting all relevant React state to its initial idle condition.

```APIDOC
## stopSession()

### Description
Closes the RTCDataChannel and RTCPeerConnection, stops all microphone tracks, and resets all React state to the idle state.

### Method
`stopSession()`

### Parameters
None

### Response
None

### Example
```typescript
stopSession();
```
```

--------------------------------

### sendClientEvent(message)

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Sends a JSON-serialized event to the OpenAI Realtime model over the `oai-events` RTCDataChannel. If an `event_id` is not provided in the message, a new UUID is automatically generated.

```APIDOC
## sendClientEvent(message)

### Description
Sends a JSON-serialized event to the OpenAI Realtime model via the `oai-events` RTCDataChannel. Auto-assigns a `crypto.randomUUID()` event ID if one is not provided.

### Method
`sendClientEvent(message: any)`

### Parameters
- **message** (any) - The event payload to send. Can include an optional `event_id`.

### Request Body
(Implicitly, the `message` object is serialized to JSON)

### Response
None (sends data over the data channel)

### Examples
```typescript
// Example: Force a model response turn
sendClientEvent({ type: "response.create" });

// Example: Submit a tool call result back to the model
sendClientEvent({
  type: "conversation.item.create",
  item: {
    type: "function_call_output",
    call_id: "call_abc123",
    output: JSON.stringify({ response: "Tool executed successfully.", issPosition: { latitude: "51.72", longitude: "-123.45" } }),
  },
});
```
```

--------------------------------

### Send Client Event via Data Channel

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Sends a JSON-serialized event to the OpenAI Realtime model over the `oai-events` RTCDataChannel. Automatically assigns a `crypto.randomUUID()` event ID if one is not provided.

```typescript
const sendClientEvent = useCallback((message: any) => {
  if (dataChannel?.readyState === "open") {
    message.event_id = message.event_id || crypto.randomUUID();
    dataChannel.send(JSON.stringify(message));
  } else {
    console.error("Failed to send message - no data channel available", message);
  }
}, [dataChannel]);
```

```typescript
// Example: Force a model response turn
sendClientEvent({ type: "response.create" });
```

```typescript
// Example: Submit a tool call result back to the model
sendClientEvent({
  type: "conversation.item.create",
  item: {
    type: "function_call_output",
    call_id: "call_abc123",
    output: JSON.stringify({ response: "Tool executed successfully.", issPosition: { latitude: "51.72", longitude: "-123.45" } }),
  },
});
```

--------------------------------

### triggerAnimation(objectName)

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Emits a Spline scene event to trigger a pre-configured animation for a specified 3D object. This function is used to animate planets, moons, or control camera views and resets within the scene.

```APIDOC
## triggerAnimation(objectName)

### Description
Calls `spline.current.emitEvent("mouseDown", objectName)` on the loaded Spline application instance to trigger a pre-configured animation for the named 3D object (planet name, moon name, or a trigger object like `"trigger_reset"`).

### Method
`triggerAnimation(objectName: string)`

### Parameters
- **objectName** (string) - The name of the object in the Spline scene to trigger an animation on. Examples include planet names (e.g., "Mars"), moon names, or control objects (e.g., "trigger_reset").

### Response
None

### Examples
```typescript
// Example: Focus on Mars
triggerAnimation("Mars");

// Example: Switch to high-level orbit view
triggerAnimation("trigger_camera_high_level");

// Example: Reset camera to initial position
triggerAnimation("trigger_reset");
triggerAnimation("trigger_camera_main");
```
```

--------------------------------

### Stop WebRTC Session

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Closes the RTCDataChannel and RTCPeerConnection, stops microphone tracks, and resets all related React state to its idle configuration.

```typescript
function stopSession() {
  dataChannel?.close();
  peerConnection.current?.close();

  // Stop microphone
  audioStream?.getTracks().forEach((track) => track.stop());

  // Reset all state
  setIsSessionStarted(false);
  setIsSessionActive(false);
  setDataChannel(null);
  setToolCall(null);
  setAudioStream(null);
  setIsListening(false);
  peerConnection.current = null;
  tracks.current = null;
  if (audioElement.current) audioElement.current.srcObject = null;
}
```

--------------------------------

### Trigger Spline Scene Animation

Source: https://context7.com/openai/openai-realtime-solar-system/llms.txt

Emits a `mouseDown` event on a specified object in the Spline scene to trigger a pre-configured animation. Handles potential errors during event emission.

```typescript
function triggerAnimation(objectName: string) {
  if (spline.current) {
    try {
      spline.current.emitEvent("mouseDown", objectName);
      // Triggers the mouseDown animation event on the named object in the Spline scene
      // Valid object names: "Sun", "Mercury", "Venus", "Earth", "Mars",
      //   "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto",
      //   "ISS", "Io", "Europa", "Ganymede", "Callisto",
      //   "Kerberos", "Styx", "Nix", "Hydra", "Charon",
      //   "trigger_reset", "trigger_camera_main", "trigger_camera_high_level"
    } catch (error) {
      console.error("Failed to trigger animation:", error);
    }
  }
}
```

```typescript
// Example: Focus on Mars
triggerAnimation("Mars");
```

```typescript
// Example: Switch to high-level orbit view
triggerAnimation("trigger_camera_high_level");
```

```typescript
// Example: Reset camera to initial position
triggerAnimation("trigger_reset");
triggerAnimation("trigger_camera_main");
```

--------------------------------

### Embed Spline Scene in React Component

Source: https://github.com/openai/openai-realtime-solar-system/blob/main/README.md

This component embeds a Spline scene using its URL. Configure the scene ID and handle load events.

```html
<Spline
  scene="https://prod.spline.design/<scene_id>/scene.splinecode"
  onLoad="{onLoad}"
/>
```

--------------------------------

### Trigger Spline Animation Event in React

Source: https://github.com/openai/openai-realtime-solar-system/blob/main/README.md

This code snippet shows how to emit a 'mouseDown' event to trigger an animation on a specific object within a Spline scene. Ensure the event is configured in your Spline scene.

```typescript
spline.current.emitEvent("mouseDown", "object_name")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.