velt-recorder-best-practices

Files (32)

• AGENTS.full.md
• AGENTS.md
• README.md
• SKILL.md
• metadata.json
• data-hooks.md · rules/react/data/
• debug-common-issues.md · rules/react/debug/
• events-hooks.md · rules/react/events/
• _sections.md · rules/shared/
• _template.md · rules/shared/
• config-max-length.md · rules/shared/config/
• config-picture-in-picture.md · rules/shared/config/
• config-quality-encoding.md · rules/shared/config/
• config-type-and-mode.md · rules/shared/config/
• core-auth-provider.md · rules/shared/core/
• core-permissions.md · rules/shared/core/
• core-setup.md · rules/shared/core/
• core-webhooks.md · rules/shared/core/
• data-delete-download.md · rules/shared/data/
• data-fetch-subscribe.md · rules/shared/data/
• data-rest-api.md · rules/shared/data/
• data-types-reference.md · rules/shared/data/
• editor-enable-configure.md · rules/shared/editor/
• editor-standalone.md · rules/shared/editor/
• events-lifecycle.md · rules/shared/events/
• ui-ai-transcription.md · rules/shared/ui/
• ui-control-panel-mode.md · rules/shared/ui/
• ui-countdown-settings.md · rules/shared/ui/
• ui-playback-options.md · rules/shared/ui/
• ui-wireframes.md · rules/shared/ui/
• wireframe-variables-recorder-transcription.md · rules/shared/wireframe-variables/
• wireframe-variables-recorder.md · rules/shared/wireframe-variables/

SKILL.md (first lines)

# 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

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Core Setup | CRITICAL | `core-` |
| 2 | Recording Configuration | HIGH | `config-` |
| 3 | Data Management | HIGH | `data-` |
| 4 | Event Handling | MEDIUM-HIGH | `events-` |
| 5 | Video Editor | MEDIUM | `editor-` |
| 6 | UI/UX Configuration | MEDIUM | `ui-` |
| 7 | Debugging & Testing | LOW-MEDIUM | `debug-` |
| 8 | Wireframe Variables | MEDIUM | `wireframe-variables-` |

## 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

From velt-js/velt-plugin-cursor, MIT.