# Screen reader demo

A self contained web page that explains screen readers to a sighted audience. Built for the talk on 2 May 2026. Uses page two of `BJJ-2025-1271.R1_NO_ALT.pdf` as the test document.

## What is in this folder

```
screen-reader-demo/
  index.html                               The demo page. Open this in a browser.
  README.md                                This file.
  img/
    prisma-page.png                        Page two of the BJJ paper, the PRISMA flow figure.
    forest-plot-page.png                   Page three of the BJJ paper, the forest plot table.
  audio/
    00-intro.wav                           Screen reader introduces itself.

    Figure read (Part three):
    01-inaccessible-figure.wav             Realistic, 240 wpm.
    01-inaccessible-figure-slow.wav        Slower, 210 wpm.
    02-accessible-figure.wav               Realistic, 240 wpm.
    02-accessible-figure-slow.wav          Slower, 210 wpm.

    Table read (Part four):
    03-inaccessible-table.wav              Realistic, 240 wpm.
    03-inaccessible-table-slow.wav         Slower, 210 wpm.
    04-accessible-table.wav                Realistic, 240 wpm.
    04-accessible-table-slow.wav           Slower, 210 wpm.

    Wall of text vs structured headings (Part five):
    05-inaccessible-wall.wav               Realistic, 240 wpm.
    05-inaccessible-wall-slow.wav          Slower, 210 wpm.
    06-accessible-headings.wav             Realistic, 240 wpm.
    06-accessible-headings-slow.wav        Slower, 210 wpm.

    Generic vs descriptive links (Part six):
    07-inaccessible-links.wav              Realistic, 240 wpm.
    07-inaccessible-links-slow.wav         Slower, 210 wpm.
    08-accessible-links.wav                Realistic, 240 wpm.
    08-accessible-links-slow.wav           Slower, 210 wpm.

    Diagram with and without alt text (Part seven):
    09-inaccessible-diagram.wav            Realistic, 240 wpm.
    09-inaccessible-diagram-slow.wav       Slower, 210 wpm.
    10-accessible-diagram.wav              Realistic, 240 wpm.
    10-accessible-diagram-slow.wav         Slower, 210 wpm.
```

The page rendering script lives one level up at `../../scripts/build_screen_reader_demo_assets.py`.

## How to open the demo

Double click `index.html`. It opens in your default browser. No server, no internet. Everything works offline. The browser may ask you to allow audio playback the first time you press play. Allow it.

If you want a fresh window for the talk, open the file in Chrome or Edge full screen by pressing F11.

## How the demo flows during the talk

1. **Hero**, sets the scene in one paragraph.
2. **Part one, what a screen reader actually is.** Click "Play introduction" to let the screen reader speak first. This is the icebreaker. The audience hears the voice before they read another word.
3. **Part two, the page we are testing.** Show the rendered page. Read out the caption. The audience now knows what the figure looks like to a sighted reader.
4. **Part three, the same figure two ways.** This is the centrepiece. Play the slower button on the inaccessible side first so the audience can follow what the screen reader actually said. Then play the realistic button to show how fast it really sounds. Repeat on the accessible side. Side by side comparison is the whole point.
5. **Part four, the same table two ways.** Same pattern, on the forest plot table from page three. Image now sits above the comparison so the audience can see what the screen reader is trying to read.
6. **Part five, the same paragraph with and without headings.** Synthesised content rather than the BJJ paper. Audience sees a "wall of text" version on the left and a structured version with H2 and H3 on the right. Audio shows what each sounds like, and the transcript explains why heading tags let a user skim.
7. **Part six, the same links described and undescribed.** Three "click here" links versus three descriptive links. The audio reads what shows up when a screen reader user pulls up a link list.
8. **Part seven, the same diagram with and without alt text.** A simple Venn diagram drawn inline as SVG. The visual is identical for both reads. The audio shows the difference between "graphic" with no description, and a plain language description of the diagram.
9. **Part eight, what remediation actually changes.** Six numbered points. Read them aloud or let the audience read.
10. **Part nine, the PDF remediation industry.** Names the Indian companies, the demand drivers, and the gap. Ends with a link to the interest group form.

## The two play buttons next to each comparison

Each comparison player has two buttons.

