@vidtreo/recorder-react 1.8.0 → 1.10.0

package/README.md

@@ -9,7 +9,7 @@ npm install @vidtreo/recorder-react
 ```
 
 **Peer Dependencies:**
-- `@vidtreo/recorder >=1.0.5`
+- `@vidtreo/recorder >=1.9.0`
 - `react >=18.0.0`
 - `react-dom >=18.0.0`
 
@@ -48,6 +48,7 @@ import VidtreoRecorder from '@vidtreo/recorder-react';
 |------|------|----------|---------|-------------|
 | `apiKey` | `string` | No* | - | API key for authentication. Required if `VIDTREO_API_KEY` env var not set and `getAccessToken` is not used. |
 | `getAccessToken` | `() => Promise<string>` | No* | - | Returns a short-lived desktop access token minted by your server. Use instead of `apiKey` (exactly one of the two; passing both shows a configuration error, see [Credentials](#temporary-access-tokens)). Called again whenever a fresh token is needed, including when a queued upload resumes after a reload. |
+| `audioOnly` | `boolean` | No | `false` | Record audio from the microphone only. See [Audio-Only Recording](#audio-only-recording) |
 | `countdownDuration` | `number` | No | - | Countdown duration in milliseconds before recording starts |
 | `minTimeRecord` | `number` | No | - | Minimum recording time in milliseconds before stop is allowed. Must not be greater than `maxRecordingTime` when both are positive. |
 | `maxRecordingTime` | `number` | No | - | Maximum recording time in milliseconds |
@@ -74,6 +75,29 @@ import VidtreoRecorder from '@vidtreo/recorder-react';
 `tabVisibilityOverlayText` is optional. When `enableTabVisibilityOverlay` is enabled and text is omitted, the component
 uses a localized default based on `lang` and `texts`. Overlay rendering is skipped for screen capture recordings.
 
+### Audio-Only Recording
+
+Set `audioOnly` to record from the microphone only. The camera is never requested and no video preview is rendered. The recorder shows a compact voice-note pill (about 20rem wide, 56px high): a red record/stop button, a live waveform of dots that freezes while paused or uploading, the elapsed time (with `/ 10:00` when the environment sets a maximum duration) and a microphone button that opens a menu with the microphone selector, plus pause/resume and mute while recording. Status text, permission requests, errors, upload progress (`Uploading 42%`) and the completion message appear in a small caption below the pill.
+
+```tsx
+<VidtreoRecorder
+  apiKey="your-api-key"
+  audioOnly
+  onUploadComplete={(result) => {
+    if (result.mediaType === 'audio') {
+      console.log('Audio uploaded:', result.audioId);
+    }
+  }}
+/>
+```
+
+- Audio recording must be enabled for the environment in the backend. When it is not, the recorder shows "Audio recording is not enabled for this environment" (`audioRecordingDisabled`) and `onError` receives an error whose `code` is `"recording.audio-disabled"` (`ERROR_AUDIO_RECORDING_DISABLED` from `@vidtreo/recorder`).
+- The microphone selector, mute, pause/resume and stop work as for video, from the pill and its menu. The camera selector, source switching and the tab visibility overlay are not shown.
+- The permission flow asks only for the microphone.
+- On mobile, `overlay` and `embed` show the same pill. `mobileMode="native"` and `nativeCamera` are ignored and fall back to `overlay`, because the native camera only captures video.
+- Format, bitrate, channels, processing and the maximum duration come from the environment audio settings. The recorder stops automatically at the maximum duration.
+- Demo mode has no environment audio settings, so audio-only recording needs a real backend.
+
 ### Example with Callbacks
 
 ```tsx
