Storage
How storage detection, automatic updates, and the app data directory work.
Storage Modes
Replay Control reads the storage mode from the RePlayOS configuration and adapts accordingly:
| Mode | Description |
|---|---|
| SD card | Default storage on the RePlayOS SD card |
| USB | Most common for large collections (USB drive) |
| NVMe | Pi 5 PCIe NVMe support |
| NFS | Network share from a desktop or NAS |
The storage mode can be changed in the RePlayOS configuration. When the mode changes, the app detects it automatically and refreshes the library.
Automatic Library Updates
On local storage (SD, USB, NVMe), the app monitors the roms/ directory for changes. New, modified, or deleted ROMs trigger an automatic library update for the affected system.
On NFS, automatic detection is not available (filesystem notifications do not work across network mounts). Use the “Rescan Game Library” button to reconcile the library to current disk state after external changes.
Storage Change Detection
The app monitors the RePlayOS configuration file for changes. When the storage mode or path changes:
- The library is refreshed automatically
- All connected browsers are notified and reload to reflect the new state
This also applies to skin/theme changes, which are pushed to all browsers instantly.
If the configured storage target cannot be activated (for example NVMe is selected but no NVMe drive is mounted), Replay Control keeps the last successfully opened storage online when one exists and shows a storage-status banner. The banner names the configured target, the fallback storage if available, and tells the user to insert the device or change the selection in RePlayOS settings. Read-only browsing remains available on the fallback storage, but launch, rebuild/rescan, upload, rename/delete, metadata refresh, media downloads, favorites, and other storage-scoped mutations are blocked until the configured storage is ready. On first boot with no usable storage, the /waiting page shows the same configured-storage problem instead of silently waiting on an unspecified device.
If RePlayOS temporarily reports a lower-priority fallback storage while the previous local storage is still readable, Replay Control keeps the previous storage online and blocks storage-scoped mutations. This prevents accidental rescans or launches against the SD card when the intended USB or NVMe storage is still the user’s active library. NFS outage recovery does not probe the stale share because hard-mounted NFS reads can block.
Long-running startup scans, manual rescans/rebuilds, and ROM-watcher scans are tied to the storage generation that was active when they started. A storage swap or transition into a configured-storage error cancels stale scan work before it writes the next system, preventing fallback or old-storage scan results from landing after the active storage state has changed.
Filesystem Adaptation
The app automatically adapts its database configuration to the underlying filesystem:
- POSIX-capable filesystems (ext4, btrfs, xfs) – optimized for concurrent access
- exFAT/FAT32 (common on USB drives) – adapted for filesystem limitations
- NFS – adapted for network storage constraints
No user configuration is needed.
Corruption Recovery
If the library database becomes corrupted (e.g., due to unexpected power loss), the app detects it at runtime and shows a recovery banner:
- Library database – can be fully rebuilt from the ROM files (no data loss)
- User data database – restored from automatic backups taken at each healthy startup
App Data Directory
The app stores its data in .replay-control/ on the ROM storage device, separate from the RePlayOS configuration. This directory contains:
- Library database – game library index, imported metadata, thumbnail index (rebuildable)
- User data database – box art overrides, saved videos (persistent)
- Settings – region preference, font size, skin override
- Media – downloaded box art, screenshots, and title screen images
This data travels with the ROM collection if you move the storage device to another Pi.
Config Boundary
Two configuration files serve different purposes:
- RePlayOS config (on the SD card) – system-level settings (Wi-Fi, NFS, storage mode, skin). Managed by RePlayOS and read by the app. Lives only on the SD card regardless of ROM storage location.
- App settings (on ROM storage) – app-specific preferences (region, language, font size). Travels with the ROM collection.