Usage Guide

Everything you need to analyze HTML accessibility with Speakable — from installation to CI/CD integration.

Installation

Install as a project dependency for programmatic use and CI pipelines, or globally for CLI access anywhere.

Terminal

# Install as a project dependency
npm install @reticular/speakable

# Or install globally for CLI access
npm install -g @reticular/speakable

CLI Commands

The speakable binary accepts HTML file paths as arguments. All options are flags — no subcommands.

Terminal

# Basic analysis (JSON output, NVDA by default)
speakable page.html

# Choose output format: json, text, audit, or both
speakable page.html -f text
speakable page.html -f json
speakable page.html -f audit
speakable page.html -f both

# Choose screen reader: nvda, jaws, voiceover, or all
speakable page.html -s nvda
speakable page.html -s jaws
speakable page.html -s voiceover
speakable page.html -s all

# Filter to specific elements with a CSS selector
speakable page.html --selector "button"

# Compare two HTML files (semantic diff)
speakable new.html --diff old.html

# Batch process multiple files
speakable --batch file1.html file2.html file3.html

# Write output to a file
speakable page.html -o output.json

# Read from stdin
cat page.html | speakable -

# Validate round-trip serialization
speakable page.html --validate

Output Formats

Speakable supports four output formats, each suited to different workflows.

Format	Flag	Description
JSON	-f json	Canonical accessibility model as deterministic JSON. Best for CI/CD, snapshot testing, and programmatic comparison.
Text	-f text	Screen reader announcement text. Shows what each reader would say, line by line. Human-readable.
Audit	-f audit	Structured report with landmark structure, heading hierarchy, interactive elements, detected issues (error/warning/info), and summary statistics.
Both	-f both	JSON model and screen reader text combined in a single output.

Pro Features

Batch Processing

Analyze multiple files in a single run. Batch mode continues processing even if individual files fail, and reports a summary at the end.

speakable --batch file1.html file2.html file3.html

Semantic Diff

Compare before/after HTML to detect accessibility regressions. The diff identifies added, removed, and changed nodes with property-level detail (name, role, state, focus).

speakable new.html --diff old.html

CI/CD Integration

Use exit codes and JSON output for automated pipeline checks. Exit 0 = success, exit 1 = user error, exit 2 = content issues or diff changes, exit 3 = system error.

npx @reticular/speakable page.html -f audit

Web Analyzer

The web analyzer at /tool lets you paste HTML directly and see results instantly — no installation required.

Paste your HTML into the textarea
Select a screen reader (NVDA, JAWS, VoiceOver, or All)
Optionally enter a CSS selector to focus on specific elements
Click Analyze to see the predicted output

Toggle diff mode to compare two HTML snippets side by side. Speakable will show you exactly which accessibility tree nodes were added, removed, or changed between the two versions.

After analyzing, click the 🔊 icon in the output toolbar to hear the results read aloud, or switch to line-by-line mode to navigate the output one announcement at a time using keyboard shortcuts.

Voice Announcer

The web analyzer and browser extension include a built-in voice announcer that reads analysis output aloud using the browser's native SpeechSynthesis API.

Play All

Reads the entire output sequentially with pauses between lines and longer pauses between screen reader sections.

Line-by-Line Navigation

Mimics how screen reader users actually navigate: one element at a time.

Key	Action
↓ / j	Move to next line and speak it
↑ / k	Move to previous line and speak it
Enter / Space	Play all from current line
Escape	Stop speech and exit line-by-line mode

Voice & Speed Controls

The voice dropdown includes a voice selector and a speed slider ranging from 0.5x to 2.0x.

Best Practices

Run in CI for regression detection

Add Speakable to your build pipeline so every PR is checked for accessibility changes.

Use selectors for component-level analysis

Focus on specific components with --selector rather than analyzing entire pages.

Check all three readers

Use -s all to see cross-platform differences. NVDA, JAWS, and VoiceOver each have unique announcement patterns.

Save JSON baselines for snapshot testing

Store JSON output as baselines, then use --diff to detect changes between versions.

Start with audit reports

Use -f audit for a quick overview of accessibility health before diving into specific reader output.