@tavus/cvi-ui 0.0.1-beta.1

package/.prettierrc.js

@@ -0,0 +1,24 @@
+/** @type {import('prettier').Config} */
+export default {
+  semi: true,
+  singleQuote: true,
+  tabWidth: 2,
+  trailingComma: 'es5',
+  printWidth: 100,
+  bracketSpacing: true,
+  arrowParens: 'always',
+  endOfLine: 'lf',
+  // Remove comments
+  proseWrap: 'never',
+  htmlWhitespaceSensitivity: 'css',
+  embeddedLanguageFormatting: 'off',
+  singleAttributePerLine: false,
+  bracketSameLine: false,
+  jsxSingleQuote: false,
+  quoteProps: 'as-needed',
+  jsxBracketSameLine: false,
+  requirePragma: false,
+  insertPragma: false,
+  useTabs: true,
+  vueIndentScriptAndStyle: false,
+}; 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tavus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# Tavus CVI Component Library
+
+A CLI tool for installing and managing CVI (Conversational Video Interface) components for React applications. This library provides pre-built components for creating real-time multimodal video conversations with AI replicas.
+
+## Usage
+
+**Initialize the project**:
+
+   ```bash
+   npx @tavus/cvi-ui init
+   ```
+
+   This will:
+
+   - Create a `cvi-components.json` configuration file
+   - Prompt for TypeScript preference
+   - Install the necessary dependencies
+
+**Add components to your project**:
+
+   ```bash
+   npx @tavus/cvi-ui add conversation
+   ```
+
+**Wrap your app with the CVI provider**:
+
+   ```tsx
+   import { CVIProvider } from './components/cvi/components/cvi-provider';
+
+   function App() {
+     return (
+       <CVIProvider>
+         {/* Your app content */}
+       </CVIProvider>
+     );
+   }
+   ```
+
+**Add conversation components**:
+
+   ```tsx
+   import { Conversation } from './components/cvi/components/conversation';
+
+   function Call() {
+     return (
+       <div>
+         <Conversation {...conversationProps} />
+       </div>
+     );
+   }
+   ```
+
+## Available Components
+
+### Core Components
+
+- **`cvi-provider`** - Main provider component that wraps your app with CVI context
+
+### Hooks
+
+#### Core Call Management
+
+- **`use-cvi-call`** – Provides basic join and leave functionality for CVI calls.
+- **`use-start-haircheck`** – Manages device-permission checks and initializes the camera to start a haircheck session.
+
+#### Media Controls
+
+- **`use-local-camera`** – Manages local camera state and toggle functionality.
+- **`use-local-microphone`** – Manages local microphone state and toggle functionality.
+- **`use-local-screenshare`** – Manages screen-share state and toggle functionality.
+- **`use-request-permissions`** – Requests permissions and handles audio processing setup.
+
+#### Participant Management
+
+- **`use-replica-ids`** – Retrieves Tavus–replica participant IDs.
+- **`use-remote-participant-ids`** – Retrieves remote participant IDs.
+
+#### Conversation & Events
+
+- **`use-observable-event`** – Listens for CVI events.
+- **`use-send-app-message`** – Sends CVI app messages.
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Related Links
+
+- [CVI Documentation](https://docs.tavus.io/sections/conversational-video-interface/cvi-overview)
+- [Tavus Examples](https://github.com/Tavus-Engineering/tavus-examples)
+

package/dev-components/components/cvi-provider/index.tsx

@@ -0,0 +1,9 @@
+import { DailyProvider } from "@daily-co/daily-react";
+
+export const CVIProvider = ({ children }: { children: React.ReactNode }) => {
+  return (
+    <DailyProvider>
+      {children}
+    </DailyProvider>
+  )
+}

package/dev-components/hooks/README.md

@@ -0,0 +1,499 @@
+# CVI Hooks Documentation
+
+This documentation is organized by functionality to help you find the right hook for your needs.
+
+## Table of Contents
+
+### 🔧 Core Call Management
+
+- [useCVICall](#usecvicall) - Basic call join/leave functionality
+- [useStartHaircheck](#usestarthaircheck) - Device permissions and camera initialization
+
+### 🎥 Media Controls
+
+- [useLocalCamera](#uselocalcamera) - Camera state and toggle
+- [useLocalMicrophone](#uselocalmicrophone) - Microphone state and toggle
+- [useLocalScreenshare](#uselocalscreenshare) - Screen sharing state and toggle
+- [useRequestPermissions](#userequestpermissions) - Permission requests with audio processing
+
+### 👥 Participant Management
+
+- [useReplicaIDs](#usereplicaiids) - Get Tavus replica participant IDs
+- [useRemoteParticipantIDs](#useremoteparticipantiids) - Get remote participant IDs
+
+### 💬 Conversation & Events
+
+- [useObservableEvent](#useobservableevent) - Listen for CVI conversation events
+- [useSendAppMessage](#usesendappmessage) - Send CVI app messages
+
+---
+
+## 🔧 Core Call Management
+
+### useCVICall
+
+A React hook that provides basic call management functionality.
+
+#### Purpose
+
+- Manages call join/leave operations
+- Provides access to the Daily call instance
+
+#### Return Values
+
+| Property    | Type                        | Description                        |
+| ----------- | --------------------------- | ---------------------------------- |
+| `joinCall`  | `({ url: string }) => void` | Function to join a call by URL     |
+| `leaveCall` | `() => void`                | Function to leave the current call |
+
+#### Usage
+
+```tsx
+import { useCVICall } from './hooks/use-cvi-call';
+
+const CallManager = () => {
+  const { joinCall, leaveCall } = useCVICall();
+
+  const handleJoin = () => {
+    joinCall({ url: 'https://your-daily-room-url' });
+  };
+
+  return (
+    <div>
+      <button onClick={handleJoin}>Join Call</button>
+      <button onClick={leaveCall}>Leave Call</button>
+    </div>
+  );
+};
+```
+
+### useStartHaircheck
+
+A React hook that manages device permissions and camera initialization for the hair-check component.
+
+#### Purpose
+
+- Monitors device permission states
+- Starts camera and microphone when appropriate
+- Provides permission state for UI conditional rendering
+- Handles permission request flow
+
+#### Return Values
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `isPermissionsPrompt` | `boolean` | Browser is prompting for device permission |
+| `isPermissionsLoading` | `boolean` | Permissions are being processed or camera is initializing |
+| `isPermissionsGranted` | `boolean` | Device permission granted |
+| `isPermissionsDenied` | `boolean` | Device permission denied |
+| `requestPermissions` | `() => void` | Function to request camera and microphone permissions |
+
+#### Usage
+
+```tsx
+import { useStartHaircheck } from './hooks/use-start-haircheck';
+
+const HairCheckComponent = () => {
+  const {
+    isPermissionsPrompt,
+    isPermissionsLoading,
+    isPermissionsGranted,
+    isPermissionsDenied,
+    requestPermissions
+  } = useStartHaircheck();
+
+  useEffect(() => {
+    requestPermissions();
+  }, []);
+
+  return (
+    <div>
+      {isPermissionsLoading && <InitializingSpinner />}
+      {isPermissionsPrompt && <PermissionPrompt />}
+      {isPermissionsDenied && <PermissionDeniedMessage />}
+      {isPermissionsGranted && <VideoPreview />}
+    </div>
+  );
+};
+```
+
+---
+
+## 🎥 Media Controls
+
+### useLocalCamera
+
+A React hook that provides local camera state and toggle functionality.
+
+#### Purpose
+
+- Manages local camera state (on/off)
+- Tracks camera permission and ready state
+
+#### Return Values
+
+| Property         | Type         | Description                            |
+| ---------------- | ------------ | -------------------------------------- |
+| `onToggleCamera` | `() => void` | Function to toggle camera on/off       |
+| `isCamReady`     | `boolean`    | Camera permission is granted and ready |
+| `isCamMuted`     | `boolean`    | Camera is currently turned off         |
+
+#### Usage
+
+```tsx
+import { useLocalCamera } from './hooks/use-local-camera';
+
+const CameraControls = () => {
+  const { onToggleCamera, isCamReady, isCamMuted } = useLocalCamera();
+
+  return (
+    <button
+      onClick={onToggleCamera}
+      disabled={!isCamReady}
+    >
+      {isCamMuted ? 'Turn Camera On' : 'Turn Camera Off'}
+    </button>
+  );
+};
+```
+
+### useLocalMicrophone
+
+A React hook that provides local microphone state and toggle functionality.
+
+#### Purpose
+
+- Manages local microphone state (on/off)
+- Tracks microphone permission and ready state
+
+#### Return Values
+
+| Property             | Type         | Description                                |
+| -------------------- | ------------ | ------------------------------------------ |
+| `onToggleMicrophone` | `() => void` | Function to toggle microphone on/off       |
+| `isMicReady`         | `boolean`    | Microphone permission is granted and ready |
+| `isMicMuted`         | `boolean`    | Microphone is currently turned off         |
+
+#### Usage
+
+```tsx
+import { useLocalMicrophone } from './hooks/use-local-microphone';
+
+const MicrophoneControls = () => {
+  const { onToggleMicrophone, isMicReady, isMicMuted } = useLocalMicrophone();
+
+  return (
+    <button
+      onClick={onToggleMicrophone}
+      disabled={!isMicReady}
+    >
+      {isMicMuted ? 'Unmute' : 'Mute'}
+    </button>
+  );
+};
+```
+
+### useLocalScreenshare
+
+A React hook that provides local screen sharing state and toggle functionality.
+
+#### Purpose
+
+- Manages screen sharing state (on/off)
+- Provides screen sharing toggle function
+- Handles screen share start/stop with optimized display media options
+
+#### Return Values
+
+| Property              | Type         | Description                                |
+| --------------------- | ------------ | ------------------------------------------ |
+| `onToggleScreenshare` | `() => void` | Function to toggle screen sharing on/off   |
+| `isScreenSharing`     | `boolean`    | Whether screen sharing is currently active |
+
+#### Display Media Options
+
+When starting screen share, the hook uses the following optimized settings:
+
+- **Audio**: Disabled (false)
+- **Self Browser Surface**: Excluded
+- **Surface Switching**: Included
+- **Video Resolution**: 1920x1080
+
+#### Usage
+
+```tsx
+import { useLocalScreenshare } from './hooks/use-local-screenshare';
+
+const ScreenShareControls = () => {
+  const { onToggleScreenshare, isScreenSharing } = useLocalScreenshare();
+
+  return (
+    <button
+      onClick={onToggleScreenshare}
+      className={isScreenSharing ? 'active' : ''}
+    >
+      {isScreenSharing ? 'Stop Sharing' : 'Share Screen'}
+    </button>
+  );
+};
+```
+
+### useRequestPermissions
+
+A React hook that requests camera and microphone permissions with optimized audio processing settings.
+
+#### Purpose
+
+- Requests camera and microphone permissions from the user
+- Starts camera and audio with specific configuration
+- Applies noise cancellation audio processing
+- Provides a clean interface for permission requests
+
+#### Return Values
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `requestPermissions` | `() => Promise<DailyDeviceInfos>` | Function to request camera and microphone permissions |
+
+#### Configuration
+
+When requesting permissions, the hook uses the following settings:
+
+- **Video**: Started on (startVideoOff: false)
+- **Audio**: Started on (startAudioOff: false)
+- **Audio Source**: Default system audio input
+- **Audio Processing**: Noise cancellation enabled
+
+#### Usage
+
+```tsx
+import { useRequestPermissions } from './hooks/use-request-permissions';
+
+const PermissionRequest = () => {
+  const requestPermissions = useRequestPermissions();
+
+  const handleRequestPermissions = async () => {
+    try {
+      await requestPermissions();
+      console.log('Permissions granted successfully');
+    } catch (error) {
+      console.error('Failed to get permissions:', error);
+    }
+  };
+
+  return (
+    <button onClick={handleRequestPermissions}>
+      Request Camera & Microphone Permissions
+    </button>
+  );
+};
+```
+
+---
+
+## 👥 Participant Management
+
+### useReplicaIDs
+
+A React hook that returns the IDs of all Tavus replica participants in a call.
+
+#### Purpose
+
+- Filters and returns participant IDs where `user_id` includes 'tavus-replica'
+
+#### Return Value
+
+- `string[]` — Array of replica participant IDs
+
+#### Usage
+
+```tsx
+import { useReplicaIDs } from './hooks/use-replica-ids';
+
+const ids = useReplicaIDs();
+// ids is an array of participant IDs for Tavus replicas
+```
+
+### useRemoteParticipantIDs
+
+A React hook that returns the IDs of all remote participants in a call.
+
+#### Purpose
+
+- Returns participant IDs for all remote participants (excluding local user)
+
+#### Return Value
+
+- `string[]` — Array of remote participant IDs
+
+#### Usage
+
+```tsx
+import { useRemoteParticipantIDs } from './hooks/use-remote-participant-ids';
+
+const remoteIds = useRemoteParticipantIDs();
+// remoteIds is an array of remote participant IDs
+```
+
+---
+
+## 💬 Conversation & Events
+
+### useObservableEvent
+
+A React hook that listens for CVI app messages and provides a callback mechanism for handling various conversation events.
+
+#### Purpose
+
+- Listens for app messages from the Daily.co call mapped to CVI events
+- Handles various conversation event types (utterances, tool calls, speaking events, etc.)
+- Provides type-safe event handling for CVI interactions
+
+#### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `callback` | `(event: AppMessage<T>['data']) => void` | Function called when app messages are received |
+
+#### Event Types
+
+This hook handles all CVI conversation events. For detailed information about each event type, see the [Tavus Interactions Protocol Documentation](https://docs.tavus.io/sections/conversational-video-interface/live-interactions).
+
+#### Usage
+
+```tsx
+import { useObservableEvent } from './hooks/cvi-events-hooks';
+
+const ConversationHandler = () => {
+  useObservableEvent((event) => {
+    switch (event.event_type) {
+      case 'conversation.utterance':
+        console.log('Speech:', event.properties.speech);
+        break;
+      case 'conversation.replica.started_speaking':
+        console.log('Replica started speaking');
+        break;
+      case 'conversation.user.stopped_speaking':
+        console.log('User stopped speaking');
+        break;
+    }
+  });
+
+  return <div>Listening for conversation events...</div>;
+};
+```
+
+### useSendAppMessage
+
+A React hook that provides a function to send CVI app messages to other participants in the call.
+
+#### Purpose
+
+- Sends various types of conversation messages to the CVI system
+- Supports echo, respond, interrupt, and context management messages
+- Provides type-safe message sending with proper validation
+- Enables real-time communication with Tavus replicas and conversation management
+
+#### Return Value
+
+- `(message: SendAppMessageProps) => void` - Function that sends the message when called
+
+#### Message Types
+
+This hook supports all CVI interaction types. For detailed information about each interaction type and their properties, see the [Tavus Interactions Protocol Documentation](https://docs.tavus.io/sections/conversational-video-interface/live-interactions).
+
+#### Usage
+
+```tsx
+import { useSendAppMessage } from './hooks/cvi-events-hooks';
+
+const MessageSender = () => {
+  const sendMessage = useSendAppMessage();
+
+  // Send a text echo
+  const sendTextEcho = () => {
+    sendMessage({
+      message_type: "conversation",
+      event_type: "conversation.echo",
+      conversation_id: "conv-123",
+      properties: {
+        modality: "text",
+        text: "Hello, world!",
+        audio: "",
+        sample_rate: 16000,
+        inference_id: "inf-456",
+        done: true
+      }
+    });
+  };
+
+  // Send a text response
+  const sendResponse = () => {
+    sendMessage({
+      message_type: "conversation",
+      event_type: "conversation.respond",
+      conversation_id: "conv-123",
+      properties: {
+        text: "This is my response to the conversation."
+      }
+    });
+  };
+
+  // Interrupt the current conversation
+  const interruptConversation = () => {
+    sendMessage({
+      message_type: "conversation",
+      event_type: "conversation.interrupt",
+      conversation_id: "conv-123"
+    });
+  };
+
+  // Overwrite LLM context
+  const updateContext = () => {
+    sendMessage({
+      message_type: "conversation",
+      event_type: "conversation.overwrite_llm_context",
+      conversation_id: "conv-123",
+      properties: {
+        context: "New conversation context that replaces the existing one."
+      }
+    });
+  };
+
+  // Append to LLM context
+  const appendContext = () => {
+    sendMessage({
+      message_type: "conversation",
+      event_type: "conversation.append_llm_context",
+      conversation_id: "conv-123",
+      properties: {
+        context: "Additional context to append to the existing conversation."
+      }
+    });
+  };
+
+  // Adjust sensitivity settings
+  const adjustSensitivity = () => {
+    sendMessage({
+      message_type: "conversation",
+      event_type: "conversation.sensitivity",
+      conversation_id: "conv-123",
+      properties: {
+        participant_pause_sensitivity: "medium",
+        participant_interrupt_sensitivity: "high"
+      }
+    });
+  };
+
+  return (
+    <div>
+      <button onClick={sendTextEcho}>Send Text Echo</button>
+      <button onClick={sendResponse}>Send Response</button>
+      <button onClick={interruptConversation}>Interrupt</button>
+      <button onClick={updateContext}>Update Context</button>
+      <button onClick={appendContext}>Append Context</button>
+      <button onClick={adjustSensitivity}>Adjust Sensitivity</button>
+    </div>
+  );
+};
+```