@tavus/cvi-ui 0.0.1-beta.2 → 0.0.1-beta.4

package/README.md

@@ -2,102 +2,69 @@
 
 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
+## Quick Start
 
 **Initialize the project**:
 
-   ```bash
-   npx @tavus/cvi-ui init
-   ```
+```bash
+npx @tavus/cvi-ui@latest init
+```
 
-   This will:
+This will:
 
-   - Create a `cvi-components.json` configuration file
-   - Prompt for TypeScript preference
-   - Install the necessary dependencies
+- 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
-   ```
+```bash
+npx @tavus/cvi-ui@latest add conversation
+```
 
 **Wrap your app with the CVI provider**:
 
-   ```tsx
-   import { CVIProvider } from './components/cvi/components/cvi-provider';
+```tsx
+import { CVIProvider } from './components/cvi/components/cvi-provider';
 
-   function App() {
-     return (
-       <CVIProvider>
-         {/* Your app content */}
-       </CVIProvider>
-     );
-   }
-   ```
+function App() {
+  return (
+    <CVIProvider>
+      {/* Your app content */}
+    </CVIProvider>
+  );
+}
+```
 
 **Add conversation components**:
 
-   ```tsx
-   import { Conversation } from './components/cvi/components/conversation';
+```tsx
+import { Conversation } from './components/cvi/components/conversation';
 
-   function Call() {
-     return (
-       <div>
-         <Conversation {...conversationProps} />
-       </div>
-     );
-   }
-   ```
+function CVI() {
+  return (
+    <div
+      style={{
+        width: '100%',
+        height: '100%',
+        maxWidth: '1200px',
+        margin: '0 auto',
+      }}
+    >
+      <Conversation conversationUrl='YOUR_TAVUS_MEETING_URL' onLeave={() => {}} />
+    </div>
+  );
+}
+```
 
-## Available Components
+## Documentation
 
-### Core Components
+- [CVI Documentation](https://docs.tavus.io/sections/conversational-video-interface/component-library/overview)
 
-- **`cvi-provider`** - Main provider component that wraps your app with CVI context
+## Examples
 
-### UI Components
-
-- **`controls`** - Video chat control buttons with device selection capabilities
-  - `MicrophoneButton` - Toggle microphone with device dropdown
-  - `CameraButton` - Toggle camera with device dropdown  
-  - `ScreenShareButton` - Toggle screen sharing
-
-- **`hair-check`** - Pre-call interface for testing and configuring audio/video devices
-  - Live camera preview with mirror effect
-  - Permission management and device controls
-  - Join interface with loading states
-
-### 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.
+- [Tavus Examples](https://github.com/Tavus-Engineering/tavus-examples)
 
 ## 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/README.md

@@ -2,100 +2,186 @@
 
 ## Components
 
-### Controls
+### Hair Check 01
 
-The `Controls` component provides a set of video chat control buttons with integrated device selection capabilities.
+The `HairCheck` component provides a pre-call interface for users to test and configure their audio/video devices before joining a video chat.
+
+#### Features:
+
+- **Device Testing**: Live preview of camera feed with mirror effect
+- **Permission Management**: Handles camera and microphone permission requests
+- **Device Controls**: Integrated microphone and camera controls
+- **Join Interface**: Call-to-action button to join the video chat
+- **Responsive Design**: Works on both desktop and mobile devices
+
+#### Usage:
+
+```tsx
+import { HairCheck } from './hair-check';
+
+<HairCheck
+  isJoinBtnLoading={false}
+  onJoin={() => handleJoinCall()}
+  onCancel={() => handleCancel()}
+/>
+```
+
+#### Props:
+
+- `isJoinBtnLoading` (boolean): Shows loading state on join button
+- `onJoin` (function): Callback when user clicks join
+- `onCancel` (function, optional): Callback when user cancels
+
+#### Key Features:
+
+- Automatic permission request flow
+- Visual feedback for different permission states
+- Fallback user avatar when camera is unavailable
+- Integrated device controls for easy testing
+- Clean, intuitive interface for pre-call setup
+
+### Conversation 01
+
+The `Conversation` component provides a complete video chat interface for one-to-one conversations with AI replicas, featuring main video display, self-view preview, and integrated controls.
+
+#### Features:
+
+- **Main Video Display**: Large video area showing the AI replica or screen share
+- **Self-View Preview**: Small preview window showing local camera feed
+- **Screen Sharing Support**: Automatic switching between replica video and screen share
+- **Device Controls**: Integrated microphone, camera, and screen share controls
+- **Error Handling**: Graceful handling of camera/microphone permission errors
+- **Responsive Layout**: Adaptive design for different screen sizes
+
+#### Usage:
+
+```tsx
+import { Conversation } from './conversation-01';
+
+<Conversation
+  conversationUrl={conversationUrl}
+  onLeave={() => handleLeaveCall()}
+/>
+```
+
+#### Props:
+
+- `conversationUrl` (string): Daily.co room URL for joining
+- `onLeave` (function): Callback when user leaves the conversation
+
+### Audio Wave
+
+The `AudioWave` component provides real-time audio level visualization for video chat participants, displaying animated bars that respond to audio input levels.
+
+#### Features:
+
+- **Real-time Audio Visualization**: Three animated bars that respond to audio levels
+- **Active Speaker Detection**: Visual distinction between active and inactive speakers
+- **Performance Optimized**: Uses `requestAnimationFrame` for smooth animations
+- **Responsive Design**: Compact circular design that fits well in video previews
+- **Audio Level Scaling**: Intelligent volume scaling for consistent visual feedback
+
+#### Usage:
+
+```tsx
+import { AudioWave } from './audio-wave';
+
+<AudioWave id={participantId} />
+```
+
+#### Props:
+
+- `id` (string): The participant's session ID to monitor audio levels for
+
+### Media Controls
+
+The `media-controls` module provides simple toggle buttons for microphone, camera, and screen sharing, designed for direct use in video chat interfaces.
 
 #### Exported Components:
 
-- **`MicrophoneButton`**: A button component that toggles microphone on/off with a dropdown for device selection
-- **`CameraButton`**: A button component that toggles camera on/off with a dropdown for device selection
-- **`ScreenShareButton`**: A button component that toggles screen sharing on/off
+- **`MicToggleButton`**: Toggles microphone mute/unmute state
+- **`CameraToggleButton`**: Toggles camera on/off
+- **`ScreenShareButton`**: Toggles screen sharing on/off
 
 #### Usage:
 
 ```tsx
