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?

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

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"
  }
}

© 2024 npr