Play

A play as returned by the play routes.

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

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.

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

station object

The abbreviated station stamped onto a play — just enough for a player to label what is playing and to record which station it came from. The full object is Station.

idstringrequired

The station id. Numeric, but always serialized as a string. This value is specific to placement, and it should never be persisted outside of a single session - use uuid for long term station references.

Example: 727

namestringrequired

The station's display name.

Example: Pop Rock

uuidstringrequired

The station's stable external identifier — the one to persist, since id above changes with the placement.

Example: FgT1_Yzvr_e05ANk2uCYdZi

pre_gainnumbernullable

Station-level gain adjustment in dB, to be applied before playback. null when the station has no adjustment configured.

Play

{
  "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,
  "station": {
    "id": "727",
    "name": "Pop Rock",
    "uuid": "FgT1_Yzvr_e05ANk2uCYdZi",
    "pre_gain": 0
  }
}