Pica Pica turns local OBS Replay Buffer clips into a fast, private game library. It scans game folders, builds thumbnails and video metadata locally, and presents everything in a responsive streaming-style desktop interface.
Milestone 1 is a working local-first prototype. It never uploads, renames, moves, overwrites, or deletes original videos.
- Native Windows desktop foundation with Tauri 2 and Rust; transitional Linux Electron AppImage path using the same Rust sidecar
- Responsive React 19 interface built from shadcn/ui primitives and shared layout tokens
- Native folder picker and asynchronous library scans
- SQLite index with idempotent migrations and stable path-based clip IDs
- Sidecar-first FFmpeg/ffprobe detection, bounded parallel probing, and cached thumbnails
- Optional RAWG metadata search and SteamGridDB artwork with user-owned API keys
- Custom poster and hero overrides copied into the local cache
- Safe unresolved-game workflow with editable local metadata
- HTML5 playback for compatible H.264/AVC and AAC-LC clips, with external VLC or mpv playlists for every other format
- Browser demo adapter for frontend development without private clip data
- Reduced-motion support, keyboard focus states, and responsive player layout
The local vertical slice is implemented: onboarding → folder scan → game gallery → game detail → clip player. It now includes opt-in RAWG search, SteamGridDB artwork, secure OS-keychain storage, custom artwork, bundled checksum-verified FFmpeg tools, incremental probing and cursor-paginated clip pages. Automatic file watching, multiple libraries, code signing and stable installers remain follow-up work.
- Node.js 22 or newer
- pnpm 11 or newer
- Rust stable 1.85 or newer (current stable recommended)
- Platform-specific Tauri prerequisites for the Windows/Tauri host
- Optional for development:
ffmpegandffprobeonPATH; release builds bundle vetted binaries
Compatible MP4/M4V/MOV clips encoded as H.264/AVC with an 8-bit 4:2:0 pixel format and AAC-LC audio play directly in the application through the platform WebView. HEVC, MKV, 10-bit video, unusual audio codecs, and clips that fail WebView playback can be handed to an installed VLC or mpv player as an ordered game playlist. Pica Pica never transcodes originals or creates large compatibility copies.
For the most predictable in-app playback, configure future OBS recordings as H.264/AVC with AAC-LC audio and put the complete listening mix on audio track 1. Additional isolated AAC-LC tracks can remain in the recording for editing, but Pica Pica does not mix those tracks inside the HTML player. Install VLC or mpv when you want to play older or less compatible clips without conversion.
After upgrading an existing library to this playback model, Pica Pica automatically rescans pending compatibility rows in the background with at most four media workers. Existing thumbnails and cached file metadata are reused, database rows are updated in place, and original clips remain untouched. If FFmpeg/ffprobe is unavailable during development, pending rows are retried after the tools become available.
pnpm install
pnpm devpnpm dev opens the browser-safe demo library. To run the native application:
pnpm tauri devThe experimental Linux host runs Electron against the pica-sidecar Rust binary. Build the sidecar in an approved Linux environment, run pnpm dev in one terminal, then run pnpm electron:dev:host in another. Set PICA_PICA_SIDECAR when the binary is not at src-tauri/target/debug/pica-sidecar. The manual GitHub workflow performs the packaged build; it is the default validation path on personal development machines.
Quality checks:
pnpm check
cd src-tauri
cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --lockedBuild the desktop executable without packaging an installer:
pnpm tauri build --no-bundleThe manual Desktop Preview GitHub Actions workflow builds two unsigned test packages:
- Windows x64: NSIS setup executable (
.exe) - Linux x64: legacy Tauri AppImage (
.AppImage)
Open the repository's Actions tab, select Desktop Preview, choose Run workflow, and download the resulting artifact after both jobs finish. Preview artifacts are retained for seven days. The separate Linux Electron Preview workflow builds the same x64 Electron/Rust-sidecar package for pull-request and manual validation. Tagged previews publish it alongside the Windows installer.
Tagged versions are also published on the repository's Releases page. Preview releases remain unsigned, so Windows may display a SmartScreen warning. Release packages bundle pinned FFmpeg/ffprobe binaries for probing and thumbnails; VLC and mpv are never downloaded or bundled and must already be installed for external playback. The workflows verify fixed SHA-256 digests before packaging, include provenance records, and ship a SHA256SUMS.txt file for the finished installers. The maintainer procedure is documented in docs/releasing.md.
Download the release asset ending in .AppImage. The x64 (also called x86_64 or amd64) build supports both 64-bit Intel and AMD processors; it is not limited to AMD hardware. It does not support ARM64 devices.
Do not run the Windows .exe installer on Linux. Desktop environments can launch it through Wine, which opens the Windows NSIS setup wizard and displays Windows paths such as C:\\Users\\…; that installs the Windows build into Wine rather than installing the native Linux application.
Make the AppImage executable, then launch it:
chmod +x Pica*.AppImage
./Pica*.AppImagePica Pica reads direct subfolders of the selected root as games:
OBS Clips/
├── Overwatch 2/
│ ├── Replay 2026-07-18 21-44-03.mp4
│ └── Replay 2026-07-18 22-11-40.mp4
├── Valorant/
└── Minecraft/
The SQLite database and derived cache live in the platform-specific application data directory. This avoids modifying a clip folder that may be read-only, synchronized, or located on removable media. The selected root is persisted; original media remains untouched.
Typical cache contents:
Pica Pica app data/
├── library.sqlite
└── cache/
├── artwork/
├── external-playlists/ # temporary while an external player is managed
├── metadata/
└── thumbnails/
src/app— application composition and routingsrc/components— reusable shadcn-style UI, library, layout, and player componentssrc/features— stateful library and metadata workflowssrc/data— typed native client plus isolated browser demo adaptersrc-tauri/src/commands— narrow frontend-to-native command boundarysrc-tauri/src/library— scanning and orchestrationsrc-tauri/src/database— SQLite access and migrationssrc-tauri/src/metadata— provider abstraction and offline starter catalogsrc-tauri/src/video— FFmpeg/ffprobe adaptersrc-tauri/src/player— external VLC/mpv discovery and ordered playlist hand-off
See docs/architecture.md for design decisions and extension points. See docs/scalability.md for the large-library data flow, performance boundaries and remaining background-job work.
The offline catalog remains the zero-configuration fallback. With user-provided keys, RAWG supplies normalized game metadata and SteamGridDB supplies posters and hero artwork. Provider IDs are stored separately so either service can be replaced. Normalized metadata and downloaded artwork are cached locally for offline use.
API keys are never written to SQLite, metadata JSON or the repository. Pica Pica stores them through the operating-system credential service: Windows Credential Manager, macOS Keychain or Linux Secret Service.
RAWG and SteamGridDB have their own attribution and non-commercial-use terms. Pica Pica does not redistribute their data or artwork in its installers.
Development builds use bundled tools when present and otherwise fall back to PATH. Public installers contain checksum-verified LGPL-compatible FFmpeg builds for probing and thumbnails. See docs/ffmpeg-packaging.md.
Read CONTRIBUTING.md before opening a change. The project is free software under GPL-3.0-or-later. Contributions use the same terms.