@vidtreo/recorder-vue 1.13.0 → 1.15.0

package/README.md

@@ -291,6 +291,19 @@ const { state, actions, audioLevel, controller } = useVidtreoRecorder({
 </template>
 ```
 
+### Passing a config object or a getter
+
+`useVidtreoRecorder` and `useMobileWebRecorder` accept either a config object or a getter `() => config`. A plain object is read once. Pass a getter when the config comes from props or other reactive state: the recorder calls it whenever it needs the latest values, so callbacks and a replaced `getAccessToken` reach it without reinitializing. Only adding or removing the `getAccessToken` provider (for example switching to `apiKey`) reinitializes the recorder.
+
+```ts
+const props = defineProps<{ getAccessToken: () => Promise<string> }>();
+
+const recorder = useVidtreoRecorder(() => ({
+  getAccessToken: props.getAccessToken,
+  onUploadComplete: (result) => console.log(result),
+}));
+```
+
 ### What the composable returns
 
 ```ts
@@ -352,13 +365,83 @@ const { state, actions, audioLevel, controller } = useVidtreoRecorder({
 | `stopPreview` | `() => void` | Tear the preview stream down. |
 | `downloadVideo` | `() => void` | Download the last `recordedBlob` (demo mode). |
 | `clearUploadError` | `() => void` | Clear `uploadErrorCode` after the user dismisses the upload error. |
+| `mark` | `(marker: { id: string; label: string }) => void` | Record the current position in the recording. See [Markers](#markers). |
 | `cleanup` | `() => void` | Release all resources. Useful before unmounting. |
 
+### Markers
+
+Call `actions.mark({ id, label })` while recording to note where something happens, for example when your UI moves on to the next question. The SDK stores the position in seconds of the recording (without paused time, rounded to the millisecond) and uploads the markers with that recording. The backend returns them as `markers` on the video or audio.
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { useVidtreoRecorder } from "@vidtreo/recorder-vue";
+
+const questions = [
+  { id: "q1", text: "First question" },
+  { id: "q2", text: "Second question" },
+];
+const index = ref(0);
+const { state, actions } = useVidtreoRecorder({ apiKey: "your-api-key" });
+
+function next() {
+  index.value += 1;
+  const question = questions[index.value];
+  actions.mark({ id: question.id, label: question.text });
+}
+</script>
+
+<template>
+  <p>{{ questions[index].text }}</p>
+  <button v-if="state.recordingState === 'recording'" @click="next">
+    Next question
+  </button>
+</template>
+```
+
+For example, `actions.mark({ id: "q2", label: "Second question" })` when the second question appears gives the uploaded video `markers: [{ id: "q2", time: 42.318, label: "Second question" }]`.
+
+- Labels are free text. The SDK never reads or changes them.
+- Each recording starts with no markers. Without `mark()` nothing changes and the upload has no `markers` key.
+- Markers are kept in the upload queue, so they are sent when an upload resumes after a reload.
+- `mark()` throws a `RecordingMarkerError` from `@vidtreo/recorder` when no recording is running (a paused recording counts as running), when `id` is not 1 to 64 characters or `label` is not 1 to 500 characters, when the `id` is already used in the recording, or after 200 markers. Its `code` is one of `recording.marker-not-recording`, `recording.marker-invalid-id`, `recording.marker-invalid-label`, `recording.marker-duplicate-id` or `recording.marker-limit-reached`.
+- The stock `VidtreoRecorder` component has no markers UI. Call `mark()` through its template ref (see [Markers with the component](#markers-with-the-component)) or use the composable.
+
+### Markers with the component
+
+Put a template ref on the stock `VidtreoRecorder` to mark from your own UI:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  VidtreoRecorder,
+  type VidtreoRecorderExposed,
+} from "@vidtreo/recorder-vue";
+
+const recorderRef = ref<VidtreoRecorderExposed | null>(null);
+
+function showSecondQuestion() {
+  recorderRef.value?.mark({ id: "q2", label: "Second question" });
+}
+</script>
+
+<template>
+  <VidtreoRecorder ref="recorderRef" :recorder-props="{ apiKey: 'your-api-key' }" />
+  <button @click="showSecondQuestion">Next question</button>
+</template>
+```
+
+- The exposed `mark()` follows the same rules as `actions.mark()`. Before the recorder is ready or when no recording is running, it throws a `RecordingMarkerError` with code `recording.marker-not-recording`.
+- It marks the recording of whichever recorder the component shows: desktop, mobile embed or mobile overlay. In native camera mode (`nativeCamera` or `mobileMode: "native"`) it does nothing, because the device's camera app records outside the page.
+- `StandardRecorder`, `MobileWebRecorderUI` and `NativeCameraUI` expose the same `mark()`, and so does the `<VidtreoRecorder>` that `@vidtreo/recorder-nuxt` auto-imports.
+- `isRecordingMarkerError`, the `ERROR_RECORDING_MARKER_*` codes and the `RecordingMarkerError` type are exported from `@vidtreo/recorder-vue`, so you don't need to import `@vidtreo/recorder`.
+
 ### Specialized composables
 
 | Composable | Purpose |
 |------------|---------|
-| `useMobileWebRecorder(config)` | Wraps `useVidtreoRecorder` and adds `isModalOpen`, `openModal`, `closeModal`, `canCloseModal` for the mobile overlay experience. |
+| `useMobileWebRecorder(config)` | Takes the same config object or `() => config` getter as `useVidtreoRecorder`. Wraps it and adds `isModalOpen`, `openModal`, `closeModal`, `canCloseModal` for the mobile overlay experience. |
 | `useNativeCamera(config)` | File-input + transcoding flow used when `mobileMode: "native"`. Returns `{ state, actions }` with `handleFileSelect`, `processAndUpload`, `downloadVideo`, `reset`. Resumes queued native uploads on mount (except in demo mode); `state` includes `uploadPhase`, `uploadRetryAttempt` and `uploadErrorCode`. |
 | `usePermissionFlow(options)` | Drives the camera/mic permission overlay. Returns `{ isActive, isComplete, currentStep, steps, recoveryData, requestPermission, retryPermission }` — useful if you want to build a fully custom permission UI. |
 | `useRecorderTranslations(translations)` | Splits a `TranslationKeys` object into `preview`, `buttons`, and `settings` subsets as `ComputedRef`s. Accepts `MaybeRefOrGetter<TranslationKeys>` so it stays reactive when the language changes. |
@@ -641,7 +724,7 @@ For other SSR setups, wrap the component in `<ClientOnly>` (Nuxt) or guard it be
 
 ## TypeScript
 
-Every public surface is typed. The package also re-exports `getUploadErrorCode` and `UPLOAD_ERROR_INSUFFICIENT_CREDITS` from `@vidtreo/recorder`. Import types directly:
+Every public surface is typed. The package also re-exports `getUploadErrorCode`, `UPLOAD_ERROR_INSUFFICIENT_CREDITS`, `isRecordingMarkerError`, the `ERROR_RECORDING_MARKER_*` codes and the `RecordingMarkerError` type from `@vidtreo/recorder`. Import types directly:
 
 ```ts
 import type {
@@ -659,6 +742,7 @@ import type {
   MobileMode,
   AudioWarning,
   RecordingStopResult,
+  VidtreoRecorderExposed,
 } from "@vidtreo/recorder-vue";
 ```
 

package/dist/components/MobileWebRecorderUI.vue.d.ts

@@ -1,7 +1,7 @@
-import type { UseVidtreoRecorderConfig } from "../types";
+import type { UseVidtreoRecorderConfig, VidtreoRecorderExposed } from "../types";
 type __VLS_Props = {
     config: UseVidtreoRecorderConfig;
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, VidtreoRecorderExposed, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/components/MobileWebRecorderUIContent.vue.d.ts

@@ -1,7 +1,7 @@
-import type { UseVidtreoRecorderConfig } from "../types";
+import type { UseVidtreoRecorderConfig, VidtreoRecorderExposed } from "../types";
 type __VLS_Props = {
     config: UseVidtreoRecorderConfig;
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, VidtreoRecorderExposed, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/components/NativeCameraUI.vue.d.ts

@@ -1,7 +1,7 @@
-import type { UseVidtreoRecorderConfig } from "../types";
+import type { UseVidtreoRecorderConfig, VidtreoRecorderExposed } from "../types";
 type __VLS_Props = {
     config: UseVidtreoRecorderConfig;
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, VidtreoRecorderExposed, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/components/StandardRecorder.vue.d.ts

@@ -1,9 +1,9 @@
 import type { RecordingUploadResult, UploadProgressPhase } from "@vidtreo/recorder";
-import type { VidtreoRecorderProps } from "../types";
+import type { VidtreoRecorderExposed, VidtreoRecorderProps } from "../types";
 type __VLS_Props = {
     recorderProps: VidtreoRecorderProps;
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, VidtreoRecorderExposed, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     error: (error: Error) => any;
     uploadProgress: (progress: number, phase: UploadProgressPhase | null) => any;
     transcodingProgress: (progress: number) => any;

package/dist/components/StandardRecorderContent.vue.d.ts

@@ -1,9 +1,9 @@
 import { type RecordingUploadResult, type UploadProgressPhase } from "@vidtreo/recorder";
-import type { VidtreoRecorderProps } from "../types";
+import type { VidtreoRecorderExposed, VidtreoRecorderProps } from "../types";
 type __VLS_Props = {
     recorderProps: VidtreoRecorderProps;
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, VidtreoRecorderExposed, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     error: (error: Error) => any;
     uploadProgress: (progress: number, phase: UploadProgressPhase | null) => any;
     transcodingProgress: (progress: number) => any;

package/dist/components/VidtreoRecorder.vue.d.ts

@@ -1,9 +1,9 @@
 import { type RecordingUploadResult, type UploadProgressPhase } from "@vidtreo/recorder";
-import type { VidtreoRecorderProps } from "../types";
+import type { VidtreoRecorderExposed, VidtreoRecorderProps } from "../types";
 type __VLS_Props = {
     recorderProps: VidtreoRecorderProps;
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, VidtreoRecorderExposed, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     error: (error: Error) => any;
     uploadProgress: (progress: number, phase: UploadProgressPhase | null) => any;
     transcodingProgress: (progress: number) => any;

package/dist/components/ui/AudioBar.vue.d.ts

@@ -3,7 +3,6 @@ import type { TranslationKeys } from "../../i18n/translations";
 import type { VidtreoRecorderState } from "../../types";
 type __VLS_Props = {
     state: VidtreoRecorderState;
-    audioLevel: number;
     translations: TranslationKeys;
     isStopLocked: boolean;
     isRetrying: boolean;

package/dist/components/ui/AudioVisualizer.vue.d.ts

@@ -1,5 +1,4 @@
 type __VLS_Props = {
-    audioLevel: number;
     isMuted: boolean;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/components/ui/PreviewContent.vue.d.ts

@@ -42,7 +42,6 @@ type __VLS_Props = {
     isRecording: boolean;
     isProcessingRecording: boolean;
     controller: RecorderController | null;
-    audioLevel: number;
     buttonVisibility: ButtonVisibility;
     currentSourceType: SourceType;
     isStopLocked: boolean;