Demo Video

Demo Video

Narrated MP4 demos of real HMIS screens. Playwright drives the running app through the menus only, an injected overlay adds a cursor, click highlights and captions, edge-tts voices each step, and ffmpeg mixes it all. Everything comes from a script, so when the UI changes you re-run the video instead of re-recording it.

Works on both Windows and Linux (verified on Ubuntu). See the Linux notes under Work dir and Credentials below — the only differences are the one-time pip setup and how credential paths are supplied; the recording/build/upload steps themselves are identical.

Worked examples:

• examples/pharmacy-issue-own-department/ — the first accepted video; normal case, login happens silently before narration starts.
• examples/login-department-select/ — a video about logging in itself, using manualLogin: true (see Recorder API below).
• examples/pvc-card-print/ — a video whose key moment is a print button (see Printing below).

Printing (print buttons, receipts, cards)

Chrome's print dialog is browser UI, not page content: Playwright's video never contains it, a headless recorder can't open it, and on this machine the shell can't screenshot the desktop either. Show what gets printed instead, with scripts/printcap.js:

1. await pc.install(r.page) at the start of flow. It makes print() and document.execCommand('print') (which PrimeFaces p:printer tries first) record the printed document instead of opening the dialog.
2. After clicking the print button: html = await pc.waitForPrint(page, n) (n = 1-based print count).
3. pdf = await pc.toPdf(page.context(), HMIS_BASE, html, 'x.pdf') renders that exact HTML with Chrome's print engine at the CSS @page size, then { png, pages } = pc.toPng(pdf) (needs pip install pymupdf).
4. pc.showPrinted(page, png, 'Printed front') overlays it on camera; pc.hidePrinted(page) removes it.
5. Narrate the dialog settings (printer, Margins, Scale) in a caption-only step.

Assert pages === 1 (or whatever the paper needs): the PDF is real verification, not decoration. The first take of the PVC card video exposed that every card side printed as 2 pages (#24305). If the user wants the real dialog in the video, they must screenshot it themselves (PrtScn) and you show the image as a still the same way.

Rules

• Only open the application root URL. Reach every page through the menus, exactly as a user would. If a page has no menu path, stop: the missing menu path is the finding. File an issue and fix it before recording (see CLAUDE.md Testing rules).
• Record on local or QA, never production. Everything on screen is published. Use test departments and test patients only.
• Every step of the storyline must really happen. If the flow shows "blocked by default", make setup() put the configuration back to its default in an unrecorded browser session first. Never fake a screen state.
• Look at the output before handing it over (check_frames.py). Green scripts are not proof that the video shows the right thing.

Workflow

1. Storyline. Agree the before → change → after story and the menu path with the user. Then walk the path once with plain Playwright (dump element ids, take screenshots) to find selectors and confirm every step is reachable.
2. Work dir. tmp/demo-videos/<slug>/ (gitignored). One-time setup in tmp/demo-videos/: npm init -y && npm i playwright, then NODE_OPTIONS=--dns-result-order=ipv4first npx playwright install ffmpeg, then python -m pip install edge-tts imageio-ffmpeg. The recorder launches the installed Google Chrome (channel: 'chrome'), because Playwright's own Chromium download fails on this network. Chrome must be installed; there is no npx playwright install chromium step. On Debian/Ubuntu, the plain pip install fails with externally-managed-environment (PEP 668). Use python -m pip install --user --break-system-packages edge-tts imageio-ffmpeg instead (a venv also works, but needs python3-venv installed first, which most boxes don't have by default).
3. script.json. Write one {id, say} per step, one or two short sentences each. Name menus and buttons exactly as they are labelled on screen. For a Sinhala or Tamil version, reuse the same ids and flow.js, translate only the say text, and keep the on-screen labels in English exactly as the app shows them ("Pharmacy මෙනුව විවෘත කර, Consumption ක්ලික් කරන්න"). Ask for a native speaker's review before the video goes to users.
4. Voice. Run python <skill>/scripts/tts.py [voice]. The default voice is en-GB-SoniaNeural. For Sinhala use si-LK-ThiliniNeural; for Tamil use ta-LK-SaranyaNeural.
5. flow.js. Copy the example and edit it. Each step is r.step(id) → actions → r.done(), and r.done() waits until that step's narration has finished. Add a throw wherever the result must be true (e.g. the block message appears, the screen opens), so a wrong recording fails loudly.
6. Record. Run HMIS_BASE=http://localhost:8080/rh/ DEPT="<login dept>" node flow.js. It exits non-zero if a throw fires. Don't pipe it (e.g. | tail), because the pipe hides the failure and build.py would then build a broken video.
7. Build. Run python <skill>/scripts/build.py <slug>.mp4.
8. Check. Run python <skill>/scripts/check_frames.py <slug>.mp4 and read frames/sheet.png. Every caption must match what is on screen at that moment. Fix the flow and repeat steps 6–8 until it does.
9. Deliver. Save the MP4 in tmp/demo-videos/ and report its path. Say which environment and test data appear in it.
10. Publish to YouTube (optional, only when asked). HMIS is open source and these videos go out public on the channel the token belongs to. Write youtube.json in the work dir (title of at most 100 characters, plus optional tags, privacy, language such as si/ta, playlistId and description, which defaults to the script.json narration). Run python <skill>/scripts/upload.py <slug>.mp4 --dry-run, show the user the metadata, and upload only after they confirm: python <skill>/scripts/upload.py <slug>.mp4. The script writes youtube-upload.json, which blocks a second upload of the same video unless you pass --force. Report the youtu.be link. The one-time setup is below.

