PlayBase

The parts of a play common to every route that returns one. Concrete responses use Play or SearchPlay, which add the station.

idstringrequired

The play id. Numeric, but always serialized as a string. Every subsequent call about this play (start, elapse, complete, skip, invalidate, like, dislike, unlike) is addressed by this id.

Example: 1122334455

audio_file objectrequired

A single playable, transcoded audio file plus its music metadata. Several properties are emitted only when they apply, so their absence is meaningful — see the individual descriptions.

idstringrequired

The Feed.fm audio file id. Numeric, but always serialized as a string.

Example: 9876543

duration_in_secondsintegerrequired

Playback length of the file, in whole seconds.

Example: 213

codecstringrequired

The codec of the delivered file, e.g. mp3 or aac. Selected from the formats the caller asked for.

Example: mp3

urluri

The URL to stream or download. This may be a CloudFront-signed URL that expires roughly 20 minutes after it was issued, so it should be used promptly and never cached long-term. Absent when the play was created without a resolvable URL. If this URL is unplayable because it has expired (it has an Expires query parameter that is a unix epoch timestamp, and it is in the past), then a new POST /play request should be made to generate a new, valid, URL rather than a call to POST /play/{play_id}/invalidate.

Signed URLs include app_id (the authenticated application's ID), client_id (the resolved client's UUID), and, when available, audio_file_id and play_id in the query string. These IDs are covered by the CloudFront signature. Use the complete URL as returned: changing any ID invalidates the URL. These URLs are not bound to an IP address; their 20-minute expiry still applies.

bitrateinteger

Delivered bitrate in kbps. Emitted only when the underlying play has a known bitrate.

Example: 128

track objectrequired

The individual song an audio file renders.

idstringrequired

The Feed.fm track id. Numeric, but always serialized as a string.

Example: 1234567

titlestringrequired

The song title.

Example: Real Live Flesh

release objectrequired

The album the track was released on. Named release throughout the API; there is no album key.

idstringrequired

The Feed.fm release id. Numeric, but always serialized as a string.

Example: 89012

titlestringrequired

The album title.

Example: Kissing The Beehive

artist objectrequired

The performing artist for a track.

idstringrequired

The Feed.fm artist id. Numeric, but always serialized as a string.

Example: 345

namestringrequired

The artist name.

Example: Kissing The Beehive

extra objectrequired

Free-form per-file metadata stored alongside the audio file and passed through verbatim. The keys vary by catalog and by client; treat any key not documented here as optional and unstable. Commonly seen keys include trim_start and trim_end.

property name*any

likedboolean

Present and true when this client has liked the track. The key is omitted entirely when the track is not liked — it is never sent as false, so callers must test for presence rather than for value.

Possible values: [true]

can_seekboolean

Present and true when the licensing for this play permits seeking within the file. Omitted entirely otherwise; never sent as false.

Possible values: [true]

can_cacheboolean

Present and true when the file may be cached locally for offline playback. Omitted entirely otherwise; never sent as false.

Possible values: [true]

previewboolean

Present and true when this play is a preview rather than a reportable play. Omitted entirely otherwise; never sent as false.

Possible values: [true]

replaygain_track_gainnumber

ReplayGain track adjustment in dB, to be applied by the player for consistent loudness. Emitted only when a non-zero value is known.

Example: -6.5

start_atnumber

Offset in seconds the player should start at, rather than the beginning of the file. Emitted only when non-zero.

Example: 30

PlayBase
{
  "id": "1122334455",
  "audio_file": {
    "id": "9876543",
    "duration_in_seconds": 213,
    "codec": "mp3",
    "url": "string",
    "bitrate": 128,
    "track": {
      "id": "1234567",
      "title": "Real Live Flesh"
    },
    "release": {
      "id": "89012",
      "title": "Kissing The Beehive"
    },
    "artist": {
      "id": "345",
      "name": "Kissing The Beehive"
    },
    "extra": {},
    "liked": true,
    "can_seek": true,
    "can_cache": true,
    "preview": true,
    "replaygain_track_gain": -6.5
  },
  "start_at": 30
}