-import { MicrophoneButton, CameraButton, ScreenShareButton } from './controls';
+import { MicToggleButton, CameraToggleButton, ScreenShareButton } from './media-controls';
 
-// Use individual control buttons
-<MicrophoneButton />
-<CameraButton />
+<MicToggleButton />
+<CameraToggleButton />
 <ScreenShareButton />
 ```
 
-#### Component Details:
+#### Key Features:
 
-**MicrophoneButton**
+- Simple, accessible toggle buttons
+- Visual state indicators (muted, unmuted, on/off)
+- Disabled state when device is not ready
+- Uses Daily.co hooks for device state
+- CSS modules for styling
 
-- Toggles microphone mute/unmute state
-- Shows visual indicators for muted/unmuted states
-- Includes device selection dropdown
-- Disabled when microphone is not ready
-- Uses `useLocalMicrophone` and `useDevices` hooks
+---
 
-**CameraButton**
+### Device Select
 
-- Toggles camera on/off
-- Shows visual indicators for camera muted/unmuted states
-- Includes device selection dropdown
-- Disabled when camera is not ready or no camera is available
-- Uses `useLocalCamera` and `useDevices` hooks
+The `device-select` module provides advanced device selection controls, including dropdowns for choosing microphones and cameras, and integrated toggle buttons.
 
-**ScreenShareButton**
+#### Exported Components:
 
-- Toggles screen sharing on/off
-- Shows visual feedback with different icons for active/inactive states
-- Uses `useLocalScreenshare` hook
+- **`SelectDevice`**: Dropdown for selecting a device from a list
+- **`MicSelectBtn`**: Microphone toggle button with device selection
+- **`CameraSelectBtn`**: Camera toggle button with device selection
+- **`ScreenShareButton`**: Button to toggle screen sharing
 
-**SelectDevice**
+#### Usage:
 
-- Reusable dropdown component for device selection
-- Accepts devices array, current value, disabled state, and onChange handler
-- Includes custom dropdown arrow styling
+```tsx
+import { SelectDevice, MicSelectBtn, CameraSelectBtn, ScreenShareButton } from './device-select';
 
-#### Key Features:
+<SelectDevice value={currentDeviceId} devices={devices} disabled={false} onChange={setDevice} />
+<MicSelectBtn />
+<CameraSelectBtn />
+<ScreenShareButton />
+```
 
-- Automatic device detection and switching via Daily.co hooks
-- Visual state indicators with SVG icons
-- Accessibility support with screen reader labels (`srOnly` class)
-- Responsive design with mobile-friendly controls
-- Integration with Daily.co device management system
-- CSS modules for scoped styling
+#### Props (SelectDevice):
 
-### Hair Check
+- `value` (string): Currently selected device ID
+- `devices` (array): List of device objects `{ device: MediaDeviceInfo }[]`
+- `disabled` (boolean): Whether the dropdown is disabled
+- `onChange` (function): Callback when device is changed
 
-The `HairCheck` component provides a pre-call interface for users to test and configure their audio/video devices before joining a video chat.
+#### Key Features:
 
-#### Features:
+- Integrated device selection and toggling
+- Dropdowns for camera/microphone selection
+- Visual state indicators and accessibility support
+- Uses Daily.co device management hooks
+- CSS modules for styling
 
-- **Device Testing**: Live preview of camera feed with mirror effect
-- **Permission Management**: Handles camera and microphone permission requests
-- **Device Controls**: Integrated microphone and camera controls
-- **Join Interface**: Call-to-action button to join the video chat
-- **Responsive Design**: Works on both desktop and mobile devices
+---
+
+### CVI Provider
+
+The `CVIProvider` component wraps your app with the Daily.co provider context, enabling all Daily React hooks and components to function.
 
 #### Usage:
 
 ```tsx
