Velt Recorder Best Practices

Comprehensive implementation guide for Velt's Recorder system in React and Next.js applications. Contains 25 rules across 8 categories, prioritized by impact to guide automated code generation and integration patterns.

When to Apply

Reference these guidelines when:

• Adding audio, video, or screen recording to a React/Next.js application
• Setting up VeltRecorderTool, VeltRecorderControlPanel, and VeltRecorderPlayer
• Configuring VeltRecorderNotes for pinned recordings
• Integrating the VeltVideoEditor for post-recording editing
• Configuring recording quality constraints and encoding options
• Requesting device permissions (camera, microphone, screen)
• Subscribing to recording lifecycle events
• Managing recording data (fetch, subscribe, delete, download)
• Enabling AI transcription and summary display
• Configuring Picture-in-Picture mode for screen recordings
• Setting max recording duration limits
• Choosing between floating and thread control panel modes
• Binding Recorder wireframe slots with template variables (velt-data, velt-if, velt-class)

Rule Categories by Priority

Quick Reference

1. Core Setup (CRITICAL)

• core-setup — Add VeltRecorderTool, VeltRecorderControlPanel, and VeltRecorderPlayer
• core-permissions — Request device permissions for camera, microphone, and screen capture
• core-webhooks — Handle the recorder.done server-side webhook event (RecorderPayload, RecorderTrigger)

2. Recording Configuration (HIGH)

• config-type-and-mode — Select recording type (all, audio, video, screen) and customize tool button
• config-max-length — Set maximum recording duration
• config-picture-in-picture — Enable PiP for screen recordings (Chrome only)
• config-quality-encoding — Configure recording quality constraints and encoding options

3. Data Management (HIGH)

• data-hooks — Use React hooks (useRecordings, useRecorderAddHandler) for reactive data
• data-fetch-subscribe — Fetch or subscribe to recording data via API
• data-delete-download — Delete recordings and download latest video version
• data-rest-api — Retrieve recordings via REST API (server-side, with pagination)

4. Event Handling (MEDIUM-HIGH)

• events-lifecycle — Subscribe to all 11 recorder events via API
• events-hooks — Use useRecorderEventCallback hook for React event subscriptions

5. Video Editor (MEDIUM)

• editor-enable-configure — Enable video editor with auto-open, retake, timeline preview
• editor-standalone — Embed standalone VeltVideoEditor component

6. UI/UX Configuration (MEDIUM)

• ui-control-panel-mode — Choose floating vs thread mode for VeltRecorderControlPanel
• ui-playback-options — Configure fullscreen playback and click-to-play behavior
• ui-countdown-settings — Control countdown timer and embedded settings
• ui-ai-transcription — Configure AI transcription and summary display

7. Debugging & Testing (LOW-MEDIUM)

• debug-common-issues — Common recorder issues and solutions

8. Wireframe Variables (MEDIUM)

• wireframe-variables-recorder — Bind Recorder wireframe slots (button, pin, control panel, player, expanded player) using velt-data / velt-if / velt-class; covers the six naming-conflict variables and the shared player behaviour callbacks
• wireframe-variables-recorder-transcription — Bind Transcription, Subtitles, and Subtitles-Dialog wireframe slots using componentConfig.<name> paths; covers vttFileTextArray iteration via content-item-wireframe, segment / currentTime context variables, and transcript / subtitle behaviour callbacks

How to Use

Read individual rule files for detailed explanations and code examples:

rules/shared/core/core-setup.md
rules/shared/config/config-type-and-mode.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Source pointers to official documentation

Compiled Documents

• AGENTS.md — Compressed index of all rules with file paths (start here)
• AGENTS.full.md — Full verbose guide with all rules expanded inline