@exode-team/react-recorder

Готовый компонент записи и отправки голосовых сообщений для React-приложений. Компонент инкапсулирует работу с MediaRecorder, визуализацию волны и UX-паттерн «нажал — запись началась», оставляя вам полный контроль над загрузкой файла и локализацией.

Возможности

• поддержка простого сценария «нажал — запись началась» без удержания и свайпов;
• встроенная визуализация уровней сигнала и предпросмотр записанного фрагмента;
• управление воспроизведением, паузой и повторным набором;
• адаптация текстов/aria-лейблов через проп messages;
• строгая типизация и SDK-подобный API (uploader, callbacks жизненного цикла).
• [NEW] Хук useVoiceRecorder для создания кастомного UI.

Установка

yarn add @exode-team/react-recorder styled-components
# или
npm install @exode-team/react-recorder styled-components

Компонент требует React 17+ и styled-components в качестве peer dependency.

Быстрый старт

import React from 'react';
import { AudioRecorder, StorageSpaceEnum } from '@exode-team/react-recorder';


const Example = () => {
    const uploader = async (file: File) => {
        const body = new FormData();
        body.append('file', file);
        const response = await fetch('/api/upload', { method: 'POST', body });
        return response.json();
    };

    return (
        <AudioRecorder uploader={uploader}
                       space={StorageSpaceEnum.User}
                       onUploaded={(file) => console.log('Uploaded', file)}
                       onUploadError={(error) => console.error(error)}/>
    );
};

API

<AudioRecorder />

| Проп | Тип | Обязателен | По умолчанию | Описание | |------------------------|----------------------------|------------|-------------------------|------------------------------------------------------------------------------| | uploader | UploadStrategy<T> | ✅ | — | Функция, которая принимает File и возвращает результат (DTO, URL и т. д.). | | onUploaded | (file: T) => void | — | — | Колбэк после успешной загрузки. | | onUploadError | (error: unknown) => void | — | — | Обработчик ошибок загрузки. | | space | StorageSpace | — | StorageSpaceEnum.User | Пространство хранения при загрузке. | | uploadId | string | — | crypto.randomUUID() | Идентификатор загрузки. | | messages | RecorderMessagesInput | — | встроенные тексты | Локализация кнопок и aria-лейблов. | | fileName | string | — | record.webm | Имя файла при сохранении. | | mimeType | string | — | audio/webm | MIME-тип создаваемого файла. | | autoResetAfterUpload | boolean | — | true | Сбрасывать UI после onUploaded. | | className | string | — | — | Пользовательский класс контейнера. | | onRecordingStart | () => void | — | — | Колбэк старта записи. | | onRecordingStop | (blob: Blob) => void | — | — | Колбэк остановки записи. | | onRecordingDelete | () => void | — | — | Колбэк удаления записанного файла. | | onRecordingError | (error: unknown) => void | — | — | Ошибка при записи. | | onPermissionDenied | (error: unknown) => void | — | — | Отказ в доступе к микрофону. |

useVoiceRecorder

Хук для создания собственного интерфейса записи, если стандартный AudioRecorder не подходит.

import { useVoiceRecorder } from '@exode-team/react-recorder';


const MyCustomRecorder = () => {
    const {
        isRecording,
        startRecording,
        stopRecording,
        audioURL
    } = useVoiceRecorder({
        onRecordingStop: (blob) => console.log('Recorded blob:', blob),
    });

    return (
        <div>
            <button onClick={isRecording ? stopRecording : startRecording}>
                {isRecording ? 'Stop' : 'Record'}
            </button>
            {audioURL && <audio src={audioURL} controls/>}
        </div>
    );
};

Параметры хука (UseVoiceRecorderOptions):

• space, uploadId, uploader, onUploaded
• fileName, mimeType
• autoResetAfterUpload
• onRecordingStart, onRecordingStop, onRecordingDelete, onRecordingError, onPermissionDenied

Возвращаемое значение (UseVoiceRecorderResult):

• Состояния: isRecording, isPaused, isPlaying, hasRecording
• Данные: audioURL, recordingTime, playbackTime, playbackDuration, audioLevels, previewLevels
• Методы: startRecording, stopRecording, cancelRecording, deleteRecording, toggleRecordingPause, togglePlayback, stopPlayback, sendRecording
• Утилиты: formatTime

Типы

StorageSpaceEnum

export const StorageSpaceEnum = {
    User: 'user',
    Shared: 'shared',
    System: 'system',
} as const;

Сборка

Команда yarn build (или npm run build) запускает Rollup, который собирает ESModule, CommonJS и декларации TypeScript. .npmignore настроен так, чтобы в пакет попадали только dist, README и LICENSE.

Лицензия

MIT © Exode.