Troubleshooting

Common problems and what to try. If a fix below doesn’t work, file an issue or email web.dev.hari@gmail.com with:

The site URL where it happened.
What you expected to happen, and what actually happened.
Whether the screen reader was on or off.
Browser and OS version.

Check, in order:

Is your system volume on? Wholisphere uses the Web Speech API; nothing happens if your system is muted.
Is the screen reader actually on? Open the popup and confirm the Screen reader tile shows “On”. If it’s off, click it.
Is the page still loading? Wholisphere waits for the page to settle (DOMContentLoaded + a brief debounce) before speaking. Heavy pages can take a few seconds.
Are you in Focus mode? Wholisphere stays out of the way in Focus mode for typing-friendly pages. Press \ to switch to Browse mode.
Did the page block all audio? Some sites silence Web Speech API output until you click on the page once (browser autoplay rules). Click anywhere on the page once, then try again.

A few common cases and what’s happening:

It read a meta-text region first (“This article is semi-protected”). Wholisphere skips well-known wrapper meta-text on Wikipedia and similar sites, but if your site has its own pattern, the skip-link landing finds the first focusable element inside the wrapper target. If that’s not what you want, press H to jump to the H1.
It double-spoke a link with an icon (“Settings, Settings” or “lock icon, Heading 1”). This was a known issue earlier in the prototype; the dedupe rule now drops images-inside-links from the cursor. If you still see it, that’s a regression worth filing.
It announced the page title twice on SPA nav. Some apps fire pushState and update the document title on near-simultaneous frames; Wholisphere debounces but a 200 ms flicker can slip through. File the URL and we’ll tighten.

A capability says “permission denied” or “unavailable”

Capabilities that need extra permission and what they need:

Capability	Permission
Voice command	Microphone (Chrome will prompt the first time)
Live captions	Microphone (or tab audio if your browser supports it)
Describe image / Describe video	None beyond default — but cross-origin images can’t be captured
All cloud LLM features	Internet connection

If Chrome already denied microphone for the page, click the camera/lock icon in the URL bar and reset to “Ask”.

”Cross-origin” errors when describing images or videos

The browser security model prevents extensions from reading pixel data from images or videos hosted on a different origin than the page (unless the host sets crossorigin="anonymous" plus appropriate CORS headers). Wholisphere detects this and stops cleanly with a message.

Workarounds:

For embedded YouTube videos: open the video on YouTube directly. The Wholisphere capability works there.
For cross-origin images on news sites: right-click → “Open image in new tab”, then run Describe image on the new tab.

Cloud-AI capabilities timing out

Symptoms: the screen reader says “Analyzing page…” and never finishes; or describe-image hangs.

Causes:

The backend is rate-limited or down.
Your network is unstable.
The page is huge (a 100k-word reference) and the LLM is taking a long time to outline it.

What to do:

Cancel: most cloud-AI capabilities respect “Stop reading” (Control key) or “Off” (click the popup tile).
Retry: many transient failures resolve on a second click.
File an issue if it’s persistent.

”Extension context invalidated” in the console

Means: the extension was reloaded in chrome://extensions/ while the tab was still open. The content script’s connection to the background worker is severed. Hard-refresh the tab (Cmd+Shift+R / Ctrl+Shift+R) to pick up the new extension.

The Wholisphere widget is a floating button at the bottom-right of every page. To move or hide it:

Right-click the button to dismiss for this site.
Open the popup and toggle Hide widget on this site in Site settings.
The keyboard shortcut still opens it (Ctrl+Shift+, / your configured shortcut).

The screen reader’s voice sounds robotic

Wholisphere uses your operating system’s installed voices via the Web Speech API. The voice quality is whatever Chrome exposes:

macOS: System Settings → Accessibility → Spoken Content → System Voice. Premium voices (“Samantha”, “Daniel”) are significantly better; download them once and they’re available to Chrome.
Windows: Settings → Time & Language → Speech → Add voices.
Chrome OS: Built-in Google voices are fine but limited.

Pick your preferred voice in the Wholisphere popup under Voice settings — Wholisphere remembers your choice across all capabilities that speak.

Site settings reset on a different laptop

This is by design today: per-site preferences sync across laptops, but global preferences (TTS voice, rate, screen-reader on/off) are local-only. See the Privacy page for what’s where.

If you want global prefs to follow you, that’s a feature on the roadmap.

File an issue

If your problem isn’t covered here, please report it. Issues are tracked on the project repository (URL pending public release).

Or email web.dev.hari@gmail.com directly.