Run it on your computer

Mock mode, in four commands

Needs macOS or Linux, uv, Node 24 and liblouis (brew install liblouis, or apt install liblouis-bin liblouis-data). On Linux the heart replays; the brain from Wikimedia Commons does not, because its image normalizes to other pixels there, so no recording of it matches (services/api/tests/recorded_png.py).

git clone https://github.com/DeepakKTS/talking-tactile.git
cd talking-tactile
make install
MOCK_META=1 make dev

The API runs on port 8000 and the web app on http://localhost:5173. Ctrl-C stops both.

Make a sheet

1. Once the API answers (the first start can take 40 s), open http://localhost:5173/author, choose fixtures/heart.png, keep the default options and press “Make a tactile sheet”.
2. Wait for “Ready for review.” (about 25 s). The “Needs you” list shows the septum, and a merge proposal shows the aortic arch.
3. Press “Mark all parts checked”, confirm, then “Publish for students”.
4. Press “Open version 1 in Explore”, then Enter or “Start exploring”: Explore says the sheet’s title and summary. Touch needs a camera over the printed sheet (the live setup below).

What mock mode cannot do

On this path a typed question says “Questions are not working right now”. Recorded answers exist only for the heart and the brain as the question eval published them (the heart with the aortic arch merged and two teacher descriptions). To get them, run make demo-sheets before MOCK_META=1 make dev, and before uploading the heart yourself: it publishes both sheets exactly as the eval did, in mock mode, in about a minute. The brain replays with grade band “6 to 8”.

make check runs every test, lint and type check, as CI does.

Live, with an iPhone

Live mode calls Muse Spark, SAM 3.1 and Muse Voice Transcribe, and costs Meta Model API credits. The Mac runs the API and serves the app to the phone over HTTPS on the local network. These steps follow README.md and docs/DEMO.md.

1. The key. Copy the example file and set MODEL_API_KEY in it. The key stays on the Mac; the browser never sees it.

   cp .env.example services/api/.env

2. A certificate for the phone. An iPhone opens the camera only on an HTTPS page. With mkcert installed and its local root made (mkcert -install), make a certificate for this Mac’s LAN address and .local name. Run it again when the LAN address changes.

   cd apps/web && npm run cert:phone

3. Trust the mkcert root on the iPhone. Send the phone the rootCA.pem file from the folder mkcert -CAROOT prints, install it as a profile, then turn on full trust for it under Settings, General, About, Certificate Trust Settings. These are mkcert’s steps for iOS, not the repository’s.
4. Check the setup. make preflight prints OK or FAIL for each check: the key file (never printed), the phone certificate, the ports, the published sheets, CI and the credits left. Fix every FAIL first.

   make preflight

5. Start the servers. make demo-live starts the API on 127.0.0.1:8000, the web app for the phone over HTTPS on port 5173 and the Gate B touch-test page on port 8443, under caffeinate -i so the Mac cannot sleep mid-call. It refuses to start while one of those ports is in use, and prints the iPhone addresses. Ctrl-C stops all three. make demo-mock does the same with no Meta calls.

   make demo-live
   caffeinate -dimsu      # in another terminal: keeps the display awake

6. Open the app on the iPhone. On the same Wi-Fi, in Safari, use the Mac’s .local name first (scutil --get LocalHostName prints it), or the address npm run cert:phone printed. Start with the device check:

   https://<your-mac>.local:5173/explore?check=1

7. Publish a sheet first. A fresh clone has no published sheets. Make one in Author on the Mac (https://localhost:5173/author, as make demo-live prints it), print it, then open it in Explore on the phone.

The phone connection guide covers the device check, printing, the mount and setting the corners.