FolioSpace Library is an optional self-hosted personal digital asset catalog. It runs with Docker/Compose on a Mac, Windows or Linux computer, or a compatible NAS. It provides a unified indexing layer and client API for books, comics, PDFs, user-owned game libraries, videos, and future spatial media clients.
It is not a cloud media service and does not distribute games, ROMs, BIOS files, firmware, books, comics, movies, or third-party content catalogs. It indexes user-owned local files and exposes stable service URLs to web and native clients without leaking real host paths.
FolioSpace is optional for SpatialEMU. SpatialEMU can open supported local files directly without a FolioSpace server. A NAS and coding are not required; you need Docker, one or more media folders, the FolioSpace service URL, and an access token created during first-run web setup.
The SpatialEMU macOS app is a client, not the FolioSpace server. FolioSpace Library currently runs from this published Linux AMD64/ARM64 Docker image.
The published Compose default is port 8080. Leave FOLIOSPACE_API_TOKEN empty for the beginner path, open the web setup page, create a token with at least 8 characters, select a mounted container path such as /games, then enter the service URL and the same token in SpatialEMU and select Connect.
Reuse existing audited MAME launch profiles across core versions when official listxml evidence proves the complete ROM/dependency definition is unchanged. Exact profiles remain preferred.
Includes 1,889 content definitions for 631 sets across MAME 0.287, 0.288, and 0.289, plus the foliospace-mame-content-registry administrator tool. No ROMs, BIOS files, or private catalog records are included.
Cross-version responses echo the client runtime and expose contentAudit provenance; source file checksums and dependencies are verified. Different definitions require a fresh audit.
Existing custom evidence files remain authoritative and are not overwritten. The bundled defaults apply only when no custom registry is installed. See the upgrade notes.
Preserves the 1.00 FBNeo hotfix: supported official clients are not blocked just because their App fingerprint or coreBuildId changes.
Keeps CIA installation, resumable downloads, and bilingual beginner setup. Available as funland/foliospace-library:1.01 and latest for Linux AMD64 and ARM64.
Release 1.00 makes the optional SpatialEMU + FolioSpace workflow approachable on ordinary Docker hosts.
SpatialEMU can open supported local files without FolioSpace; FolioSpace remains an optional self-hosted catalog and sync service.
Mac, Windows, Linux, and compatible NAS hosts share one Compose path. A NAS and coding are not required.
First-run Web setup explains the required storage folders, service URL, token, and SpatialEMU connection steps before showing advanced catalog policy.
English and Simplified Chinese setup guidance link separately to the connection guide and FolioSpace product overview.
Existing 0.998 CIA installation, Range delivery, and game compatibility behavior remain unchanged. Service, Client API, Web, and source MCP metadata report version 1.00.
0.998 Release: Resumable Nintendo 3DS CIA Installation
Release 0.998 adds an explicit client-side Nintendo 3DS CIA installation contract.
CIA catalog and manifest responses identify install content consistently and include original filename, byte size, SHA-1, and authenticated download routes.
Apple clients advertise cia-install-v1 before requesting the dedicated installation action; unsupported clients receive a stable diagnostic instead of a missing launch profile.
CIA downloads preserve byte ranges for interrupted-transfer recovery. Azahar performs final signature, encryption, title identity, and base/update/DLC validation.
Malformed or truncated CIA header/section layouts are rejected during scanning, while .3ds, .cci, and .cxi launch behavior remains unchanged.
Existing FBNeo compatibility fixes from 0.997 remain included. Service, Client API, Web, and source MCP metadata report version 0.998.
0.997 Release: Stable FBNeo Coverage and Historical ROM Compatibility
Release 0.997 restores stable Apple default FBNeo target coverage while keeping runtime and ROM validation strict.
Hotfix: FBNeo coreSha256 and coreBuildId values are diagnostic only for supported official Windows, macOS, iOS, iPadOS, visionOS, tvOS, and Android clients, and no longer gate an otherwise approved launch profile.
FBNeo approval still requires the exact client/platform/architecture, libretro/fbneo route, ROM profile, and complete dependency closure. MAME content-set matching and Android Flycast identity rules are unchanged.
Historical member filenames are accepted when their exact size and CRC match the installed FBNeo DAT.
The field-proven Captain Commando ioc1.ic7 PLD variant (279 bytes, CRC 0d182081) is accepted only for the captcomm set; unrelated or damaged content remains blocked.
Default FBNeo rebuilds cover stable SpatialEMU iOS, iPadOS, and visionOS core identities plus the approved Windows target instead of producing Windows-only profiles.
Deployment-supplied target documents remain authoritative for client/platform coverage, including legacy tvOS targets.
Android keeps its existing manifest-first, pinned-DAT FBNeo flow. Android Flycast/NAOMI and MAME launch policies are unchanged.
The FBNeo runtime-identity hotfix needs only a server image update and no catalog re-analysis. Deployments with partial FBNeo profiles should still run Analyze Catalog once after checking their target document. Service, Client API, Web, and source MCP metadata report version 0.997.
0.996 Release: Audited Point Blank Launch Support
Release 0.996 adds strict FBNeo launch profiles for Point Blank on SpatialEMU Apple clients.
Exact ptblank and ptblanka fingerprints route to FBNeo on iOS, iPadOS, and visionOS.
Stable packaged-core coreBuildId identities replace whole-application fingerprints for these profiles; unknown builds remain rejected and approved legacy SHA-256 profiles continue to work.
ptblank resolves with namcoc75.zip; ptblanka resolves with its parent ptblank.zip and namcoc75.zip.
namcoc75.zip is hidden from client game directories as a dependency while remaining available to audited manifests.
Existing Client API routes remain backward compatible. Service, Client API, Web, and source MCP metadata report version 0.996.
0.995 Release: Safe Native Delivery and Targeted Curation
Release 0.995 expands safe native game delivery, compatibility curation, and offline access.
Nintendo 3DS libraries validate direct .3ds/.cci NCSD images, .cxi NCCH images, and safe single-image ZIP packages before indexing. Launchable images stream as their original inner bytes, while .cia packages are explicitly marked for client-side installation.
ZIP-backed game downloads support single-range requests even when the inner archive stream is not seekable, enabling resumable Nintendo DS, Nintendo 3DS, and other validated single-ROM downloads.
Game Curation can rebuild FBNeo or MAME compatibility for one game without deleting unrelated profiles. The MAME audit includes a fingerprint-pinned exception for the verified Time Crisis package that embeds its exact namcoc71 device ROM, without rewriting the ZIP.
Android ARM64 launch resolution accepts the pinned Flycast v4 runtime identity for Dreamcast, NAOMI, Atomiswave, and audited NAOMI 2 packages. Split NAOMI 2 sets require their checksummed parent ZIP, while user-managed firmware is not injected into Android manifests.
Book manifests expose a byte-exact authenticated download URL with HTTP Range and HEAD support for offline reading.
The Client Home API can omit collection expansion for faster first-screen loading, and scans skip _maintenance directories by default.
Existing Client API routes remain backward compatible. Service, Client API, Web, and source MCP metadata report version 0.995.
0.994 Release: Offline Identity and Expanded Game Delivery
Release 0.994 expands native game delivery and adds stable offline identity for books and comics.
Nintendo DS .nds files and supported single-ROM ZIP packages are indexed as canonical nds games, matched against Nintendo DS artwork, and negotiated only with the exact melonds-ds core on supported physical Apple clients.
3DO .cue, .iso, and .chd images are indexed as canonical 3do games. CUE manifests preserve every referenced track, exclude BIOS files from the public catalog, and require an Opera-compatible client runtime.
Konami Python 1 .py1 descriptors are indexed as one game with their seven validated relative dependencies, complete file checksums, and an explicit pcsx2-reliquary launch contract.
PC-98 mixed packages containing USER.FDI plus CUE/BIN CD media are published as one launchable game with a complete ordered manifest instead of separate or missing entries.
Audited NAOMI Project Justice revisions preserve canonical clone and parent identities, while Atomiswave manifests include the shared awbios.zip dependency when required.
Game file downloads support HTTP Range requests, enabling resumable downloads and large-image streaming without restarting from byte zero.
Book, EPUB, PDF, CBZ, and ZIP DTOs add nullable contentHash, contentHashAlgorithm, fileSize, and contentRevision fields. A serialized background worker computes full-file SHA-256 values without blocking list or manifest requests and invalidates them when source bytes or page manifests change.
Existing Client API routes remain backward compatible. Service, Client API, Web, and MCP metadata report version 0.994.
0.993 Release: Virtual Boy and Dynamic Platform Catalog
Release 0.993 adds Nintendo Virtual Boy support and removes the need for clients to hard-code game-platform filters.
Virtual Boy .vb and .vboy ROMs are indexed with canonical virtualboy metadata and existing client-safe manifests.
Local boxart artwork uses normalized filename matching and takes priority over cached network artwork.
The authenticated /api/client/games/platforms endpoint publishes stable platform IDs, display titles, aliases, counts, and availability.
/api/client/info advertises gamePlatformCatalog; older integrations can continue using /api/client/games/facets.
MCP adds foliospace.get_game_platform_catalog for agents that need the complete server-owned platform catalog.
Existing Client API response shapes remain backward compatible. Service, Client API, Web, and MCP metadata report version 0.993.
0.992 Release: Manifest Stability and Progressive Loading
Release 0.992 stabilizes game delivery and reduces startup work on large self-hosted libraries.
Manifest-first game delivery remains the compatible default for existing and mobile clients; launch-profile resolution is explicitly capability-gated.
Arcade manifests include audited parent, BIOS, device, QSound, and Capcom ZN dependencies when required.
ZIP contents take precedence over filename guesses, preventing cartridge ROMs inside ZIP archives from being published as similarly named CPS/MAME sets.
Self-contained MAME clones can satisfy merged parent ROM requirements from their own archive.
Game searches prioritize launchable entries over same-name records that still require curation.
The Game Curation Center batches status queries, eliminating per-item SQLite reads on large pages.
The web home screen progressively loads first-screen sections, pages collections, defers maintenance data, and polls only active scan state.
Existing Client API response shapes remain backward compatible. Service, Client API, Web, and MCP metadata report version 0.992.
Release 0.990 adds a complete game-library preparation workflow for new and existing self-hosted installations.
The new Game Curation Center separates published games, dependencies, and records that still need attention.
Automatic post-scan analysis is enabled by default for fresh installations and can be configured from the web UI.
Compatibility analysis rebuilds audited FBNeo/MAME launch profiles from administrator-supplied policy files without modifying source ROMs.
Only launchable records are published to native clients; incomplete archives and unresolved dependencies remain visible to administrators as needs-curation.
Background analysis, artwork, and metadata tasks are bounded, observable, and protected against duplicate concurrent runs.
Batch artwork matching supports local sidecars, cover folders, media/<ROM name>/boxFront.*, and optional Libretro fallback.
Web metadata editing covers titles, descriptions, genres, developers, publishers, dates, regions, and explicit source selection.
Optional Hasheous lookup is hash-based and opt-in. Local-only operation remains the default, and metadata outages never block scanning.
First-run setup includes game-catalog automation and advanced FBNeo/MAME/runtime policy paths.
Service, Client API, Web, and MCP metadata report version 0.990.
Release 0.982 makes audited arcade launch profiles durable and rebuildable for existing libraries.
Audited profiles and their complete entry/dependency closure are persisted in SQLite.
The explicit foliospace-rebuild-launch-profiles command validates existing FBNeo ZIP sets against a deployment-supplied official Arcade DAT without rescanning or rewriting ROM files.
It also supports an official MAME 0.288 listxml audit for selected platforms. Model 2 archives are matched by ZIP stem and promoted only when their complete parent, device, and BIOS closure validates.
Every published FBNeo game passes logical ROM name, uncompressed size, CRC, and parent/BIOS dependency checks.
Windows FBNeo profiles require the exact approved core SHA-256; unknown or mismatched cores return 409 runtime-profile-not-available.
Deployment-supplied target files can publish the same audited FBNeo closure to Apple physical-device builds using their exact reported core SHA-256, while mobile MAME 0.287 and Windows MAME 0.288 profiles remain separate.
SFC/SNES profile negotiation recognizes Libretro bsnes alongside Snes9x and Mesen-S.
Client lists, facets, search, and played shelves hide dependency and needs-curation records instead of advertising games that cannot launch.
Existing users do not need to rescan their game libraries. Only missing hashes or rejected ROM sets need a targeted rescan or repair.
Service, Client API, and MCP source metadata report version 0.982.
The official FBNeo Arcade DAT is intentionally not bundled. Place it at /config/policies/fbneo-arcade.dat, then run once after upgrading:
Release 0.981 adds launch-profile negotiation without forcing every ordinary console game into a per-runtime audit table.
POST /api/client/games/{gameId}/resolve matches the authoritative client/runtime inventory against a validated canonical manifest.
Ordinary console platforms reuse existing single-file and multi-file manifests. Known Libretro platform/core combinations do not require a per-build core hash.
Curated DOS packages preserve the archive download plus their safe inner executable, arguments, working directory, and launch candidates. Unknown DOS entries still return a profile conflict.
Windows runtime versions such as PCSX2 2.6.3.0 and DOSBox Staging 0.82.2.0 are normalized only for policy matching; the successful response echoes the exact selected request tuple.
Virtua Striker resolves its required segabill.zip dependency for Windows MAME 0.288.
Tekken Tag Tournament can receive the compatible logical entry name without renaming or rewriting the physical ROM archive.
CPS1, CPS2, and CPS3 are exposed as separate canonical platforms. Audited sf2, sfa, and sfiii profiles match the exact packaged FBNeo core SHA-256.
MAME 0.288 profiles now cover six audited Mahjong sets. mcnpshnt receives the required logical ym2413.zip dependency without renaming ym2413_instruments.zip on disk.
Responses include profile revision, exact selected runtime identity, logical filenames, available checksums, and complete dependency closure.
Unsupported runtime combinations return an explicit 409 runtime-profile-not-available; the server never substitutes the closest or newest MAME set.
The legacy game manifest remains unchanged for existing clients.
MCP adds foliospace.resolve_game_launch_profile for trusted agent integrations.
Service, Client API, and MCP metadata report version 0.981.
0.98 Release: Expanded Platforms and Curated DOS Launches
Release 0.98 expands the game catalog while keeping launch details stable for native clients.
PSP, Nintendo GameCube, and PlayStation 2 files receive canonical platform metadata and web/API filters.
NAOMI 2 filtering now remains distinct from adjacent arcade platforms.
MCP adds foliospace.list_game_platforms, using full-library facets and launchable-item counts.
Curated DOS collections can read games.json metadata, match covers, index archive packages, and expose executable launch commands and working directories.
DOS manifests preserve archive-relative paths so clients can extract a package and start the intended executable reliably.
Service, Client API, Web, and MCP metadata report version 0.98.
Release 0.978 adds profile-scoped game play-time synchronization for GameEMU and other native clients.
Clients report cumulative active emulation time through idempotent launch-session heartbeats, so retries and out-of-order reports never double-count time.
GET and PUT /api/client/games/{gameId}/play-stats provide total play seconds, launch count, and first/last played timestamps.
GET /api/client/games/played provides a profile-scoped, paginated played-game catalog for recent activity and play-time dashboards.
MCP adds foliospace.get_game_play_stats and foliospace.report_game_play_session for trusted local agents.
MCP also provides foliospace.list_played_games for aggregate game-history queries without one request per game.
/api/client/info advertises gamePlayStats: true for capability detection.
Service and MCP metadata report version 0.978.
0.977 Release: Expanded Console and Arcade ROM Support
Release 0.977 adds canonical scanning, filtering, artwork, and complete launch manifests for six additional platforms.
Dreamcast GDI/CDI/CHD packages retain every required track under one launchable game.
Sega Saturn CUE/BIN and ISO games are counted by disc rather than by physical track file.
NEC PC-FX supports CUE, CCD, TOC, CHD, M3U, multi-disc grouping, Pegasus metadata, and local cover folders.
Nintendo 64 validates .z64, .v64, and .n64 byte order and can stream the raw ROM from a supported single-ROM ZIP.
NEC PC-98 adds validated floppy/hard-disk formats, CP932 title decoding, duplicate merging, multi-disk manifests, and artwork sidecars.
Sega Model 2 preserves MAME ZIP shortnames and bytes, adds friendly titles and compatibility states, and keeps BIOS dependencies outside ordinary platform counts.
Client API facets, manifests, MCP tools, web filters, and authenticated downloads use stable canonical platform metadata.
Service and MCP metadata now report version 0.977.
Release 0.969 improves scan results for PDF-heavy libraries and mixed folders that contain generated artwork.
PDF scans now read lightweight embedded Info metadata when available, mapping title, author, and subject to FolioSpace title, creator, and description fields.
Libraries can define scan exclude directories from the web UI, API, or MCP.
The scanner skips common generated folders such as media, thumbnails, covers, __MACOSX, and @eaDir, preventing artwork and sidecar folders from being indexed as books.
Service and MCP metadata now report version 0.969.