@vidtreo/recorder-vue 1.13.0 → 1.14.0

package/README.md

@@ -352,8 +352,78 @@ 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 |
@@ -641,7 +711,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 +729,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/index.d.ts

@@ -1,5 +1,5 @@
 import "@vidtreo/ui-styles/recorder.css";
-export { CONFIG_ERROR_CREDENTIAL_CONFLICT, getUploadErrorCode, isCredentialConflictError, UPLOAD_ERROR_INSUFFICIENT_CREDITS, } from "@vidtreo/recorder";
+export { CONFIG_ERROR_CREDENTIAL_CONFLICT, ERROR_RECORDING_MARKER_DUPLICATE_ID, ERROR_RECORDING_MARKER_INVALID_ID, ERROR_RECORDING_MARKER_INVALID_LABEL, ERROR_RECORDING_MARKER_LIMIT_REACHED, ERROR_RECORDING_MARKER_NOT_RECORDING, getUploadErrorCode, isCredentialConflictError, isRecordingMarkerError, type RecordingMarkerError, type RecordingMarkerErrorCode, UPLOAD_ERROR_INSUFFICIENT_CREDITS, } from "@vidtreo/recorder";
 export { default as MobileWebRecorderUI } from "./components/MobileWebRecorderUI.vue";
 export { default as NativeCameraUI } from "./components/NativeCameraUI.vue";
 export { default as StandardRecorder } from "./components/StandardRecorder.vue";
@@ -14,4 +14,4 @@ export type { ButtonTranslations, PreviewTranslations, RecorderTranslations, Set
 export { useRecorderTranslations } from "./composables/use-recorder-translations";
 export { useVidtreoRecorder } from "./composables/use-vidtreo-recorder";
 export { defaultTranslations, getTranslations, type PartialTranslations, type TranslationKeys, } from "./i18n/translations";
-export type { AccessTokenProvider, AudioWarning, MediaType, MobileMode, RecordingPrompt, RecordingPromptCountdown, RecordingPromptCountdownPlacement, RecordingState, RecordingStopResult, RecordingUploadResult, SourceType, UploadErrorCode, UploadProgressPhase, UseVidtreoRecorderConfig, UseVidtreoRecorderReturn, VidtreoRecorderActions, VidtreoRecorderEmits, VidtreoRecorderProps, VidtreoRecorderState, } from "./types";
+export type { AccessTokenProvider, AudioWarning, MediaType, MobileMode, RecordingMarker, RecordingMarkerInput, RecordingPrompt, RecordingPromptCountdown, RecordingPromptCountdownPlacement, RecordingState, RecordingStopResult, RecordingUploadResult, SourceType, UploadErrorCode, UploadProgressPhase, UseVidtreoRecorderConfig, UseVidtreoRecorderReturn, VidtreoRecorderActions, VidtreoRecorderEmits, VidtreoRecorderExposed, VidtreoRecorderProps, VidtreoRecorderState, } from "./types";