@yetric/audioplayer 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yetric AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# `@yetric/audioplayer`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Headless TypeScript audio player for modern browsers.
+
+[GitHub](https://github.com/yetric/audioplayer)
+
+## Status
+
+`1.0.0` is the current stable release line.
+
+Recommended current focus:
+
+- use the browser package
+- validate it in `podcast-app`
+- treat React Native support as later work
+
+## Install
+
+```bash
+npm install @yetric/audioplayer
+```
+
+React usage:
+
+```bash
+npm install @yetric/audioplayer react
+```
+
+## Quick Start
+
+```ts
+import { createAudioPlayer } from "@yetric/audioplayer";
+
+const player = createAudioPlayer();
+
+await player.play({
+  id: "episode-42",
+  src: "https://cdn.example.com/episode-42.mp3",
+  title: "Episode 42",
+  artist: "Podcast Name",
+});
+
+player.subscribe((state) => {
+  console.log(state.status, state.progress.playedFraction);
+});
+```
+
+The first milestone is not "generic media player." It is "good enough to replace the current `podcast-app` audio layer with a simpler, testable, framework-agnostic library."
+
+## Product Direction
+
+- Browser-first, using `HTMLAudioElement` as the primary engine
+- Headless core API, so React/Angular/Web Components/vanilla JS can all use the same package
+- Imperative instance API first: `const player = createAudioPlayer()`
+- Queue management lives inside the player instance for `1.0`
+- Persistence is opt-in, with `localStorage` as the first storage adapter
+- `load()` accepts one flat audio source object in `1.0`
+- `subscribe(state)` is the primary UI model, with typed events for side effects
+- Every source / queue item must have a stable caller-provided `id`
+- `play(...)` may auto-load the requested item instead of requiring a separate `load()`
+- `1.0` is optimized for one active player instance per app/page
+- When playback finishes without auto-advancing, the current item remains loaded with `status: "ended"`
+- Strong TypeScript types without making vanilla JS usage awkward
+- React Native compatibility treated as a later adapter problem, not a 1.0 blocker
+
+## 1.0 Goal
+
+`1.0.0` is ready when `podcast-app` can use this package for:
+
+- load / replace a source
+- play / pause
+- seek
+- playback rate changes
+- progress reporting
+- queue navigation
+- persisted resume state
+- Media Session integration
+
+## Early API Shape
+
+```ts
+import { createAudioPlayer } from "@yetric/audioplayer";
+
+const player = createAudioPlayer();
+
+await player.load({
+  id: "episode-42",
+  src: "https://cdn.example.com/episode-42.mp3",
+  title: "Episode 42",
+  artist: "My Podcast",
+  artwork: "https://cdn.example.com/episode-42.jpg",
+});
+
+await player.play();
+player.seek(120);
+player.setRate(1.25);
+
+const unsubscribe = player.subscribe((state) => {
+  console.log(state.status, state.currentTime);
+});
+```
+
+The public API should stay small. Extra behavior like persistence, progress pings, analytics, and Media Session should be opt-in modules or config hooks around the same core. The first persistence target is `localStorage`, but the design should leave room for custom storage backends later. UI consumers should mostly read state through `subscribe(...)`, while integrations can rely on typed events instead of diffing state manually.
+
+## Planned Package Surface
+
+- `@yetric/audioplayer`
+  - headless browser player core
+  - queue support
+  - persistence hooks
+  - Media Session integration
+- later:
+  - `@yetric/audioplayer-react`
+    - provider-owned singleton player for app-level usage
+    - hook-based consumption on top of the provider
+  - `@yetric/audioplayer-rn`
+
+## Repo Docs
+
+- [`docs/ROADMAP.md`](./docs/ROADMAP.md)
+- [`docs/V1_ISSUES.md`](./docs/V1_ISSUES.md)
+- [`docs/API_CONTRACT.md`](./docs/API_CONTRACT.md)
+- [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
+- [`docs/CORE_GUIDE.md`](./docs/CORE_GUIDE.md)
+- [`docs/REACT_GUIDE.md`](./docs/REACT_GUIDE.md)
+- [`docs/INTEGRATIONS.md`](./docs/INTEGRATIONS.md)
+- [`docs/RECIPES.md`](./docs/RECIPES.md)
+- [`docs/MIGRATION_PODCAST_APP.md`](./docs/MIGRATION_PODCAST_APP.md)
+- [`docs/ANGULAR_EXAMPLE.md`](./docs/ANGULAR_EXAMPLE.md)
+- [`docs/WEB_COMPONENT_EXAMPLE.md`](./docs/WEB_COMPONENT_EXAMPLE.md)
+
+## External Docs
+
+- Docusaurus site source: [`website/`](./website/)
+- Local dev: `npm run docs:start`
+- Production build: `npm run docs:build`
+
+## Local Demo
+
+- Start demo: `npm run demo:start`
+- Build demo: `npm run demo:build`
+- Preview demo build: `npm run demo:preview`
+
+## Examples
+
+- [`examples/vanilla/index.html`](./examples/vanilla/index.html)
+- [`examples/vanilla/playlist-demo.js`](./examples/vanilla/playlist-demo.js)
+- [`examples/react/App.tsx`](./examples/react/App.tsx)
+- [`examples/react/PodcastPlayerDemo.tsx`](./examples/react/PodcastPlayerDemo.tsx)