One player for every release

This feature requires the release-player API, browser app and database migration. Documentation or a player ID alone does not activate it. Use the existing authenticated Recoup API or MCP. Select an artist from your authorized roster, then call create_release_player with its artistId, a release name, at least one of spotifyUrl or appleUrl, and the website’s allowedOrigins. Select organizationId for an authorized organization workspace; ownership comes from authentication.

{
  "artistId": "ARTIST_ACCOUNT_UUID",
  "organizationId": "ORGANIZATION_UUID",
  "name": "Release title",
  "spotifyUrl": "https://open.spotify.com/album/ALBUM_ID",
  "appleUrl": "https://music.apple.com/us/album/release/APPLE_ID",
  "allowedOrigins": ["https://artist.example", "https://www.artist.example"]
}

The returned player is disabled by default. Review its destinations and approved origins, then explicitly publish using update_release_player with id, the current revision, and enabled: true. Publishing requires an active paid Recoup workspace. Destination, artwork, title and origin edits use the same operation; owner/artist attribution is immutable. Updates invalidate active sessions so changed configuration cannot silently collect under old permissions. Recoup returns listenUrl, spotifyEmbedUrl, and appleEmbedUrl. Only offer providers configured for that release. The listening page needs no custom website build. Add source, medium, campaign, and content query parameters to campaign links. The hosted listening page also accepts their utm_ equivalents. They are bounded campaign labels, not fields for personal information.

<iframe
  src="https://app.recoupable.dev/listen/PLAYER_UUID/spotify?parent=https%3A%2F%2Fartist.example&source=instagram&campaign=release"
  title="Recoup music player"
  allow="autoplay; encrypted-media"
></iframe>

The website sends a player ID and its exact origin, not a provider token, email, owner ID or arbitrary release override. Recoup handles provider authorization, playback and reporting. Display the direct DSP destination as a fallback for unavailable browser playback. For a listening-only player, a verified Spotify Premium account stays in the browser player. By default, a verified Spotify Free account automatically opens the configured release in Spotify after authorization; no extra playback click is required in Recoup. An unavailable profile lookup is not treated as proof of a Free account. Spotify chooses whether the destination opens in its app or website, and its Free-account playback rules still apply. The release owner can instead select freePlayback: "audio" and supply audioUrl. Upload an MP3 or WAV through the authenticated POST /api/sites/assets endpoint in the same workspace (currently up to 4 MB), then pass its returned asset.url to create_release_player or update_release_player. Recoup verifies workspace ownership, object existence and audio metadata. Audio mode also requires a Spotify destination for fallback. Fans do not select this policy, and embed query parameters cannot override it.

{
  "id": "PLAYER_UUID",
  "revision": 1,
  "freePlayback": "audio",
  "audioUrl": "WORKSPACE_UPLOADED_ASSET_URL"
}

After a verified Free-account sign-in, audio mode opens the uploaded-file controls in Recoup. Premium keeps Spotify streaming. If the file is absent, Free accounts open Spotify; if the file fails to load, the player offers the existing Open in Spotify link. This version plays one uploaded file per release player, not an uploaded playlist. Uploaded-file playback does not generate Spotify streams and is excluded from the DSP playback reports; fan connection reporting still applies. Switch back using freePlayback: "spotify"; optionally clear audioUrl to null in the same update. Embedded websites must handle the recoup:open-dsp message with provider: "spotify", verify both the player origin and iframe window, then navigate to their configured Spotify destination. Do not accept a destination URL from the message. Gatsby implements this handler. Recoup can capture the available fan profile before this handoff, but playback after leaving the player is outside its listening telemetry. get_release_player_fans returns available Spotify-confirmed profile/email across this artist’s releases in the same workspace. get_release_player_activity returns 30-day campaign totals and paginated fan-linked track/play/pause/skip activity. Apple Music sessions are anonymous in this version; they do not capture an email or connect to a Spotify fan identity. Events cover this player while it is open, not listening elsewhere in the DSP. Sign-in does not grant email marketing consent. Keep any explicit updates signup separate. Reported listening time and play events are not confirmed DSP streams or evidence of causal stream uplift. Use catalog stream measurements separately for that question.

Deployment configuration

The API owns SITES_SPOTIFY_CLIENT_ID and the optional PLAYER_APP_ORIGIN (default https://app.recoupable.dev). Register ${PLAYER_APP_ORIGIN}/s/spotify/callback on the same Spotify developer app. Session signing uses PLAYER_SESSION_SECRET, or the API’s existing service-role key with a separate signing context. Never expose either signing key. The browser app uses the existing server-only SITES_API_URL override for a local/preview API. Provider credentials stay on the trusted player origin. Existing Apple developer signing credentials supply the short-lived, origin-bound browser token. Apply release-player migrations 20261010060000 through 20261010060004, release the API and browser app, register and enable the player’s destinations/origins, then verify actual provider authorization, fan readback, playback and activity readback before declaring a campaign live. For the Gatsby Grace artist website (a Next.js app, not the Gatsby framework), set NEXT_PUBLIC_RECOUP_PLAYER_ID and NEXT_PUBLIC_RECOUP_WISH_PLAYER_ID to the corresponding registered player IDs. Until configured, Gatsby retains its direct DSP links.

​Deployment configuration

Deployment configuration