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

```bash
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

| Requirement | Detail |
|---|---|
| **Node.js** | 22.22.1 (exact; see `.nvmrc`) |
| **npm** | 10.9.4 |
| **OS** | macOS, Windows, Linux |
| **Disk** | Recordings stored in Electron's `userData/recordings/` directory |

### Install from Source

```bash
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

```bash
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"
    ```bash
    npm run build
    ```

=== "macOS"
    ```bash
    npm run build:mac
    ```

=== "Windows"
    ```bash
    npm run build:win
    ```

=== "Linux"
    ```bash
    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

```bash
npm run dev
```

```text
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.

| Setting | Values | Default |
|---|---|---|
| **Padding** | `0`–`100` (percentage) | `50` |
| **Aspect Ratio** | `16:9`, `9:16`, `1:1`, `4:3`, `4:5`, `16:10`, `10:16`, `native` | `16:9` |
| **Export Quality** | `medium`, `good`, `source` | `good` |
| **Export Format** | `mp4`, `gif` | `mp4` |

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:

| Action | Default Shortcut |
|---|---|
| Add Zoom | `Z` |
| Add Trim | `T` |
| Add Speed | `S` |
| Add Annotation | `A` |
| Add Blur | `B` |
| Add Keyframe | `F` |
| Delete Selected | `Ctrl+D` / `Cmd+D` |
| Play / Pause | `Space` |

**Fixed shortcuts** (not customizable):

| Action | Shortcut |
|---|---|
| Undo | `Ctrl+Z` / `Cmd+Z` |
| Redo | `Ctrl+Shift+Z` / `Ctrl+Y` / `Cmd+Shift+Z` |
| Cycle Annotations Forward | `Tab` |
| Cycle Annotations Backward | `Shift+Tab` |
| Delete Selected (alt) | `Delete` / `Backspace` |
| Pan Timeline | `Shift+Ctrl+Scroll` |
| Zoom Timeline | `Ctrl+Scroll` |
| Frame Back | `←` |
| Frame Forward | `→` |

> [!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`.

| Code | Language |
|---|---|
| `en` | English (default) |
| `zh-CN` | Chinese (Simplified) |
| `es` | Spanish |
| `fr` | French |
| `tr` | Turkish |
| `ko-KR` | Korean |

> [!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:

| Region Type | Purpose | Shortcut |
|---|---|---|
| **Zoom** | Magnify a portion of the screen at a specific time range | `Z` |
| **Trim** | Cut out a section of the video | `T` |
| **Speed** | Change playback speed for a time range | `S` |
| **Annotation** | Add text, images, emojis, arrows, or blur overlays | `A` (text) / `B` (blur) |

**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:

| Layout | Description |
|---|---|
| **Picture in Picture** | Webcam floats in a corner (default: bottom-right) with rounded corners and drop shadow |
| **Vertical Stack** | Webcam spans full width at the bottom; screen fills the rest |
| **Dual Frame** | Side-by-side 2:1 split (screen gets 2/3 width, webcam gets 1/3) |

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:**

| Size Preset | Frame Rate Options |
|---|---|
| Small, Medium, Large, Custom | 10, 15, 20, 25, 30 fps |

## 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:
   ```bash
   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).

---

_Generated May 2026 from siddharthvaddem/openscreen at 899504f. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._