Skip to main content

1.4: Resilience and Reach

Status: proposed. Additive only, no breaking changes.

Theme​

Make playback behave well on bad networks and offline, and make the library easier to adopt outside React.

Evidence and hypotheses​

Repo evidence:

  • The state model has idle, loading, ready, playing, paused, ended and error. It has no distinct state for stalled or rebuffering playback, so a UI cannot tell a slow network from a paused player.
  • Offline playback is a candidate use case for browser apps; the app must continue to own its cache and service worker.
  • Error codes are typed, but a failed load needs a manual retry by the caller.
  • Angular and Web Component usage exists only as documentation (ANGULAR_EXAMPLE.md, WEB_COMPONENT_EXAMPLE.md).

Hypotheses to validate:

  • Mobile listeners hit stalls often enough that a buffering indicator matters.
  • Preloading the next queue item reduces gaps between episodes.

Scope​

ItemPrioritySizeNotes
Buffering and stalled state: waiting and stalled engine events surfaced as a state flag or statusP0MMust not break existing status consumers. Prefer an additive flag over a new status value.
Retry policy for failed loads: configurable attempts and backoff, off by defaultP0MEmits events per attempt. Clears stale error on success.
Source resolver hook: the app can map a source to another URL (cached blob, local file) before loadP1MThe hook for offline playback. The library does not own caching.
Preload the next queue itemP1MOpt-in. Needs a second engine or a hidden element. Measure before shipping.
Official Web Component entry point (a custom element on a subpath export)P2MTurns the docs example into a tested export
Angular service example moves from docs into a tested example projectP2SA package only if there is demand
Structured diagnostics: an opt-in event stream for errors and stallsP2SHelps field debugging without owning analytics
llms.txt, llms-full.txt, Markdown page export, troubleshooting section, first LLM evals, two more demosP1MSee DOCS_PLAN.md
Exploration: audio visualization data (waveform peaks or spectrum) for visual clientsP2MNeeds Web Audio and CORS-enabled audio. The engine owns the element, so this may belong with the 2.0 engine work. Decide after a spike.

Out of scope​

  • Owning caching, downloads or background sync. The app and its service worker do that.
  • HLS, DASH or adaptive streaming (2.0 area).
  • Casting.

Success measures​

  • A UI built only from library state can show loading, buffering, playing, paused, ended and error distinctly.
  • A load that fails transiently recovers without app code when a retry policy is set.
  • A repository example plays an already-cached audio source offline through the source resolver.

Risks​

  • Preloading doubles audio resources and can hurt data-limited users. Default off.
  • Stall detection differs across browsers. Test on Chromium, Firefox and Safari before promising behavior.

Open questions​

  • Is a buffering flag enough, or do consumers need a new status value? A new value risks breaking exhaustive switches in consumer code.
  • Does a Web Component export belong in this package or a separate one?

Release gate​

Publish 1.4.0-beta.1, test the repository demo on a throttled network and the offline example without a network connection, validate Web Component and Angular work with their example projects, and pass the automated checks before promoting.