@hiyve/react-clips

Clip composition tool with client-side recording, multi-clip grid, and media playback for Hiyve video conferencing.

Installation

npm install @hiyve/react-clips
Copy

Peer dependencies:

npm install @hiyve/react @hiyve/utilities @mui/material @mui/icons-material @emotion/react @emotion/styled react
Copy

Optional peer dependencies:

• @hiyve/react-collaboration — host ClipComposition inside FileSessionHost for full file-management workflows
• @hiyve/react-media-player — enhanced clip playback with waveforms, regions, and volume controls (falls back to native <audio> / <video> elements)

Quick Start

import { HiyveProvider } from '@hiyve/react';
import { ClipComposition } from '@hiyve/react-clips';

function App() {
  return (
    <HiyveProvider region="us-east-2">
      <ClipComposition
        enableRecording
        enableDragReorder
        maxClips={10}
        onClipAdded={(clip) => console.log('Added:', clip.name)}
        onError={(err) => console.error(err)}
      />
    </HiyveProvider>
  );
}
Copy

Tokens are generated automatically when your server uses @hiyve/admin middleware. See @hiyve/react for HiyveProvider configuration options.

Components

Hooks

Utilities

ClipComposition Props

Imperative Handle

ClipComposition exposes a ref with the following methods:

import { useRef } from 'react';
import { ClipComposition, type ClipCompositionRef } from '@hiyve/react-clips';

function MyEditor() {
  const ref = useRef<ClipCompositionRef>(null);

  return (
    <>
      <ClipComposition ref={ref} />
      <button onClick={() => ref.current?.save()}>Save Now</button>
    </>
  );
}
Copy

Using Hooks Directly

useClipRecorder

Record audio or video clips with device selection and max duration enforcement:

import { useClipRecorder } from '@hiyve/react-clips';

function MyRecorder() {
  const recorder = useClipRecorder({
    maxDuration: 120, // 2 minutes
    onError: (err) => console.error(err),
  });

  return (
    <div>
      <p>State: {recorder.state}</p>
      {recorder.state === 'idle' && (
        <button onClick={recorder.initialize}>Initialize</button>
      )}
      {recorder.state === 'ready' && (
        <button onClick={recorder.start}>Record</button>
      )}
      {recorder.state === 'recording' && (
        <>
          <span>{recorder.duration}s</span>
          <button onClick={recorder.pause}>Pause</button>
          <button onClick={recorder.stop}>Stop</button>
        </>
      )}
      {recorder.state === 'paused' && (
        <>
          <button onClick={recorder.resume}>Resume</button>
          <button onClick={recorder.stop}>Stop</button>
        </>
      )}
      {recorder.state === 'stopped' && recorder.previewUrl && (
        <>
          <audio src={recorder.previewUrl} controls />
          <button onClick={recorder.discard}>Discard</button>
        </>
      )}
    </div>
  );
}
Copy

Recorder states:

Audio capture profiles

Browsers capture microphone audio for phone calls by default: echo cancellation, noise suppression and automatic gain, downmixed to mono. That flattens an instrument or an audio interface into a compressed, band-limited recording. Clips therefore record with an instrument profile unless the user chooses otherwise: processing off, stereo and 48 kHz requested where the device allows, tracks tagged as music, and the encoder set to 256 kbps stereo (128 kbps mono) instead of the browser's voice-class default.

The voice profile keeps the browser's speech processing — the right choice for spoken notes, and for recording over speakers, since instrument does not remove speaker sound from the recording.

The user picks in ClipSettingsDialog; the choice is remembered. Set the starting profile per context with the audioProfile prop on ClipComposition / ClipRecorder, or the option on useClipRecorder; the hook exposes audioProfile and setAudioProfile.

// A composition used for spoken feedback, recorded over speakers
<ClipComposition audioProfile="voice" ... />
Copy

useClipPersistence

Auto-save composition data with retry logic:

