Clipbin recorder v1 specification

This document defines the v1 product requirements agreed on 2026-10-08. See README.md for the current implementation status.

Build an open-source desktop game recorder inspired by Plays.tv, using Rust, GPUI, and libobs through libobs-rs. The core experience is automatic recording, browsing a session while it is still active, saving recent clips, and protecting bookmarked moments.

Platforms and distribution

Target Windows and Linux, covering Wayland and X11. Wayland is the user's available Linux test environment; X11 and Windows need their own validation before release.
Initial Linux validation setup: CachyOS, Hyprland, AMD Radeon RX 9070 XT, recording at 1440p60.
Steam is the v1 game-discovery/launcher integration. The recording core must not depend on Steam-specific data structures so other integrations can be added later.
Use official OBS capture components only. Existing community capture plugins, including obs-vkcapture, and custom game hooks are excluded.
Windows: upstream OBS Game Capture with original signed hook binaries; official OBS Window Capture is also available.
Linux X11: upstream OBS Xcomposite Window Capture.
Native Linux Wayland: upstream OBS PipeWire capture using the XDG desktop portal. Offer both window and monitor capture, selected by the user.
Restore portal permissions/source selection where supported. If restoration fails, show a recording-needs-attention notification with a select-source action. Automatic recording is conditional on a usable, permitted capture source.
Monitor capture includes whatever is displayed on that monitor during alt-tab. Switching from window to monitor capture requires the user's selection; do not silently broaden the capture target.
Bundle a pinned, compatible OBS runtime and required official components. Users should not need a separate OBS installation. Graphics drivers remain system-provided.
Pin Rust OBS bindings, OBS runtime, and plugins as a tested version set. Exact versions and platform package formats are implementation decisions.

Automatic recording and reliability

Start on login by default, with a setting to disable it.
Detect recognised Steam games and start recording immediately, without per-game approval or routine manual start/stop.
Keep recording when the user alt-tabs, browses footage, edits a range, or exports a clip.
Stop/finalise the session when its game exits.
Closing the main window leaves background recording active. Provide an explicit Quit action.
Normal recording is silent: no routine start/stop notifications or recording overlay.
Show honest recording state in the application: waiting for capture, starting, recording, or failed.
Report recording only when capture is usable and footage is successfully being written. A detected process, permission grant, or accepted start command alone is insufficient.
Source loss, permission failure, encoder failure, output failure, and insufficient physical disk space must clear the recording state and produce a persistent, actionable failure alert.
Recover temporary failures automatically with bounded retries. Keep the unavailable/error state until recording actually resumes.
Missing footage is represented clearly in the session timeline. Recovery must not imply that the interrupted period was captured.
Anti-cheat risk is a primary concern. Use the original official capture foundation, preserve Windows hook signatures, and avoid changing anti-cheat/trust protections to enable capture. Successful capture alone is not evidence of a blanket anti-cheat approval.

Recording defaults and audio

Default video: 1080p at 60 FPS.
Resolution and frame rate are configurable, including the user's intended 1440p60 configuration.
Hardware video codec choices: H.264, HEVC, and AV1. H.264 is the default.
Offer a codec as usable only when the runtime/device supports its hardware encoder. Failure to obtain a working encoder follows the honest-status and failure-alert rules.
Keep system audio enabled by default.
Microphone recording is opt-in.
Preserve system and microphone audio on separate tracks, retaining their appropriate channel layouts.
Export a combined system/microphone playback track by default, with an option to preserve separate tracks for editing.
How quality presets map to individual encoder settings, and any hardware-codec fallback policy, must be chosen during implementation without hiding a recording failure.

Sessions, timeline, and editor

Keep complete recorded sessions browsable after gameplay until cleanup removes eligible footage.
Provide a session library and a continuous timeline/VOD for each session.
Active sessions can be browsed and clipped while their recording continues.
The newest footage may appear two to five seconds behind recording while its segment finalises.
Do not provide a live recording preview. Decode/play video when the user browses it.
Editor controls: play/pause, seeking, thumbnails, bookmark navigation, draggable start/end handles, and audio controls.
Clip selection/export uses keyframe-aligned boundaries. Frame-exact cuts are not required.
Preserve all selected footage when extending a selection to suitable keyframe boundaries, and show the actual export range.
Show unavailable or removed parts of a session honestly. Protect footage currently being edited or exported from cleanup.
A clip must remain playable across retained recording segment boundaries.

Clip hotkey and bookmarks