YouTube publishing setup (one time)

Credentials live outside the repo in C:/Credentials/youtube/ on Windows (override with YT_CREDENTIALS_DIR). On Linux there is no default path — always set YT_CREDENTIALS_DIR (e.g. /home/<user>/Credentials/youtube). Use pip install google-api-python-client google-auth-oauthlib (add --user --break-system-packages on Debian/Ubuntu).

1. In Google Cloud Console (as the Google account that owns or manages the channel), create a project and enable YouTube Data API v3.
2. Under Google Auth Platform, create the branding: app name, support email, audience External, contact email. Accept the User Data Policy (ask the user to do this).
3. Under Audience → Test users, add the Google account. Re-open the Audience page and confirm "1 user (1 test)": the side-panel Save can silently fail to stick.
4. Under Clients → Create client → Desktop app, click Download JSON and save it as client_secret.json. The secret cannot be shown again once the dialog closes, so find the file first. Chrome may save it to a non-default Downloads folder.
5. The first upload.py run opens the consent page. Pick the Google account; for a Brand Account channel such as CareCode, pick it on the channel chooser that follows. On "Google hasn't verified this app", click Continue. The script saves token.json. While the app is in Testing mode that token lasts about 7 days, after which the consent page simply reappears.

Recorder API (r inside flow)

Environment variables: VIEW sets the window size. The default 1920x1080 is the zoom level users work at, where the whole top menu fits on one line; below about 1760 px wide it wraps to two lines. Captions scale with the width. Credentials come from HMIS_USER/HMIS_PASS, or otherwise from C:/Credentials/hmis_web_login.txt (Windows default). On Linux there is no default path — always set HMIS_USER/HMIS_PASS explicitly.

run(chromium, { setup, flow, manualLogin }): by default (manualLogin unset/false) the recorder logs in and picks DEPT silently before recording narration, and that portion is trimmed from the final video — this is right for a video about some other feature. Set manualLogin: true to skip that automatic step and have flow perform (and narrate) the login and department-selection itself, e.g. for a video that teaches login — see examples/login-department-select/. Read credentials inside flow with creds() (also exported from recorder.js), which resolves HMIS_USER/HMIS_PASS the same way the automatic login does.