dither-player 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erick Donado
+
+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,104 @@
-# Temporary Holding Version
+# dither-player
 
-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.
+A small music player for personal sites. Your own tracks play with a 1-bit dithered visualizer, and an optional second tab holds a playlist of songs you like from Apple Music, Spotify, YouTube or SoundCloud.
+
+- **A tag for any web page**: `<dither-player>`, one script, no build step. Works on Neocities, Nekoweb, GitHub Pages or anywhere else.
+- **A React component**: `<DitherPlayer />`, client-only, works in Next.js.
+- **English and Spanish built in**, following the page's language. Every word can be changed.
+
+The visualizer uses the same ordered dithering as [dither-moon](https://github.com/KanuSaru/dither-moon), so the two sit well together.
+
+## Any web page
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/dither-player@1/dist/dither-player.js"></script>
+
+<dither-player playlist="https://music.apple.com/co/playlist/…" artist="Your name">
+  <a href="music/night-bus.mp3">Night bus</a>
+  <a href="music/tide.mp3">Tide</a>
+</dither-player>
+```
+
+The tracks are ordinary links, so without JavaScript the page still lists them and they still play or download.
+
+| Attribute | What it does |
+| --- | --- |
+| `playlist` | Share link of a public playlist; adds a **Faves** tab |
+| `artist` | Shown on phone lock screens (per track: `data-artist` on the link) |
+| `lang` | `en` or `es`. Without it, the page's language, including later changes |
+| `tab` | `mine` or `faves`, the tab to open on |
+| `visualizer` | `false` to hide it |
+| `pixel-size`, `bars` | Visualizer pixel size (default 3) and height in its pixels (default 12) |
+| `label-…` | Any of the words, e.g. `label-faves="Songs I like"`, `label-faves-text="On repeat lately."` |
+
+## React
+
+```bash
+npm install dither-player
+```
+
+```jsx
+import { DitherPlayer } from "dither-player/react";
+
+<DitherPlayer
+  tracks={[{ title: "Night bus", src: "/music/night-bus.mp3" }]}
+  playlist="https://open.spotify.com/playlist/…"
+  lang="es"
+  labels={{ faves: "Favoritas", favesText: "Lo que más escucho." }}
+/>
+```
+
+It keeps playing while it stays mounted. In Next.js, put it in a layout (a sidebar, a footer) and the music carries on as visitors move between pages.
+
+## Without a framework
+
+```js
+import { createPlayer } from "dither-player";
+
+const player = createPlayer(document.querySelector("#music"), { tracks, playlist, lang: "en" });
+player.update({ lang: "es" }); // any option; a playing track keeps playing
+player.state; // { playing, index, track, time, duration }
+player.destroy();
+```
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `tracks` | `[]` | `{ title, src, artist? }`, in order. Files on your own site. |
+| `playlist` | `""` | Apple Music, Spotify, YouTube (playlist) or SoundCloud share link |
+| `lang` | page language | `"en"` or `"es"` (others fall back to English) |
+| `labels` | | Replace words: `region mine faves play pause prev next seek empty noPlaylist favesText favesTitle load loadNote`. `{x}` is the service's name. |
+| `artist` | `""` | For lock screens |
+| `visualizer` | `true` | |
+| `pixelSize` | `3` | Screen pixels per visualizer pixel |
+| `bars` | `12` | Visualizer height |
+| `tab` | `"mine"` if there are tracks | |
+
+## Looks
+
+It takes the text color and font of wherever you put it. Fine-tune with CSS variables on the player or any parent:
+
+```css
+dither-player {
+  --dp-ink: #e7e2d6;      /* lines, icons, bars, filled buttons */
+  --dp-muted: #918c81;    /* secondary text */
+  --dp-line: #2b2a26;     /* borders */
+  --dp-accent: #7390ff;   /* hover and focus */
+  --dp-on-ink: #0d0d0c;   /* text and icons on filled buttons */
+  --dp-mono: "VT323", monospace;
+}
+```
+
+## Good to know
+
+- **Browsers don't allow sound before a click**, so nothing autoplays. The visualizer starts with the first press of play.
+- **The playlist's player only loads when a visitor opens it**, so the services don't load scripts or cookies on every page view. Apple Music and Spotify play full songs to their own members and previews to everyone else; that's their rule.
+- **The visualizer needs the files on your own site.** Browsers mute audio from other sites when a page analyses it, so if any track lives elsewhere, the player plays without the visualizer.
+- **Media keys and lock screens** work: play, pause, previous, next.
+- It respects `prefers-reduced-motion`: the bars stay still.
+- Only share music you have the rights to.
+
+## License
+
+MIT, Erick Donado. The demo loop in `demo/` is synthesized for this project and free to use.

package/dist/dither-player.js

@@ -0,0 +1,54 @@
+(()=>{var Q=Object.defineProperty;var X=e=>{throw TypeError(e)};var ce=(e,n,t)=>n in e?Q(e,n,{enumerable:!0,configurable:!0,writable:!0,value:t}):e[n]=t;var de=(e,n)=>{for(var t in n)Q(e,t,{get:n[t],enumerable:!0})};var ee=(e,n,t)=>ce(e,typeof n!="symbol"?n+"":n,t),pe=(e,n,t)=>n.has(e)||X("Cannot "+t);var te=(e,n,t)=>n.has(e)?X("Cannot add the same private member more than once"):n instanceof WeakSet?n.add(e):n.set(e,t);var q=(e,n,t)=>(pe(e,n,"access private method"),t);var J={};de(J,{CSS:()=>K,DitherPlayerElement:()=>T,LABELS:()=>E,LANGUAGES:()=>ne,createPlayer:()=>V,defineDitherPlayer:()=>W,embedFor:()=>P,labelsFor:()=>B});function P(e){let n;try{n=new URL(String(e||"").trim())}catch{return null}let t=n.hostname.replace(/^www\./,"");return t==="music.apple.com"||t==="embed.music.apple.com"?{src:`https://embed.music.apple.com${n.pathname}${n.search}`,service:"Apple Music",height:450}:t==="open.spotify.com"?{src:`https://open.spotify.com/embed${n.pathname.replace(/^\/intl-[a-z-]+/i,"").replace(/^\/embed/,"")}`,service:"Spotify",height:352}:(t==="youtube.com"||t==="music.youtube.com"||t==="m.youtube.com")&&n.searchParams.get("list")?{src:`https://www.youtube-nocookie.com/embed/videoseries?list=${encodeURIComponent(n.searchParams.get("list"))}`,service:"YouTube",height:200}:t==="soundcloud.com"?{src:`https://w.soundcloud.com/player/?url=${encodeURIComponent(n.origin+n.pathname)}&visual=false&show_comments=false`,service:"SoundCloud",height:360}:null}var E={en:{region:"Music player",mine:"Mine",faves:"Faves",play:"Play",pause:"Pause",prev:"Previous track",next:"Next track",seek:"Position in the track",empty:"No tracks yet.",noPlaylist:"No playlist yet.",favesText:"",favesTitle:"Playlist",load:"Open the playlist on {x}",loadNote:"Loads {x}'s player. It plays full songs for its members and previews for everyone else."},es:{region:"Reproductor de m\xFAsica",mine:"M\xEDas",faves:"Favoritas",play:"Reproducir",pause:"Pausar",prev:"Pista anterior",next:"Siguiente pista",seek:"Posici\xF3n en la pista",empty:"A\xFAn no hay pistas.",noPlaylist:"A\xFAn no hay playlist.",favesText:"",favesTitle:"Playlist",load:"Abrir la playlist en {x}",loadNote:"Carga el reproductor de {x}. Reproduce canciones completas a sus usuarios y fragmentos al resto."}},ne=Object.keys(E);function B(e,n){return{...E[String(e||"en").slice(0,2).toLowerCase()]??E.en,...n||{}}}var L="var(--dp-ink, currentColor)",O="var(--dp-muted, color-mix(in srgb, currentColor 62%, transparent))",N="var(--dp-line, color-mix(in srgb, currentColor 22%, transparent))",U="var(--dp-accent, var(--dp-ink, currentColor))",re="var(--dp-on-ink, Canvas)",ae="var(--dp-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace)",K=`
+.dp{display:grid;grid-template-columns:minmax(0,1fr);gap:.6rem;min-width:0}
+.dp [hidden]{display:none!important}
+.dp button{font:inherit;color:inherit;cursor:pointer}
+.dp button:focus-visible,.dp input:focus-visible{outline:2px solid ${U};outline-offset:2px}
+.dp-tabs{display:flex}
+.dp-tabs button{flex:1;font-family:${ae};font-size:.95em;line-height:1;padding:.35em .5em;color:${O};background:transparent;border:1px solid ${N}}
+.dp-tabs button+button{border-left:none}
+.dp-tabs button[aria-selected=true]{color:${L};border-color:${L};box-shadow:inset 0 0 0 3em ${L};-webkit-text-fill-color:${re}}
+.dp-panel{display:grid;grid-template-columns:minmax(0,1fr);gap:.5rem;min-width:0}
+.dp-viz{min-width:0;overflow:hidden;color:${L};border-bottom:1px solid ${N};padding-bottom:2px}
+.dp-viz canvas{display:block;image-rendering:pixelated}
+.dp-now{display:grid;gap:.1rem;min-width:0}
+.dp-title{margin:0;font-weight:700;line-height:1.25;overflow-wrap:anywhere}
+.dp-time{margin:0;font-family:${ae};font-size:.95em;line-height:1.1;color:${O};font-variant-numeric:tabular-nums;white-space:pre}
+.dp-seek{-webkit-appearance:none;appearance:none;width:100%;height:14px;margin:0;color:${L};background:transparent;cursor:pointer}
+.dp-seek::-webkit-slider-runnable-track{height:2px;background:${N}}
+.dp-seek::-moz-range-track{height:2px;background:${N}}
+.dp-seek::-moz-range-progress{height:2px;background:currentColor}
+.dp-seek::-webkit-slider-thumb{-webkit-appearance:none;width:10px;height:10px;margin-top:-4px;background:currentColor;border:0;border-radius:0}
+.dp-seek::-moz-range-thumb{width:10px;height:10px;background:currentColor;border:0;border-radius:0}
+.dp-buttons{display:flex;gap:.4rem}
+.dp-buttons button{display:grid;place-items:center;width:2.25rem;height:2.25rem;padding:0;color:${L};background:transparent;border:1px solid ${N}}
+.dp-buttons button.dp-main{border-color:${L};box-shadow:inset 0 0 0 3em ${L}}
+.dp-buttons button.dp-main svg{color:${re}}
+.dp-buttons button:hover{border-color:${U}}
+.dp-buttons svg{width:13px;height:13px}
+.dp-list{margin:0;padding:.35rem 0 0;list-style:none;display:grid;border-top:1px dashed ${N}}
+.dp-list button{width:100%;text-align:left;font-size:.875em;color:${O};background:none;border:0;padding:.15rem 0}
+.dp-list button[aria-current=true]{color:inherit}
+.dp-list button[aria-current=true]::before{content:"\\25B8\\00A0";color:${U}}
+.dp-note{margin:0;font-size:.875em;color:${O}}
+.dp-small{margin:0;font-size:.8em;color:${O}}
+.dp-load{justify-self:start;font-size:.95em;background:transparent;border:1px solid ${N};padding:.35em .6em}
+.dp-load:hover{border-color:${U}}
+.dp-embed{display:block;width:100%;border:0}
+`;function ie(e){if(typeof document>"u")return;let n=e.getRootNode?.()??document,t=n instanceof Document?n.head:n;if(!t||t.querySelector?.("style[data-dither-player]"))return;let i=document.createElement("style");i.setAttribute("data-dither-player",""),i.textContent=K,t.prepend(i)}var ue=[0,8,2,10,12,4,14,6,3,11,1,9,15,7,13,5].map(e=>(e+.5)/16);function me(e){let n=getComputedStyle(e).color.match(/[\d.]+/g);return n?n.slice(0,3).map(Number):[230,226,214]}function oe(e,n){let t=e.getContext("2d"),i=typeof matchMedia=="function"&&matchMedia("(prefers-reduced-motion: reduce)").matches,l=null,p=new Uint8Array(0),f=[],h=!1,z=0,A=!0;function b(){let c=e.parentElement,g=Math.max(8,Math.floor((c?.clientWidth||120)/n.pixelSize)),w=Math.max(3,n.height);(e.width!==g||e.height!==w)&&(e.width=g,e.height=w,e.style.width=`${g*n.pixelSize}px`,e.style.height=`${w*n.pixelSize}px`),f.length!==g&&(f=new Array(g).fill(0))}function a(){b();let c=e.width,g=e.height,w=h&&l&&!i;w&&l.getByteFrequencyData(p);let x=me(e),C=t.createImageData(c,g),k=!1;for(let v=0;v<c;v++){let R=Math.min(p.length-1,Math.floor(Math.pow(p.length||1,v/c))),y=w&&R>=0?p[R]/255:0;f[v]+=(y-f[v])*(y>f[v]?.6:.15),f[v]>.01&&(k=!0);let I=Math.max(1/g,.9*f[v])*g;for(let $=0;$<g;$++)if(Math.min(1,Math.max(0,I-$))*(1-.6*$/g)>ue[($&3)*4+(v&3)]){let r=((g-1-$)*c+v)*4;C.data[r]=x[0],C.data[r+1]=x[1],C.data[r+2]=x[2],C.data[r+3]=255}}return t.putImageData(C,0,0),k}function o(){z=0;let c=A?a():!0;(h||c)&&(z=requestAnimationFrame(o))}let M=typeof ResizeObserver<"u"?new ResizeObserver(()=>a()):null;e.parentElement&&M?.observe(e.parentElement);let F=typeof IntersectionObserver<"u"?new IntersectionObserver(([c])=>{A=c.isIntersecting}):null;return F?.observe(e),a(),{connect(c){l=c,p=new Uint8Array(c.frequencyBinCount)},setRunning(c){h=c,z||(z=requestAnimationFrame(o))},resize(c){Object.assign(n,c),a()},redraw:a,destroy(){cancelAnimationFrame(z),M?.disconnect(),F?.disconnect()}}}var he={tracks:[],playlist:"",lang:null,labels:null,artist:"",visualizer:!0,pixelSize:3,bars:12,tab:null},j={play:"M1 0h1v1h1v1h1v1h1v1h1v1H5v1H4v1H3v1H2v1H1z",pause:"M1 0h2v9H1zM5 0h2v9H5z",prev:"M0 0h2v9H0zM6 0h1v9H6V8H5V7H4V6H3V3h1V2h1V1h1z",next:"M7 0h2v9H7zM1 0h1v1h1v1h1v1h1v3H4v1H3v1H2v1H1z"},Y=e=>`<svg viewBox="0 0 9 9" aria-hidden="true" shape-rendering="crispEdges" fill="currentColor"><path d="${e}"/></svg>`,D=e=>!Number.isFinite(e)||e<0?"0:00":`${Math.floor(e/60)}:${String(Math.floor(e%60)).padStart(2,"0")}`,se=(e,n)=>String(e).replace("{x}",n),Z=e=>typeof location<"u"&&e.every(n=>{try{return new URL(n.src,location.href).origin===location.origin}catch{return!1}}),be=(e,n)=>e.length===n.length&&e.every((t,i)=>t.src===n[i].src&&t.title===n[i].title&&t.artist===n[i].artist);function V(e,n={}){let t={...he,...n},i=(t.tracks||[]).filter(r=>r&&r.src),l=0,p=t.tab||(i.length||!t.playlist?"mine":"faves"),f=!1,h=null,z=!1;ie(e);let A=document.createElement("div");A.className="dp",A.setAttribute("role","region"),A.innerHTML=`
+    <div class="dp-tabs" role="tablist">
+      <button type="button" role="tab" data-tab="mine"></button>
+      <button type="button" role="tab" data-tab="faves"></button>
+    </div>
+    <div class="dp-panel" role="tabpanel" data-panel="mine">
+      <div class="dp-viz"><canvas aria-hidden="true"></canvas></div>
+      <div class="dp-now"><p class="dp-title"></p><p class="dp-time"></p></div>
+      <input class="dp-seek" type="range" min="0" max="0" step="0.1" value="0">
+      <div class="dp-buttons">
+        <button type="button" data-act="prev">${Y(j.prev)}</button>
+        <button type="button" data-act="toggle" class="dp-main"></button>
+        <button type="button" data-act="next">${Y(j.next)}</button>
+      </div>
+      <ol class="dp-list"></ol>
+      <p class="dp-note dp-empty"></p>
+    </div>
+    <div class="dp-panel" role="tabpanel" data-panel="faves"></div>`,e.appendChild(A);let b=r=>A.querySelector(r),a={tabs:b(".dp-tabs"),tabMine:b('[data-tab="mine"]'),tabFaves:b('[data-tab="faves"]'),mine:b('[data-panel="mine"]'),faves:b('[data-panel="faves"]'),viz:b(".dp-viz"),title:b(".dp-title"),time:b(".dp-time"),seek:b(".dp-seek"),prev:b('[data-act="prev"]'),toggle:b('[data-act="toggle"]'),next:b('[data-act="next"]'),list:b(".dp-list"),empty:b(".dp-empty"),now:b(".dp-now"),buttons:b(".dp-buttons")},o=new Audio;o.preload="metadata";let M=oe(a.viz.querySelector("canvas"),{pixelSize:t.pixelSize,height:t.bars}),F=()=>B(t.lang||(e.host??e).closest?.("[lang]")?.getAttribute("lang")||document.documentElement.lang,t.labels);function c(){let r=o.currentTime,s=o.duration,m=i.length>1?`  \xB7  ${l+1}/${i.length}`:"";a.time.textContent=`${D(r)} / ${D(s)}${m}`,a.seek.max=Number.isFinite(s)?String(s):"0",a.seek.value=String(r),a.seek.setAttribute("aria-valuetext",`${D(r)} / ${D(s)}`)}function g(){a.list.textContent="",!(i.length<2)&&i.forEach((r,s)=>{let m=document.createElement("li"),u=document.createElement("button");u.type="button",u.textContent=r.title||`Track ${s+1}`,u.addEventListener("click",()=>k(s,!0)),m.appendChild(u),a.list.appendChild(m)})}function w(){let r=F(),s=P(t.playlist),m=a.faves.querySelector("iframe");if(f&&s&&m?.src===s.src){m.title=r.favesTitle;return}if(a.faves.textContent="",!s){let d=document.createElement("p");d.className="dp-note",d.textContent=r.noPlaylist,a.faves.appendChild(d);return}if(f){let d=document.createElement("iframe");d.className="dp-embed",d.src=s.src,d.height=String(s.height),d.title=r.favesTitle,d.loading="lazy",d.allow="autoplay *; encrypted-media *; fullscreen *; clipboard-write",a.faves.appendChild(d);return}if(r.favesText){let d=document.createElement("p");d.className="dp-note",d.textContent=r.favesText,a.faves.appendChild(d)}let u=document.createElement("button");u.type="button",u.className="dp-load",u.textContent=se(r.load,s.service),u.addEventListener("click",()=>{f=!0,w()});let S=document.createElement("p");S.className="dp-small",S.textContent=se(r.loadNote,s.service),a.faves.append(u,S)}function x(){let r=F(),s=i.length>0&&!!P(t.playlist);A.setAttribute("aria-label",r.region),a.tabs.hidden=!s,a.tabMine.textContent=r.mine,a.tabFaves.textContent=r.faves,a.tabMine.setAttribute("aria-selected",String(p==="mine")),a.tabFaves.setAttribute("aria-selected",String(p==="faves"));let m=s?p==="mine":i.length>0||!t.playlist;a.mine.hidden=!m,a.faves.hidden=m;let u=i.length>0;for(let d of[a.viz,a.now,a.seek,a.buttons])d.hidden=!u;a.viz.hidden=!u||!t.visualizer,a.empty.hidden=u,a.empty.textContent=r.empty,a.prev.hidden=a.next.hidden=a.list.hidden=i.length<2,a.prev.setAttribute("aria-label",r.prev),a.next.setAttribute("aria-label",r.next),a.toggle.setAttribute("aria-label",o.paused?r.play:r.pause),a.toggle.innerHTML=Y(o.paused?j.play:j.pause),a.seek.setAttribute("aria-label",r.seek);let S=i[l];a.title.textContent=S&&S.title||"",[...a.list.querySelectorAll("button")].forEach((d,le)=>{le===l?d.setAttribute("aria-current","true"):d.removeAttribute("aria-current")}),c()}function C(){let r=i[l];if(!(!r||typeof navigator>"u"||!("mediaSession"in navigator)))try{navigator.mediaSession.metadata=new MediaMetadata({title:r.title||"",artist:r.artist||t.artist||""})}catch{}}function k(r,s){if(!i.length)return;l=(r%i.length+i.length)%i.length;let m=s??!o.paused;o.src=i[l].src,C(),x(),m&&v()}function v(){if(i.length){if(o.src||k(l,!1),t.visualizer&&!h&&typeof AudioContext<"u"&&Z(i))try{h=new AudioContext;let r=h.createMediaElementSource(o),s=h.createAnalyser();s.fftSize=256,s.smoothingTimeConstant=.75,r.connect(s),s.connect(h.destination),M.connect(s)}catch{}h?.resume?.(),o.play().catch(()=>{})}}let R=()=>o.paused?v():o.pause(),y=(r,s,m)=>r.addEventListener(s,m);y(a.tabMine,"click",()=>(p="mine",x())),y(a.tabFaves,"click",()=>(p="faves",x())),y(a.toggle,"click",R),y(a.prev,"click",()=>k(l-1)),y(a.next,"click",()=>k(l+1)),y(a.seek,"input",()=>{o.currentTime=Number(a.seek.value),c()}),y(o,"timeupdate",c),y(o,"loadedmetadata",c),y(o,"durationchange",c),y(o,"play",()=>{M.setRunning(!0),x()}),y(o,"pause",()=>{M.setRunning(!1),x()}),y(o,"ended",()=>{i.length>1&&l<i.length-1?k(l+1,!0):i.length>1&&k(0,!1)});let I=typeof navigator<"u"&&"mediaSession"in navigator?navigator.mediaSession:null,$={play:()=>v(),pause:()=>o.pause(),previoustrack:()=>k(l-1),nexttrack:()=>k(l+1)};for(let[r,s]of Object.entries($))try{I?.setActionHandler(r,s)}catch{}let _=typeof MutationObserver<"u"?new MutationObserver(()=>{t.lang||(x(),w())}):null;return _?.observe(document.documentElement,{attributes:!0,attributeFilter:["lang"]}),g(),i.length&&(o.src=i[0].src,C()),w(),x(),{update(r={}){if(z)return;let s=t.playlist;t={...t,...r};let m=(t.tracks||[]).filter(u=>u&&u.src);if(h&&!Z(m)&&(m=m.filter(u=>Z([u]))),!be(i,m)){let u=i[l]?.src;i=m;let S=i.findIndex(d=>d.src===u);g(),S>=0?l=S:(l=0,o.pause(),o.removeAttribute("src"),i.length&&(o.src=i[0].src),C())}t.playlist!==s&&(f=!1),r.tab&&(p=r.tab),M.resize({pixelSize:t.pixelSize,height:t.bars}),w(),x()},play:v,pause:()=>o.pause(),select:r=>k(r,!0),get state(){return{playing:!o.paused,index:l,track:i[l]??null,time:o.currentTime,duration:Number.isFinite(o.duration)?o.duration:0}},audio:o,destroy(){z=!0,o.pause(),o.removeAttribute("src"),M.destroy(),_?.disconnect(),h?.close?.();for(let r of Object.keys($))try{I?.setActionHandler(r,null)}catch{}A.remove()}}}var fe=typeof HTMLElement>"u"?class{}:HTMLElement,ge=Object.keys(E.en).map(e=>`label-${e.replace(/[A-Z]/g,n=>`-${n.toLowerCase()}`)}`),H,G,T=class extends fe{constructor(){super(...arguments);te(this,H)}connectedCallback(){if(!this.shadowRoot){let t=this.attachShadow({mode:"open"});t.innerHTML="<style>:host{display:block}</style>"}this.player=V(this.shadowRoot,q(this,H,G).call(this)),this.watch=new MutationObserver(()=>this.player?.update(q(this,H,G).call(this))),this.watch.observe(this,{childList:!0,subtree:!0,attributes:!0,attributeFilter:["href","data-artist"]})}disconnectedCallback(){this.watch?.disconnect(),this.player?.destroy(),this.player=null}attributeChangedCallback(){this.player?.update(q(this,H,G).call(this))}get state(){return this.player?.state}play(){this.player?.play()}pause(){this.player?.pause()}};H=new WeakSet,G=function(){let t=[...this.querySelectorAll("a[href]")].map(p=>({title:p.textContent.trim(),src:p.href,artist:p.dataset.artist||void 0})),i={};for(let p of Object.keys(E.en)){let f=this.getAttribute(`label-${p.replace(/[A-Z]/g,h=>`-${h.toLowerCase()}`)}`);f!=null&&(i[p]=f)}let l=(p,f)=>{let h=Number(this.getAttribute(p));return Number.isFinite(h)&&h>0?h:f};return{tracks:t,playlist:this.getAttribute("playlist")||"",artist:this.getAttribute("artist")||"",lang:this.getAttribute("lang")||null,tab:this.getAttribute("tab")||null,pixelSize:l("pixel-size",3),bars:l("bars",12),visualizer:this.getAttribute("visualizer")!=="false",labels:i}},ee(T,"observedAttributes",["playlist","artist","lang","tab","pixel-size","bars","visualizer",...ge]);function W(e="dither-player"){typeof customElements<"u"&&!customElements.get(e)&&customElements.define(e,class extends T{})}W();globalThis.DitherPlayer=J;})();

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "dither-player",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "A small music player for personal sites: your own tracks with a 1-bit dithered visualizer, plus a tab for a playlist from Apple Music, Spotify, YouTube or SoundCloud. A custom element and a React component.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./react": {
+      "types": "./src/react.d.ts",
+      "default": "./src/react.js"
+    },
+    "./dist/dither-player.js": "./dist/dither-player.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "sideEffects": [
+    "./src/browser.js",
+    "./dist/dither-player.js"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "build": "esbuild src/browser.js --bundle --format=iife --minify --target=es2020 --legal-comments=none --outfile=dist/dither-player.js"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0"
+  },
+  "keywords": [
+    "music-player",
+    "audio-player",
+    "visualizer",
+    "dither",
+    "pixel-art",
+    "1-bit",
+    "indieweb",
+    "web-component",
+    "react"
+  ],
+  "author": "Erick Donado (https://github.com/KanuSaru)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KanuSaru/dither-player.git"
+  },
+  "homepage": "https://github.com/KanuSaru/dither-player#readme"
+}

package/src/browser.js

@@ -0,0 +1,5 @@
+// The script-tag build: registers <dither-player> and exposes the API as window.DitherPlayer.
+import * as api from "./index.js";
+
+api.defineDitherPlayer();
+globalThis.DitherPlayer = api;

package/src/element.js

@@ -0,0 +1,88 @@
+// <dither-player> custom element. The tracks are plain links inside it, so without
+// JavaScript the page still shows them as links to the files:
+//
+//   <dither-player playlist="https://music.apple.com/…" artist="Kanu">
+//     <a href="music/night-bus.mp3">Night bus</a>
+//     <a href="music/tide.mp3" data-artist="Kanu & friends">Tide</a>
+//   </dither-player>
+//
+// Attributes (all optional): playlist, artist, lang, tab, pixel-size, bars,
+// visualizer ("false" turns it off), and label-<name> to change any of the words,
+// e.g. label-faves="Songs I like".
+
+import { createPlayer } from "./player.js";
+import { LABELS } from "./labels.js";
+
+const Base = typeof HTMLElement === "undefined" ? class {} : HTMLElement;
+const LABEL_ATTRS = Object.keys(LABELS.en).map((k) => `label-${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`);
+
+export class DitherPlayerElement extends Base {
+  static observedAttributes = ["playlist", "artist", "lang", "tab", "pixel-size", "bars", "visualizer", ...LABEL_ATTRS];
+
+  connectedCallback() {
+    if (!this.shadowRoot) {
+      const root = this.attachShadow({ mode: "open" });
+      root.innerHTML = "<style>:host{display:block}</style>";
+    }
+    this.player = createPlayer(this.shadowRoot, this.#options());
+    // tracks added or removed later are picked up too
+    this.watch = new MutationObserver(() => this.player?.update(this.#options()));
+    this.watch.observe(this, { childList: true, subtree: true, attributes: true, attributeFilter: ["href", "data-artist"] });
+  }
+
+  disconnectedCallback() {
+    this.watch?.disconnect();
+    this.player?.destroy();
+    this.player = null;
+  }
+
+  attributeChangedCallback() {
+    this.player?.update(this.#options());
+  }
+
+  /** The playing state: { playing, index, track, time, duration }. */
+  get state() {
+    return this.player?.state;
+  }
+  play() {
+    this.player?.play();
+  }
+  pause() {
+    this.player?.pause();
+  }
+
+  #options() {
+    const tracks = [...this.querySelectorAll("a[href]")].map((a) => ({
+      title: a.textContent.trim(),
+      src: a.href,
+      artist: a.dataset.artist || undefined,
+    }));
+    const labels = {};
+    for (const k of Object.keys(LABELS.en)) {
+      const v = this.getAttribute(`label-${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`);
+      if (v != null) labels[k] = v;
+    }
+    const num = (name, fallback) => {
+      const v = Number(this.getAttribute(name));
+      return Number.isFinite(v) && v > 0 ? v : fallback;
+    };
+    return {
+      tracks,
+      playlist: this.getAttribute("playlist") || "",
+      artist: this.getAttribute("artist") || "",
+      lang: this.getAttribute("lang") || null, // without it, the page's language (and its changes)
+      tab: this.getAttribute("tab") || null,
+      pixelSize: num("pixel-size", 3),
+      bars: num("bars", 12),
+      visualizer: this.getAttribute("visualizer") !== "false",
+      labels,
+    };
+  }
+}
+
+/** Register the element (once). */
+export function defineDitherPlayer(name = "dither-player") {
+  if (typeof customElements !== "undefined" && !customElements.get(name)) {
+    customElements.define(name, class extends DitherPlayerElement {});
+  }
+}

package/src/embed.js

@@ -0,0 +1,40 @@
+// Turns a playlist's share link into the address of that service's own player.
+// Supported: Apple Music, Spotify, YouTube (playlists) and SoundCloud.
+
+/**
+ * @param {string} link  the link from the service's Share button
+ * @returns {{ src: string, service: string, height: number } | null}
+ */
+export function embedFor(link) {
+  let u;
+  try {
+    u = new URL(String(link || "").trim());
+  } catch {
+    return null;
+  }
+  const host = u.hostname.replace(/^www\./, "");
+
+  if (host === "music.apple.com" || host === "embed.music.apple.com") {
+    return { src: `https://embed.music.apple.com${u.pathname}${u.search}`, service: "Apple Music", height: 450 };
+  }
+  if (host === "open.spotify.com") {
+    // links can carry a locale ("/intl-es/playlist/…") that the embed doesn't take
+    const path = u.pathname.replace(/^\/intl-[a-z-]+/i, "").replace(/^\/embed/, "");
+    return { src: `https://open.spotify.com/embed${path}`, service: "Spotify", height: 352 };
+  }
+  if ((host === "youtube.com" || host === "music.youtube.com" || host === "m.youtube.com") && u.searchParams.get("list")) {
+    return {
+      src: `https://www.youtube-nocookie.com/embed/videoseries?list=${encodeURIComponent(u.searchParams.get("list"))}`,
+      service: "YouTube",
+      height: 200,
+    };
+  }
+  if (host === "soundcloud.com") {
+    return {
+      src: `https://w.soundcloud.com/player/?url=${encodeURIComponent(u.origin + u.pathname)}&visual=false&show_comments=false`,
+      service: "SoundCloud",
+      height: 360,
+    };
+  }
+  return null;
+}

package/src/index.d.ts

@@ -0,0 +1,65 @@
+export interface Track {
+  /** Shown in the player and on lock screens. */
+  title: string;
+  /** Address of the audio file (mp3, m4a, ogg…), on the same site. */
+  src: string;
+  /** Default: the player's `artist`. */
+  artist?: string;
+}
+
+export type Labels = typeof import("./labels.js").LABELS.en;
+
+export interface PlayerOptions {
+  /** Your own tracks, in order. */
+  tracks?: Track[];
+  /** Share link of a playlist (Apple Music, Spotify, YouTube or SoundCloud); adds a second tab. */
+  playlist?: string;
+  /** "en" or "es". Default: the page's language, and it follows changes to it. */
+  lang?: string | null;
+  /** Replace any of the words. `{x}` is the playlist's service. */
+  labels?: Partial<Labels> | null;
+  /** Shown on lock screens for tracks without their own artist. */
+  artist?: string;
+  /** The 1-bit spectrum above the controls. Default true. */
+  visualizer?: boolean;
+  /** Screen pixels per visualizer pixel. Default 3. */
+  pixelSize?: number;
+  /** Visualizer height, in its own pixels. Default 12. */
+  bars?: number;
+  /** Tab to open on. Default: "mine" when there are tracks. */
+  tab?: "mine" | "faves" | null;
+}
+
+export interface PlayerState {
+  playing: boolean;
+  index: number;
+  track: Track | null;
+  time: number;
+  duration: number;
+}
+
+export interface PlayerController {
+  update(options: PlayerOptions): void;
+  play(): void;
+  pause(): void;
+  select(index: number): void;
+  readonly state: PlayerState;
+  readonly audio: HTMLAudioElement;
+  destroy(): void;
+}
+
+export declare function createPlayer(container: HTMLElement | ShadowRoot, options?: PlayerOptions): PlayerController;
+
+export declare function embedFor(link: string): { src: string; service: string; height: number } | null;
+
+export declare const LABELS: { en: Labels; es: Labels };
+export declare const LANGUAGES: readonly string[];
+export declare function labelsFor(lang?: string | null, overrides?: Partial<Labels> | null): Labels;
+export declare const CSS: string;
+
+export declare class DitherPlayerElement extends HTMLElement {
+  readonly state: PlayerState | undefined;
+  play(): void;
+  pause(): void;
+}
+export declare function defineDitherPlayer(name?: string): void;

package/src/index.js

@@ -0,0 +1,5 @@
+export { createPlayer } from "./player.js";
+export { embedFor } from "./embed.js";
+export { LABELS, LANGUAGES, labelsFor } from "./labels.js";
+export { CSS } from "./styles.js";
+export { DitherPlayerElement, defineDitherPlayer } from "./element.js";

package/src/labels.d.ts

@@ -0,0 +1,7 @@
+declare const en: {
+  region: string; mine: string; faves: string; play: string; pause: string; prev: string; next: string;
+  seek: string; empty: string; noPlaylist: string; favesText: string; favesTitle: string; load: string; loadNote: string;
+};
+export declare const LABELS: { en: typeof en; es: typeof en };
+export declare const LANGUAGES: readonly string[];
+export declare function labelsFor(lang?: string | null, overrides?: Partial<typeof en> | null): typeof en;

package/src/labels.js

@@ -0,0 +1,45 @@
+// The player's words, in English and Spanish. Any of them can be replaced with the
+// `labels` option. {x} is filled in with the name of the playlist's service.
+
+export const LABELS = {
+  en: {
+    region: "Music player",
+    mine: "Mine",
+    faves: "Faves",
+    play: "Play",
+    pause: "Pause",
+    prev: "Previous track",
+    next: "Next track",
+    seek: "Position in the track",
+    empty: "No tracks yet.",
+    noPlaylist: "No playlist yet.",
+    favesText: "",
+    favesTitle: "Playlist",
+    load: "Open the playlist on {x}",
+    loadNote: "Loads {x}'s player. It plays full songs for its members and previews for everyone else.",
+  },
+  es: {
+    region: "Reproductor de música",
+    mine: "Mías",
+    faves: "Favoritas",
+    play: "Reproducir",
+    pause: "Pausar",
+    prev: "Pista anterior",
+    next: "Siguiente pista",
+    seek: "Posición en la pista",
+    empty: "Aún no hay pistas.",
+    noPlaylist: "Aún no hay playlist.",
+    favesText: "",
+    favesTitle: "Playlist",
+    load: "Abrir la playlist en {x}",
+    loadNote: "Carga el reproductor de {x}. Reproduce canciones completas a sus usuarios y fragmentos al resto.",
+  },
+};
+
+export const LANGUAGES = Object.keys(LABELS);
+
+/** Words for a language ("es", "es-CO"…, anything else is English), with overrides on top. */
+export function labelsFor(lang, overrides) {
+  const base = LABELS[String(lang || "en").slice(0, 2).toLowerCase()] ?? LABELS.en;
+  return { ...base, ...(overrides || {}) };
+}

package/src/player.js

@@ -0,0 +1,399 @@
+// The player: your own tracks with a 1-bit visualizer, plus an optional tab with a
+// playlist from Apple Music, Spotify, YouTube or SoundCloud. Plain DOM, no framework.
+
+import { embedFor } from "./embed.js";
+import { labelsFor } from "./labels.js";
+import { injectStyles } from "./styles.js";
+import { createVisualizer } from "./visualizer.js";
+
+const DEFAULTS = {
+  tracks: [], // [{ title, src, artist? }]
+  playlist: "", // share link of a playlist; adds the second tab
+  lang: null, // "en" | "es"; null = the page's language
+  labels: null, // replace any of the words (see labels.js)
+  artist: "", // shown on lock screens when a track has no artist of its own
+  visualizer: true,
+  pixelSize: 3, // screen pixels per visualizer pixel
+  bars: 12, // visualizer height, in its own pixels
+  tab: null, // "mine" | "faves" to open on; null = mine if there are tracks
+};
+
+// pixel icons on a 9×9 grid
+const ICONS = {
+  play: "M1 0h1v1h1v1h1v1h1v1h1v1H5v1H4v1H3v1H2v1H1z",
+  pause: "M1 0h2v9H1zM5 0h2v9H5z",
+  prev: "M0 0h2v9H0zM6 0h1v9H6V8H5V7H4V6H3V3h1V2h1V1h1z",
+  next: "M7 0h2v9H7zM1 0h1v1h1v1h1v1h1v3H4v1H3v1H2v1H1z",
+};
+const icon = (d) =>
+  `<svg viewBox="0 0 9 9" aria-hidden="true" shape-rendering="crispEdges" fill="currentColor"><path d="${d}"/></svg>`;
+
+const clock = (s) =>
+  !Number.isFinite(s) || s < 0 ? "0:00" : `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
+
+const fill = (text, x) => String(text).replace("{x}", x);
+
+// Browsers silence audio from other sites once a page analyses it, so the
+// visualizer only connects when every track is on this site.
+const allLocal = (list) =>
+  typeof location !== "undefined" &&
+  list.every((t) => {
+    try {
+      return new URL(t.src, location.href).origin === location.origin;
+    } catch {
+      return false;
+    }
+  });
+
+const sameTracks = (a, b) =>
+  a.length === b.length && a.every((t, i) => t.src === b[i].src && t.title === b[i].title && t.artist === b[i].artist);
+
+/**
+ * Builds the player inside `container`.
+ * @param {HTMLElement} container
+ * @param {Partial<typeof DEFAULTS>} [options]
+ */
+export function createPlayer(container, options = {}) {
+  let opts = { ...DEFAULTS, ...options };
+  let tracks = (opts.tracks || []).filter((t) => t && t.src);
+  let index = 0;
+  let tab = opts.tab || (tracks.length || !opts.playlist ? "mine" : "faves");
+  let embedOpen = false;
+  let audioCtx = null;
+  let destroyed = false;
+
+  injectStyles(container);
+  const root = document.createElement("div");
+  root.className = "dp";
+  root.setAttribute("role", "region");
+  root.innerHTML = `
+    <div class="dp-tabs" role="tablist">
+      <button type="button" role="tab" data-tab="mine"></button>
+      <button type="button" role="tab" data-tab="faves"></button>
+    </div>
+    <div class="dp-panel" role="tabpanel" data-panel="mine">
+      <div class="dp-viz"><canvas aria-hidden="true"></canvas></div>
+      <div class="dp-now"><p class="dp-title"></p><p class="dp-time"></p></div>
+      <input class="dp-seek" type="range" min="0" max="0" step="0.1" value="0">
+      <div class="dp-buttons">
+        <button type="button" data-act="prev">${icon(ICONS.prev)}</button>
+        <button type="button" data-act="toggle" class="dp-main"></button>
+        <button type="button" data-act="next">${icon(ICONS.next)}</button>
+      </div>
+      <ol class="dp-list"></ol>
+      <p class="dp-note dp-empty"></p>
+    </div>
+    <div class="dp-panel" role="tabpanel" data-panel="faves"></div>`;
+  container.appendChild(root);
+
+  const $ = (sel) => root.querySelector(sel);
+  const ui = {
+    tabs: $(".dp-tabs"),
+    tabMine: $('[data-tab="mine"]'),
+    tabFaves: $('[data-tab="faves"]'),
+    mine: $('[data-panel="mine"]'),
+    faves: $('[data-panel="faves"]'),
+    viz: $(".dp-viz"),
+    title: $(".dp-title"),
+    time: $(".dp-time"),
+    seek: $(".dp-seek"),
+    prev: $('[data-act="prev"]'),
+    toggle: $('[data-act="toggle"]'),
+    next: $('[data-act="next"]'),
+    list: $(".dp-list"),
+    empty: $(".dp-empty"),
+    now: $(".dp-now"),
+    buttons: $(".dp-buttons"),
+  };
+
+  const audio = new Audio();
+  audio.preload = "metadata";
+  const viz = createVisualizer(ui.viz.querySelector("canvas"), { pixelSize: opts.pixelSize, height: opts.bars });
+
+  const words = () =>
+    labelsFor(
+      // inside a shadow root, look from the element that holds it
+      opts.lang || (container.host ?? container).closest?.("[lang]")?.getAttribute("lang") || document.documentElement.lang,
+      opts.labels,
+    );
+
+  // ---- drawing the controls from the current state
+
+  function renderTime() {
+    const t = audio.currentTime, d = audio.duration;
+    const count = tracks.length > 1 ? `  ·  ${index + 1}/${tracks.length}` : "";
+    ui.time.textContent = `${clock(t)} / ${clock(d)}${count}`;
+    ui.seek.max = Number.isFinite(d) ? String(d) : "0";
+    ui.seek.value = String(t);
+    ui.seek.setAttribute("aria-valuetext", `${clock(t)} / ${clock(d)}`);
+  }
+
+  function renderList() {
+    ui.list.textContent = "";
+    if (tracks.length < 2) return;
+    tracks.forEach((t, i) => {
+      const li = document.createElement("li");
+      const b = document.createElement("button");
+      b.type = "button";
+      b.textContent = t.title || `Track ${i + 1}`;
+      b.addEventListener("click", () => select(i, true));
+      li.appendChild(b);
+      ui.list.appendChild(li);
+    });
+  }
+
+  function renderFaves() {
+    const w = words();
+    const embed = embedFor(opts.playlist);
+    // an open embed stays as it is (rebuilding it would stop what it's playing)
+    const open = ui.faves.querySelector("iframe");
+    if (embedOpen && embed && open?.src === embed.src) {
+      open.title = w.favesTitle;
+      return;
+    }
+    ui.faves.textContent = "";
+    if (!embed) {
+      const p = document.createElement("p");
+      p.className = "dp-note";
+      p.textContent = w.noPlaylist;
+      ui.faves.appendChild(p);
+      return;
+    }
+    if (embedOpen) {
+      const f = document.createElement("iframe");
+      f.className = "dp-embed";
+      f.src = embed.src;
+      f.height = String(embed.height);
+      f.title = w.favesTitle;
+      f.loading = "lazy";
+      f.allow = "autoplay *; encrypted-media *; fullscreen *; clipboard-write";
+      ui.faves.appendChild(f);
+      return;
+    }
+    if (w.favesText) {
+      const p = document.createElement("p");
+      p.className = "dp-note";
+      p.textContent = w.favesText;
+      ui.faves.appendChild(p);
+    }
+    const b = document.createElement("button");
+    b.type = "button";
+    b.className = "dp-load";
+    b.textContent = fill(w.load, embed.service);
+    // the service's player only loads when asked, so it costs nothing until then
+    b.addEventListener("click", () => {
+      embedOpen = true;
+      renderFaves();
+    });
+    const note = document.createElement("p");
+    note.className = "dp-small";
+    note.textContent = fill(w.loadNote, embed.service);
+    ui.faves.append(b, note);
+  }
+
+  function render() {
+    const w = words();
+    const both = tracks.length > 0 && !!embedFor(opts.playlist);
+    root.setAttribute("aria-label", w.region);
+    ui.tabs.hidden = !both;
+    ui.tabMine.textContent = w.mine;
+    ui.tabFaves.textContent = w.faves;
+    ui.tabMine.setAttribute("aria-selected", String(tab === "mine"));
+    ui.tabFaves.setAttribute("aria-selected", String(tab === "faves"));
+    // with only a playlist, it's the whole player; with only tracks, the tab is hidden
+    const showMine = both ? tab === "mine" : tracks.length > 0 || !opts.playlist;
+    ui.mine.hidden = !showMine;
+    ui.faves.hidden = showMine;
+
+    const has = tracks.length > 0;
+    for (const el of [ui.viz, ui.now, ui.seek, ui.buttons]) el.hidden = !has;
+    ui.viz.hidden = !has || !opts.visualizer;
+    ui.empty.hidden = has;
+    ui.empty.textContent = w.empty;
+    ui.prev.hidden = ui.next.hidden = ui.list.hidden = tracks.length < 2;
+    ui.prev.setAttribute("aria-label", w.prev);
+    ui.next.setAttribute("aria-label", w.next);
+    ui.toggle.setAttribute("aria-label", audio.paused ? w.play : w.pause);
+    ui.toggle.innerHTML = icon(audio.paused ? ICONS.play : ICONS.pause);
+    ui.seek.setAttribute("aria-label", w.seek);
+
+    const t = tracks[index];
+    ui.title.textContent = t ? t.title || "" : "";
+    [...ui.list.querySelectorAll("button")].forEach((b, i) => {
+      if (i === index) b.setAttribute("aria-current", "true");
+      else b.removeAttribute("aria-current");
+    });
+    renderTime();
+  }
+
+  // ---- playing
+
+  function setMeta() {
+    const t = tracks[index];
+    if (!t || typeof navigator === "undefined" || !("mediaSession" in navigator)) return;
+    try {
+      navigator.mediaSession.metadata = new MediaMetadata({ title: t.title || "", artist: t.artist || opts.artist || "" });
+    } catch {
+      /* not supported */
+    }
+  }
+
+  function select(i, play) {
+    if (!tracks.length) return;
+    index = ((i % tracks.length) + tracks.length) % tracks.length;
+    const keep = play ?? !audio.paused;
+    audio.src = tracks[index].src;
+    setMeta();
+    render();
+    if (keep) start();
+  }
+
+  function start() {
+    if (!tracks.length) return;
+    if (!audio.src) select(index, false);
+    // the analyser can only be made after a click (the browser's rule for sound)
+    if (opts.visualizer && !audioCtx && typeof AudioContext !== "undefined" && allLocal(tracks)) {
+      try {
+        audioCtx = new AudioContext();
+        const src = audioCtx.createMediaElementSource(audio);
+        const an = audioCtx.createAnalyser();
+        an.fftSize = 256;
+        an.smoothingTimeConstant = 0.75;
+        src.connect(an);
+        an.connect(audioCtx.destination);
+        viz.connect(an);
+      } catch {
+        /* no visualizer; the music still plays */
+      }
+    }
+    audioCtx?.resume?.();
+    audio.play().catch(() => {});
+  }
+
+  const toggle = () => (audio.paused ? start() : audio.pause());
+
+  // ---- events
+
+  const on = (el, type, fn) => el.addEventListener(type, fn);
+  on(ui.tabMine, "click", () => ((tab = "mine"), render()));
+  on(ui.tabFaves, "click", () => ((tab = "faves"), render()));
+  on(ui.toggle, "click", toggle);
+  on(ui.prev, "click", () => select(index - 1));
+  on(ui.next, "click", () => select(index + 1));
+  on(ui.seek, "input", () => {
+    audio.currentTime = Number(ui.seek.value);
+    renderTime();
+  });
+  on(audio, "timeupdate", renderTime);
+  on(audio, "loadedmetadata", renderTime);
+  on(audio, "durationchange", renderTime);
+  on(audio, "play", () => {
+    viz.setRunning(true);
+    render();
+  });
+  on(audio, "pause", () => {
+    viz.setRunning(false);
+    render();
+  });
+  on(audio, "ended", () => {
+    if (tracks.length > 1 && index < tracks.length - 1) select(index + 1, true);
+    else if (tracks.length > 1) select(0, false); // back to the start, stopped
+  });
+
+  const session = typeof navigator !== "undefined" && "mediaSession" in navigator ? navigator.mediaSession : null;
+  const handlers = {
+    play: () => start(),
+    pause: () => audio.pause(),
+    previoustrack: () => select(index - 1),
+    nexttrack: () => select(index + 1),
+  };
+  for (const [k, fn] of Object.entries(handlers)) {
+    try {
+      session?.setActionHandler(k, fn);
+    } catch {
+      /* action not supported */
+    }
+  }
+
+  // page language changes (a language switch) update the words
+  const langWatch =
+    typeof MutationObserver !== "undefined"
+      ? new MutationObserver(() => {
+          if (!opts.lang) {
+            render();
+            renderFaves();
+          }
+        })
+      : null;
+  langWatch?.observe(document.documentElement, { attributes: true, attributeFilter: ["lang"] });
+
+  renderList();
+  if (tracks.length) {
+    audio.src = tracks[0].src;
+    setMeta();
+  }
+  renderFaves();
+  render();
+
+  return {
+    /** Change any option; the rest keep their values. A playing track keeps playing if it's still listed. */
+    update(next = {}) {
+      if (destroyed) return;
+      const prevPlaylist = opts.playlist;
+      opts = { ...opts, ...next };
+      let nextTracks = (opts.tracks || []).filter((t) => t && t.src);
+      // once the visualizer is connected, tracks from other sites would play silent
+      if (audioCtx && !allLocal(nextTracks)) nextTracks = nextTracks.filter((t) => allLocal([t]));
+      if (!sameTracks(tracks, nextTracks)) {
+        const current = tracks[index]?.src;
+        tracks = nextTracks;
+        const found = tracks.findIndex((t) => t.src === current);
+        renderList();
+        if (found >= 0) index = found;
+        else {
+          index = 0;
+          audio.pause();
+          audio.removeAttribute("src");
+          if (tracks.length) audio.src = tracks[0].src;
+          setMeta();
+        }
+      }
+      if (opts.playlist !== prevPlaylist) embedOpen = false;
+      if (next.tab) tab = next.tab;
+      viz.resize({ pixelSize: opts.pixelSize, height: opts.bars });
+      renderFaves();
+      render();
+    },
+    play: start,
+    pause: () => audio.pause(),
+    /** Jump to a track by its position (0 = first). */
+    select: (i) => select(i, true),
+    get state() {
+      return {
+        playing: !audio.paused,
+        index,
+        track: tracks[index] ?? null,
+        time: audio.currentTime,
+        duration: Number.isFinite(audio.duration) ? audio.duration : 0,
+      };
+    },
+    /** The <audio> element, for anything not covered here. */
+    audio,
+    destroy() {
+      destroyed = true;
+      audio.pause();
+      audio.removeAttribute("src");
+      viz.destroy();
+      langWatch?.disconnect();
+      audioCtx?.close?.();
+      for (const k of Object.keys(handlers)) {
+        try {
+          session?.setActionHandler(k, null);
+        } catch {
+          /* ignore */
+        }
+      }
+      root.remove();
+    },
+  };
+}

package/src/react.d.ts

@@ -0,0 +1,9 @@
+import type { CSSProperties, ReactElement } from "react";
+import type { PlayerOptions } from "./index.js";
+
+export interface DitherPlayerProps extends PlayerOptions {
+  className?: string;
+  style?: CSSProperties;
+}
+
+export declare function DitherPlayer(props: DitherPlayerProps): ReactElement;

package/src/react.js

@@ -0,0 +1,35 @@
+"use client";
+
+// React component. Works with React 18 and 19, including Next.js (client only).
+//
+//   import { DitherPlayer } from "dither-player/react";
+//   <DitherPlayer tracks={[{ title: "Night bus", src: "/music/night-bus.mp3" }]} playlist="https://…" />
+//
+// It keeps playing across re-renders; put it in a layout to keep playing between pages.
+
+import { createElement, useEffect, useRef } from "react";
+import { createPlayer } from "./player.js";
+
+export function DitherPlayer({ className, style, tracks, playlist, lang, labels, artist, visualizer, pixelSize, bars, tab }) {
+  const box = useRef(null);
+  const player = useRef(null);
+  const opts = { tracks, playlist, lang, labels, artist, visualizer, pixelSize, bars, tab };
+  for (const k of Object.keys(opts)) if (opts[k] === undefined) delete opts[k];
+  const key = JSON.stringify(opts);
+
+  useEffect(() => {
+    player.current = createPlayer(box.current, JSON.parse(key));
+    return () => {
+      player.current?.destroy();
+      player.current = null;
+    };
+    // created once; later changes go through update()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    player.current?.update(JSON.parse(key));
+  }, [key]);
+
+  return createElement("div", { ref: box, className, style });
+}

package/src/styles.js

@@ -0,0 +1,69 @@
+// Default look. Everything follows the text color it sits in; restyle it with these
+// CSS variables on the player or any parent (all optional):
+//   --dp-ink     lines, icons, bars and filled buttons         (default: the text color)
+//   --dp-muted   secondary text                                (default: text color at 62%)
+//   --dp-line    borders                                       (default: text color at 22%)
+//   --dp-accent  hover and focus                               (default: the ink)
+//   --dp-on-ink  text and icons on filled buttons              (default: Canvas, the page background)
+//   --dp-mono    font for times and tabs                       (default: the system monospace)
+//
+// The defaults live in var() fallbacks, never as declarations, so values set on a
+// parent always win. Filled buttons get their fill from box-shadow in the ink color,
+// and their text/icon color separately, so the two can never collapse into one.
+
+const INK = "var(--dp-ink, currentColor)";
+const MUTED = "var(--dp-muted, color-mix(in srgb, currentColor 62%, transparent))";
+const LINE = "var(--dp-line, color-mix(in srgb, currentColor 22%, transparent))";
+const ACCENT = "var(--dp-accent, var(--dp-ink, currentColor))";
+const ON_INK = "var(--dp-on-ink, Canvas)";
+const MONO = "var(--dp-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace)";
+
+export const CSS = `
+.dp{display:grid;grid-template-columns:minmax(0,1fr);gap:.6rem;min-width:0}
+.dp [hidden]{display:none!important}
+.dp button{font:inherit;color:inherit;cursor:pointer}
+.dp button:focus-visible,.dp input:focus-visible{outline:2px solid ${ACCENT};outline-offset:2px}
+.dp-tabs{display:flex}
+.dp-tabs button{flex:1;font-family:${MONO};font-size:.95em;line-height:1;padding:.35em .5em;color:${MUTED};background:transparent;border:1px solid ${LINE}}
+.dp-tabs button+button{border-left:none}
+.dp-tabs button[aria-selected=true]{color:${INK};border-color:${INK};box-shadow:inset 0 0 0 3em ${INK};-webkit-text-fill-color:${ON_INK}}
+.dp-panel{display:grid;grid-template-columns:minmax(0,1fr);gap:.5rem;min-width:0}
+.dp-viz{min-width:0;overflow:hidden;color:${INK};border-bottom:1px solid ${LINE};padding-bottom:2px}
+.dp-viz canvas{display:block;image-rendering:pixelated}
+.dp-now{display:grid;gap:.1rem;min-width:0}
+.dp-title{margin:0;font-weight:700;line-height:1.25;overflow-wrap:anywhere}
+.dp-time{margin:0;font-family:${MONO};font-size:.95em;line-height:1.1;color:${MUTED};font-variant-numeric:tabular-nums;white-space:pre}
+.dp-seek{-webkit-appearance:none;appearance:none;width:100%;height:14px;margin:0;color:${INK};background:transparent;cursor:pointer}
+.dp-seek::-webkit-slider-runnable-track{height:2px;background:${LINE}}
+.dp-seek::-moz-range-track{height:2px;background:${LINE}}
+.dp-seek::-moz-range-progress{height:2px;background:currentColor}
+.dp-seek::-webkit-slider-thumb{-webkit-appearance:none;width:10px;height:10px;margin-top:-4px;background:currentColor;border:0;border-radius:0}
+.dp-seek::-moz-range-thumb{width:10px;height:10px;background:currentColor;border:0;border-radius:0}
+.dp-buttons{display:flex;gap:.4rem}
+.dp-buttons button{display:grid;place-items:center;width:2.25rem;height:2.25rem;padding:0;color:${INK};background:transparent;border:1px solid ${LINE}}
+.dp-buttons button.dp-main{border-color:${INK};box-shadow:inset 0 0 0 3em ${INK}}
+.dp-buttons button.dp-main svg{color:${ON_INK}}
+.dp-buttons button:hover{border-color:${ACCENT}}
+.dp-buttons svg{width:13px;height:13px}
+.dp-list{margin:0;padding:.35rem 0 0;list-style:none;display:grid;border-top:1px dashed ${LINE}}
+.dp-list button{width:100%;text-align:left;font-size:.875em;color:${MUTED};background:none;border:0;padding:.15rem 0}
+.dp-list button[aria-current=true]{color:inherit}
+.dp-list button[aria-current=true]::before{content:"\\25B8\\00A0";color:${ACCENT}}
+.dp-note{margin:0;font-size:.875em;color:${MUTED}}
+.dp-small{margin:0;font-size:.8em;color:${MUTED}}
+.dp-load{justify-self:start;font-size:.95em;background:transparent;border:1px solid ${LINE};padding:.35em .6em}
+.dp-load:hover{border-color:${ACCENT}}
+.dp-embed{display:block;width:100%;border:0}
+`;
+
+/** Put the styles in the document (or the shadow root) the player lives in, once. */
+export function injectStyles(el) {
+  if (typeof document === "undefined") return;
+  const root = el.getRootNode?.() ?? document;
+  const target = root instanceof Document ? root.head : root;
+  if (!target || target.querySelector?.("style[data-dither-player]")) return;
+  const style = document.createElement("style");
+  style.setAttribute("data-dither-player", "");
+  style.textContent = CSS;
+  target.prepend(style);
+}

package/src/visualizer.js

@@ -0,0 +1,105 @@
+// A 1-bit spectrum: one column per frequency band, dense at the bottom and thinning
+// out toward the top, ordered-dithered with the same 4×4 Bayer grid as dither-moon.
+
+const BAYER = [0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5].map((v) => (v + 0.5) / 16);
+
+function inkOf(el) {
+  const m = getComputedStyle(el).color.match(/[\d.]+/g);
+  return m ? m.slice(0, 3).map(Number) : [230, 226, 214];
+}
+
+/**
+ * @param {HTMLCanvasElement} canvas
+ * @param {{ pixelSize: number, height: number }} size  screen pixels per bar pixel, rows
+ */
+export function createVisualizer(canvas, size) {
+  const ctx = canvas.getContext("2d");
+  const still = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+  let analyser = null;
+  let bins = new Uint8Array(0);
+  let levels = [];
+  let running = false;
+  let frame = 0;
+  let visible = true;
+
+  function fit() {
+    const box = canvas.parentElement;
+    const W = Math.max(8, Math.floor((box?.clientWidth || 120) / size.pixelSize));
+    const H = Math.max(3, size.height);
+    if (canvas.width !== W || canvas.height !== H) {
+      canvas.width = W;
+      canvas.height = H;
+      canvas.style.width = `${W * size.pixelSize}px`;
+      canvas.style.height = `${H * size.pixelSize}px`;
+    }
+    if (levels.length !== W) levels = new Array(W).fill(0);
+  }
+
+  function draw() {
+    fit();
+    const W = canvas.width, H = canvas.height;
+    const live = running && analyser && !still;
+    if (live) analyser.getByteFrequencyData(bins);
+    const ink = inkOf(canvas);
+    const img = ctx.createImageData(W, H);
+    let moving = false;
+    for (let x = 0; x < W; x++) {
+      // columns spread over the bands on a log scale, closer to how we hear
+      const b = Math.min(bins.length - 1, Math.floor(Math.pow(bins.length || 1, x / W)));
+      const target = live && b >= 0 ? bins[b] / 255 : 0;
+      levels[x] += (target - levels[x]) * (target > levels[x] ? 0.6 : 0.15);
+      if (levels[x] > 0.01) moving = true;
+      const v = Math.max(1 / H, 0.9 * levels[x]) * H;
+      for (let y = 0; y < H; y++) {
+        const fill = Math.min(1, Math.max(0, v - y)) * (1 - (0.6 * y) / H);
+        if (fill > BAYER[(y & 3) * 4 + (x & 3)]) {
+          const i = ((H - 1 - y) * W + x) * 4;
+          img.data[i] = ink[0];
+          img.data[i + 1] = ink[1];
+          img.data[i + 2] = ink[2];
+          img.data[i + 3] = 255;
+        }
+      }
+    }
+    ctx.putImageData(img, 0, 0);
+    return moving;
+  }
+
+  function loop() {
+    frame = 0;
+    const moving = visible ? draw() : true;
+    if (running || moving) frame = requestAnimationFrame(loop);
+  }
+
+  const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(() => draw()) : null;
+  if (canvas.parentElement) ro?.observe(canvas.parentElement);
+  const io =
+    typeof IntersectionObserver !== "undefined"
+      ? new IntersectionObserver(([e]) => {
+          visible = e.isIntersecting;
+        })
+      : null;
+  io?.observe(canvas);
+  draw();
+
+  return {
+    connect(node) {
+      analyser = node;
+      bins = new Uint8Array(node.frequencyBinCount);
+    },
+    setRunning(on) {
+      running = on;
+      if (!frame) frame = requestAnimationFrame(loop);
+    },
+    resize(next) {
+      Object.assign(size, next);
+      draw();
+    },
+    redraw: draw,
+    destroy() {
+      cancelAnimationFrame(frame);
+      ro?.disconnect();
+      io?.disconnect();
+    },
+  };
+}