pulse-player

A premium drop-in music player — now on npm for Vue, React, Svelte, Angular, Web Components, and React Native.

_{▶ Watch the 3-minute demo on YouTube — 9 themes, ambient EQ, pulso heartbeat, drag-to-resize, FAB radial menu, keyboard shortcuts, multi-framework architecture.}

v3.0.0-rc.0 is LIVE on npm (2026-06-08). The 7 @pulse-music/* packages shipped after a 21-tag audit-driven alpha cycle (types, core, tokens, web-component, react, svelte, react-native). The Vue 3 reference (src/lib/) stays source-available — vendor it directly or use the Web Component from any Vue template. The Angular wrapper stays source-available (packages/angular/) until the peer floor decision is made for rc.1. Try it now: npm install @pulse-music/react @pulse-music/core — see the install block below. Architecture map: docs/universal/ARCHITECTURE.md. Cadence to v3.0.0 stable: docs/universal/VERSION_STRATEGY.md. Roadmap: docs/universal/ROADMAP.md.

Originally a Vue 3 music player that grows with the page.

Now an audio component you can drop into any framework.

Framework	Package	Status today	Chrome parity vs Vue v2.3.4
Vue 3	pulse-player v2.3.4 (source-available, not on npm)	✅ Reference implementation (validated, 26 alphas byte-identical) — vendor via git or use Web Component	100 %
React 18 / 19	@pulse-music/react	✅ wrapper + 16 RTL tests + apps/demo-react runnable	~95 %
Svelte 5	@pulse-music/svelte	✅ plain TS hook + 8 store tests + apps/demo-svelte runnable	~95 %
Web Components	@pulse-music/web-component	✅ <pulse-player> + <pulse-fab> (Lit) + 22 element tests	~95 %
Vanilla HTML / Solid / Astro / Qwik	@pulse-music/web-component	✅ apps/demo-vanilla runnable, inherits web-component chrome	~95 %
Angular 17+	@pulse-music/angular (private)	⚠️ PulseModule + 5 smoke tests, source-available only — not on npm yet (peer floor decision deferred to rc.1)	~95 % (code), 0 % (distribution)
React Native	@pulse-music/react-native	✅ rc.1 LIVE on npm (expo-av + Reanimated) + Expo demo Android-tested	~60 %

Need the full premium chrome today (resize handle, three responsive states, social icons, prev / next, FAB drag, palette / menu, fullscreen)? → use the Vue version. Just need the audio engine + minimum card chrome (play / pause / variants / ambient EQ / pulso)? → any framework wrapper works.

Try it in 30 seconds

   

See docs/universal/SANDBOXES.md for the per-framework playground templates.

Install from npm (published 2026-06-08)

# React 18 / 19
npm install @pulse-music/react @pulse-music/core

# Svelte 5
npm install @pulse-music/svelte @pulse-music/core

# Vanilla / Solid / Astro / Qwik (Web Component)
npm install @pulse-music/web-component

# React Native (Expo SDK 56+)
npm install @pulse-music/react-native @pulse-music/core
# then from your app dir:
npx expo install expo-av react-native-reanimated react-native-gesture-handler react-native-svg @react-native-async-storage/async-storage

# Vue 3 (reference build v2.3.4 — source-available, see Vue setup below)
# Until the Vue rc.1 package ships at @pulse-music/vue, the Vue reference
# is consumed directly from this repository (git clone or git submodule).
# Tracking issue: https://github.com/YamadaBlog/pulse-player/issues

Vue 3 install path (honest): the Vue v2.3.4 reference build at src/lib/ is not yet published to npm — it ships as the source-of-truth + visual regression baseline for the multi-framework wrappers. Vue consumers today either (a) use the Custom Element via @pulse-music/web-component from any Vue 3 template, or (b) vendor src/lib/ into their app via git submodule. A published @pulse-music/vue package ships at v3.0.0 stable cut — see docs/universal/VERSION_STRATEGY.md §"Vue publishing decision".

Package	Version	Bundle gzip	Source
@pulse-music/types	3.0.0-rc.0	0.1 kB	npm
@pulse-music/core	3.0.0-rc.0	2 kB	npm
@pulse-music/tokens	3.0.0-rc.0	0.6 kB	npm
@pulse-music/web-component	3.0.0-rc.1	8.5 kB	npm
@pulse-music/react	3.0.0-rc.0	1 kB	npm
@pulse-music/svelte	3.0.0-rc.0	0.4 kB	npm
@pulse-music/react-native	3.0.0-rc.1	12 kB	npm
pulse-player (Vue v2.3.4)	2.3.4	14 kB	source-available at src/lib/, npm publish at v3.0.0 stable
@pulse-music/angular	rc.0	1 kB	source-available at packages/angular/, private until rc.1

Production-framework integration snippets

Copy-paste-ready integration patterns for the most-asked-about meta-frameworks. Each one is the smallest possible "Pulse is now in my app" sample — ~30-50 LOC, no extra abstractions.

• Next.js 14+ (App Router) — client-component pattern + SSR-safe dynamic import
• Nuxt 3+ — .client.vue + <ClientOnly> wrappers
• SvelteKit 2+ — +page.svelte + Vite optimizeDeps tweak
• Astro 4+ — Custom Element + client:load directive
• Vanilla HTML + CDN — one <script type="module"> line, no build step

How Pulse compares

Honest, datapoint-by-datapoint comparison with Plyr, Howler.js, WaveSurfer.js, Vidstack Player, and react-player. See docs/universal/COMPARISON.md for the full table — including when Pulse is not the right choice. Headline summary:

You build…	Use…
A content site / portfolio / landing page with polished audio	Pulse (smallest scope, premium chrome, multi-framework)
A media platform at scale (Netflix-clone, podcast app, music streaming)	Vidstack or Plyr (battle-tested, video + HLS)
A DAW / audio editor / podcast cutter (waveform UI)	WaveSurfer.js + Howler
A React-only app needing YouTube / Vimeo embed	react-player
A game with 3D spatial audio	Howler.js

Architecture & process docs

docs/universal/ARCHITECTURE.md — dependency graph · docs/universal/FEATURE_MATRIX.md — what works in each framework · docs/universal/API.md — canonical API reference · docs/universal/LICENSING.md — the MIT-and-why strategy · docs/universal/PRICING.md — business model locked · docs/universal/METRICS_TRACKING.md — adoption discipline · docs/universal/ROADMAP.md — per-alpha plan · docs/universal/COMPARISON.md — vs Plyr / Vidstack / Howler · docs/universal/SCREEN_READER_TEST_PLAN.md — manual SR test plan · docs/universal/VERSION_STRATEGY.md — alpha → rc → stable cadence · docs/_archive/ — superseded docs (RENAMING_DECISION, RN_RUNTIME_SETUP, PROTECTION_NOTES, PUBLISH_CHECKLIST, GIF_GUIDE).

A drop-in inline card.  ·  A floating draggable FAB.  ·  One global audio session.
_{Every visible dimension scales from a single CSS variable.}

---

👥  Used by

You're early. Pulse v3.0.0-rc.0 went live on npm on 2026-06-08. We track real production users here as they come on board — see docs/universal/METRICS_TRACKING.md for the public adoption metrics.

Shipping Pulse in production? Open a PR adding your project + logo to this section. We honour requests to stay anonymous.

✨  What it is

pulse-player started as two Vue 3 components — MusicPlayer (inline card) + MiniPlayer (floating FAB) — backed by a Pinia store that owns the audio session. Drop them anywhere, they stay in sync. Mount the FAB at the app root, playback survives every route change.

As of v3.0.0-rc.0 (2026-06-08), the same chrome ships across 5 web frameworks under the @pulse-music/* scope on npm:

• React 18 / 19 — npm install @pulse-music/react @pulse-music/core
• Svelte 5 — npm install @pulse-music/svelte @pulse-music/core
• Web Components / Vanilla / Solid / Astro / Qwik — npm install @pulse-music/web-component
• Angular 17+ — @pulse-music/angular (NgModule, awaiting peer-dep floor bump)
• Vue 3 — pulse-player (v2.3.4 reference) or @pulse-music/vue (re-export)

All wrappers share the same @pulse-music/core audio engine and @pulse-music/tokens variant tokens. See docs/universal/ARCHITECTURE.md.

The unusual bit: every visible dimension scales from one CSS variable. A ResizeObserver watches the container, writes --pulse-scale inline, and the entire component — artwork, title, icons, buttons, padding, shadows, EQ bars, progress — breathes together. Three responsive states layer on top: narrow below 220 px (NOW PLAYING label hides, social icons stay), compact below 130 px (top row collapses), FAB below 110 px (the player morphs into a circular disc). No media queries. No layout breaks.

🎨  Themes

Nine curated background presets ship in, including a true transparent variant with the original dashboard's gradient + noise texture intact. Pass accentColor to retune the EQ + progress hue.

Vinyl  ·  warm analog, gold border	Sunset  ·  sepia / brown gradient
Midnight  ·  deep navy → violet	Aurora  ·  teal / cyan night
Light  ·  inverted palette for light-mode apps

Also available: Auto · Transparent (hero above) · Dark · Solid · Custom.   → Full customization guide

📐  Responsive — built in

Compact < 130 px

Mobile ≈ 390 px

Tablet ≈ 820 px

Desktop ≥ 1280 px

Same component, four screens, zero breakpoints. → Read the responsive guide

⚡  Quick start

git clone https://github.com/YamadaBlog/pulse-player.git
cd pulse-player
npm install && npm run dev       # http://localhost:5174

In your own app, copy src/lib/ and:

<MusicPlayer variant="vinyl" />
<MiniPlayer />

That's it. Pinia is the only setup step. → Detailed install + usage

📚  Documentation

📖   API reference	Props for MusicPlayer, MiniPlayer, the useAudioStore state + actions + keyboard surface
🏗️   Architecture	How the store, audio element and FFT analyser fit together (with diagram)
🎨   Customization	Variants, accent colors, CSS variables, custom backgrounds
📐   Responsive	The auto-scale curve, the four responsive states, drag-to-resize
🛠️   Advanced usage	Replace playlist, custom controls, multiple players, hide on routes
▶️   Guided demo tour	The "Watch demo" feature — scenario, controls, fullscreen, custom steps
🔔   Events & telemetry	Opt-in typed subscribe() API + per-session counters (no third-party tracking)
⚡   Performance	Bundle map, runtime cost per hot path, integration guidelines, prefers-reduced-motion story
🆘   Troubleshooting	Autoplay rejection, 404s, EQ silent, FAB persistence, hydration mismatch
🧪   Examples	3 ready-to-fork integrations: minimum SPA, custom playlist, event subscriptions
🚀   Release procedure	Tag → GitHub Release → npm publish flow with release-notes templates
📝   Changelog	Every version from 0.1.0 to today, with rationale

💎  Highlights

Truly proportional	One CSS variable scales artwork, type, chrome and shadows together.
Container-aware	Sizes itself off its container, not the viewport.
Three responsive states	Narrow (≤ 220 px) → compact (≤ 130 px) → FAB (≤ 110 px). All driven by ResizeObserver, no media queries.
Drag-to-resize	Optional handle in the bottom-right corner. Pointer events. Mouse, touch, stylus.
Persistent session	One Pinia store. Survives every route change.
9 themes + custom	Includes a true transparent variant with gradient + noise.
Ambient EQ	64-bar GPU-composited spectrum across the player. Globally toggleable.
Pulso ripple	Optional heartbeat ring around the FAB — only while music is playing.
Guided demo tour	~50 s scripted walkthrough with pause / resume / step jump and fullscreen.
Opt-in events	store.subscribe('play', …) returns an unsubscribe. Plus play / pause / track-change counters. No third-party tracking.
a11y	prefers-reduced-motion honoured everywhere — tweens snap, scrolls jump, transitions disabled.
Tiny	~49 kB gzipped (JS + CSS combined). Three deps (Vue, Pinia, lucide-vue-next). Zero domain code.

🗺️  Roadmap

• Volume slider + mute on the inline card
• Shuffle / repeat modes
• Persist currentTime to localStorage (persistKey already covers FAB position)
• Keyboard shortcuts (Space, ←, →) in the demo tour
• Media Session API (hardware media keys + lock-screen art)
• Waveform variant (canvas alternative to the EQ bars)
• Extract src/lib/shared/ to deduplicate variant CSS between MusicPlayer and MiniPlayer
• Publish as a standalone npm package

📝  Changelog

Every release is pinned to a signed git tag (v1.0.0 … v1.0.12) and surfaced as a GitHub Release.

Latest	One-line summary
v1.0.12	Spotlight blur stays active during the Pulso demo step; boost to the FAB section is 1.5× slower for readability.
v1.0.11	Options divider between the FAB colour palette and the action buttons.
v1.0.10	Stable 680 × 233 baseline for the demo stages — never shrinks, grows past the baseline if the player does.
v1.0.6 → 1.0.9	Pick-a-mood demo step rewritten — precise framing, single continuous descent, title always in view; pulso ring + heartbeat aligned to the beat.
v1.0.1 → 1.0.5	Ambient EQ moved to a pure-CSS animation (0 JS / frame), bullet-proof pulso centring, dem o tour pause / resume / step jump, distance-aware scroll easings.
v1.0.0	Production-ready: CI matrix, 30 unit tests, ESLint + Prettier + Husky, npm-publish-ready package.json, shared PulseVariant type, CONTRIBUTING.md.

Full history with rationale per release: CHANGELOG.md.

📄  License

MIT. The two demo tracks under public/audio/ are shipped for local testing only and are not part of the MIT-licensed source — replace them with content you own before redistributing.

_{Built with Vue 3, Pinia, a ResizeObserver and a small amount of obsessive proportional tuning.}