Provide independently configurable clip and bookmark actions/hotkeys.
The clip hotkey requests the last X time from the moment it is pressed; default X is two minutes.
Export the requested range in the background without stopping recording.
If the current segment must finish before export, retain the original request timestamp instead of shifting the range to when the job runs.
For a shorter newly started session, use the available footage and show its actual duration.
Protect source segments until export succeeds. Surface export failures; do not report successful saving before the exported file is complete.
The separate bookmark action places a timeline marker and protects a configurable interval.
Bookmark defaults: two minutes before and 30 seconds after the marker, independently configurable from the clip duration.
Protection for the post-bookmark period applies as that footage is recorded, ending at the actual session end if gameplay exits sooner.
Protected bookmarks remain available until the user releases/removes their protection.

Storage and exports

Default storage budget: 50 GB, configurable.
The budget counts only UNPROTECTED session footage.
Protected bookmarked footage and exported clips do not count toward the session budget. Total app storage may therefore exceed the configured budget.
Cleanup is storage-based only; there is no age-based expiry.
Remove the oldest eligible footage from completed sessions first, then old unprotected footage from the active session when needed.
Retain protected bookmark, editing, and export ranges even when neighbouring footage is removed.
Exported clips never expire automatically; users can delete them explicitly.
Distinguish budget-counted session usage from protected/saved usage in storage information.
Physical disk exhaustion remains a hard failure: stop/finalise safely, report that recording is unavailable, and offer corrective actions without silently deleting protected footage.
V1 exports local files only, with quick actions to open a clip or its folder.
Export MP4 while preserving the recorded video codec.
Use remuxing for compatible, keyframe-aligned clips without video re-encoding.
Keep capture running independently of export work.

Recording architecture and lightweight operation

Preferred architecture: one hardware-encoded video stream written into short, independently usable, keyframe-aligned disk segments.
Present those segments as one session timeline. Keep timestamps, segment availability, bookmarks, and retention/protection metadata consistent.
Keep recording independent of UI work. UI browsing, thumbnail generation, and export must not block the capture path.
Avoid unnecessary CPU frame copies where supported by the official capture path.
Generate/cache thumbnails in the background. Decode playback video on demand and keep work/queues bounded.
Prioritise recording over background thumbnails and exports.
Best-effort lightweight operation is the v1 performance goal.
No numerical FPS/frametime overhead promise, performance-monitoring feature, or formal benchmark programme is required in v1. Recording health checks remain required to support honest status.

Acceptance checks for implementation

A recognised Steam game starts a recording session automatically with a usable permitted source; exiting the game finalises it.
Alt-tab, closing the main window, playback, range selection, and export leave recording active.
Portal cancellation/revocation, source loss, encoder failure, and disk-write failure never leave a false recording status or a false successful-export status.
Recovery preserves a visible timeline gap for footage that was not captured.
The clip hotkey saves the default last two minutes using its request timestamp, including a range crossing segment boundaries.
Bookmark protection covers its configured pre/post interval and survives cleanup of adjacent footage.
The 50 GB default budget evicts only unprotected session footage; bookmarks and exported clips remain outside it.
MP4 exports preserve the chosen recorded codec and provide the agreed default/optional audio tracks.
The GPUI editor plays and seeks retained footage across segment boundaries, including active sessions within the agreed availability delay.
Packaged builds use a verified compatible OBS/bindings/plugin set on Windows, Wayland, and X11.

Implementation validation before building out the UI

Prove the pinned official OBS capture/runtime path on CachyOS/Hyprland/RX 9070 XT, including permission restoration and capture-health failure detection.
Verify hardware encoder availability for H.264, HEVC, and AV1 on each supported platform/device combination.
Verify short keyframe-aligned segment rollover with one continuous encoder, export across boundaries, and the two-to-five-second availability window. Do not assume the Rust convenience wrapper exposes every required OBS output option.
Prototype GPUI playback, seeking, and the agreed audio handling for all offered codecs.
Establish the global hotkey integration for Windows, Wayland, and X11 using supported OS/desktop mechanisms.
Establish game/process/session identity rules, including startup discovery, launchers spawning child processes, and ambiguous simultaneous games.
Establish recovery of session metadata/completed segments after an unexpected process exit.
Confirm distribution/licensing requirements for the pinned components. Exact playback backend, packaging formats, default hotkey bindings, and retry intervals can be selected during implementation.

Primary sources checked during the interview

OBS Game Capture availability and modes: https://obsproject.com/kb/game-capture-source
OBS Window Capture sources: https://obsproject.com/kb/window-capture-sources
Official X11 source registration: https://github.com/obsproject/obs-studio/blob/master/plugins/linux-capture/linux-capture.c
Official PipeWire/portal implementation and restoration: https://github.com/obsproject/obs-studio/blob/master/plugins/linux-pipewire/screencast-portal.c
Portal persistence and restoration limits: https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.ScreenCast.html
OBS signed capture-hook compatibility: https://obsproject.com/kb/capture-hook-certificate-update
Rust OBS bindings, platform notes, API stability: https://github.com/libobs-rs/libobs-rs

12 KiB Raw Blame History