-import { HairCheck } from './hair-check';
+import { CVIProvider } from './cvi-provider';
 
-<HairCheck
-  isJoinBtnLoading={false}
-  onJoin={() => handleJoinCall()}
-  onCancel={() => handleCancel()}
-/>
+<CVIProvider>
+  {/* your app components */}
+</CVIProvider>
 ```
 
 #### Props:
 
-- `isJoinBtnLoading` (boolean): Shows loading state on join button
-- `onJoin` (function): Callback when user clicks join
-- `onCancel` (function, optional): Callback when user cancels
+- `children` (ReactNode): Components to be wrapped by the provider
 
 #### Key Features:
 
-- Automatic permission request flow
-- Visual feedback for different permission states
-- Fallback user avatar when camera is unavailable
-- Integrated device controls for easy testing
-- Clean, intuitive interface for pre-call setup
+- Provides Daily.co context to all child components
+- Required for using Daily React hooks and video/audio components
+- Simple wrapper for app-level integration

package/dev-components/components/audio-wave/audio-wave.module.css

@@ -0,0 +1,33 @@
+.container {
+	overflow: hidden;
+	border: 1px solid white;
+	width: 1.5rem;
+	height: 1.5rem;
+	border-radius: 9999px;
+	will-change: transform;
+	transform: translateZ(0);
+}
+
+.waveContainer {
+	display: flex;
+	justify-content: center;
+	align-items: center;
+	gap: 0.125rem;
+	width: 100%;
+	height: 100%;
+}
+
+.bar {
+	width: 0.25rem;
+	height: 0.25rem;
+	background-color: white;
+	border-radius: 9999px;
+	transition: height 200ms ease-out;
+	will-change: height;
+	transform: translateZ(0);
+}
+
+.barInactive {
+	width: 0.25rem !important;
+	height: 0.25rem !important;
+}

package/dev-components/components/audio-wave/index.tsx

@@ -0,0 +1,55 @@
+import React, { useCallback, useRef, memo } from "react";
+import { useActiveSpeakerId } from "@daily-co/daily-react";
+import { useAudioLevelObserver } from "@daily-co/daily-react";
+import styles from "./audio-wave.module.css";
+
+export const AudioWave = memo(({ id }: { id: string }) => {
+	const activeSpeakerId = useActiveSpeakerId();
+	const isActiveSpeaker = activeSpeakerId === id;
+
+	const leftBarRef = useRef<HTMLDivElement>(null);
+	const centerBarRef = useRef<HTMLDivElement>(null);
+	const rightBarRef = useRef<HTMLDivElement>(null);
+	const animationFrameRef = useRef<number | undefined>(undefined);
+
+	useAudioLevelObserver(
+		id,
+		useCallback((volume) => {
+			// Cancel any pending animation frame to prevent accumulation
+			if (animationFrameRef.current) {
+				cancelAnimationFrame(animationFrameRef.current);
+			}
+
+			// Use requestAnimationFrame to batch DOM updates
+			animationFrameRef.current = requestAnimationFrame(() => {
+				const scaledVolume = Number(Math.max(0.01, volume).toFixed(2));
+				if (leftBarRef.current && centerBarRef.current && rightBarRef.current) {
+					leftBarRef.current.style.height = `${20 + scaledVolume * 40}%`;
+					centerBarRef.current.style.height = `${20 + scaledVolume * 130}%`;
+					rightBarRef.current.style.height = `${20 + scaledVolume * 40}%`;
+				}
+			});
+		}, []),
+	);
+
+	return (
+		<div className={styles.container}>
+			<div className={styles.waveContainer}>
+				<div
+					ref={leftBarRef}
+					className={`${styles.bar} ${!isActiveSpeaker ? styles.barInactive : ''}`}
+				/>
+				<div
+					ref={centerBarRef}
+					className={`${styles.bar} ${!isActiveSpeaker ? styles.barInactive : ''}`}
+				/>
+				<div
+					ref={rightBarRef}
+					className={`${styles.bar} ${!isActiveSpeaker ? styles.barInactive : ''}`}
+				/>
+			</div>
+		</div>
+	);
+});
+
+AudioWave.displayName = 'AudioWave';