# @hiyve/react-capture

Recording, streaming, and transcription components for Hiyve.

## Installation

```bash
npx @hiyve/cli login
npm install @hiyve/react-capture
```

## Quick Start

```tsx
import {
  RecordingControls,
  RecordingIndicator,
  StreamingControls,
  TranscriptViewer,
  TranscriptionControls,
} from '@hiyve/react-capture';
import { HiyveProvider } from '@hiyve/react';

function MeetingRoom() {
  return (
    <HiyveProvider generateRoomToken={generateRoomToken}>
      <RecordingIndicator size="medium" />
      <RecordingControls
        onRecordingStarted={(id) => console.log('Recording:', id)}
        onRecordingStopped={() => console.log('Stopped')}
      />
      <StreamingControls
        onStreamingStart={() => console.log('Live')}
        onStreamingStop={() => console.log('Off air')}
      />
      <TranscriptionControls />
      <TranscriptViewer maxHeight={400} />
    </HiyveProvider>
  );
}
```

## Components

### Recording

| Component | Description |
|-----------|-------------|
| `RecordingControls` | Start/stop recording with options for transcription, auto-compose, and meeting summary |
| `RecordingIndicator` | Visual indicator showing active recording status with elapsed time |

### Streaming

| Component | Description |
|-----------|-------------|
| `StreamingControls` | Start/stop live streaming with RTMP configuration |
| `StreamingIndicator` | Visual indicator showing active streaming status with elapsed time |
| `StreamingUrlDisplay` | Displays and copies the stream URL |
| `StreamingSettingsDialog` | Full-screen dialog for configuring streaming options (cloud vs. custom RTMP, display mode, MP4 save) |
| `StreamingSettingsForm` | Inline form variant of streaming settings |

### Transcription

| Component | Description |
|-----------|-------------|
| `TranscriptViewer` | Scrollable, real-time transcript display grouped by speaker |
| `TranscriptionControls` | Start/stop live transcription |
| `TranscriptionGroup` | Renders a single speaker group within the transcript |

## Hooks

| Hook | Description |
|------|-------------|
| `useTranscriptionGrouping` | Groups transcription entries by speaker and time window |
| `useStreamingDuration` | Tracks elapsed streaming time in seconds |

## Utilities

| Export | Description |
|--------|-------------|
| `formatDuration` | Formats seconds into `M:SS` or `H:MM:SS` display |
| `groupByDate` | Groups transcription entries by date |
| `getSpeakerColor` | Returns a deterministic color for a speaker ID |
| `formatTimestamp` | Formats a transcription timestamp for display |
| `getConfidenceLevel` | Returns `'high'`, `'medium'`, or `'low'` from a confidence score |
| `needsDateDivider` | Checks whether a date divider should be shown between two transcription entries |
| `formatDateDivider` | Formats a date for display as a divider between transcription groups |
| `getDisplayName` | Returns a display name for a speaker, falling back to user ID |
| `getInitials` | Returns initials from a speaker name or ID |
| `getSentimentColor` | Returns a color string for a sentiment value |
| `debounce` | Debounces a function call by the given delay |
| `formatTranscriptionDuration` | Formats seconds into a duration string (alias of `formatDuration` from transcription) |

## Key Types

### Recording

| Type | Description |
|------|-------------|
| `RecordingControlsProps` | Props for the `RecordingControls` component |
| `RecordingIndicatorProps` | Props for the `RecordingIndicator` component |
| `RecordingOptions` | Options passed when starting a recording |
| `RecordingControlsLabels` | Label overrides for recording controls |
| `RecordingControlsIcons` | Icon overrides for recording controls |
| `RecordingControlsStyles` | Style overrides for recording controls |
| `RecordingIndicatorColors` | Color overrides for the recording indicator |
| `RecordingIndicatorStyles` | Style overrides for the recording indicator |
| `RecordingIndicatorSizeConfig` | Size configuration for the recording indicator |

### Streaming

| Type | Description |
|------|-------------|
| `StreamingControlsProps` | Props for the `StreamingControls` component |
| `StreamingIndicatorProps` | Props for the `StreamingIndicator` component |
| `StreamingUrlDisplayProps` | Props for the `StreamingUrlDisplay` component |
| `StreamingSettingsDialogProps` | Props for the `StreamingSettingsDialog` component |
| `StreamingSettingsFormProps` | Props for the `StreamingSettingsForm` component |
| `StreamingOptions` | Options passed when starting a stream |
| `StreamingMode` | Streaming mode (`'cloud'` or `'custom'`) |
| `StreamingConfig` | Full streaming configuration object |
| `StreamingControlsLabels` | Label overrides for streaming controls |
| `StreamingControlsIcons` | Icon overrides for streaming controls |
| `StreamingControlsStyles` | Style overrides for streaming controls |
| `StreamingIndicatorColors` | Color overrides for the streaming indicator |
| `StreamingIndicatorStyles` | Style overrides for the streaming indicator |
| `StreamingIndicatorSizeConfig` | Size configuration for the streaming indicator |
| `StreamingUrlLabels` | Label overrides for the URL display |
| `StreamingSettingsLabels` | Label overrides for the settings dialog/form |

### Transcription

