Ship a player
in 30 seconds.

THREE STEPS TO LIVE

You'll have a working player on your page before your coffee's cold. No account migration, no SDK install — just the dashboard and a snippet.

THE EMBED SNIPPET

One tag does all of it. Copy this from the dashboard with your real ID swapped in:

embed.html<!-- drop where you want the player -->
<script src="https://cil101101.com/shop/resona/embed/p.js"
        data-player="PLAYER_ID"></script>

ATTRIBUTES

With data-api set, the loader resolves the player from {data-api}/api/player/{id} instead of the default host. Everything else — skin, accent, tracks — still comes from that player's saved config.

THREE SKINS, ONE PLAYER

Pick a skin per player in the dashboard. Every skin shares the same engine — auto-theme, persistent playback, synced lyrics — they just differ in footprint.

The skin is stored on the player, so the API returns it as the skin field — the loader reads it and renders the matching layout. Custom skins and overrides are a Pro feature (see below).

THE COVER DRIVES THE COLOR

Resona's signature trick: on each track change the player samples the dominant color from that track's cover art on a canvas, boosts its saturation, and hot-swaps it in as the live accent. Progress bar, play button glow, controls and ambient tint all shift to match the artwork — so every track ships its own mood, automatically.

HOW IT WORKS

• The cover loads with crossorigin="anonymous" so it can be read on a canvas.
• Mid-luminance pixels are averaged (pure black and blown-out white are ignored) to find the real dominant tone.
• That color is pushed onto the --accent CSS variable, and everything tinted by it transitions smoothly.
• If the canvas is CORS-tainted (cover host sends no CORS headers), it silently falls back to the player's saved accent.

OVERRIDE IT

Want your brand color locked in regardless of artwork? Set a fixed accent on the player in the dashboard. When an accent is set, the API returns it as accent and the player uses it as-is — auto-extraction is skipped, so the look stays consistent across every track.

MANAGING PLAYLISTS

Everything about a player — its tracks, order, skin, accent, autoplay, and lyrics — lives in the dashboard. You never touch the embed again after pasting it; edits propagate to every page running that player.

IN THE DASHBOARD YOU CAN

• Add tracks by pasting an audio URL plus a cover URL — no uploads, no storage limits.
• Reorder the queue by drag — the pos field sets play order in the API response.
• Attach synced lyrics (an LRC string per track) for line-by-line highlight and auto-scroll (Pro).
• Set the skin and accent, toggle autoplay, and remove Resona branding (Pro).
• Watch play analytics — per-player play counts roll up from the /play beacon.

OPEN THE DASHBOARD →

PUBLIC API

The embed loader talks to a small public API. You can call it directly too — for a custom front-end, server-side render, or your own analytics. The base URL is https://resona.a0916897655.workers.dev (override per-embed with data-api).

GET  /api/player/:id

Returns a player's public config and ordered tracks. No auth — this is what the embed fetches on load.

GET /api/player/abc123 → 200{
  "id": "abc123",
  "name": "Summer Singles",
  "skin": "cover",            // classic | mini | cover
  "accent": null,              // hex to pin, or null = auto-theme
  "autoplay": false,
  "tracks": [
    {
      "pos": 1,
      "title": "Midnight Drive",
      "artist": "Kō Aoki",
      "src_url": "https://cdn.example.com/midnight.mp3",
      "cover_url": "https://cdn.example.com/midnight.jpg",
      "lrc": "[00:12.40]Headlights on the coast road\n..."
    }
  ]
}

POST  /api/player/:id/play

A fire-and-forget play-count beacon — the player pings it when a track starts. No auth, no body required; send the track position if you want per-track counts.

POST /api/player/abc123/play// request body (optional)
{ "pos": 1 }

// → 204 No Content

Call it yourself with a one-liner:

beacon.jsfetch("https://resona.a0916897655.workers.dev/api/player/abc123/play", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ pos: 1 })
});

OWNER ROUTES

Creating players, editing tracks, reading analytics and every other write operation lives behind owner routes. These require a Firebase Bearer token and are managed for you inside the dashboard — there's no public write API to wire up by hand.

FAQ & FIXES