Filesystem

Beam keeps durable user content separate from replaceable application caches. Use this reference when backing up, moving, inspecting, or troubleshooting a Beam installation.

Where Beam stores user files

Beam resolves the operating system's Videos folder and creates Beam/user inside it. A redirected or localized Videos folder changes the resolved location, so the paths below are the usual defaults rather than hard-coded locations.

• Windows: %USERPROFILE%\Videos\Beam\user
• macOS: ~/Movies/Beam/user
• Linux: ${XDG_VIDEOS_DIR:-~/Videos}/Beam/user

Open the folder on Windows

Press

Win+R

, paste %USERPROFILE%\Videos\Beam\user, then press

↵

. Windows expands %USERPROFILE% and opens the folder in File Explorer.

Open the folder on macOS

Open Finder, press

⌘+Shift+G

, paste ~/Movies/Beam/user, then press

↵

. Finder expands ~ to your home folder.

Open the folder on Linux

Open your file manager, press

Ctrl+L

, enter ~/Videos/Beam/user, then press

↵

. For a redirected Videos directory, run xdg-open "$(xdg-user-dir VIDEOS)/Beam/user" in a terminal.

The folder is created on demand

Some directories appear only after their feature is first used. Record once before looking for projects/, or import a background before looking for the wallpaper library.

User-data layout

The Beam/user directory can contain the following durable data:

Beam/user/
├── preferences.json
├── projects/
│   └── project-<readable-name>/
├── media/
│   └── wallpapers/
│       ├── image/
│       └── video/
└── models/
    └── whisper/

• preferences.json stores appearance, recorder behavior, selected devices, shortcuts, onboarding state, presets, and saved window placement. It is created or replaced with normalized defaults when needed.
• projects/ stores every Beam project and its recording sessions. This is the most important directory to back up.
• media/wallpapers/image/ and media/wallpapers/video/ store copies of backgrounds imported into the shared wallpaper library. They are optional.
• models/whisper/ stores downloaded local transcription models, their manifests, and temporary .partial downloads. Models are optional and can be downloaded again.

Recordings and projects

Each project uses a readable directory name such as project-vivid-cosmic. The stable project UUID lives inside project.json, so the directory name is not the project's identity. Renaming a project can also rename its directory.

Project directory

A developed project can look like this:

project-<name>/
├── project.json                         required
├── thumbnail.webp                       optional
├── media/                               optional imported editor media
├── backgrounds/                         optional project backgrounds
└── session-<uuid>/                      one or more recording sessions
    ├── manifest.json                    completed session
    ├── manifest.partial.json            interrupted/in-progress recovery state
    ├── health.jsonl                     capture diagnostics
    ├── timing.jsonl                     clock synchronization anchors
    ├── screen/                          screen video segments
    ├── system-audio/                    optional system-audio segments
    ├── microphone/                      optional microphone segments
    ├── camera/                          optional camera segments
    ├── cursor/                          optional cursor and interaction data
    └── session/teleprompter.json        optional teleprompter document

Required project metadata

• project.json is the project manifest and source of truth. It contains the schema version, stable project ID, display name, timestamps, session references, composition, presentation settings, captions, zoom state, and imported-asset references.
• Each completed session normally has manifest.json, which describes the platform, selected sources, permissions, warnings, track formats, segments, metrics, and completion state.
• manifest.partial.json preserves recoverable metadata while capture is active or when a session did not finalize. A recovered session may legitimately use it instead of manifest.json.

Do not edit manifests by hand

The manifests are versioned application data with cross-file references. Manual edits, moving individual session files, or renaming files inside a project can make media unavailable in the editor.

Track and media directories

• screen/ contains numbered MP4 screen segments when screen capture succeeded.
• system-audio/, microphone/, and camera/ contain numbered WebM segments written for the corresponding enabled sources.
• The five track directories can exist even when a source was not selected. Use the session manifest's tracks entries and statuses—not the presence of an empty directory—to determine what was recorded.
• Temporary .partial media files can exist during an active or interrupted browser-media write. Finalized segments are renamed atomically.
• media/ contains copies of videos, images, or audio imported into the editor. Removing an unused imported asset through Beam can remove its copied file.
• backgrounds/ contains copies of backgrounds imported specifically into that project.

Cursor, interactions, and diagnostics

• cursor/cursor.json contains recorded cursor events when cursor capture is available.
• cursor/telemetry.json contains normalized cursor movement samples used by editor behavior such as cursor following.
• cursor/shapes.json describes native cursor shapes; cursor/shapes/*.png can contain captured bitmap shapes when required by the platform or compatibility path.
• cursor/input.json contains permitted shortcut and click interaction metadata. Typed text is not stored.
• health.jsonl records capture health and interruptions; timing.jsonl records timing anchors used to align tracks. Keep both with the session when moving or diagnosing a project.

Optional presentation files

• thumbnail.webp is a generated project-card preview and can be recreated.
• session/teleprompter.json exists only after a teleprompter document is saved for that session.
• Generated captions and editor configuration are stored in project.json; they are not separate subtitle files inside the project.

Back up the complete project directory

Copy project-<name>/ as one unit while Beam is not recording. A lone screen MP4 does not include the editor composition, optional tracks, cursor data, captions, or diagnostics.

Updates

Downloaded updates are stored in the operating system's cache, separately from projects. The pending/ directory can contain the installer or update archive and update-info.json. Beam clears the updater cache after the new version starts successfully, while preserving an update that is still awaiting installation.

• Windows: %LOCALAPPDATA%\beam-updater\pending
• macOS: ~/Library/Caches/beam-updater/pending
• Linux: ${XDG_CACHE_HOME:-~/.cache}/beam-updater/pending

Update state

Beam also stores update-cache-state.json in Electron's application-data directory so it can distinguish an installed update from one still pending. The usual parent directories are %APPDATA%\Beam on Windows, ~/Library/Application Support/Beam on macOS, and ${XDG_CONFIG_HOME:-~/.config}/Beam on Linux.

Updater files are disposable

Do not back up or move the updater cache. If no update is actively downloading or waiting to restart, it can be removed and Beam will download a future update again. Never delete it while an update is downloading or ready to install.