| Type | Description |
|------|-------------|
| `TranscriptionEntry` | A single transcription entry with speaker, text, and timestamp |
| `TranscriptionGroupType` | A group of transcription entries by the same speaker |
| `TranscriptViewerProps` | Props for the `TranscriptViewer` component |
| `TranscriptionControlsProps` | Props for the `TranscriptionControls` component |
| `TranscriptionGroupProps` | Props for the `TranscriptionGroup` component |
| `TranscriptionLabels` | Label overrides for the transcript viewer |
| `TranscriptionControlLabels` | Label overrides for transcription controls |
| `TranscriptionColors` | Color overrides for the transcript viewer |
| `TranscriptionControlColors` | Color overrides for transcription controls |
| `TranscriptionStyles` | Style overrides for the transcript viewer |

## Customization

Every component supports customization through `labels`, `icons`, `colors`, and `styles` props. Pass a partial object to override only the values you need -- unspecified keys use defaults.

### Recording

```tsx
import {
  RecordingControls,
  defaultRecordingControlsLabels,
  defaultRecordingIndicatorColors,
} from '@hiyve/react-capture';

// Localize labels
<RecordingControls
  labels={{
    record: 'Grabar',
    stopRecording: 'Detener',
    startRecording: 'Iniciar',
  }}
/>

// Custom indicator colors
<RecordingIndicator
  isRecording={true}
  colors={{
    background: 'rgba(0, 0, 0, 0.5)',
    indicator: '#ffffff',
    text: '#ffffff',
  }}
  size="large"
/>
```

**Recording defaults and merge functions:**

| Default | Merge Function |
|---------|---------------|
| `defaultRecordingControlsLabels` | `mergeRecordingControlsLabels` |
| `defaultRecordingControlsIcons` | `mergeRecordingControlsIcons` |
| `defaultRecordingControlsStyles` | `mergeRecordingControlsStyles` |
| `defaultRecordingIndicatorColors` | `mergeRecordingIndicatorColors` |
| `defaultRecordingIndicatorStyles` | `mergeRecordingIndicatorStyles` |
| `defaultRecordingIndicatorSizeConfigs` | -- |

### Streaming

```tsx
import {
  StreamingControls,
  StreamingSettingsDialog,
} from '@hiyve/react-capture';

// Localize streaming controls
<StreamingControls
  labels={{
    goLive: 'En direct',
    stopStreaming: 'Couper',
  }}
  icons={{
    live: <MyLiveIcon />,
  }}
/>

// Custom streaming settings dialog labels
<StreamingSettingsDialog
  open={open}
  onClose={() => setOpen(false)}
  labels={{
    title: 'Options de diffusion',
    cloudStreaming: 'Cloud',
    customRtmp: 'RTMP personnalise',
  }}
/>
```

**Streaming defaults and merge functions:**

| Default | Merge Function |
|---------|---------------|
| `defaultStreamingControlsLabels` | `mergeStreamingControlsLabels` |
| `defaultStreamingControlsIcons` | `mergeStreamingControlsIcons` |
| `defaultStreamingControlsStyles` | `mergeStreamingControlsStyles` |
| `defaultStreamingIndicatorColors` | `mergeStreamingIndicatorColors` |
| `defaultStreamingIndicatorStyles` | `mergeStreamingIndicatorStyles` |
| `defaultStreamingIndicatorSizeConfigs` | -- |
| `defaultStreamingUrlLabels` | `mergeStreamingUrlLabels` |
| `defaultStreamingSettingsLabels` | `mergeStreamingSettingsLabels` |
| `defaultStreamingConfig` | -- |

### Transcription

```tsx
import {
  TranscriptViewer,
  TranscriptionControls,
  defaultTranscriptionColors,
} from '@hiyve/react-capture';

// Light theme transcript viewer
<TranscriptViewer
  colors={{
    background: '#ffffff',
    text: '#212121',
    localUser: '#1565c0',
  }}
  styles={{
    padding: 20,
    fontSize: '1rem',
  }}
  maxHeight={500}
/>

// Custom control labels
<TranscriptionControls
  labels={{
    startTranscription: 'Begin',
    stopTranscription: 'End',
    transcribing: 'Active...',
  }}
/>
```

**Transcription defaults and merge functions:**

| Default | Merge Function |
|---------|---------------|
| `defaultTranscriptionLabels` | `mergeTranscriptionLabels` |
| `defaultTranscriptionControlLabels` | `mergeTranscriptionControlLabels` |
| `defaultTranscriptionColors` | `mergeTranscriptionColors` |
| `defaultTranscriptionControlColors` | `mergeTranscriptionControlColors` |
| `defaultTranscriptionStyles` | `mergeTranscriptionStyles` |

## Requirements

- **`@hiyve/react`** (`^2.0.0`) -- components must be rendered inside `HiyveProvider`
- **`@hiyve/rtc-client`** -- WebRTC client (provided by HiyveProvider)
- **`@hiyve/utilities`** (`^1.0.0`)
- **`@mui/material`** (`^5.0.0 || ^6.0.0`) and **`@mui/icons-material`**
- **`@emotion/react`** (`>=11`) and **`@emotion/styled`** (`>=11`)
- **`react`** (`^18.0.0`)

## License

Proprietary - Hiyve SDK