@vidtreo/recorder-react 1.7.9 → 1.9.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`
 
@@ -46,12 +46,14 @@ import VidtreoRecorder from '@vidtreo/recorder-react';
 
 | Prop | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
-| `apiKey` | `string` | No* | - | API key for authentication. Required if `VIDTREO_API_KEY` env var not set. |
+| `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 |
 | `userMetadata` | `Record<string, unknown>` | No | - | Custom metadata to attach to recordings |
-| `recordingPrompt` | `RecordingPrompt` | No | - | Prompt shown during recording. Use `countdown: { show, placement: "above-countdown" }` to float it over the countdown. |
+| `recordingPrompt` | `RecordingPrompt` | No | - | Prompt shown during recording. Use `countdown: { show, placement: "above-countdown" }` to float it over the countdown. A `label` field is still accepted for backward compatibility but is not displayed. |
 | `enableSourceSwitching` | `boolean` | No | `true` | Enable switching between camera and screen |
 | `enableMute` | `boolean` | No | `true` | Enable mute/unmute functionality |
 | `enablePause` | `boolean` | No | `true` | Enable pause/resume functionality |
@@ -62,17 +64,40 @@ import VidtreoRecorder from '@vidtreo/recorder-react';
 | `maxFileSize` | `number` | No | `2560` | Maximum file size in megabytes (default: 2.5GB) |
 | `lang` | `string` | No | `"en"` | Language code for UI text (`"en"` or `"es"`) |
 | `texts` | `PartialTranslations` | No | - | Custom text overrides for localization |
