Hooks

The React SDK currently exports one primary hook, useOrgaAI(), which exposes methods and state for creating, managing, and interacting with Orga sessions.

`useOrgaAI()`

Access Orga SDK methods and session state directly in your components.


import { useOrgaAI } from "@orga-ai/react";
 
const {
  startSession,
  endSession,
  enableMic,
  disableMic,
  toggleMic,
  enableCamera,
  disableCamera,
  toggleCamera,
  connectionState,
  aiAudioStream,
  userVideoStream,
  conversationItems,
  isCameraOn,
  isMicOn,
  conversationId,
  model,
  voice,
  temperature,
  instructions,
  modalities,
  updateParams,
} = useOrgaAI();

useOrgaAI() must be used within an <OrgaAIProvider>.

Returns

Name	Type	Description
`startSession`	`(config?: SessionConfig) => Promise<void>`	Starts a new real-time session with optional configuration. Use this to begin an AI interaction.
`endSession`	`() => Promise<void>`	Gracefully closes the active session and releases all streams.
`enableMic`	`() => Promise<void>`	Enables the user’s microphone for input.
`disableMic`	`() => Promise<void>`	Disables the microphone, muting input audio.
`toggleMic`	`() => Promise<void>`	Toggles the microphone’s enabled state.
`enableCamera`	`() => Promise<void>`	Enables the user’s camera for video input.
`disableCamera`	`() => Promise<void>`	Disables the camera, stopping video input.
`toggleCamera`	`() => Promise<void>`	Toggles the camera’s enabled state.
`connectionState`	`ConnectionState`	Current connection state — `"disconnected"`, `"connecting"`, or `"connected"`.
`aiAudioStream`	`MediaStream \| null`	The AI’s audio output stream. Pass this to `<OrgaAudio>`.
`userVideoStream`	`MediaStream \| null`	The user’s video input stream. Pass this to `<OrgaVideo>`.
`conversationItems`	`ConversationItem[]`	All conversation messages exchanged within the current session, including transcriptions and responses.
`isCameraOn`	`boolean`	Whether the camera is currently active.
`isMicOn`	`boolean`	Whether the microphone is currently active.
`conversationId`	`string \| null`	Unique ID of the current conversation.
`model`	`OrgaAIModel \| null`	Current AI model (e.g. `"orga-1-beta"`).
`voice`	`OrgaAIVoice \| null`	Current AI voice.
`temperature`	`number \| null`	Current temperature value for model sampling.
`instructions`	`string \| null`	Custom instructions or persona text set for the current session.
`modalities`	`Modality[]`	Enabled modalities for the session (e.g., audio, video).
`updateParams`	`(params: { model?: OrgaAIModel; voice?: OrgaAIVoice; temperature?: number; instructions?: string; modalities?: Modality[] }) => void`	Updates session parameters dynamically during a live session.

Example Usage

app/page.tsx


'use client'
import { useOrgaAI, OrgaVideo, OrgaAudio } from "@orga-ai/react";
 
export default function Home() {
  const {
    startSession,
    endSession,
    toggleMic,
    toggleCamera,
    connectionState,
    userVideoStream,
    aiAudioStream,
    isMicOn,
    isCameraOn,
    updateParams,
  } = useOrgaAI();
 
  const handleStart = async () => {
    await startSession({
      onSessionConnected: () => console.log("Connected!"),
    });
    updateParams({ model: "orga-1-beta", voice: "alloy" });
  };
 
  return (
    <div className="p-6">
      <p>Connection: {connectionState}</p>
      <p>Mic: {isMicOn ? "On" : "Off"}</p>
 
      <div className="mt-4 space-x-2">
        <button onClick={toggleMic}>Toggle Mic</button>
        <button onClick={toggleCamera}>Toggle Camera</button>
        <button onClick={handleStart}>Start Session</button>
        <button onClick={endSession}>End Session</button>
      </div>
 
      <OrgaVideo stream={userVideoStream} className="w-full h-64 rounded bg-black mt-4" />
      <OrgaAudio stream={aiAudioStream} />
    </div>
  );
}

This creates a simple experience:

Starts a real‑time Orga session.
Toggles the mic and camera.
Updates AI model parameters on the fly.
Streams user and AI media to UI components.

Notes

⚙️ useOrgaAI only works when your component tree is wrapped in <OrgaAIProvider>.
🧠 Session configuration (model, voice, etc.) is shared globally within the provider context.
🪄 Debug connection events by initializing Orga with logLevel: 'debug':
```
OrgaAI.init({
  logLevel: 'debug',
  ...
});
```

Next Steps

Components → UI primitives such as <OrgaAIProvider> and media components.
Architecture → Understand how context, hooks, and the core runtime interact.
API Reference → Reference for the OrgaAI class.