Skip to content

getting-started.md

Latest commit

 

History

History
111 lines (77 loc) · 5.51 KB

getting-started.md

File metadata and controls

111 lines (77 loc) · 5.51 KB
Raw

Getting started

In this tutorial you capture a complete think-aloud session — voice plus clicks — and turn it into a time-aligned Markdown report. It takes about five minutes, and you need a Mac with a microphone.

You follow the same path Alice takes on her first session: she installs Testimony, explores the built-in demo app while talking, and ends with a report that shows what she said next to what she did.

1. Install Testimony

One command installs the testimony binary into ~/.local/bin — no admin rights needed — and then offers to set up two dependencies: ffmpeg, which step 2's recording needs, and a local speech-recognition engine, which step 6 relies on:

curl -fsSL https://raw.githubusercontent.com/REPPL/Testimony/main/install.sh | sh

Each prompt lists the exact replies it accepts. Answer brew when it offers ffmpeg — or local if you have no Homebrew, which is the only install option the prompt then lists — and whisperx when it offers the engine. At those two prompts, only the words the prompt lists install anything — the ffmpeg prompt also accepts local (a static build, no Homebrew), and, when you have Homebrew, the engine prompt also accepts whisper.cpp (without Homebrew it offers whisperx alone) — and any other reply, including y, skips that dependency, which matters because step 2 needs ffmpeg. The one yes/no confirmation inside the whisperx setup (installing its uv tool) is the exception: there y accepts.

The installer verifies the testimony binary against the release's published SHA256SUMS and, when an authenticated GitHub CLI (gh) is available, against its SLSA build-provenance attestation too, refusing to install whenever that verification does not confirm the build. A gh that cannot attempt the verification — not authenticated, or too old to know attestations — is told apart from a failed verification: the installer says so and proceeds on the checksum alone, exactly as it does with no gh at all. The dependencies carry weaker guarantees: the local ffmpeg build for macOS is checked against a pinned publisher key only when gpg is on your machine, and it warns you when it installs one unverified; uv and whisperx are fetched from their publishers unverified. The installer also tells you if ~/.local/bin still needs adding to your PATH.

Check the install:

testimony version

2. Start a capture session

testimony record -demo

One command creates a fresh session directory (for example sessions/2026-07-17_174858), starts recording your microphone into that directory, serves a small instrumented settings app, and prints the URL to open — the exact commands for the next steps print once you stop the session (step 5). The first run asks for Microphone permission — grant it in System Settings and run the command again. Keep this terminal open: it records your voice and captures your clicks for the whole session.

If you would rather not capture the microphone, run testimony demo instead, record your voice separately in QuickTime Player, save the file, and pass it to transcribe in step 6 with -audio ~/Desktop/session.m4a. Everything else is the same.

3. Say the start marker

Say "session start" aloud. Recording is already running, so this spoken marker lands in the transcript and helps verify the clocks line up.

4. Explore and think aloud

Open the printed URL (http://localhost:8737) in your browser and work through the settings app while saying what you think, expect, and notice — out loud, continuously.

Alice changes the display name to "Alice", clicks Save, and says what she observes. The demo app contains at least one intentional usability flaw; find it by talking.

5. Stop the session

In the terminal, press Ctrl+C. The recorder finalises audio.wav, the capture server stops, and the exact next commands are printed with the real session directory.

6. Transcribe the recording

Point transcribe at the session directory — no audio file to name, because the recording is already in the session as audio.wav:

testimony transcribe -session sessions/2026-07-17_174858

This runs speech recognition locally on your machine — using the WhisperX engine you installed in step 1 — and writes transcript.jsonl into the session directory. It also prints the clock offset it uses to align the recording with the session — note it, and see how alignment works if it ever looks wrong.

7. Merge speech and clicks

testimony merge -session sessions/2026-07-17_174858

This interleaves the transcript with the captured interactions into a single timeline.jsonl.

8. Generate and read the report

testimony report -session sessions/2026-07-17_174858
open sessions/2026-07-17_174858/report.md

The report pairs each utterance with the interface events around it:

**[00:22] P1:** “Hm. I clicked save and nothing happened. No message, no
spinner. I can't actually tell if it saved.”
  - [00:24] click `[data-testid=save-btn]` "Save" (#general)

That is a complete session: what Alice said, aligned with what she did, on the record.

Where next