DOCSEARCHbyAlgolia
Submit Docs

Podcast Namespace

repository·main·Indexed 19 days ago

https://github.com/podcastindex-org/podcast-namespace

A community-driven RSS namespace for the Podcasting 2.0 movement, providing a standardized way for creators to deliver rich metadata to aggregators and apps. It includes definitions for formalized tags such as <podcast:transcript>, <podcast:funding>, and <podcast:chapters>, along with implementation requirements and a JSON Chapters format specification.

Tokens
52.7K
Snippets
130
Records
200
Agent score
65%

What's inside podcast-namespace

  1. Overview of the podcast Namespace

    main

    The podcast namespace is a holistic RSS namespace designed to synthesize fragmented podcasting namespaces into a single, compact, and efficient standard. It is part of the larger Podcasting 2.0 project, which aims to return control of podcasting protocols to the open community.

    Developers can use this namespace to deliver new functionality to podcast apps and aggregators through standardized, community-controlled tags.

    Key resources for developers:

    • Official XMLNS Definition: The authoritative definition of all formalized tags (see docs/1.0.md).
    • Implementation Support: A list of platforms and apps currently implementing these tags (see docs/element-support.md).
    • Example Feed: A side-by-side comparison of the podcastindex namespace and the Apple iTunes namespace (see example.xml).

  2. JSON Chapters Format Specification

    main

    The JSON Chapters format is a specification for providing chapter markers for podcast episodes. This file is referenced in an RSS feed using the <podcast:chapters> tag of the "podcast" namespace and must be hosted on a publicly accessible URL.

    Requirements:

    • Content-type: Must be served with application/json+chapters.
    • Ordering: Chapters are assumed to be in ascending order based on their startTime.
    • Version: The format version is specified in the root object.

  3. What is the <podcast:valueTimeSplit> element?

    main

    The <podcast:valueTimeSplit> element enables time-based changes to value recipient information during the playback of a feed's enclosure content. It allows a podcast to specify different value splits (e.g., for payments or revenue sharing) for specific time intervals within an episode.

    It functions as a hybrid of <podcast:soundbite> and <podcast:remoteItem>, allowing you to either:

    1. Specify alternative <podcast:valueRecipient> tags directly within the split.
    2. Reference a single <podcast:remoteItem> tag to pull value recipient information from another RSS item.

    Key Rules for Implementation:

    • Nesting: If a <podcast:remoteItem> is used, any <podcast:valueTimeSplit> tags contained within that remote item must be ignored by the playback app. Only the root-level splits of the remote item should be used.
    • Fee Calculation: Fees from the default (non-split) <podcast:valueRecipient> tags in the parent <podcast:value> element should be calculated before any value is allocated to the <podcast:valueTimeSplit> block.

  4. Configure Show type (Episodic vs Serial)

    main

    The <itunes:type> tag (within <channel>) determines how episodes are presented in the Apple Podcasts app:

    • episodic (default): Episodes are consumed without a specific order. The newest episodes are presented first. Requires <pubDate> for each episode.
    • serial: Episodes are intended to be consumed in sequential order. The oldest episodes are presented first. Requires <itunes:episode> numbers for each episode.
    <itunes:type>serial</itunes:type>

  5. Use "List" medium variants for collection feeds

    main

    To describe a feed that acts as a collection of other items rather than containing direct <item> or <podcast:liveItem> elements, append the letter L to the standard medium name (e.g., musicL, podcastL, audiobookL).

    List Mediums:

    • Standard Lists: Created by suffixing the medium name with L (e.g., musicL). These feeds should exclusively contain <podcast:remoteItem> elements.
    • mixed: A specialized list medium describing a feed of <podcast:remoteItem> elements that point to different remote medium types (e.g., a feed containing both music and podcasts).

  6. Understand the "podcast:social" specification

    main

    The podcast:social specification allows podcasters to define how listeners can interact with their content on social networks and discussion platforms. It provides a structured way for podcast apps to guide users toward specific platforms for engagement (likes, comments, shares) and to facilitate seamless onboarding (sign-up) for decentralized platforms.

    The specification consists of three primary elements:

    1. <podcast:social>: Placed in the <channel> element to declare which platforms the podcast uses.
    2. <podcast:socialSignUp>: Nested within <podcast:social> to provide sign-up URLs for listeners.
    3. <podcast:socialInteract>: Placed in either the <channel> or <item> element to link to specific social posts or interaction points (e.g., a specific comment thread for an episode).

    Note: This is a draft specification and may change. For the most current information, refer to the official documentation.

  7. Use OpenStreetMap (OSM) IDs for rich geographic discovery

    main

    While the geo attribute provides a permanent point for simple map pins, the osm attribute is the primary way to enable complex, programmatic searches.

    Key Implementation Details:

    • Canonical Location: When using osm, the canonical latitude/longitude is the one returned by the OpenStreetMap API, not necessarily the one in the geo attribute.
    • Format: The value must include both a type (N, W, or R) and an ID. Example: W5013364 (a Way) or R148838 (a Relation).
    • Avoid place_id: Do not use place_id from OSM API responses, as these are unique to specific data mirrors. Always use osm_id.
    • Search Capabilities: Using OSM IDs allows developers to build advanced queries (e.g., via Overpass API) to find podcasts about specific categories of places, such as "all podcasts about wineries in Adelaide" or "all podcasts about gothic cathedrals in France."

  8. Implement the Play-to-Pay payment model

    main

    The podcast:value specification follows a "Play-to-Pay" model rather than a traditional paywall.

    For App Developers:

    • When a user presses play on an episode containing a value block, a compatible app should begin streaming micropayments to the designated recipients.
    • The amount of each payment is determined by the listener.
    • If a listener chooses not to pay, the app should simply ignore the value block.

    For Creators:

    • Include the value block in your feed to designate single or multiple destinations for micropayments.

  9. Handle Lightning Address (lnaddress) recipients

    main

    When using type="lnaddress", the address attribute contains a Lightning Address (e.g., user@wallet.com).

    To ensure successful payments, applications should resolve the pubkey and custom record data by calling https://<domain>/.well-known/keysend/<username> before sending the payment. It is highly recommended to cache these results to minimize network requests.

  10. Understand the Value-4-Value (V4V) License and Ecosystem

    main

    The Value-4-Value (V4V) Master Use License is a monetization model designed for the instant and direct exchange of digital currency (e.g., Bitcoin) between listeners and content owners via RSS feeds.

    Core Concepts

    • Value Block (The Split): A set of technology instructions embedded in an RSS Feed that identifies monetization recipients and their digital wallet addresses. This allows multiple stakeholders to share value automatically.
    • The Valueverse: The ecosystem of V4V-enabled applications, distributors, and users participating in this direct exchange model.
    • V4V-App: A platform that enables the connection between a Listener's digital wallet and an Owner's digital wallet to facilitate instant global transfers.
    • Value Cast & Value Host: Promotional partners (programmers, shows, or personalities) that use V4V-licensed content to expand audiences while participating in the value exchange.
    • ISRC Code: An International Standard Recording Code that serves as a unique identifier for a recording, tied to ownership and copyright, and must be embedded in the license notation.

  12. Use the podcast:chapters API to sync episodes

    main

    The podcast:chapters API allows a Podcast Hosting service to automatically notify a Chapters Provider service whenever a new episode is published. This eliminates the manual process of copying JSON URLs from a chapter management tool into an RSS feed.

    To implement this, the Podcast Hosting service must allow users to configure a custom endpoint URL provided by their chosen Chapters Provider.