Soundcheck

Soundcheck answers one question: did my change break anything? You snapshot a whole site, update a plugin, switch PHP or deploy, then compare. Soundcheck shows only what's different, most serious first. This page explains what it checks, when to use it and how a run works.

rhythm soundcheck snapshot staging.yoursite.com   # before
# …update plugins, switch PHP, deploy…
rhythm soundcheck compare                         # after

Soundcheck ships as its own binary, rhythm-soundcheck. You normally run it through rhythm soundcheck (or the short alias rhythm sc). The installer sets it up along with Tuner; if you see rhythm: soundcheck isn't installed, run rhythm install soundcheck. See Install.

Important

Check only sites you own or have permission to test. Soundcheck browses like a visitor at a polite pace. It only submits forms when you turn on the submit level. It refuses to on sites you list as production. See Responsible use.

What it checks

Soundcheck opens every page in headless Chrome, at desktop and phone size. It runs five modules on each page.

Module	What it looks for	Page
🩺 health	Server errors and 404s, PHP fatals, warnings, notices and deprecations with file and line, the WordPress "critical error" screen, white screens, framework error pages, JavaScript errors, failed XHR, REST and admin-ajax calls, broken links and assets, mixed content, lost titles, a new noindex.	Page health
🖼️ visual	Full-page screenshots, compared pixel by pixel. Regions that change on their own (sliders, clocks, ads) are learned and ignored. A change shared by many pages is reported once.	Visual changes
🖱️ interact	Forms and controls read from the page, then menus, tabs, accordions and modals clicked to find dead clicks and clicks that throw. Opt in to submit forms with test data and to run your own YAML flows.	Interactions, Forms and flows
🗄️ cache	Which cache layer serves pages and how often, private pages (cart, checkout, account) served from cache, logged-in content leaking to visitors, cached pages carrying expired WordPress nonces, stale copies.	Cache
⚡ speed	Lab LCP, CLS, TBT, TTFB, weight and requests per page; slowdowns past a noise floor; site-wide suggestions grouped by cause, including what each plugin costs.	Speed

Soundcheck is built for PHP and WordPress (it knows plugin paths, nonces, form plugins and cache plugins) and works on any site.

When to use it

• Before and after a change. Plugin and theme updates, a WordPress or PHP upgrade, a new cache rule, a deploy. Take a snapshot, make the change, compare.
• Staging against production. rhythm soundcheck staging.yoursite.com --against yoursite.com checks both now and compares them, with no snapshot.
• In CI. Fail a pull request or a deploy when something broke. See CI.
• A one-off health check. rhythm soundcheck run yoursite.com lists the problems a site has right now.

Soundcheck isn't a security scanner; that's Tuner. The two complement each other: Tuner looks for what an attacker could use, Soundcheck for what your last change did to visitors.

How a run works

flowchart LR
  A["Discover<br/>sitemaps, links"] --> B["Visit<br/>headless Chrome,<br/>desktop + mobile"]
  B --> C["Check<br/>each module"]
  C --> D["Snapshot<br/>.soundcheck/"]
  D -.-> E["Compare<br/>same pages again"]
  E --> F["Report<br/>terminal, HTML,<br/>Markdown, JSON, JUnit"]

Loading

1. Discover. Soundcheck fetches the start page (following redirects, so http becomes https and apex becomes www when the site says so), reads robots.txt and the sitemaps and follows the links it finds in each page the browser renders. Pages that share a URL pattern, such as /product/{slug}/, are grouped. A few samples stand for the rest. Admin, login, feeds and URLs with side effects (log out, add to cart) are never visited. See Discovery.
2. Visit. Each page opens in its own background window of a private browser session (like a private window, never logged in), eight at a time and at most 5 page loads a second, with the browser's cache off so every page loads cold. Soundcheck records the response, redirects, console errors, failed requests, every resource, lab timings and the visible text, then takes a full-page screenshot. The page then reloads at phone size (390 px wide) for a second screenshot.
3. Check. While the page is open, the interact module reads its forms and clicks its controls; links in the rendered page join the queue. Then every module checks the recorded page. After the last page, site-wide checks run: links to pages that weren't visited, the cache double fetch and leak test, speed suggestions and your flows.
4. Snapshot. snapshot saves the run (run.json and the screenshots) in .soundcheck/snapshots/<name>/. A snapshot takes each screenshot twice, a moment apart, to learn the regions that change on their own.
5. Compare. compare checks the snapshot's pages again, with no new discovery, then diffs the two runs. New errors become BROKE, other new problems NEW, visual and content differences CHANGED, slowdowns SLOWER and problems that went away FIXED.
6. Report. The terminal shows the result live. Every run also writes a standalone report.html with before/after sliders. You can also save Markdown, JSON or JUnit. See Reading results.

With every module on, a 37-page local test site took 54 s for the snapshot and 47 s for the compare; a 101-page static site on a 16-core machine took 92 s and 61 s. Large sites stay manageable because grouping caps how many pages of each pattern are checked; see FAQ.

The browser

Soundcheck drives Chrome or Chromium through the DevTools protocol. It uses an installed Chrome when it finds one. Otherwise it downloads a pinned Chromium once, on first use, into your cache folder. rhythm soundcheck update installs or refreshes it; --browser points at a specific binary. See FAQ.

Files

Everything Soundcheck records stays in your project, in ./.soundcheck/: snapshots, recent runs and comparisons, screenshots and reports. Inside a git repository, the snapshots and runs are added to .git/info/exclude so screenshots are never committed by accident, while config.yaml and flows/ stay visible for your team. See Configuration.

Where to go next

You want to…	Read
Take a snapshot and compare, step by step	Your first check
Understand BROKE, NEW, CHANGED, SLOWER and FIXED	Reading results
Control which pages are checked	Discovery
Test forms and scripted journeys	Forms and flows
Check caching and logged-in leaks	Cache
Wire it into CI	CI
Change defaults for a project	Configuration
Look up a flag	CLI reference
Fix a problem	FAQ and troubleshooting

---

_{← FAQ and troubleshooting · Home · Your first check →}