- **Play at screen reader speed.** This is 240 words a minute. It is the realistic experience. Most sighted listeners with no exposure to screen readers will not catch every word. That feeling is the point.
- **Play at a slower pace.** Same words, 210 words a minute. Noticeably easier to follow than realistic speed without crawling. The audience can follow every word and understand exactly where the inaccessible reading went wrong, or what the accessible version got right.

In the talk, lead with the slower button if you want the audience to **understand**, then play the realistic button if you want the audience to **feel** what the experience is actually like. Or play one then the other. Either order works.

The "Stop audio" bar at the top of the page stops whatever is playing. If you click a different play button while audio is running, it stops the old one and starts the new one automatically.

## How the audio was made

Microsoft Zira, a built in Windows speech voice, recorded by a small Python program. Zira is recognisable as a screen reader voice because it is also the voice Windows Narrator uses by default. NVDA itself uses a different voice called eSpeak NG, but eSpeak NG is not installed on this laptop. The pedagogical point lands either way. If you want the literal NVDA timbre later, install eSpeak NG and rerender.

## When you would want to change the audio

Only if you decide one of the clips says something you want to change. For example:

- The inaccessible figure read feels too long for the audience.
- You want a third clip that reads an equation.
- You want a Hindi version.
- You want a different voice or speed.

In every other case, ignore this section. The clips are already made. Nothing else has to happen.

## How to change the audio, step by step

1. Open the build script in any editor:

   `C:\Users\deepa\Projects\equitabledocs-portal\scripts\build_screen_reader_demo_assets.py`

2. Find the section that begins with `CLIPS = {`. Each clip is one entry. The key is the file name. The value is the words it speaks.

3. Edit the words inside the quotes. Save the file.

4. Open a terminal in the portal folder. Run:

   `python scripts/build_screen_reader_demo_assets.py`

5. The program speaks each clip and saves it to the `audio/` folder. It also re renders the page image. Takes about 30 seconds.

6. Refresh the demo page in the browser. The new audio plays automatically.

If you add a brand new clip, also add a play button to `index.html`. Copy one of the existing button blocks and change the `data-play` and `data-label` values to match your new file name and label.

## How to add a new comparison section

If you want a third comparison later, for example an equation read:

1. In the script, add two new entries to `CLIPS` (the realistic version) and two to `SLOW_CLIPS` (the slow version).

2. Run the script.

3. In `index.html`, copy the entire "Part four. The same table" section. Change the headings, the lead paragraph, the button file names, and the transcript text.

4. Save and reopen.

This is the same pattern in three places in the file. If you find it confusing, send me the new clip text and I will wire it in.

## What the demo does not need

- No internet during the talk.
- No server running.
- No login.
- No screen reader installed on the laptop. The audio is pre recorded.

## What to check the morning of the talk

- Speakers on the laptop or projector are working. Play the intro clip. If you hear it, every other clip will work.
- The page image loads. If you only see a placeholder, the `img/prisma-page.png` file is missing.
- Browser zoom is at one hundred per cent or higher so the audience can read the transcripts if they want.

## Where to grow this demo next

A few good follow ups, in rough priority order:

1. Add a third comparison that reads a mathematical equation, both the inaccessible "x squared minus y squared" run on and the accessible MathML announcement.
2. Add a Hindi clip pair, using a Hindi speech voice if installed.
3. Add an Indic script reading order example, since that gap is mentioned in part six but not demoed.
4. Add a clip showing a heading list. Screen reader users press H to jump heading to heading. Without tagged headings, that key does nothing.
5. Pre record an actual NVDA capture as an alternative to the synthesised Zira voice, so the audience hears the real timbre.

## Voice rules to keep in mind when editing

This demo follows the EquitableDocs public site voice. Read `equitabledocs.github.io/CLAUDE.md` Section 3.4 before changing copy. The high frequency rules:

- No em dashes or en dashes anywhere. Use commas, colons, or full stops.
- No rhetorical, slogan, or advocacy flavoured copy. Read like gov.uk and DAISY, not like an awareness campaign.
- No specific Rupee per page rates on this page.
- Frame as Global South with India as the example, never narrowed to India only.

## Test fixture provenance

The PDF used for the demo is `BJJ-2025-1271.R1_NO_ALT.pdf`, sitting in the qc repo at `equitabledocs-qc/research/test_fixtures/`. It is a real research paper, "Superior compared with anteroinferior plating for mid shaft fractures of the clavicle, a meta analysis", published in The Bone and Joint Journal volume 108 B, number 5, May 2026. Used here as a research test document, not modified.