import { useClipPersistence } from '@hiyve/react-clips';

const persistence = useClipPersistence({
  client,
  clips,
  title: 'My Composition',
  lockMode: 'unlocked',
  collaborationMode: 'public',
  enabled: true,
  userId: 'user-123',
  autoSaveInterval: 5000,
  onSaved: (fileId) => console.log('Saved:', fileId),
  onError: (err) => console.error(err),
});

// persistence.save()            — trigger manual save
// persistence.isSaving          — currently saving?
// persistence.hasUnsavedChanges — pending changes?
// persistence.lastSaved         — last save timestamp
// persistence.fileId            — current file ID
// persistence.markUnsaved()     — mark as changed
Copy

Session Management

For full file-management workflows (browse compositions, create new ones, switch between them) use FileSessionHost from @hiyve/react-collaboration with ClipComposition registered as the editor for the clip-composition resource type. See @hiyve/react-collaboration for details.

Customization

All visual aspects are customizable through four prop objects. Only override the keys you want to change — defaults are applied for the rest.

Labels (ClipCompositionLabels)

~40 text strings covering header, save status, toolbar, recorder, player, grid, collaboration, and error messages. Includes two functions: lastSaved(date) and clipCount(count).

<ClipComposition
  labels={{
    title: 'Sound Clips',
    startRecording: 'Record',
    noClips: 'No clips yet — start recording!',
    lastSaved: (date) => `Saved at ${date.toLocaleTimeString()}`,
  }}
/>
Copy

Icons (ClipCompositionIcons)

25 icon slots, each accepting a ReactNode. Defaults use @mui/icons-material.

import { MicNone, FiberManualRecord } from '@mui/icons-material';

<ClipComposition
  icons={{
    recordAudio: <MicNone />,
    startRecording: <FiberManualRecord color="error" />,
  }}
/>
Copy

Colors (ClipCompositionColors)

24 color values for container, header, toolbar, recorder, grid, clip cards, save status, and collaboration mode indicators.

<ClipComposition
  colors={{
    containerBackground: '#2d2d2d',
    recordingIndicator: '#e53935',
    clipCardBackground: '#383838',
  }}
/>
Copy

Styles (ClipCompositionStyles)

12 numeric/string values for border radius, padding, grid layout, and component dimensions.

<ClipComposition
  styles={{
    borderRadius: 12,
    gridGap: 16,
    gridMinColumnWidth: 320,
    playerHeight: 150,
  }}
/>
Copy

Defaults and Merge Functions

Features

• Record audio and video clips directly in the browser
• Multi-clip responsive grid with drag-and-drop reordering
• Toolbar transport controls for all clips together: synchronized Play All / Stop All, Rewind All, and an audio-passthrough master toggle (when passthrough is enabled)
• Enhanced playback with waveforms, named regions, and volume controls (when @hiyve/react-media-player is installed)
• Native <audio> / <video> fallback when media player is not available
• Auto-save with configurable interval and manual save trigger
• Lock/unlock compositions to prevent editing
• Private/public collaboration modes for clip visibility
• Device selection for microphone and camera
• Mirror the camera preview while recording video (on by default), remembered between sessions — preview only, the saved clip is never mirrored
• Pause/resume recording with duration tracking
• Max recording duration enforcement (configurable, hard limit 30 minutes)
• Imperative ref API for programmatic control
• Works both inside and outside HiyveProvider
• Fully customizable labels, icons, colors, and styles

Constants

Key Types

Style Utilities

Seven style-generating functions for building custom layouts:

Requirements

• React 18+
• MUI v9 (@mui/material, @mui/icons-material, @emotion/react, @emotion/styled)
• @hiyve/react — provides HiyveProvider context (components work outside the provider with limited functionality)
• @hiyve/utilities — debug logging and retry utilities
• Browser support: MediaRecorder API required for recording (Chrome, Firefox, Edge, Safari 14.1+)