Profile: audio

Profile Schema

An audio document represents an audio resource. Audio resources contain 0 or more links to audio files themselves, as well as metadata about the audio and its intended use.

The audio profile is intended to be used as “type” profile.

Structure

The audio profile requires the following attributes:

  • enclosures - An array of links to the audio files themselves. See the “Enclosures” section below.
  • isAvailable - Is this audio available? This will be false for audio that has not been fully processed yet.
  • isDownloadable - Should this audio be available for download?
  • isEmbeddable - Should this audio be available for rendering in an embedded player?
  • isStreamable - Should this audio be available for streaming? Please only use this if your audio is streaming audio and also meant for an On Air type of show See more below

In addition, audio specifies a number of optional attributes:

  • title - The title of the audio.
  • source - An identifier (e.g., GUID, filename, or URL) to use to direct one back to the audio source.
  • duration - The duration of this audio in seconds (if known); this value must be >= 1.
  • availabilityMessage - What message should be displayed based on this audio’s availability? (ex: “Audio will become available later today”)
  • songTitle - If this audio contains a song, the title of the song.
  • songArtist - If this audio contains a song, the artist of the song.
  • songTrackNumber - If this audio contains a song, the number of the track in the collection this song appears in.
  • albumTitle - If this audio contains a song, the title of the album it appears on.
  • albumArtist - If this audio contains a song, the artist of the album it appears on.
  • streamExpirationDateTime - The date and time at which this stream should no longer be served in RFC3339 format set in UTC time (ex: 2021-11-04T08:49:00Z). See our tutorial on UTC time for more help.
  • transcriptLink - A link to a CDS document representing the transcript of this audio; this link is not guaranteed valid. Clients should follow the link to confirm the document’s existence before rendering. This link must contain an extension rel, and can optionally have an always-display rel. These strings are to be contained in the rels property array.
  • transcriptWebPageLink - A link to a web page displaying the transcript of this audio. This link cannot have rels.
  • embeddedPlayerLink - A link to a web page displaying an embedded audio player for this audio. This link cannot have rels.

Enclosures

Each enclosure in the audio document represents a link to an audio file. Each link object is represented by the following attributes:

Name Type Required? Explanation
fileSize integer No The size (in bytes) of the linked audio file
href string Yes The string URL of the audio file itself; must use the http or https scheme
rels string array No A set of strings describing the relationship between the current document and the linked document
type string No The media type of the linked file (ex: audio/wav)

An example enclosure link is below:

{
  "href": "https://npr-audio-host.org/audio-files/the-podcast/episode-1.mp3",
  "rels": [
    "sponsored",
    "tracked"
  ],
  "type": "audio/mpeg",
  "fileSize": 50000000
}

Audio enclosure rels

Currently, the following rel values are used in enclosure links:

  • sponsored - Indicates the linked file contains sponsorship messages
  • tracked - Indicates the linked file contains tracking for analytics purposes
  • premium - Indicates the linked file is “premium” audio intended for subscribing users only

An important note about isStreamable

The use case for setting isStreamable to true is when you have a Live broadcast audio to play for clients. This could be:

  • A radio station live stream
  • A live broadcast of a show

Simply having HLS or other streamable audio does not qualify here for isStreamable. You should (In cases where there’s HLS audio but it is not a station stream or live show) use an enclosure for HLS but without setting isStreamable to true.

An example of why this is important:

The NPR App will display a On Air icon for any content that has isStreamable set to true. If your audio is just streaming but not actually “On Air” then that would be a confusing experience for the user in the NPR App.

Example audio document 

{
  "id": "12345",
  "profiles": [
    {
      "href": "/v1/profiles/audio",
      "rels": [
        "type"
      ]
    },
    {
      "href": "/v1/profiles/document"
    }
  ],
  "tile": "Episode 1: How we made a podcast",
  "source": "77e9d521-3340-47ea-a3d8-b10b98b1e481",
  "enclosures": [
    {
      "href": "https://npr-audio-host.org/audio-files/the-podcast/episode-1.mp3",
      "rels": [
        "sponsored",
        "tracked"
      ],
      "type": "audio/mpeg",
      "fileSize": 50000000
    }
  ],
  "duration": 360,
  "isAvailable": true,
  "isDownloadable": true,
  "isStreamable": true,
  "availabilityMessage": "This audio is available.",
  "transcriptLink": {
    "href": "/v1/documents/12345-transcript",
    "rels": [
      "extension",
      "always-display"
    ]
  },
  "transcriptWebPageLink": { 
    "href": "https://the-podcast.com/episode-1/transcript.html" 
  },
  "embeddedPlayerLink": { 
    "href": "https://the-podcast.com/episode-1/player.html"
  }
}

© 2025 npr