@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 — enables session management (ClipsSession component)
• @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 apiKey="your-api-key" roomName="my-room">
      <ClipComposition
        enableRecording
        enableDragReorder
        maxClips={10}
        onClipAdded={(clip) => console.log('Added:', clip.name)}
        onError={(err) => console.error(err)}
      />
    </HiyveProvider>
  );
}
Copy

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 state machine: idle → requesting → ready → recording ⇄ paused → stopped → saving → ready

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

ClipsSession integrates with @hiyve/react-collaboration for file management:

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

<ClipsSession
  labels={{
    emptyState: { title: 'My Clips', createButton: 'New' },
  }}
  clipCompositionProps={{
    enableRecording: true,
    maxClips: 10,
  }}
  onError={(err) => console.error(err)}
  sx={{ height: '100%' }}
/>
Copy

The session provides an empty state with a file list and create button. Clicking "New Composition" opens a CreateCompositionDialog to name the composition before creation. When a composition is opened or created, it renders ClipComposition with a session header for save/close controls.

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)

19 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
• 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
• Pause/resume recording with duration tracking
• Max recording duration enforcement (configurable, hard limit 30 minutes)
• Imperative ref API for programmatic control
• Session management with file list integration (when @hiyve/react-collaboration is installed)
• 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 v5 or v6 (@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+)