-| `onUploadComplete` | `(result: { recordingId: string; uploadUrl: string }) => void` | No | - | Callback when upload completes |
-| `onUploadProgress` | `(progress: number) => void` | No | - | Callback for upload progress (0-1) |
-| `onUploadError` | `(error: Error) => void` | No | - | Callback when upload fails |
+| `onUploadComplete` | `(result: RecordingUploadResult) => void` | No | - | Callback when upload completes. Same payload for the desktop/overlay recorder and native camera mode. See [Upload Completion Payload](#upload-completion-payload) |
+| `onUploadProgress` | `(progress: number, phase: UploadProgressPhase \| null) => void` | No | - | Callback for upload progress (0-1) in every mode. `phase` is `"preparing"`, `"transferring"`, `"finalizing"`, `"completed"` or `null` when not reported yet (the first `0` call) |
+| `onUploadError` | `(error: Error) => void` | No | - | Callback when upload fails. Use `getUploadErrorCode(error)` to read the [error code](#upload-errors) |
 | `onRecordingStart` | `() => void` | No | - | Callback when recording starts |
-| `onRecordingStop` | `() => void` | No | - | Callback when recording stops |
-| `onTranscodingProgress` | `(progress: number) => void` | No | - | Callback for transcoding progress (0-100) |
-| `onError` | `(error: Error) => void` | No | - | Callback for any errors |
+| `onRecordingStop` | `() => void` | No | - | Callback when recording stops (once per recording, when finalization starts) |
+| `onTranscodingProgress` | `(progress: number) => void` | No | - | Callback for transcoding progress (0-1). While it runs the recorder shows the `finishing` progress overlay |
+| `onError` | `(error: Error) => void` | No | - | Callback for any errors, including the credential conflict configuration error |
 
 `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
@@ -82,8 +107,8 @@ uses a localized default based on `lang` and `texts`. Overlay rendering is skipp
     console.log('Recording uploaded:', result.recordingId);
     console.log('View at:', result.uploadUrl);
   }}
-  onUploadProgress={(progress) => {
-    console.log(`Upload: ${Math.round(progress * 100)}%`);
+  onUploadProgress={(progress, phase) => {
+    console.log(`Upload (${phase ?? "starting"}): ${Math.round(progress * 100)}%`);
   }}
   onError={(error) => {
     console.error('Error:', error.message);
@@ -91,6 +116,92 @@ uses a localized default based on `lang` and `texts`. Overlay rendering is skipp
 />
 ```
 
+### Temporary Access Tokens
+
+```tsx
+<VidtreoRecorder
+  getAccessToken={async () => {
+    const response = await fetch('/api/vidtreo-token');
+    const { token } = await response.json();
+    return token;
+  }}
+/>
+```
+
+The token is never stored. If an upload is interrupted, the component calls `getAccessToken` again when the upload resumes.
+
+Pass either `apiKey` or `getAccessToken`, not both. The prop types reject both at compile time; at runtime (for example from JavaScript) the component renders the configuration error "Provide either apiKey or getAccessToken, not both" and calls `onError` once with an error whose `code` is `CONFIG_ERROR_CREDENTIAL_CONFLICT` (`"config.credential-conflict"`, from `@vidtreo/recorder`). Passing neither (outside demo mode, and without `VIDTREO_API_KEY` in the environment) renders the `errorApiKeyRequired` configuration error and calls `onError` once. Demo mode ignores credentials.
+
+### Progress Overlays
+
+After you stop a recording the preview shows a progress overlay until the upload finishes:
+
+| Stage | Label key | Progress |
+|-------|-----------|----------|
+| Finalizing the recording (before transcoding reports progress) | `finishing` | 0% |
+| Transcoding | `finishing` | transcoding progress |
+| Uploading | `uploading`, `finalizing` when the backend is finalizing, `retryingUpload` while a retry is pending | upload progress |
+
+The same overlays show in the mobile overlay recorder. In native camera mode a resumed upload without a preview shows a standalone progress bar with the same labels.
+
+### Upload Completion Payload
+
+`onUploadComplete` receives a `RecordingUploadResult`: every field of the backend upload result plus the backward-compatible `recordingId` and `uploadUrl`.
+
+```typescript
+import type { RecordingUploadResult } from '@vidtreo/recorder-react';
+
+type RecordingUploadResult = {
+  recordingId: string;           // same value as id
+  uploadUrl: string;             // "" when the backend has no URL yet
+  id: string;
+  publicId: string;
+  filename: string;
+  fileSize: number;
+  mimeType: string;
+  duration: number | null;
+  status: string;
+  createdAt: string;
+  transferStatus: 'pending' | 'transferring' | 'transferred' | 'failed' | null;
+  transferError: string | null;
+  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
+};
+```
+
+### Upload Errors
+
+When an upload fails with a known cause, the component shows a dialog (`role="alertdialog"`) after recording and processing finish, and `onUploadError` receives an error with a code:
+
+```tsx
+import VidtreoRecorder, {
+  getUploadErrorCode,
+  UPLOAD_ERROR_INSUFFICIENT_CREDITS,
+} from '@vidtreo/recorder-react';
+
+<VidtreoRecorder
+  apiKey="your-api-key"
+  onUploadError={(error) => {
+    if (getUploadErrorCode(error) === UPLOAD_ERROR_INSUFFICIENT_CREDITS) {
+      notifyAdmin();
+    }
+  }}
+/>
+```
+
+| Code | Meaning |
+|------|---------|
+| `upload.insufficient-credits` | The account has no credits left (HTTP 402). The upload is not retried. |
+
+`getUploadErrorCode` returns `null` for other errors. Network errors are retried automatically before they are reported.
+
+### Upload Resume
+
+Uploads are queued in IndexedDB before they are sent, in every mode (desktop, mobile overlay, mobile embed, and native camera). If the page is reloaded or the connection drops, the next mounted `VidtreoRecorder` resumes the upload with the same idempotency key and sends only the parts that are missing. Progress shows again while it resumes, and `onUploadComplete` fires with the full payload when it finishes. Mount the component with the same credentials (`apiKey` or `getAccessToken`) so the upload can resume. If IndexedDB is unavailable, uploads go directly to the backend without persistence.
+
 ### Minimum Recording Time
 
 ```tsx
@@ -147,6 +258,10 @@ function CustomRecorder() {
   countdown: number | null;
   timer: string;
   uploadProgress: number | null;
+  uploadPhase: UploadProgressPhase | null;   // 'preparing' | 'transferring' | 'finalizing' | 'completed'
+  uploadRetryAttempt: number | null;
+  uploadErrorCode: UploadErrorCode | null;   // 'upload.insufficient-credits'
+  transcodingProgress: number | null;
   devices: {
     cameras: MediaDeviceInfo[];
     microphones: MediaDeviceInfo[];
@@ -158,15 +273,18 @@ 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
 - `switchSource(sourceType: 'camera' | 'screen')` - Switch between camera and screen
+- `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
 
 ### Hook Return
@@ -372,6 +490,70 @@ function App() {
 |-----|----------------|-----------------|
 | `initializingCamera` | Initializing camera... | Inicializando cámara... |
 | `grantPermissions` | Grant camera and microphone permissions when prompted | Otorga permisos de cámara y micrófono cuando se solicite |
+| `browserUnsupported` | This browser is not supported | Este navegador no es compatible |
+| `browserUnsupportedDynamic` | `{browser} ({version}) is not supported, please use <a href="https://www.google.com/chrome/" target="_blank" rel="noopener noreferrer">Chrome</a>` | `{browser} ({version}) no es compatible, por favor usa <a href="https://www.google.com/chrome/" target="_blank" rel="noopener noreferrer">Chrome</a>` |
+| `browserUnsupportedSafari` | `Safari (latest stable) is supported. If you experience issues, please use <a href="https://www.google.com/chrome/" target="_blank" rel="noopener noreferrer">Chrome</a>` | `Safari (última versión estable) es compatible. Si experimentas problemas, por favor usa <a href="https://www.google.com/chrome/" target="_blank" rel="noopener noreferrer">Chrome</a>` |
+| `browserUnsupportedFirefox` | `Firefox is not supported, please use <a href="https://www.google.com/chrome/" target="_blank" rel="noopener noreferrer">Chrome</a>` | `Firefox no es compatible, por favor use <a href="https://www.google.com/chrome/" target="_blank" rel="noopener noreferrer">Chrome</a>` |
+| `retryCamera` | Retry Camera | Reintentar Cámara |
+| `cameraInUse` | Your camera is being used by another application. Close other apps using the camera (Zoom, Teams, Discord) and try again. | Tu cámara está siendo usada por otra aplicación. Cierra otras apps que usen la cámara (Zoom, Teams, Discord) e intenta de nuevo. |
+| `cameraNotFound` | No camera detected. Connect a camera or check your device settings. | No se detectó ninguna cámara. Conecta una cámara o revisa la configuración de tu dispositivo. |
+| `cameraPermissionDenied` | Camera access was denied. Allow camera access in your browser settings and try again. | Se denegó el acceso a la cámara. Permite el acceso a la cámara en la configuración de tu navegador e intenta de nuevo. |
+| `cameraTimeout` | The camera took too long to start. Close other apps using the camera and try again. | La cámara tardó demasiado en iniciar. Cierra otras apps que usen la cámara e intenta de nuevo. |
+| `failedToStartCamera` | Failed to start camera | Error al iniciar la cámara |
+| `audioInUse` | Your microphone is being used by another application. Close other apps using the microphone (Zoom, Teams, Discord) and try again. | Tu micrófono está siendo usado por otra aplicación. Cierra otras apps que usen el micrófono (Zoom, Teams, Discord) e intenta de nuevo. |
+| `audioNotFound` | No microphone detected. Connect a microphone or check your device settings. | No se detectó ningún micrófono. Conecta un micrófono o revisa la configuración de tu dispositivo. |
+| `audioPermissionDenied` | Microphone access was denied. Allow microphone access in your browser settings and try again. | Se denegó el acceso al micrófono. Permite el acceso al micrófono en la configuración de tu navegador e intenta de nuevo. |
+| `audioTimeout` | The microphone took too long to start. Close other apps using the microphone and try again. | El micrófono tardó demasiado en iniciar. Cierra otras apps que usen el micrófono e intenta de nuevo. |
+| `failedToStartAudio` | Failed to start microphone | Error al iniciar el micrófono |
+| `audioErrorTitle` | Microphone unavailable | Micrófono no disponible |
+| `audioErrorMessage` | We couldn't access your microphone. It may be in use by another app like Zoom, Teams, or Discord. Please close it and try again. | No pudimos acceder a tu micrófono. Puede estar en uso por otra app como Zoom, Teams o Discord. Ciérrala e inténtalo de nuevo. |
+| `audioErrorRetry` | Try again | Intentar de nuevo |
+| `audioMissingTitle` | Recording has no audio | La grabación no tiene audio |
+| `audioMissingMessage` | We couldn't capture audio in this recording. Your microphone may have been disconnected or blocked by the browser. Check your microphone and record again. | No pudimos capturar audio en esta grabación. Es posible que el micrófono se haya desconectado o que el navegador lo haya bloqueado. Verifica tu micrófono y vuelve a grabar. |
+| `audioSilentTitle` | Recording is silent | La grabación quedó en silencio |
+| `audioSilentMessage` | We didn't detect any sound during the recording. Make sure your microphone is working and not muted by your operating system, then record again. | No detectamos sonido durante la grabación. Verifica que tu micrófono esté funcionando y no esté silenciado por el sistema, luego vuelve a grabar. |
+| `audioProcessingErrorTitle` | Audio processing error | Error al procesar el audio |
+| `audioProcessingErrorMessage` | We couldn't process the audio in this recording. Please record again. | No pudimos procesar el audio de esta grabación. Por favor vuelve a grabar. |
+| `audioMissingRetry` | Record again | Grabar de nuevo |
+| `audioWarningNoSignalTitle` | No microphone signal | Sin señal del micrófono |
+| `audioWarningNoSignalMessage` | We're not detecting any sound. Check that your microphone is active. | No estamos detectando sonido. Verifica que tu micrófono esté activo. |
+| `audioWarningLowSignalTitle` | Audio is very quiet | Audio muy bajo |
+| `audioWarningLowSignalMessage` | Move closer to the microphone or turn up the input volume. | Acércate al micrófono o sube el volumen de entrada. |
+| `audioWarningSpeakingMutedTitle` | You're speaking while muted | Estás hablando muteado |
+| `audioWarningSpeakingMutedMessage` | Unmute your microphone if you want your voice in the recording. | Activa el micrófono si quieres que tu voz se escuche en la grabación. |
+| `audioWarningTrackEndedTitle` | Microphone disconnected | Micrófono desconectado |
+| `audioWarningTrackEndedMessage` | The microphone was disconnected. Reconnect it before continuing. | Se desconectó el micrófono. Reconéctalo antes de continuar. |
+| `audioWarningNoChunksTitle` | No microphone input | Sin entrada del micrófono |
+| `audioWarningNoChunksMessage` | We're not receiving audio from the microphone. Check browser permissions. | No estamos recibiendo audio del micrófono. Revisa los permisos del navegador. |
+| `audioWarningTrackMutedTitle` | Microphone muted by browser | Micrófono silenciado por el navegador |
+| `audioWarningTrackMutedMessage` | The browser muted your microphone. Check site settings. | El navegador silenció tu micrófono. Revisa la configuración del sitio. |
+| `audioWarningDismiss` | Dismiss | Cerrar |
+| `cameraErrorTitle` | Camera unavailable | Cámara no disponible |
+| `cameraErrorMessage` | We couldn't access your camera. It may be in use by another app. Please close it and try again. | No pudimos acceder a tu cámara. Puede estar en uso por otra app. Ciérrala e inténtalo de nuevo. |
+| `browserErrorTitle` | Browser not supported | Navegador no compatible |
+| `browserErrorMessage` | Your browser doesn't support video recording. Please use the latest version of Chrome for the best experience. | Tu navegador no es compatible con la grabación de video. Por favor usa la última versión de Chrome. |
+| `recordingCodecUnsupportedTitle` | Recording format not supported | Formato de grabación no compatible |
+| `recordingCodecUnsupportedMessage` | This device can't use the selected video format. Close other apps, update Chrome if possible, and record again. | Este dispositivo no puede usar el formato de video seleccionado. Cierra otras apps, actualiza Chrome si es posible y vuelve a grabar. |
+| `recordingMediaEmptyTitle` | No video was produced | No se generó ningún video |
+| `recordingMediaEmptyMessage` | The browser didn't produce a usable video. Check your camera and record again. | El navegador no produjo un video utilizable. Verifica la cámara y vuelve a grabar. |
+| `recordingMediaErrorTitle` | Recording could not be finished | No se pudo finalizar la grabación |
+| `recordingMediaErrorMessage` | The browser reported an error before the video was ready to upload. Record again. | El navegador informó un error antes de preparar el video para subirlo. Vuelve a grabar. |
+| `recordingServerTranscodeFallbackTitle` | Video processing failed | No se pudo procesar el video |
+| `recordingServerTranscodeFallbackMessage` | We couldn't prepare this video for upload on your device. Record again. | No pudimos preparar este video para subirlo en tu dispositivo. Vuelve a grabar. |
+| `recordingTrackEndedTitle` | Camera stopped during recording | La cámara se detuvo durante la grabación |
+| `recordingTrackEndedMessage` | The camera feed ended before the recording finished. Check that the camera is still connected and record again. | La señal de la cámara terminó antes de finalizar la grabación. Verifica que la cámara siga conectada y vuelve a grabar. |
+| `recordingFinalizeTimeoutTitle` | Recording took too long to finish | La grabación tardó demasiado en finalizar |
+| `recordingFinalizeTimeoutMessage` | This device may be low on memory or processing power. Close other apps or browser tabs, then record again. | Es posible que este dispositivo tenga poca memoria o potencia de procesamiento. Cierra otras apps o pestañas del navegador y vuelve a grabar. |
+| `recordingStateRaceTitle` | Recording did not start correctly | La grabación no inició correctamente |
+| `recordingStateRaceMessage` | The recording could not be finalized because it did not start cleanly. Please refresh the page and record again. | No se pudo finalizar la grabación porque no inició correctamente. Actualiza la página y vuelve a grabar. |
+| `recordingNoFramesTitle` | No video was captured | No se capturó video |
+| `recordingNoFramesMessage` | We couldn't receive video frames from the camera. Check your camera connection and record again. | No pudimos recibir fotogramas de video de la cámara. Verifica la conexión de la cámara y vuelve a grabar. |
+| `recordingUnsupportedTitle` | Recording not available | Grabación no disponible |
+| `recordingUnsupportedMessage` | This device or browser can't record video reliably right now. Check your connection, update Chrome if possible, or use another device. | Este dispositivo o navegador no puede grabar video de forma estable ahora. Revisa tu conexión, actualiza Chrome si es posible o usa otro dispositivo. |
+| `recordingPipelineRetry` | Record again | Grabar de nuevo |
+| `genericErrorTitle` | Something went wrong | Algo salió mal |
+| `genericErrorMessage` | An unexpected error occurred. Please try again. | Ocurrió un error inesperado. Por favor inténtalo de nuevo. |
+| `errorRetry` | Try again | Intentar de nuevo |
 | `switchingDevice` | Switching device... | Cambiando dispositivo... |
 | `recordingStartsIn` | Recording starts in... | La grabación comienza en... |
 | `switchingSource` | Switching source... | Cambiando fuente... |
@@ -379,7 +561,6 @@ function App() {
 | `settings` | Settings | Configuración |
 | `record` | Record | Grabar |
 | `stop` | Stop | Detener |
-| `minimumRecordingTimeNotReached` | You have not met the minimum recording time yet | Aun no cumples el tiempo minimo de grabacion |
 | `pause` | Pause | Pausar |
 | `resume` | Resume | Reanudar |
 | `mute` | Mute | Silenciar |
@@ -387,11 +568,72 @@ function App() {
 | `switchSource` | Switch Source | Cambiar Fuente |
 | `camera` | Camera | Cámara |
 | `microphone` | Microphone | Micrófono |
+| `microphoneConnecting` | Connecting microphone... | Conectando micrófono... |
+| `minimumRecordingTimeNotReached` | You have not met the minimum recording time yet | Aun no cumples el tiempo minimo de grabacion |
 | `uploading` | Uploading... | Subiendo... |
+| `finalizing` | Finalizing… | Finalizando… |
+| `retryingUpload` | Retrying upload... | Reintentando subida... |
+| `uploadInsufficientCredits` | This video couldn't be uploaded. Please contact the site administrator. | No se pudo subir el video. Contacta al administrador del sitio. |
+| `uploadInsufficientCreditsTitle` | Video couldn't be uploaded | No se pudo subir el video |
+| `uploadErrorClose` | Close | Cerrar |
+| `finishing` | Finishing... | Finalizando... |
+| `userInAnotherTab` | User in another tab | Usuario en otra pestaña |
+| `download` | Download | Descargar |
+| `nativeCameraSelectVideo` | Select Video from Gallery | Seleccionar Video de la Galería |
+| `nativeCameraRecordVideo` | Record with Camera | Grabar con Cámara |
+| `nativeCameraProcessing` | Processing video... | Procesando video... |
+| `nativeCameraConfigLoading` | Loading settings... | Cargando configuración... |
+| `nativeCameraConfigLoadError` | Failed to load settings | No se pudo cargar la configuración |
+| `nativeCameraPreviewAlt` | Video preview | Vista previa del video |
+| `errorTitle` | Configuration Error | Error de Configuración |
+| `errorApiKeyRequired` | An API Key or access token provider is required. | Se requiere una API Key o un proveedor de token de acceso. |
+| `errorGeneric` | An error occurred while initializing the recorder | Ocurrió un error al inicializar la grabadora |
+| `mobileOpenCamera` | Allow Access | Permitir Acceso |
+| `mobileOpenCameraTitle` | Camera & Microphone | Cámara y Micrófono |
+| `mobileOpenCameraDescription` | We need access to your camera and microphone to start recording | Necesitamos acceso a tu cámara y micrófono para comenzar a grabar |
+| `mobileCloseCamera` | Close | Cerrar |
+| `mobileHideRecordingPrompt` | Hide prompt | Ocultar pregunta |
+| `mobileShowRecordingPrompt` | Show prompt | Mostrar pregunta |
+| `mobilePermissionDenied` | Camera Access Denied | Acceso a Cámara Denegado |
+| `mobilePermissionDeniedDescription` | Please allow camera access in your browser settings to record video. | Por favor permite el acceso a la cámara en la configuración de tu navegador para grabar video. |
+| `permissionFlowTitle` | Set Up Your Camera | Configurar tu Cámara |
+| `permissionFlowCameraTitle` | Camera & Microphone | Cámara y Micrófono |
+| `permissionFlowMicrophoneTitle` | Camera & Microphone | Cámara y Micrófono |
+| `permissionFlowCameraLabel` | We need access to your camera and microphone to start recording | Necesitamos acceso a tu cámara y micrófono para comenzar a grabar |
+| `permissionFlowMicrophoneLabel` | We need access to your camera and microphone to start recording | Necesitamos acceso a tu cámara y micrófono para comenzar a grabar |
+| `permissionFlowStatusPending` | Pending | Pendiente |
+| `permissionFlowStatusGranted` | Ready | Listo |
+| `permissionFlowStatusDenied` | Blocked | Bloqueado |
+| `permissionFlowStatusRequesting` | Click "Allow" in the browser popup above | Haz clic en "Permitir" en el aviso del navegador |
+| `permissionFlowAllowCamera` | Allow Access | Permitir Acceso |
+| `permissionFlowAllowMicrophone` | Allow Access | Permitir Acceso |
+| `permissionFlowRetry` | Try Again | Reintentar |
+| `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.
 
 ### TypeScript Support
 
-The package exports types for better type safety:
+The package exports types for better type safety, including `PartialTranslations`, `TranslationKeys`, `RecordingUploadResult`, `UploadErrorCode`, `UploadProgressPhase`, and `AccessTokenProvider`. It also re-exports `getUploadErrorCode`, `UPLOAD_ERROR_INSUFFICIENT_CREDITS`, `isCredentialConflictError` and `CONFIG_ERROR_CREDENTIAL_CONFLICT` from `@vidtreo/recorder`.
 
 ```tsx
 import VidtreoRecorder from '@vidtreo/recorder-react';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AudioWarning, AudioWarning as AudioWarning$1, RecorderController, RecordingState, RecordingState as RecordingState$1, SourceType, SourceType as SourceType$1 } 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
@@ -86,7 +86,11 @@ type TranslationKeys = {
   microphoneConnecting: string;
   minimumRecordingTimeNotReached: string;
   uploading: string;
+  finalizing: string;
   retryingUpload: string;
+  uploadInsufficientCredits: string;
+  uploadInsufficientCreditsTitle: string;
+  uploadErrorClose: string;
   finishing: string;
   userInAnotherTab: string;
   download: string;
@@ -94,6 +98,8 @@ type TranslationKeys = {
   nativeCameraRecordVideo: string;
   nativeCameraProcessing: string;
   nativeCameraConfigLoading: string;
+  nativeCameraConfigLoadError: string;
+  nativeCameraPreviewAlt: string;
   errorTitle: string;
   errorApiKeyRequired: string;
   errorGeneric: string;
@@ -119,8 +125,24 @@ type TranslationKeys = {
   permissionFlowRetry: string;
   permissionFlowRecoveryTitle: string;
   permissionFlowRecoveryInstructions: string;
-  permissionFlowRecoveryGuideHint: 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
@@ -147,6 +169,7 @@ type RecordingPrompt = {
 };
 type BaseRecorderProps = {
   backendUrl?: string;
+  audioOnly?: boolean;
   countdownDuration?: number;
   minTimeRecord?: number;
   maxRecordingTime?: number;
@@ -163,11 +186,8 @@ type BaseRecorderProps = {
   texts?: PartialTranslations; /** @deprecated Use mobileMode instead */
   nativeCamera?: boolean; /** Controls mobile recording experience. Default: "overlay" */
   mobileMode?: MobileMode;
-  onUploadComplete?: (result: {
-    recordingId: string;
-    uploadUrl: string;
-  }) => void;
-  onUploadProgress?: (progress: number) => void;
+  onUploadComplete?: (result: RecordingUploadResult$1) => void;
+  onUploadProgress?: (progress: number, phase: UploadProgressPhase$1 | null) => void;
   onUploadError?: (error: Error) => void;
   onRecordingStart?: () => void;
   onRecordingStop?: () => void;
@@ -177,15 +197,24 @@ type BaseRecorderProps = {
 type DemoModeProps = BaseRecorderProps & {
   demo: true;
   apiKey?: string;
+  getAccessToken?: never;
 };
-type ProductionModeProps = BaseRecorderProps & {
+type ApiKeyProductionModeProps = BaseRecorderProps & {
   demo?: false;
   apiKey: string;
+  getAccessToken?: never;
 };
-type VidtreoRecorderProps = DemoModeProps | ProductionModeProps;
+type AccessTokenProductionModeProps = BaseRecorderProps & {
+  demo?: false;
+  apiKey?: never;
+  getAccessToken: AccessTokenProvider$1;
+};
+type VidtreoRecorderProps = DemoModeProps | ApiKeyProductionModeProps | AccessTokenProductionModeProps;
 type UseVidtreoRecorderConfig = {
-  apiKey: string;
+  apiKey?: string;
+  getAccessToken?: AccessTokenProvider$1;
   backendUrl?: string;
+  audioOnly?: boolean;
   countdownDuration?: number;
   minTimeRecord?: number;
   maxRecordingTime?: number;
@@ -199,16 +228,18 @@ type UseVidtreoRecorderConfig = {
   enableTabVisibilityOverlay?: boolean;
   tabVisibilityOverlayText?: string;
   proxyEndpoint?: string;
-  demo?: boolean; /** @deprecated Use mobileMode instead */
+  demo?: boolean;
+  pictureInPicture?: PictureInPictureConfig$1;
+  startScreenWithoutCamera?: boolean;
+  captureSystemAudio?: boolean;
+  autoUpload?: boolean; /** @deprecated Use mobileMode instead */
   nativeCamera?: boolean; /** Controls mobile recording experience. Default: "overlay" */
   mobileMode?: MobileMode;
   lang?: string;
   texts?: PartialTranslations;
-  onUploadComplete?: (result: {
-    recordingId: string;
-    uploadUrl: string;
-  }) => void;
-  onUploadProgress?: (progress: number) => void;
+  onRecordingReady?: (recording: LocalRecording$1) => void;
+  onUploadComplete?: (result: RecordingUploadResult$1) => void;
+  onUploadProgress?: (progress: number, phase: UploadProgressPhase$1 | null) => void;
   onUploadError?: (error: Error) => void;
   onRecordingStart?: () => void;
   onRecordingStop?: () => void;
@@ -218,6 +249,8 @@ type UseVidtreoRecorderConfig = {
 type VidtreoRecorderState = {
   recordingState: RecordingState$1;
   stream: MediaStream | null;
+  sourceType: SourceType$1;
+  cameraStream: MediaStream | null;
   isMuted: boolean;
   isPaused: boolean;
   isFinalizingRecording: boolean;
@@ -230,7 +263,9 @@ type VidtreoRecorderState = {
   countdown: number | null;
   timer: string;
   uploadProgress: number | null;
+  uploadPhase: UploadProgressPhase$1 | null;
   uploadRetryAttempt: number | null;
+  uploadErrorCode: UploadErrorCode$1 | null;
   transcodingProgress: number | null;
   transitionMessage: string | null;
   isInitialized: boolean;
@@ -245,23 +280,30 @@ type VidtreoRecorderState = {
   };
 };
 type VidtreoRecorderActions = {
-  startRecording: (sourceType?: SourceType$1) => Promise<void>;
+  startRecording: (sourceType?: SourceType$1, options?: {
+    skipCountdown?: boolean;
+  }) => Promise<void>;
   stopRecording: () => Promise<RecordingStopResult>;
   pauseRecording: () => void;
   resumeRecording: () => void;
   toggleMute: () => void;
   switchSource: (sourceType: SourceType$1) => Promise<void>;
+  reselectScreenSource: () => Promise<boolean>;
   changeCamera: (deviceId: string) => Promise<void>;
   changeMic: (deviceId: string) => Promise<void>;
   startPreview: (sourceType?: SourceType$1) => Promise<void>;
   stopPreview: () => void;
   downloadVideo: () => void;
+  clearUploadError: () => void;
+  setRecordingTitle: (title: string | null) => void;
+  setPictureInPicture: (update: PictureInPictureConfigInput$1) => void;
   cleanup: () => void;
 };
 type RecordingStopResult = {
   recordingId: string;
   uploadUrl: string;
   blob: Blob;
+  mediaType: MediaType$1;
 };
 type UseVidtreoRecorderReturn = {
   state: VidtreoRecorderState;
@@ -276,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 AudioWarning, MobileMode, type PartialTranslations, RecordingPrompt, RecordingPromptCountdown, RecordingPromptCountdownPlacement, type RecordingState, RecordingStopResult, type SourceType, type TranslationKeys, UseVidtreoRecorderConfig, UseVidtreoRecorderReturn, VidtreoRecorder, VidtreoRecorder as VidtreoRecorderSSR, VidtreoRecorderActions, VidtreoRecorderProps, VidtreoRecorderState, 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 };