Release players
One player for every release
Create a listening page or embed Spotify and Apple Music playback on your artist website.
On this page
Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting.
Create and publish
Use the Recoup API or the create_release_player MCP tool. Choose an artist you can access, name the player, and provide a spotifyUrl, an appleUrl, or both. Use organizationId to create it in your organization workspace.
For website embeds, add the exact website origins to allowedOrigins. An origin includes the scheme, hostname and any non-default port, such as https://artist.example:8443. Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page.
Example create request:
{
"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"]
}New players start unpublished. Review the music links, then publish with update_release_player, passing id, the current revision, and enabled: true. Publishing requires an active paid Recoup workspace.
Use the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect.
See update a release player for the REST request and fields.
Share a listening page
Use the returned listenUrl as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player.
To track campaign traffic, add source, medium, campaign, and content query parameters. The listening page also accepts utm_source, utm_medium, utm_campaign, and utm_content. Use campaign labels, such as instagram and release; keep personal information out of links.
Embed on your website
Use the returned spotifyEmbedUrl or appleEmbedUrl for each configured service. The parent parameter must match an approved website origin.
<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>Keep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable.
For Spotify Free handoffs, the embed sends a recoup:open-dsp message with provider: "spotify". Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message.
What fans can play
Spotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify.
Spotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free.
Apple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup.
Optional uploaded audio for Spotify Free fans
You can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set freePlayback: "audio" and provide audioUrl. This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify.
Upload an MP3 or WAV through POST /api/sites/assets in the same workspace, then use the returned asset.url. The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback.
MCP arguments for update_release_player:
{
"id": "PLAYER_UUID",
"revision": 1,
"freePlayback": "audio",
"audioUrl": "WORKSPACE_UPLOADED_ASSET_URL"
}For REST, send PATCH /api/players/PLAYER_UUID with the same body except id; the player ID belongs in the URL.
Audio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link.
To restore the Spotify handoff, set freePlayback: "spotify". You can also clear audioUrl by setting it to null.
Fan contacts belong to your workspace
Spotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace.
If that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans.
- Use
get_workspace_player_fansor read workspace player fans to list contacts and their artist relationships. - Use
get_release_player_fansor read artist player fans to list fan relationships across that artist's players in the workspace.
contact_id identifies the workspace contact. Each artist relationship has its own id; activity records refer to that relationship as fan_id.
Spotify sign-in does not grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts.
Measure listening activity
Use get_release_player_activity or read listening activity for 30-day campaign totals and individual track, play, pause and skip events.
These reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are not confirmed music-service stream counts and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance.
Check your fan journey
Before promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace.