Skip to main content

1.2: Less Glue Code

Status: implementation complete. Additive only, no breaking changes.

Theme​

Reduce the integration code needed to build an audio app with the core API and React adapter.

Integration needs​

  • React consumers attach persistence, Media Session, and progress reporting manually and manage their cleanup.
  • Player controls need relative seeking with consistent clamping.
  • Components should subscribe to the state they display without polling or re-rendering on unrelated updates.
  • Examples should show loading, playback, errors, queues, and optional integrations using only the public API.
  • Playback rate presets are a candidate convenience feature; validate their usefulness in the demo before adding API surface.

Scope​

ItemPrioritySizeNotes
skip(seconds) on the player, clamped at 0 and, when the duration is known, at the durationP0SMedia Session already does this internally. Keep its unknown-duration fallback: before metadata loads, a forward skip advances from the current time instead of seeking to 0. Expose it.
React provider accepts plugin options (persistence, mediaSession, progressReporter) and tears them down itselfP0MGoal: the React example uses AudioPlayerProvider directly
useAudioPlayerState(selector) with a selector and equality checkP0SStops components re-rendering on every timeupdate
Throttled progress hook, for example useAudioPlayerProgress({ intervalMs })P1SReplaces the setInterval polling in the player UI
Exported default rate presets and a cycleRate(presets?) helperP1SOnly if the demo demonstrates a need after the other items
Browser-level tests with a real runner, covering load, seek, ended, auto-advanceP1LCloses Issue 011. Run in CI.
Recipes and the React guide updated to show the provider with pluginsP1SDocs are part of done
Keep the docs site published, remove template leftovers, merge docs/ and website/docs/ into one sourceP0MThe site is published. Consolidation remains. See DOCS_PLAN.md.
JSDoc where the type cannot say enough: units, defaults, side effects, error behavior, edge casesP0MSkip comments that restate the type.
README rewrite for newcomers, with a scope statementP0SSee OPEN_SOURCE.md
Support matrix, engines review and a stability policyP0SMatrix is backed by the browser tests
Server rendering recipe with a Node import test, bundle size budget in CI, CODE_OF_CONDUCT.mdP1SSee OPEN_SOURCE.md

Out of scope​

  • New playback features (that is 1.3).
  • Changing the flat AudioSource shape.
  • Any change to the engine boundary.

Success measures​

  • A newcomer can tell from the README what the library is for, and which browsers and frameworks it supports.
  • The React example uses the library provider and demonstrates plugin setup and cleanup without a custom provider.
  • The player UI no longer polls on an interval.
  • One browser-level test run in CI passes on Chromium.

Risks​

  • Plugin options on the provider add API surface. Keep them as thin as the attach functions, with no new behavior.
  • A browser test runner adds CI time and a flaky-test risk. Start with a handful of stable tests.

Open questions​

  • Which optional integrations belong in the minimal React example, and which need separate recipes?
  • Should skip live on the player, or only as a React helper?

Release gate​

Publish a prerelease (1.2.0-beta.1), pass the automated checks and browser tests, and verify the browser demo and React example before promoting to 1.2.0. External app adoption is not a release gate.

Delivery status​

  • Implemented: relative seeking, provider-managed plugins, state selectors, and the throttled progress hook.
  • Added: real-audio browser tests, React persistence and demo browser checks, server import/render tests, and bundle-size checks.
  • Docs: one canonical docs/ source, support matrix, stability policy, SSR recipe, provider recipes, and a code of conduct.
  • Compatibility: React 18 and 19 checks in CI, Chromium/Firefox/WebKit playback checks, ESM and CommonJS package checks.
  • Deferred: rate presets and cycleRate(). The demo already has a rate selector; an extra helper has no demonstrated need.
  • Release gate: CI must pass and the published beta package and repository demos must be verified before stable promotion.