OpenScreen User Guide

1. Quick Start

OpenScreen is a free, open-source screen recorder and video editor built with Electron. It captures your screen, webcam, and audio, then provides a full editing suite with zoom effects, annotations, trimming, speed control, blur regions, and export to MP4 or GIF — all in a single desktop application.

Key features:

• Screen and window capture at up to 4K/60fps
• Webcam overlay with multiple layout presets (picture-in-picture, vertical stack, dual frame)
• System audio and microphone recording with mixing
• Timeline-based video editor with zoom, trim, speed, and annotation regions
• Blur tool with rectangle, oval, and freehand shapes
• Text, image, emoji, and arrow annotations with custom Google Fonts
• Export to MP4 (multiple quality tiers) or GIF (configurable size/frame rate)
• Project save/load (.openscreen format)
• Customizable keyboard shortcuts
• Internationalization: English, Spanish, French, Chinese (Simplified), Turkish, Korean

Prerequisites:

• Node.js 22.22.1 and npm 10.9.4

Quick install and run:

git clone https://github.com/siddharthvaddem/openscreen.git
cd openscreen
npm install
npm run dev

The HUD overlay window appears at the bottom-center of your screen. Select a source to record, press the record button, then stop when finished — you're taken directly to the editor.

Tip

To jump straight into the editor without recording, use File → Load Project (Ctrl+O / Cmd+O) to open an existing .openscreen project or import a video file.

2. Installation

System Requirements

Install from Source

git clone https://github.com/siddharthvaddem/openscreen.git
cd openscreen
npm install

Important

The engines field in package.json enforces Node.js 22.22.1 and npm 10.9.4. Use nvm to switch versions if needed: nvm use (the repo includes an .nvmrc file).

Run in Development

npm run dev

This starts the Vite dev server and the Electron app simultaneously. Changes to renderer code hot-reload; changes to the Electron main process require a restart.

Build for Distribution

All platforms

npm run build

macOS

npm run build:mac

Windows

npm run build:win

Linux

npm run build:linux

Build output is placed in the release/ directory. The macOS build script (scripts/build_macos.sh) handles code signing, notarization, and DMG creation for both arm64 and x64 architectures.

Verify Installation

npm run dev

VITE v5.x.x ready in XXXms
  ➜  Local:   http://localhost:5173/

The HUD overlay window should appear on your primary display.

3. Configuration

User Preferences

OpenScreen persists user preferences in localStorage under the key openscreen_user_preferences. Preferences are automatically loaded on startup.

These defaults apply to every new recording/edit session. Change them from the Settings panel in the editor.

Keyboard Shortcuts

Shortcuts are persisted per-user via Electron's userData/shortcuts.json. The defaults are:

Fixed shortcuts (not customizable):

Tip

Open the shortcut configuration dialog from the editor's settings to remap any configurable shortcut. The dialog shows conflict warnings if a binding clashes with a fixed or another configurable shortcut.

Language

OpenScreen supports 6 languages. Change the language from the settings panel; the selection is saved in localStorage under openscreen-locale.

Note

The language applies to the entire UI including Electron menus and dialog text. Both the renderer and main process share the same translation files.

Custom Fonts

Add Google Fonts for use in text annotations. In the Annotation Settings panel:

1. Click Add Custom Font
2. Paste a Google Fonts @import URL (e.g., https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap)
3. The font name is auto-detected; adjust if needed
4. Click Add — the font loads and validates before saving

Custom fonts are stored in localStorage under openscreen_custom_fonts and reloaded on every app launch.

See the Admin Guide for the full configuration reference.

4. Core Usage

Recording Your Screen

1. Select a source: From the HUD overlay, click the source selector button. A floating picker shows available screens and application windows with thumbnail previews.
2. Configure audio: Toggle the microphone and system audio buttons on the HUD. Select a specific microphone from the dropdown if multiple devices are connected.
3. Enable webcam (optional): Toggle the webcam button. Grant camera permission when prompted. Select a specific camera from the dropdown.
4. Start recording: Click the record button. The tray icon changes to indicate recording is active.
5. Pause/Resume: Click the pause button during recording.
6. Stop recording: Click the stop button or use the system tray menu → Stop Recording.

After stopping, the recording is saved automatically and the editor window opens with your video loaded.

Note

OpenScreen targets 4K (3840×2160) at 60fps with adaptive bitrate: 45 Mbps for 4K, 28 Mbps for QHD (2560×1440), and 18 Mbps for lower resolutions. The actual resolution depends on your display and the selected source. Codec preference order: AV1 → H.264 → VP9 → VP8.

