org.atpodcasting.episode Documentation (EN)

main record

A podcast episode. Record key is a UUIDv5 derived from the podcast GUID (as namespace) and the episode's feedItemGuid (as name), enabling deterministic lookup from RSS feed metadata.

Record Key any Any valid record key

Properties

alternateMedia array of ref #mediaRef Optional

Alternate versions of the episode media (e.g. different formats or audio-only versions of video episodes).

maxLength: 10 items

artwork blob Optional

Episode-specific artwork. Overrides the podcast artwork when set. Recommended: 1400x1400 to 3000x3000 pixels, square, no alpha channel.

maxSize: 5.0 MB

chapters ref #chaptersRef Optional

Reference to an externally hosted chapters file.

createdAt string datetime Required

When the episode record was created.

description string Optional

A description or show notes for the episode.

maxLength: 10000 bytes

duration integer Required

Duration of the episode in seconds.

minimum: 1

episodeNumber integer Optional

Episode number within its season or the overall series.

minimum: 1

episodeType string Optional

The type of episode. Defaults to full.

Known values: full, trailer, bonus

explicit boolean Optional

Whether the episode contains explicit content. Overrides the podcast-level setting when set.

feedItemGuid string Required

The original feed item identifier. Must match the <guid> element of the corresponding RSS feed item. The record key (rkey) is derived from this value as uuid5(<podcast:guid>, feedItemGuid).

maxLength: 2000 bytes

link string uri Optional

URL of a companion webpage or show notes page for the episode.

media ref #mediaRef Required

The primary media file for the episode.

podcast ref org.atpodcasting.defs#podcastRef Required

Identifies the parent podcast. Since episodes live in the same repository as their podcast, the AT URI is always derivable from the episode's DID and the podcastGuid.

publishedAt string datetime Required

When the episode was published.

seasonNumber integer Optional

Season number of the episode.

minimum: 1

title string Required

The title of the episode.

maxLength: 500 bytes

transcript array of ref #transcriptRef Optional

References to externally hosted transcript files (e.g. VTT, SRT, JSON). Multiple entries allow providing transcripts in different formats.

maxLength: 10 items

View raw schema

{
  "key": "any",
  "type": "record",
  "record": {
    "type": "object",
    "required": [
      "podcast",
      "title",
      "media",
      "publishedAt",
      "duration",
      "feedItemGuid",
      "createdAt"
    ],
    "properties": {
      "link": {
        "type": "string",
        "format": "uri",
        "description": "URL of a companion webpage or show notes page for the episode."
      },
      "media": {
        "ref": "#mediaRef",
        "type": "ref",
        "description": "The primary media file for the episode."
      },
      "title": {
        "type": "string",
        "maxLength": 500,
        "description": "The title of the episode."
      },
      "artwork": {
        "type": "blob",
        "accept": [
          "image/png",
          "image/jpeg"
        ],
        "maxSize": 5000000,
        "description": "Episode-specific artwork. Overrides the podcast artwork when set. Recommended: 1400x1400 to 3000x3000 pixels, square, no alpha channel."
      },
      "podcast": {
        "ref": "org.atpodcasting.defs#podcastRef",
        "type": "ref",
        "description": "Identifies the parent podcast. Since episodes live in the same repository as their podcast, the AT URI is always derivable from the episode's DID and the podcastGuid."
      },
      "chapters": {
        "ref": "#chaptersRef",
        "type": "ref",
        "description": "Reference to an externally hosted chapters file."
      },
      "duration": {
        "type": "integer",
        "minimum": 1,
        "description": "Duration of the episode in seconds."
      },
      "explicit": {
        "type": "boolean",
        "description": "Whether the episode contains explicit content. Overrides the podcast-level setting when set."
      },
      "createdAt": {
        "type": "string",
        "format": "datetime",
        "description": "When the episode record was created."
      },
      "transcript": {
        "type": "array",
        "items": {
          "ref": "#transcriptRef",
          "type": "ref"
        },
        "maxLength": 10,
        "description": "References to externally hosted transcript files (e.g. VTT, SRT, JSON). Multiple entries allow providing transcripts in different formats."
      },
      "description": {
        "type": "string",
        "maxLength": 10000,
        "description": "A description or show notes for the episode."
      },
      "episodeType": {
        "type": "string",
        "description": "The type of episode. Defaults to full.",
        "knownValues": [
          "full",
          "trailer",
          "bonus"
        ]
      },
      "publishedAt": {
        "type": "string",
        "format": "datetime",
        "description": "When the episode was published."
      },
      "feedItemGuid": {
        "type": "string",
        "maxLength": 2000,
        "description": "The original feed item identifier. Must match the <guid> element of the corresponding RSS feed item. The record key (rkey) is derived from this value as uuid5(<podcast:guid>, feedItemGuid)."
      },
      "seasonNumber": {
        "type": "integer",
        "minimum": 1,
        "description": "Season number of the episode."
      },
      "episodeNumber": {
        "type": "integer",
        "minimum": 1,
        "description": "Episode number within its season or the overall series."
      },
      "alternateMedia": {
        "type": "array",
        "items": {
          "ref": "#mediaRef",
          "type": "ref"
        },
        "maxLength": 10,
        "description": "Alternate versions of the episode media (e.g. different formats or audio-only versions of video episodes)."
      }
    }
  },
  "description": "A podcast episode. Record key is a UUIDv5 derived from the podcast GUID (as namespace) and the episode's feedItemGuid (as name), enabling deterministic lookup from RSS feed metadata."
}

chaptersRef object

Reference to an externally hosted chapters file.

Properties

mimeType string Required

MIME type of the chapters file (e.g. application/json+chapters).

url string uri Required

URL of the chapters file.

View raw schema

{
  "type": "object",
  "required": [
    "url",
    "mimeType"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "URL of the chapters file."
    },
    "mimeType": {
      "type": "string",
      "description": "MIME type of the chapters file (e.g. application/json+chapters)."
    }
  },
  "description": "Reference to an externally hosted chapters file."
}

mediaRef object

Reference to an externally hosted media file.

Properties

mimeType string Required

MIME type of the media file (e.g. audio/mpeg, video/mp4).

url string uri Required

URL of the media file.

View raw schema

{
  "type": "object",
  "required": [
    "url",
    "mimeType"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "URL of the media file."
    },
    "mimeType": {
      "type": "string",
      "description": "MIME type of the media file (e.g. audio/mpeg, video/mp4)."
    }
  },
  "description": "Reference to an externally hosted media file."
}

transcriptRef object

Reference to an externally hosted transcript file.

Properties

language string language Optional

Language of the transcript (ISO 639-1 two-letter code, e.g. 'en', 'es', 'pt').

mimeType string Required

MIME type of the transcript file (e.g. text/vtt, application/x-subrip, application/json).

url string uri Required

URL of the transcript file.

View raw schema

{
  "type": "object",
  "required": [
    "url",
    "mimeType"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "URL of the transcript file."
    },
    "language": {
      "type": "string",
      "format": "language",
      "description": "Language of the transcript (ISO 639-1 two-letter code, e.g. 'en', 'es', 'pt')."
    },
    "mimeType": {
      "type": "string",
      "description": "MIME type of the transcript file (e.g. text/vtt, application/x-subrip, application/json)."
    }
  },
  "description": "Reference to an externally hosted transcript file."
}