SpaceMaker

Local backup, convert, and gallery for phone media — a desktop app that keeps your library on your PC and uses your Wi‑Fi network for phone uploads, downloads, and browsing.

SpaceMaker runs as a local desktop application (embedded web UI + FastAPI server). Your photos and videos stay under a library folder you choose; optional LAN URLs and QR codes let phones on the same network upload, download, or open the gallery without cloud services.

Features

Home hub

Four modules from one screen — only one Wi‑Fi session at a time:

• Photo backup — minimal flow: scan a QR code, files land in your library, convert runs as they arrive, open the gallery when ready.
• USB photo backup — full Extract → Convert → Visualize wizard with Wi‑Fi or ADB (cable) and Copy/Move modes.
• Receive files — send arbitrary files from phone to PC into ~/Documents/SpaceMaker/.
• Send files — pick files or folders on the desktop; phone downloads via QR.

Backup & convert

• Pull media from Wi‑Fi upload or ADB into originals/.
• Convert to web-friendly outputs: images toward AVIF, video via hardware AV1 or H.264 when available (see conversion policy).
• Library layout: originals/, converted/, error/ (encode failed after retry), invalid/ (unsupported or broken inputs).
• Review and recover problem files from the wizard or Easy-mode warnings.

Gallery

• Browse converted media only — timeline or calendar, lazy thumbnails, item pages with metadata.
• LAN URL + QR so phones on the same network can open a mobile gallery shell.
• Export-friendly downloads (e.g. JPEG/MP4) on demand from item pages.

Portable releases

• Linux: primary artifact is an AppImage (relocatable runtime + Qt WebEngine).
• First run: pinned third-party CLIs (FFmpeg, ImageMagick, adb, exiftool, …) are downloaded into your user data folder — not bundled inside the binary. Settings shows status; Continue on the setup screen (or SPACEMAKER_DEV=1 for contributors) allows system PATH fallbacks.
• Windows / macOS: optional PyInstaller onefile builds — see packaging/README.md.

Details: specs/packaging/SPEC.md, tools/README.md.

Getting started

Download

Grab the build for your OS from GitHub Releases: Linux SpaceMaker-*-x86_64.AppImage, Windows SpaceMaker.exe, macOS SpaceMaker-*-arm64.dmg (Apple Silicon) or -x86_64.dmg (Intel). Builds are unsigned: Windows SmartScreen and macOS Gatekeeper will warn on first launch (macOS: right-click → Open).

Linux (AppImage)

1. Download the latest SpaceMaker-*-*.AppImage and SHA256SUMS from this repository’s GitHub Releases page (CI publishes all platforms on version tags v* — see .github/workflows/release.yml).
2. Verify the checksum, then chmod +x SpaceMaker-*.AppImage and run it.
3. Complete Setting up components on first launch (downloads into your data folder), or install tools yourself and choose Continue.
4. Pick a module on Home and follow on-screen QR / wizard steps.

Build your own AppImage: packaging/README.md (uv run task build-appimage).

From source (quick try)

Requires uv and Python ≥ 3.11:

uv run task sync-dev
uv run task spacemaker

Use SPACEMAKER_DEV=1 if you rely on system-installed FFmpeg/adb/etc. instead of downloaded copies.

Privacy & legal

SpaceMaker is local-first: media and library paths stay on your machine; LAN access is for devices on your network you choose to connect.

• Privacy
• Third-party tools
• Disclaimer

In-app: About & Legal in the footer.

Development

Prerequisites

• uv
• Python ≥ 3.11 (managed by uv)
• Node.js + npm (Biome checks for wireframes and static UI)

Setup and run

uv run task sync-dev          # install Python + dev dependencies
npm ci                        # clean install from package-lock.json (Biome, TypeScript)
uv run task spacemaker        # desktop (pywebview + local server)
uv run task spacemaker-server # API/UI in browser only (no file picker)

After editing web/src/*.ts, rebuild the static JS with npm run build:web.

Contributor tool resolution: set SPACEMAKER_DEV=1, or override the managed folder with SPACEMAKER_TOOLS_DIR. See tools/README.md.

On first launch the app downloads pinned CLIs into your user data folder unless dev/PATH rules apply. See specs/packaging/SPEC.md.

Quality gate

uv run task checks
uv run task checks -- --fix    # auto-fix where supported
npm ci && npm run check        # Biome (JS/HTML in wireframes + static UI)

Release build (Linux)

uv run task build-appimage     # dist/SpaceMaker-<version>-<arch>.AppImage + SHA256SUMS
uv run task build-installer    # Linux AppDir only (no squashfs pack)

README screenshot

After changing the Home hub UI, refresh the committed hero image:

uv run task readme-screenshot  # writes docs/assets/readme-home.png

Uses an isolated temp profile and offscreen Qt WebEngine (same 1200×900 viewport as the desktop window). If capture fails, try QT_QPA_PLATFORM=xcb.

Project layout & conventions

• docs/ARCHITECTURE.md — hexagonal layers and runtime flow
• AGENTS.md — spec-driven development, phase gates, agent workflow
• specs/ — feature specifications and acceptance criteria
• uv run task docs-serve — browsable docs site (architecture, testing conventions) at http://127.0.0.1:8000
• codenav MCP — Python navigation via ty (symbol search, definition, references; name-based symbol_info / outline / callers / implementations)
• webnav-ts-mcp MCP (TypeScript; own repo) — JS/TS/HTML/CSS navigation for web/src/ + static/ + wireframes/ (same tool shape incl. callers / implementations; plus css_var / selector for cross-file CSS)
• jevmem MCP (long-term memory, PyPI package run with uvx) — dated facts that stay true (decisions with reasons, bug causes, gotchas, preferences) via memory_write / memory_recall; notes live outside the repo. Setup once per machine: uvx jevmem config init --api-key "..." writes ~/.jevmem/config.jsonc (key and optional db path; never committed), so .mcp.json carries no env block. Notes default to scope project:spacemaker (derived from the git repo name); pass scope="global" for personal preferences that apply everywhere.
  • jevmem stores notes for decisions with their reason, bug causes and fixes, gotchas and explicit preferences, written as facts with dates
  • Rules go in AGENTS.md. That file is always loaded, so a rule there is never missed; a rule in jevmem would only appear if recall happened to surface it
  • Current state (focus, next steps) goes in memory/ (activeContext.md, progress.md). jevmem rejects notes that read like work status, since they go stale silently
• smart-commit-guard — pre-commit + commit-msg + CI secret scan (tracked .githooks/; activate once per clone with git config core.hooksPath .githooks)
• Deep reference: docs/agent-tooling.md; when to use them: AGENTS.md "Orient before editing"

License

MIT — see pyproject.toml.