Warning

On macOS, OpenScreen requires Screen Recording permission and Microphone access in System Settings → Privacy & Security. If permissions are denied, recording will fail with a "Permission denied" error.

Editing a Video

The editor opens automatically after a recording, or use File → Load Project / Open Video to bring in existing content.

Timeline regions are the core editing concept. Each type appears as a colored bar on the timeline:

Adding a zoom region:

1. Press Z or click the zoom button
2. A new zoom region appears at the current playhead position
3. Drag the edges to adjust timing
4. Use the zoom controls to set the zoom level and focal point
5. Add keyframes (F) to animate the zoom position over time

Adding annotations:

1. Press A for a text annotation or B for a blur region
2. Position and resize the annotation on the video preview
3. Customize styling: font, size, color, background color, alignment
4. For blur: choose rectangle, oval, or freehand shape; adjust intensity

Cropping: The crop control lets you crop the video to a specific region. Adjust the crop rectangle in the video preview.

Webcam Overlay

When a recording includes webcam footage, the overlay is rendered in the editor and export with these layout options:

Webcam size is adjustable from 10% to 50% of the canvas reference dimension. Mask shapes: rectangle, rounded, circle, or square.

Tip

Drag the webcam overlay to reposition it anywhere on the canvas in picture-in-picture mode. The position is stored as normalized coordinates so it adapts to different export resolutions.

Undo and Redo

The editor maintains a full undo/redo history (up to 80 states). All region changes, crop adjustments, wallpaper changes, and settings modifications are undoable.

• Undo: Ctrl+Z / Cmd+Z
• Redo: Ctrl+Shift+Z / Ctrl+Y / Cmd+Shift+Z

During slider interactions (e.g., adjusting border radius or padding), the first change in a drag creates an undo checkpoint. Subsequent moves within the same drag update in place, so you undo the entire drag as one step.

Exporting

1. Click the Export button in the editor toolbar
2. Choose format:
   • MP4: Select quality — medium, good, or source (lossless)
   • GIF: Select size preset and frame rate
3. Click Export
4. Choose a save location in the file dialog

Warning

Exporting long videos at high quality is CPU-intensive. Community issue #157 reports slow export times on Linux. Issue #439 reports 8-minute videos taking over 1 hour at High quality. Consider using medium or good quality for faster exports.

GIF export options:

5. Common Tasks

Record a Specific Application Window

1. Click the source selector in the HUD overlay
2. In the source picker, locate the application window thumbnail
3. Click to select it
4. Start recording — only that window is captured

Record with Microphone and System Audio

1. Enable the microphone toggle on the HUD
2. Select a specific microphone device from the dropdown
3. Enable the system audio toggle
4. Start recording — both audio sources are mixed into a single track

Note

When both microphone and system audio are enabled, they are mixed using the Web Audio API with a 1.4× gain boost on the microphone channel to balance levels. Audio bitrate is 192 kbps for system audio or 128 kbps for voice-only.

Add Text Annotations with Custom Styling

1. In the editor, press A to add a text annotation at the playhead
2. Type your text in the annotation overlay
3. Open the Annotation Settings panel to customize:
   • Font family (including custom Google Fonts)
   • Font size, weight, style, decoration
   • Text color and background color (with highlight effect)
   • Text alignment (left, center, right)
4. Position and resize by dragging

Blur Sensitive Information

1. Press B to add a blur region
2. Choose a shape in the Blur Settings panel:
   • Rectangle: Standard rectangular blur
   • Oval: Elliptical blur
   • Freehand: Draw a custom blur shape directly on the video
3. Adjust blur intensity
4. Resize and position the blur region over the sensitive area

Save and Load Projects

Save your editing work as an .openscreen project file:

1. Save: Ctrl+S / Cmd+S — saves to the current project path, or prompts for a location
2. Save As: Ctrl+Shift+S / Cmd+Shift+S — always prompts for a new location
3. Load: Ctrl+O / Cmd+O — opens a file picker for .openscreen or JSON files

Projects store all editor state: regions, annotations, crop, wallpaper, settings, and references to the source video files.

Important

Project files reference video files by absolute path. If you move the source video files, the project will fail to load them. Keep video and project files together or in the recordings directory.

Import an External Video

1. In the editor, use the video file picker to browse for a video
2. Supported formats: .webm, .mp4, .mov, .avi, .mkv
3. The video loads into the editor for the full editing workflow

