Lexicon

Episode

place.pod.episode

A single podcast episode.

Lexicon schema Example record

Required properties

7 fields
showUri
uri Required

AT Protocol URI of the parent place.pod.show record.

title
string Required

Title of the episode.

audioUrl
uri Required

Direct URL to the audio file. Must be publicly accessible and use HTTPS.

guid
string Required

Globally unique, immutable episode identifier required by Apple and PSP.

audioMimeType
string Required

MIME type for the RSS enclosure, such as audio/mpeg or audio/mp4.

audioSizeBytes
integer Required

Audio file size in bytes for the RSS enclosure length attribute.

createdAt
datetime Required

ISO 8601 timestamp of when the episode record was created.

Optional properties

16 fields
description
string Optional

Summary or show notes for the episode. May contain basic formatting.

durationSeconds
integer Optional

Length of the episode in whole seconds. Strongly recommended for player UX.

episodeNumber
integer Optional

Episode number within the season or series.

seasonNumber
integer Optional

Season number the episode belongs to.

publishedAt
datetime Optional

ISO 8601 timestamp when the episode was published. May differ from createdAt.

explicit
boolean Optional

Whether this specific episode contains explicit content. Defaults to false if omitted.

imageUrl
uri Optional

Episode-specific artwork URL. Falls back to show cover if omitted.

transcriptUrl
uri Optional

URL to a transcript file. Improves accessibility and searchability.

chaptersUrl
uri Optional

URL to a chapters file. Accepts JSON or WebVTT formats.

transcriptMimeType
string Optional

MIME type for transcriptUrl; required when exporting podcast:transcript.

chaptersMimeType
string Optional

MIME type for chaptersUrl; required when exporting podcast:chapters.

link
uri Optional

Public webpage for the episode, corresponding to the RSS item link.

episodeType
string Optional

Apple episode type: full, trailer, or bonus. Full is the default when omitted.

people
array Optional

Structured episode credits such as hosts, guests, and producers.

alternateEnclosures
array Optional

Optional Podcasting 2.0 alternate media files with technical metadata.

soundbites
array Optional

Optional Podcasting 2.0 highlights with start times and durations.

Example record

JSON 
{
  "$type": "place.pod.episode",
  "showUri": "at://did:plc:abc123/place.pod.show/self",
  "title": "Episode 42: Open Standards",
  "description": "We discuss the importance of open protocols in podcasting.",
  "audioUrl": "https://cdn.example.com/ep42.mp3",
  "createdAt": "2024-01-20T08:00:00.000Z",
  "durationSeconds": 3600,
  "audioMimeType": "audio/mpeg",
  "audioSizeBytes": 52428800,
  "guid": "episode-42-open-standards",
  "explicit": false
}

Best practices

  • Always reference a valid, resolvable showUri. Broken references will cause episodes to be orphaned in directories.
  • Keep guid stable forever. Apple and other major directories use it to prevent duplicate listings.
  • Provide audioMimeType and audioSizeBytes so an RSS exporter can produce a complete enclosure tag.
  • Include durationSeconds whenever possible. Players rely on this for timeline rendering and resume tracking.
  • When providing transcriptUrl or chaptersUrl, also provide its MIME type so Podcasting 2.0 clients can consume it.
  • Use consistent audio formats and MIME types across episodes to simplify client implementations.