Klippy

Screen recording

Klippy includes a production-ready screen and camera recorder. It captures desktop, tab, or window streams, composites webcam overlays, mixes audio, and drops the finished clip straight into your media library. This page explains the recorder architecture, UI workflow, and key tuning options.

Recorder modes

  • Screen only: capture the selected display, window, or tab at up to 60 fps.
  • Screen + camera: composites webcam into a picture-in-picture layout or records it as a separate track for post-adjustments.
  • Camera only: capture the webcam with virtual background and blur options.

Open the Recording panel from the sidebar (shortcut: R) to configure layout, countdown, resolution, codec, and overlays before starting.

Architecture

Recording is orchestrated by ScreenWebcamRecorder, which composes several specialised services:

Capture pipeline

  • StreamManager negotiates getDisplayMedia, getUserMedia, and mic streams, handling retries and pre-selection.
  • CanvasRenderer composites screen, camera, pointer trails, zooms, and HUD overlays when PIP layouts are enabled.
  • AudioProcessor mixes system + mic input, applies optional noise reduction, and feeds a Web Audio destination.
  • RecordingEngine writes chunks via MediaRecorder using the preferred codec (video/webm or video/mp4 on Safari).
  • EventTracker logs clicks, keystrokes, and zoom triggers so overlays render at the correct timestamps.

Control layer

  • GlobalRecordingManager.ts keeps a singleton instance so hotkeys (⌘⇧R / Ctrl+Shift+R) work across routes.
  • useRecordingOperations manages countdowns, pause/resume, media pre-selection, and toast feedback.
  • useMediaFileCreation converts captured blobs into Klippy media items, creating separate camera tracks when requested.
  • RecorderSettingsPanel.tsx and related UI components expose presets, shortcuts, and pip margin controls.

When users capture the entire desktop, the recorder skips canvas compositing and records the raw display track to avoid Chrome’s throttling behaviour, adding the webcam as a secondary file instead.

Using the recorder

  1. Choose a layout (screen only, screen + camera, camera only) and adjust PIP position, shape, and margins.
  2. Set quality (Fast/Balanced/High), FPS, and preferred codec. Balanced 1080p @ 30 fps is a safe default.
  3. Enable overlays: cursor highlights, keystroke HUD, auto PIP positioning, or dynamic zooms.
  4. Pick the screen/tab/window when prompted. If countdown is enabled, the timer runs before capture begins.
  5. Use ⌘⇧P/Ctrl+Shift+P (or the toolbar button) to pause/resume. Stop recording from the panel or the floating HUD.

After stopping, Klippy multiplexes audio, merges optional camera tracks, and stores the result in IndexedDB. The clip automatically appears in the Media panel for immediate timeline use.

Audio handling

  • System audio (Chrome / Edge): captured via the display stream when users tick “Share tab audio” or entire screen.
  • Microphone: routed through Web Audio for gain control and optional enhancement (enableAudioEnhance).
  • Mixdown: AudioProcessor merges channels and exposes the final tracks to MediaRecorder; when separate camera track is active, its audio is bundled inside the cam file.

Integration with the editor

  • Recorded clips are stored via storageManager.storeFile and linked to the active project, enabling undo/redo like any other import.
  • When Separate camera track is enabled, the second file is automatically added to the timeline in sync with the screen recording.
  • Recorder presets persist in localStorage (klippy-recorder-presets-v1) so teams can share recommended settings.

Troubleshooting

  • Permission denied: browsers require HTTPS (or localhost) for getDisplayMedia. Verify no other tab is capturing the same screen.
  • Black captures on macOS: when sharing entire desktop with screen + cam, Chrome throttles canvas draws. The recorder automatically falls back to the raw screen track, but you can disable overlays to save GPU.
  • No system audio: Chrome/Edge need the “Share tab audio” checkbox. Safari only supports microphone capture.
  • Large file size: lower the bitrate (videoBitsPerSecond) or drop resolution; finished clips can be re-encoded with Standard exports.