Lexicon

Episode

place.pod.episode

A single podcast episode.

Required properties

5 fields
showUri
uri Required

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

title
string Required

Title of the episode.

description
string Required

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

audioUrl
uri Required

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

createdAt
datetime Required

ISO 8601 timestamp of when the episode record was created.

Optional properties

10 fields
audioMimeType
string Optional

MIME type of the audio file. Common values: audio/mpeg, audio/wav, audio/aac.

audioSizeBytes
integer Optional

File size of the audio asset in bytes. Useful for download progress indicators.

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.

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",
  "explicit": false
}

Best practices

  • Always reference a valid, resolvable showUri. Broken references will cause episodes to be orphaned in directories.
  • Include durationSeconds whenever possible. Players rely on this for timeline rendering and resume tracking.
  • Provide transcriptUrl when available. Transcripts significantly improve accessibility and search indexing.
  • Use consistent audio formats and MIME types across episodes to simplify client implementations.