Cogential--frametanium/README.md

Frametanium for the Steam Frame

Installs and updates Steam Frame apps and ports straight from their GitHub releases, like Obtainium: add any repo, and Frametanium keeps it up to date. Works from the headset or a browser.

• Add any GitHub repo by typing owner/name (or pasting a link) on the headset's on-screen keyboard, from the browser page, or by picking a suggestion made for the Frame. The built-in ports (Ship of Harkinian, 2 Ship 2 Harkinian, Starship, Lighthouse, OpenCE) are there from the start.
• Discover new Frame apps: every 12 hours (or on demand) it searches GitHub for Steam Frame projects (the steam-frame topic, "steam frame" in names and descriptions, and the community's awesome-steam-frame list) and shows the ones whose latest release has a download it can install, with ones you haven't seen marked New. Pick one to look at and add it, or hide it. Without a GitHub token, GitHub allows 60 lookups an hour, so each search checks a batch (keeping some for update checks) and the next search carries on; results are cached and only rechecked when a repo changes.
• Picks the right download: ARM64 Linux builds (aarch64/arm64, "steamframe"); checksums, Windows, macOS, Android and x86 files are passed over. You can choose another one when adding. Zips, tarballs (gz/xz/bz2/zst), AppImages and single programs all work.
• Two ways to install, picked from the download unless you choose:
  • Library app: unpacked into ~/devkit-game/<name>, given a run.sh (its own, or one that starts the ARM64 program it finds), added to the Steam library with art (the repo's GitHub card, and the project's icon or the owner's avatar), fetched when it's installed.
  • Its installer: when the download has install.sh (or contrib/install.sh, setup.sh), it's unpacked into ~/.local/share/frametanium/apps/<id> and that script runs, for tools such as SteamVR overlays. Removing the app runs its uninstaller when it has one.
• Install, update, update all, or pick any version. Pre-releases are skipped unless you turn them on for an app (they're on for apps that only have pre-releases).
• Keeps your stuff: saves live outside the install folder, ROMs placed next to run.sh are carried over, and the previous install is kept for a one-step rollback.
• Won't touch an app that's running. Only add apps you trust: their programs and installers run as your user.

Use it

• In the headset: open Frametanium in the library. D-pad to choose, A open an app (install/update, versions, previous version, pre-releases, remove), Y add an app, X discover new apps, Select update all, Start check for updates, B back/close.
• From a phone or PC: http://<frame-ip>:8643 (add apps, edit name/install style/program, remove).

Updates are checked every 6 hours and on demand.

Frametanium updates itself: it's in its own list. Updating it downloads its latest release, reinstalls the service and the headset app, and restarts the service a few seconds later (reopen the headset app to get the new one).

Files

• catalog.json: the built-in ports.
• suggestions.json: apps offered on the Add screen.
• ~/.config/frametanium/discover.json: discovered projects you've seen or hidden; ~/.cache/frametanium/discover.json caches what each search found.
• ~/.config/frametanium/catalog.json on the Frame: the apps you added and changes to built-in ones ({"id": "soh", "hidden": true} hides one; adding its repo again brings it back).
• ~/.config/frametanium/installed.json: installed versions.

Private repos

GitHub only shows releases of private repos to signed-in users. Either make the port repos public (they contain no ROMs), or save a token in the web page's Settings: a fine-grained token limited to those repos with read-only Contents access is enough. It's stored in ~/.config/frametanium/config.json (mode 600) and never sent back to the page.

Install

On the Frame: download frametanium-steam-frame-arm64.tar.gz from the latest release, unpack it and run sh install.sh. It installs the service and adds the Frametanium app to the library.

Or from a computer that can SSH into the Frame:

app/build-arm64.sh       # cross-compiles the headset app into dist/app
./deploy.sh [host]       # host defaults to frame.local

Releases: push a tag v*; .github/workflows/release.yml builds the headset app on an ARM64 runner and publishes the bundle (tools/bundle.sh). Uninstall: systemctl --user disable --now frametanium.service and remove Frametanium from the library.

Notes

• The service listens on port 8643 on your network. Set password in ~/.config/frametanium/config.json to require one in the browser (the headset app connects locally and doesn't need it).
• Standard-library Python only. The headset app is C + SDL2 with the public-domain font8x8.
• Testing on another architecture: FRAMETANIUM_EXEC_WRAPPER=qemu-aarch64-static (with QEMU_LD_PREFIX) runs ARM64 AppImages for unpacking; FRAMETANIUM_GAMES changes the install folder.