Change the Background Wallpaper

The editor includes 18 built-in wallpaper backgrounds. Select a wallpaper from the Settings panel — it appears behind the video with the configured padding. Adjust padding (0–100%) to control how much wallpaper is visible around the video.

Restart a Recording

During an active recording, click the restart button. The current recording is discarded and a new one begins immediately with the same source and audio settings.

6. Troubleshooting

Error: Permission denied / NotAllowedError

Cause: The operating system denied screen recording or microphone access.

Solution:

1. On macOS: Go to System Settings → Privacy & Security → Screen Recording and add OpenScreen
2. On macOS: Go to Privacy & Security → Microphone and grant access
3. Restart the application after changing permissions

Prevention: Grant all required permissions before the first recording.

Error: Video decode ended early

Cause: The video file may be corrupted or use an unsupported codec. This is a known issue (community issue #276).

Solution:

1. Try re-recording the video
2. If importing an external video, convert it to WebM VP9 format first:

   ffmpeg -i input.mp4 -c:v libvpx-vp9 output.webm
   

Error: Export fails on Windows

Cause: Known issue (community issue #428) where export fails with various errors on Windows.

Solution:

1. Ensure you have the latest version of OpenScreen
2. Try exporting at a lower quality setting
3. Check that you have sufficient disk space

Error: Background not shown in exported video

Cause: Known issue (community issue #376) where the configured wallpaper background doesn't appear in the exported video.

Solution:

1. Verify the wallpaper is properly selected in Settings
2. Ensure padding is greater than 0 (padding of 0 means no wallpaper is visible)

Error: Audio misaligned with speed + trim regions

Cause: Known issue (community issue #433) where audio can become misaligned when exporting with both speed changes and trim regions applied.

Solution:

1. Apply speed changes and trim regions separately — export with one, then re-import and apply the other
2. Check if removing one of the conflicting regions resolves the alignment

Error: Blurry screen display

Cause: Display scaling or resolution mismatch (community issue #437).

Solution:

1. Check your display scaling settings in your OS
2. Try running the app on your primary display
3. Ensure the latest version is installed

Error: Application force closes or won't start

Cause: Various startup failures (community issue #411).

Solution:

1. Delete the userData directory and restart
2. Ensure Node.js 22.22.1 is installed
3. Run npm install to ensure all dependencies are present
4. Check console output for specific error messages

Error: Fail to read binary file

Cause: File path issues when loading video files (community issue #379).

Solution:

1. Ensure the video file path doesn't contain special characters
2. Move the file to a path without spaces or unicode characters
3. Try importing the file through the file picker instead of loading a project

Prevention: Store recordings in the default recordings directory.

7. FAQ

Q: What video formats does OpenScreen support for import?

OpenScreen supports .webm, .mp4, .mov, .avi, and .mkv for import. Recordings are captured in WebM format using the best available codec (AV1 → H.264 → VP9 → VP8). Exports are in MP4 or GIF format.

Q: Where are my recordings stored?

Recordings are saved in Electron's user data directory under a recordings/ subdirectory. The exact path depends on your OS — check the console output at startup where RECORDINGS_DIR is logged.

Q: Can I record at 4K resolution?

Yes. OpenScreen targets 3840×2160 at 60fps and automatically adjusts to your display's capabilities. If your display is 1080p, the recording will be captured at 1080p. The bitrate scales with resolution.

Q: How do I change the webcam overlay shape?

In the editor's Settings panel, select a webcam mask shape: rectangle (default), rounded, circle, or square. Circle and square shapes force the overlay to equal width and height.

Q: Can I use custom fonts for text annotations?

Yes. Click Add Custom Font in the Annotation Settings panel and paste a Google Fonts @import URL. The font is downloaded, verified, and made available for all text annotations.

Q: What file format are project files?

Project files use the .openscreen extension and are JSON files internally. They store the full editor state and references to source video files.

Q: Is there a cursor follow feature?

Yes. OpenScreen captures cursor position telemetry at 10Hz during recording. This data is stored alongside the video file as <filename>.cursor.json and can be used for cursor-following zoom effects in the editor.

Q: How do I switch languages?

Open the Settings panel and select from the available languages. The change takes effect immediately across the entire UI, including native Electron menus.

Q: What's the maximum undo history?

The editor maintains up to 80 undo states. Selection changes are excluded from undo history (undoing a selection change would feel confusing).