Screencast Tutorial Video

Screencast Tutorial Video

Overview

This is the production half of the screencast workflow. It consumes an approved storyboard.md (from screencast-storyboard) and produces one narrated, captioned 1920x1080 MP4 that shows the real tool doing the real thing.

Everything runs natively on the macOS host, no ddev, no container. One engine per surface:

Two browser engines. Method A (browser-scene.sh) renders the page off-screen and records only the page, crisp, deterministic, no Screen-Recording permission, no cursor calibration, and nothing else on your desktop can leak into frame. Use it for almost everything. Method B (the cliclick/avfoundation split) is only for when you must show the real macOS cursor performing clicks; it captures the live screen, so it needs the permission and a clean desktop (see the privacy caution in references/browser-playwright.md).

Each scene is padded to its narration, gets a caption bar, and concatenates into final/tutorial.mp4. Every scene is independently re-renderable, change one line, re-run one script, re-concat. No timeline editing.

Requirements (hard)

• An approved storyboard.md at .tutorial-build/<slug>/storyboard.md. If it is missing, direct the user to screencast-storyboard first, do not invent one.
• macOS host with ffmpeg (a drawtext-capable build, ffmpeg-full; preflight handles this), vhs, cliclick, Node.js + Playwright, and a TTS engine: either ElevenLabs (awaz + ELEVENLABS_API_KEY, Text-to-Speech + Voices-read permissions) or OpenAI (OPENAI_API_KEY + jq). Pick with TUT_TTS=elevenlabs|openai; default is whichever key is set.
• Screen Recording permission granted to the terminal (System Settings → Privacy & Security → Screen Recording), or browser scenes capture black.

preflight.sh checks and installs all of it and reports the real state.

Helper scripts

Run every script with export TUT_SLUG=<slug> set, from the directory that holds .tutorial-build/ (the build dir is resolved relative to the working directory). To run from elsewhere, export HDIR=<absolute build dir>, the scripts and browser-scene.mjs both honor it, so scenes never land in the wrong folder. Scripts read lib.sh for shared paths and settings. For house defaults (voice, tone, resolution) a preset loads automatically, TUT_PRESET defaults to thejimbirch (the repo owner's personal preset); export TUT_PRESET=kanopi for the Kanopi kit, or TUT_PRESET=none to skip. The Kanopi kit's non-env conventions (pronunciation lexicon, intro/outro, fonts) are in presets/kanopi-brand.md. To make a preset for another brand/client, see presets/README.md.

Loaded-on-demand detail lives in references/: terminal-vhs.md, browser-playwright.md, desktop-stills.md, capture-macos.md.

Build directory

<cwd>/.tutorial-build/<slug>/
  storyboard.md            # from screencast-storyboard (input)
  assets/                  # Montserrat + Roboto Mono (preflight downloads)
  specs/NN.json            # browser-scene.sh scene spec (Method A)
  tapes/NN.tape            # normalized VHS tape (render-tape.sh writes this)
  stills/NN.png            # native-app screenshots you capture
  scenes/NN.mp4            # raw silent scene (any engine) or command card
  audio/NN.mp3             # narration (awaz/ElevenLabs or OpenAI)
  final/NN.caption.txt     # one-line caption for scene NN (empty = no bar)
  final/scene-NN.mp4       # padded + muxed + captioned
  final/tutorial.mp4       # concatenated result

NN is a zero-padded 2-digit scene number. Nothing is deleted at the end.

Scene taxonomy

intro · terminal (VHS) · desktop-still · browser-action · command-card · outro. The storyboard assigns each scene a type; map it to the engine in the table above.

Workflow

Create a todo per step.

1. Load the approved storyboard. Read .tutorial-build/<slug>/storyboard.md. If it does not exist, tell the user to run screencast-storyboard first and stop. If any scene still contains a [NEEDS: ...] marker, ask for the real value before recording that scene, do not fabricate it.

2. Preflight. export TUT_SLUG=<slug> then ./preflight.sh. Report every dependency's real state. If it exits non-zero (a required dep is missing), do not proceed and do not claim any video was produced, report the blocker.

3. Pick a voice. Run ./narrate.sh voices (lists ElevenLabs voices via awaz, or the OpenAI voice set, depending on the active engine), present the options, and ask which to use. Remember the choice as TUT_VOICE.

4. Produce each scene by type, in order. Write the one-line caption to final/NN.caption.txt first (empty file = no bar), then:

   • terminal: author a tape from templates/scene.tape, then ./render-tape.sh NN <tape>.
   • desktop-still: capture stills/NN.png, then ./still-scene.sh NN stills/NN.png <dur> [highlight].
   • browser-action, Method A (default): write a scene spec (URL + steps: scroll / highlight / wait, plus goto / click / type / submit for multi-page flows) and ./browser-scene.sh NN <spec.json>. It waits for fonts (no FOUT) and records only the page. See references/browser-playwright.md for the spec format. Method B (real on-camera cursor) only when needed: ./browser.sh start "<url>", ./record-browser.sh start NN, drive with browser.sh box + hands.sh move/click/type, ./record-browser.sh stop NN, and calibrate the box→cliclick offset once.
   • command-card: ./make-card.sh NN <seconds> "<command>".
   • intro/outro: usually a desktop-still or command-card.

5. Narrate. For each scene:

   export TUT_VOICE=<voice>          # from step 3
   ./narrate.sh NN "<narration text>"
   

   narrate.sh writes audio/NN.mp3 using the active engine (ElevenLabs via awaz, or OpenAI /v1/audio/speech). ElevenLabs extra flags pass through TUT_TTS_FLAGS (e.g. --speed, --stability); OpenAI model via TUT_OPENAI_TTS_MODEL. Pronunciation: the OpenAI instructions field (TUT_TTS_INSTRUCTIONS) is unreliable for names, if a brand/term is mispronounced, respell it phonetically in the narration text itself (e.g. write "CAN-uh-pee" for "Kanopi"). Adjust the syllable emphasis until it lands.

6. Finish each scene. ./finish-scene.sh NN for every scene. It pads the video to the narration (never trims audio to fit video), adds ~1s lead/tail silence, muxes the audio, and draws the caption bar.

7. Concatenate and present. ./concat.sh, then show the user .tutorial-build/<slug>/final/tutorial.mp4. Do not clean up. On change requests, re-produce or re-finish only the affected scenes and re-run concat.sh.

Honesty rules (hard)

• Never claim a rendered video that was not produced. Only say final/tutorial.mp4 exists after concat.sh succeeds and the file is there.
• Report real preflight failures. If preflight.sh finds a missing dependency or Screen Recording is not granted, say so plainly. Do not run the pipeline against a false green.
• Never clean up the build dir before the user is done reviewing.
• Narration syncs to video, not the reverse. finish-scene.sh pads the video to the audio; never trim the narration to fit the clip.

Common mistakes