@@ -143,6 +167,8 @@ type RecordingUploadResult = {
   transferredAt: string | null;
   r2DeleteAfter: string | null;
   r2DeletedAt: string | null;
+  mediaType?: 'audio' | 'video'; // 'audio' for audio-only recordings
+  audioId?: string;               // the audio id, set for audio-only recordings
 };
 ```
 
@@ -168,7 +194,7 @@ import VidtreoRecorder, {
 
 | Code | Meaning |
 |------|---------|
-| `upload.insufficient-credits` | The account has no credits left (HTTP 402). The upload is not retried. |
+| `upload.insufficient-credits` | The account has no credits left (HTTP 402). The upload stays queued and is retried every 5 minutes; `onUploadError` fires on each rejected attempt. The first rejection of each queued upload per page session also sets the built-in dialog and `uploadErrorCode`; repeated rejections only call `onUploadError` (no `onError`, no state change). |
 
 `getUploadErrorCode` returns `null` for other errors. Network errors are retried automatically before they are reported.
 
@@ -247,8 +273,8 @@ function CustomRecorder() {
 
 ### Hook Actions
 
-- `startRecording(sourceType?: 'camera' | 'screen')` - Start recording
-- `stopRecording()` - Stop recording and upload
+- `startRecording(sourceType?: 'camera' | 'screen' | 'audio')` - Start recording
+- `stopRecording()` - Stop recording and upload. Resolves with `{ recordingId, uploadUrl, blob, mediaType }`
 - `pauseRecording()` - Pause recording
 - `resumeRecording()` - Resume recording
 - `toggleMute()` - Toggle mute state
@@ -256,7 +282,7 @@ function CustomRecorder() {
 - `reselectScreenSource()` - Pick another screen or window without changing the source type (resolves `false` when cancelled)
 - `changeCamera(deviceId: string)` - Change camera device
 - `changeMic(deviceId: string)` - Change microphone device
-- `startPreview(sourceType?: 'camera' | 'screen')` - Start preview stream
+- `startPreview(sourceType?: 'camera' | 'screen' | 'audio')` - Start preview stream
 - `downloadVideo()` - Download the recorded video (demo mode)
 - `clearUploadError()` - Clear `uploadErrorCode` after the user dismisses the upload error
 - `cleanup()` - Clean up resources
@@ -585,6 +611,23 @@ function App() {
 | `permissionFlowRecoveryTitle` | Allow access to continue | Permite el acceso para continuar |
 | `permissionFlowRecoveryInstructions` | Open your browser settings and allow camera and microphone access, then try again. | Abre la configuración de tu navegador y permite el acceso a la cámara y micrófono, luego intenta de nuevo. |
 | `permissionFlowConnecting` | Setting up... | Preparando... |
+| `initializingMicrophone` | Initializing microphone... | Iniciando micrófono... |
+| `grantMicrophonePermission` | Grant microphone permission when prompted | Concede el permiso de micrófono cuando se te solicite |
+| `retryMicrophone` | Retry Microphone | Reintentar micrófono |
+| `audioOnlyReady` | Ready to record | Listo para grabar |
+| `audioOnlyRecording` | Recording | Grabando |
+| `audioOnlyPaused` | Paused | En pausa |
+| `audioOnlyUploading` | Uploading {progress}% | Subiendo {progress}% |
+| `audioOnlyUploaded` | Upload complete | Subida completada |
+| `audioOnlyElapsedTime` | Elapsed time | Tiempo transcurrido |
+| `audioOnlyNoMicrophones` | No microphones available | No hay micrófonos disponibles |
+| `audioRecordingDisabledTitle` | Audio recording unavailable | Grabación de audio no disponible |
+| `audioRecordingDisabled` | Audio recording is not enabled for this environment | La grabación de audio no está habilitada para este entorno |
+| `permissionFlowMicrophoneOnlyTitle` | Microphone | Micrófono |
+| `permissionFlowMicrophoneOnlyLabel` | We need access to your microphone to start recording | Necesitamos acceso a tu micrófono para comenzar a grabar |
+| `permissionFlowMicrophoneOnlyRecoveryInstructions` | Open your browser settings and allow microphone access, then try again. | Abre la configuración de tu navegador y permite el acceso al micrófono, luego intenta de nuevo. |
+| `mobileOpenMicrophoneTitle` | Microphone | Micrófono |
+| `mobileOpenMicrophoneDescription` | We need access to your microphone to start recording | Necesitamos acceso a tu micrófono para comenzar a grabar |
 
 `TranslationKeys` lists every available key.
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AccessTokenProvider, AccessTokenProvider as AccessTokenProvider$1, AudioWarning, AudioWarning as AudioWarning$1, CONFIG_ERROR_CREDENTIAL_CONFLICT, ERROR_PICTURE_IN_PICTURE_UNSUPPORTED, ERROR_SCREEN_SELECTION_CANCELLED, LocalRecording, LocalRecording as LocalRecording$1, PictureInPictureConfig, PictureInPictureConfig as PictureInPictureConfig$1, PictureInPictureConfigInput, PictureInPictureConfigInput as PictureInPictureConfigInput$1, PictureInPicturePlacement, PictureInPicturePoint, PictureInPicturePosition, PictureInPictureShape, RecorderController, RecordingState, RecordingState as RecordingState$1, RecordingUploadResult, RecordingUploadResult as RecordingUploadResult$1, SourceType, SourceType as SourceType$1, UPLOAD_ERROR_INSUFFICIENT_CREDITS, UploadErrorCode, UploadErrorCode as UploadErrorCode$1, UploadProgressPhase, UploadProgressPhase as UploadProgressPhase$1, getUploadErrorCode, isCredentialConflictError, isPictureInPictureSupported } from "@vidtreo/recorder";
+import { AccessTokenProvider, AccessTokenProvider as AccessTokenProvider$1, AudioWarning, AudioWarning as AudioWarning$1, CONFIG_ERROR_CREDENTIAL_CONFLICT, ERROR_PICTURE_IN_PICTURE_UNSUPPORTED, ERROR_SCREEN_SELECTION_CANCELLED, LocalRecording, LocalRecording as LocalRecording$1, MediaType, MediaType as MediaType$1, PictureInPictureConfig, PictureInPictureConfig as PictureInPictureConfig$1, PictureInPictureConfigInput, PictureInPictureConfigInput as PictureInPictureConfigInput$1, PictureInPicturePlacement, PictureInPicturePoint, PictureInPicturePosition, PictureInPictureShape, RecorderController, RecordingState, RecordingState as RecordingState$1, RecordingUploadResult, RecordingUploadResult as RecordingUploadResult$1, SourceType, SourceType as SourceType$1, UPLOAD_ERROR_INSUFFICIENT_CREDITS, UploadErrorCode, UploadErrorCode as UploadErrorCode$1, UploadProgressPhase, UploadProgressPhase as UploadProgressPhase$1, getUploadErrorCode, isCredentialConflictError, isPictureInPictureSupported } from "@vidtreo/recorder";
 import React from "react";
 
 //#region src/i18n/translations.d.ts
@@ -126,6 +126,23 @@ type TranslationKeys = {
   permissionFlowRecoveryTitle: string;
   permissionFlowRecoveryInstructions: string;
   permissionFlowConnecting: string;
+  initializingMicrophone: string;
+  grantMicrophonePermission: string;
+  retryMicrophone: string;
+  audioOnlyReady: string;
+  audioOnlyRecording: string;
+  audioOnlyPaused: string;
+  audioOnlyUploading: string;
+  audioOnlyUploaded: string;
+  audioOnlyElapsedTime: string;
+  audioOnlyNoMicrophones: string;
+  audioRecordingDisabledTitle: string;
+  audioRecordingDisabled: string;
+  permissionFlowMicrophoneOnlyTitle: string;
+  permissionFlowMicrophoneOnlyLabel: string;
+  permissionFlowMicrophoneOnlyRecoveryInstructions: string;
+  mobileOpenMicrophoneTitle: string;
+  mobileOpenMicrophoneDescription: string;
 };
 type PartialTranslations = Partial<TranslationKeys>;
 //#endregion
@@ -152,6 +169,7 @@ type RecordingPrompt = {
 };
 type BaseRecorderProps = {
   backendUrl?: string;
+  audioOnly?: boolean;
   countdownDuration?: number;
   minTimeRecord?: number;
   maxRecordingTime?: number;
@@ -196,6 +214,7 @@ type UseVidtreoRecorderConfig = {
   apiKey?: string;
   getAccessToken?: AccessTokenProvider$1;
   backendUrl?: string;
+  audioOnly?: boolean;
   countdownDuration?: number;
   minTimeRecord?: number;
   maxRecordingTime?: number;
@@ -284,6 +303,7 @@ type RecordingStopResult = {
   recordingId: string;
   uploadUrl: string;
   blob: Blob;
+  mediaType: MediaType$1;
 };
 type UseVidtreoRecorderReturn = {
   state: VidtreoRecorderState;
@@ -298,4 +318,4 @@ declare function VidtreoRecorder(props: VidtreoRecorderProps): React.JSX.Element
 //#region src/hooks/use-vidtreo-recorder.d.ts
 declare function useVidtreoRecorder(config: UseVidtreoRecorderConfig): UseVidtreoRecorderReturn;
 //#endregion
-export { type AccessTokenProvider, type AudioWarning, CONFIG_ERROR_CREDENTIAL_CONFLICT, ERROR_PICTURE_IN_PICTURE_UNSUPPORTED, ERROR_SCREEN_SELECTION_CANCELLED, type LocalRecording, MobileMode, type PartialTranslations, type PictureInPictureConfig, type PictureInPictureConfigInput, type PictureInPicturePlacement, type PictureInPicturePoint, type PictureInPicturePosition, type PictureInPictureShape, RecordingPrompt, RecordingPromptCountdown, RecordingPromptCountdownPlacement, type RecordingState, RecordingStopResult, type RecordingUploadResult, type SourceType, type TranslationKeys, UPLOAD_ERROR_INSUFFICIENT_CREDITS, type UploadErrorCode, type UploadProgressPhase, UseVidtreoRecorderConfig, UseVidtreoRecorderReturn, VidtreoRecorder, VidtreoRecorder as VidtreoRecorderSSR, VidtreoRecorderActions, VidtreoRecorderProps, VidtreoRecorderState, getUploadErrorCode, isCredentialConflictError, isPictureInPictureSupported, useVidtreoRecorder };
+export { type AccessTokenProvider, type AudioWarning, CONFIG_ERROR_CREDENTIAL_CONFLICT, ERROR_PICTURE_IN_PICTURE_UNSUPPORTED, ERROR_SCREEN_SELECTION_CANCELLED, type LocalRecording, type MediaType, MobileMode, type PartialTranslations, type PictureInPictureConfig, type PictureInPictureConfigInput, type PictureInPicturePlacement, type PictureInPicturePoint, type PictureInPicturePosition, type PictureInPictureShape, RecordingPrompt, RecordingPromptCountdown, RecordingPromptCountdownPlacement, type RecordingState, RecordingStopResult, type RecordingUploadResult, type SourceType, type TranslationKeys, UPLOAD_ERROR_INSUFFICIENT_CREDITS, type UploadErrorCode, type UploadProgressPhase, UseVidtreoRecorderConfig, UseVidtreoRecorderReturn, VidtreoRecorder, VidtreoRecorder as VidtreoRecorderSSR, VidtreoRecorderActions, VidtreoRecorderProps, VidtreoRecorderState, getUploadErrorCode, isCredentialConflictError, isPictureInPictureSupported, useVidtreoRecorder };