macOS setup (.dmg)

Two disk images are published for macOS: SoundChex (the client — install it on every Mac in the house) and SoundChex Server (install it on the one machine that hosts the library). Same steps for both.

1. Download the right one

  • SoundChex.dmg — the app you browse, play and read with.
  • SoundChex Server.dmg — the host app, with start/stop/log controls for the library's background services.

Both come from the download page, which points at the latest GitHub release.

2. Install

  1. Open the .dmg — a window appears with the app and an Applications shortcut.
  2. Drag the app onto Applications. Don't run it from inside the disk image; macOS treats that as a temporary location.
  3. Eject the disk image (⌘E on the mounted volume, or the eject arrow in Finder's sidebar) and delete the .dmg if you like.

3. First launch & Gatekeeper

Expect a warning on first launch. Current releases are not yet notarized with Apple, so macOS will say the app is from an unidentified developer and offer only "Move to Trash" or "Cancel". This is Gatekeeper doing its job on an unsigned app, not a defect — and because the code is public, you can always build the same app yourself instead.

To open it anyway, either:

  • Right-click the app in Applications → Open → Open — the warning gains an "Open" button when launched this way, and macOS remembers the choice; or
  • launch it normally once, then go to System Settings → Privacy & Security, scroll to the blocked-app notice, and press Open Anyway.

Either way this is a one-time step per app; subsequent launches are normal. Signed and notarized releases are on the roadmap, and this page will drop this section the day they ship.

4. After installing

SoundChex (the client)

The connect screen asks for your server's address — a LAN address like http://192.168.1.20:8000, a tailnet name, or a tunnel hostname (Remote access). The interface is served by your server, so the app keeps itself current; the binary only carries the connect screen and the offline shell.

SoundChex Server (the host app)

Runs on the machine that holds the library and gives the background services a face — the queue and scheduler workers can be started, stopped and inspected without a terminal (the same controls as Admin → Services, which is launchd-based and macOS-only). The server itself is the PHP application described in Install on macOS.

Updating

Download the new .dmg and drag the app to Applications again — replacing the old one is the whole update. Day to day this is rare: the served interface updates the moment the server does. Watch the repository (Watch → Custom → Releases) to hear when a new shell ships.

Uninstalling

Drag the app to the Trash. Your library, catalogue and settings live with the server, not in the client app — removing a client loses nothing but its saved connection.