]> Trimplayer

trimplayerapp@gmail.com https://trimplayer.com/

Applications podcast opml subscription synchronization listener PortCast defines an open JSON-based interchange format, and an optional HTTPS synchronisation API, for moving a podcast listener's data -- subscriptions, listening history, playback position, queue, bookmarks, and per-feed preferences -- between independent podcast applications without a central service. It builds on identifiers already present in RSS (item GUID, feed URL) and the Podcast Namespace (podcast:guid) so that implementations can interoperate without inventing a new identity namespace. This document specifies the file format (v0.1) and a federated synchronisation API (v0.2) that reuses the same data model. The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction A listener's relationship with their podcasts -- which shows they follow, where they stopped in an unfinished episode, the clip they bookmarked at 23:04 -- currently lives inside whichever application they happen to use. Switching applications restarts that relationship from zero. OPML solves the subscription case, but everything else (playback position, completion state, queue, bookmarks, per-feed preferences) is lost on every migration. This document specifies PortCast, a protocol whose goal is simple: a listener SHOULD be able to leave any podcast application and arrive at any other application with the relationship to their podcasts intact. PortCast defines a JSON document format (file mode, through ) and an optional HTTPS API (API mode, ) that exposes the same entities for incremental synchronisation. The two modes share a single data model; file mode is the interoperability floor that every conforming implementation can fall back to. PortCast is intentionally federated. There is no central directory, registry, or authority. Each application exposes its own endpoint on its own domain, or produces its own files. The editors of this specification commit to not operating a central service.

Design goals Listener-owned. The document is produced by the user, for the user. No vendor lock-in, no proprietary identifiers required. Interoperable identity. Use open identifiers already present in RSS (item GUID, feed URL) rather than inventing a new namespace. Implementations MAY add their own identifiers in a namespaced extension block. Lossless within the model. A conforming export captures everything the protocol defines. Anything outside the model goes in extensions so it round-trips through implementations that do not understand it. Partial and incremental. Every entity carries an updatedAt timestamp, so a future synchronisation profile can ship deltas. The v0.1 file format is a full snapshot, but the data model is synchronisation-friendly. Human-readable. A listener SHOULD be able to open the file in a text editor and recognise what it says about them. Versioned. The document declares its protocol version; implementations can negotiate behaviour.

Terminology and conformance

Requirements language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Defined roles A producer is software that writes a PortCast document or serves PortCast API responses. A consumer is software that reads a PortCast document or calls a PortCast API. A conforming producer MUST write a document that validates against the JSON Schemas published with this specification. A conforming consumer MUST accept any document that validates against those schemas, and MUST NOT reject a document because of unrecognised keys inside an extensions object ().

Document container A PortCast document is a single JSON object , encoded in UTF-8 without a byte order mark, with the following top-level shape:

Field Required Notes portcast yes Semantic-versioned string. The version of this spec. generatedAt yes RFC 3339 timestamp in UTC. generator yes Producing application identifier. owner no Optional listener identity. Producers SHOULD let users opt out. subscriptions yes Array of Subscription. MAY be empty. episodes yes Array of EpisodeState. MAY be empty. queue no Ordered array of QueueItem. bookmarks no Array of Bookmark. preferences no Preferences object. extensions no Namespaced extension data (). The file extension SHOULD be .portcast.json and the IANA media type SHOULD be application/vnd.portcast+json (see ).

Identity model Identity is the heart of an interoperability protocol. PortCast identifies entities at two levels.

Podcast identity A Subscription MUST carry at least one of: feedUrl -- the canonical RSS or Atom URL of the show. podcastGuid -- the Podcast Namespace <podcast:guid> value when the feed publishes one. This is the strongest identifier and SHOULD be preferred when matching across applications. A subscription SHOULD include both when both are available. Producers MAY also carry directory-specific identifiers (e.g., Apple Podcasts, Podcast Index) under Subscription.identifiers.*; these are advisory and not required for matching.

Episode identity An EpisodeState MUST carry at least one of: guid -- the RSS <item><guid> value (preferred). enclosureUrl -- the media URL from <enclosure url="...">. It MUST also carry a subscriptionRef (either podcastGuid or feedUrl) that matches one of the document's subscriptions[] entries. If neither a guid nor an enclosureUrl is known, an episode state MAY use a stable (subscriptionRef, publishedAt, title) tuple, but consumers are not required to match by it.

Subscriptions

unsubscribedAt is set when the listener has stopped following the show but the producer still wishes to convey historical context. Consumers MAY discard unsubscribed entries on import. tags are free-form, listener-applied labels.

Episode state

status values Value Meaning unplayed Listener has never started this episode. in_progress Listener started but did not finish. completed Listener reached the end or marked complete. archived Listener explicitly dismissed without listening. positionSeconds is REQUIRED when status is in_progress and SHOULD be zero or omitted otherwise. Producers SHOULD record a small tolerance (for example, treating the episode as completed if the listener reached within 30 seconds of the end).

Playback events The events array is OPTIONAL. Each event has a type from the set {play, pause, seek, complete, speed_change, bookmark} and attaches its own typed fields. Producers MAY include a subset; consumers MAY ignore events they do not understand. Producers that do not track event-level history can omit events entirely; the top-level fields (positionSeconds, playCount, lastPlayedAt) are still sufficient for everyday "where did I leave off" portability.

Queue

position is 1-based and MUST be unique within the queue. source is free-form (e.g., manual, auto, smart-playlist:Morning Commute).

Bookmarks

endSeconds is OPTIONAL; its presence promotes a bookmark to a clip.

Preferences

perFeed keys are podcastGuid when available, otherwise feedUrl. Per-feed values override global.

Extensions Anything outside this specification lives under an extensions object, keyed by reverse-DNS namespace:

Consumers MUST preserve extensions on round-trip even if they do not understand a namespace. This is what keeps a multi-application journey lossless.

Versioning portcast is a semantic-versioned string. Consumers: MUST accept any document whose portcast major version they support. MAY warn the listener when a minor version is newer than they understand. MUST NOT silently drop fields they do not recognise; preserve them under extensions._unknown if necessary.

Live sync API (v0.2 -- Draft) The file format defined above (v0.1) is the interoperability floor. v0.2 introduces an optional API mode: the same entities, exposed over HTTPS so clients can synchronise incrementally without a full re-export. The wire payloads in API mode reuse the v0.1 schemas; no new entity shapes are introduced. A conforming v0.2 implementation MAY implement file mode, API mode, or both. Clients MUST assume nothing beyond what a server advertises in its discovery document ().

Operating modes Mode Transport Use case File User-supplied .portcast.json One-shot migration, archival, manual transfer API HTTPS endpoints on the application's domain Live sync between two installed applications File mode is the interoperability floor: every API-mode server SHOULD implement at least GET /portcast/v1/export, which returns the same document a file export would produce.

Discovery A PortCast server SHOULD publish a discovery document at /.well-known/portcast :

capabilities is a flat string set. A read-only server omits *.write entries. A server that does not track per-event history omits events. A server that does not implement delta synchronisation omits deltas and clients fall back to fetching full collections.

Versioning and content type Endpoints live under /portcast/v1/.... The v1 is the API major version and is independent of the specification version declared inside payloads. Servers MUST set Content-Type: application/vnd.portcast+json on responses; clients SHOULD send a matching Accept header. Backwards-compatible additions (new optional fields, new capability strings) MUST NOT bump the API major version.

Authentication Implementations MUST use one of: OAuth 2.0 , with scopes drawn from portcast.read, portcast.write, portcast.history. The portcast.history scope covers event-level playback data () and is treated as more sensitive than basic read. Bearer token , appropriate for self-hosted or single-user deployments. Credentials MUST NOT appear in URL query strings. Servers MUST reject requests over plain HTTP.

Endpoints Method Path Body / Returns GET /portcast/v1/export Full PortCast document (= v0.1 file) POST /portcast/v1/import Body: full or partial PortCast document; server upserts each entity GET /portcast/v1/subscriptions { subscriptions, deletions?, syncedAt, nextCursor? } GET /portcast/v1/subscriptions/{ref} A Subscription PUT /portcast/v1/subscriptions/{ref} Body: Subscription DELETE /portcast/v1/subscriptions/{ref} Unsubscribe GET /portcast/v1/episodes { episodes, deletions?, syncedAt, nextCursor? } POST /portcast/v1/episodes Body: { episodes: [...] }; upsert GET /portcast/v1/queue { queue } PUT /portcast/v1/queue Body: { queue }; replaces in full GET /portcast/v1/bookmarks { bookmarks, deletions?, syncedAt, nextCursor? } POST /portcast/v1/bookmarks Body: Bookmark DELETE /portcast/v1/bookmarks/{bookmarkId}   GET /portcast/v1/preferences Preferences PUT /portcast/v1/preferences Body: Preferences {ref} in subscription paths is the URL-encoded podcastGuid when known, otherwise the URL-encoded feedUrl. Servers MUST accept either form. Episodes are intentionally not addressed by path because RSS GUIDs do not round-trip cleanly through URL encoding.

Delta sync Collection endpoints (subscriptions, episodes, bookmarks) MUST accept ?since=<RFC 3339 timestamp> when the server advertises the deltas capability. The response then contains only entities whose updatedAt > since, a deletions array of refs for entities removed since that timestamp, and a syncedAt timestamp the client persists for the next round. Servers SHOULD retain deletion tombstones for at least 30 days. Clients that have been offline longer SHOULD discard their cached syncedAt and perform a full pull.

Pagination Endpoints that may return large collections support cursor-based pagination. The response carries nextCursor when more pages exist; the client passes ?cursor=<value> to fetch the next page. Cursors are opaque strings. since and cursor MAY be combined.

Conditional updates Writes SHOULD use If-Match: <updatedAt> for optimistic concurrency. Servers MUST respond 412 Precondition Failed if the resource's current updatedAt is newer than the supplied value. This prevents two clients clobbering each other's position updates on the same episode.

Errors Errors are JSON, with HTTP status reflecting the class:

The initial set of code values is registered in . Servers MAY define additional codes under a reverse-DNS prefix (e.g., com.example.quota_exceeded); such vendor-prefixed codes do not require IANA registration.

Webhooks (optional) Servers advertising the webhooks capability accept registrations at POST /portcast/v1/webhooks with body:

= 32 bytes>" } ]]>

Webhook deliveries carry X-PortCast-Signature: sha256=<hex> computed over the raw request body with the registration secret as the HMAC key. Receivers MUST verify the signature and SHOULD respond 2xx within 5 seconds. Servers SHOULD retry failed deliveries with exponential backoff for at least 24 hours. Webhooks are an optimisation; the baseline pattern is client-driven polling with ?since=.

Capability fallback A client that needs a capability the server does not advertise SHOULD fall back to GET /portcast/v1/export and process the returned document as a file-mode import. This guarantees a baseline interoperability floor even for minimal server implementations.

Federation PortCast is intentionally federated. Each application exposes its own endpoint on its own domain; there is no central directory or hub. A client connecting a new account typically: Asks the listener for the application's domain. Fetches https://<domain>/.well-known/portcast. Runs the OAuth dance against the endpoints declared there. Begins delta-synchronising. Servers MUST NOT require registration with any central authority to be considered conforming.

Security considerations

Sensitivity of the data A PortCast document is a detailed record of personal listening behaviour: which shows a listener follows, when they started or finished an episode, which passages they bookmarked, and (when event-level history is included) the moment-to-moment shape of their attention. Implementers MUST treat PortCast documents and API responses as personal data of comparable sensitivity to browser history or messaging metadata.

Producer requirements Producers: SHOULD let the listener choose whether to include owner. SHOULD let the listener choose whether to include event-level history (). SHOULD NOT include device identifiers, IP addresses, geolocation, or third-party analytics identifiers in any PortCast field, including inside extensions. MUST NOT embed the listener's account credentials, API keys, OAuth tokens, or session cookies anywhere in a PortCast document. SHOULD warn the listener before transmitting a PortCast document to a third party.

Consumer requirements Consumers SHOULD treat an imported document as personal data, not as shareable telemetry. Consumers MUST NOT retransmit a received document to third parties without explicit listener consent. Consumers SHOULD make it possible for the listener to delete imported data on demand.

Transport and storage (API mode) In API mode (): Servers MUST require TLS; plain HTTP MUST be refused. Credentials MUST NOT appear in URL query strings or path components; they MUST be carried in HTTP request headers. Servers MUST scope OAuth tokens to a single listener account. Servers SHOULD support per-client token revocation. The portcast.history scope SHOULD be requested separately from portcast.read.

Threat model and out-of-scope risks PortCast does not, in v0.1, define a signing or sealing mechanism: a document cannot be cryptographically attributed to the producer that wrote it. Consumers SHOULD treat the source of a document as out-of-band-authenticated (e.g., the listener manually selected the file or authorised the OAuth client). Adding a signed manifest is listed as a future work item. PortCast does not protect against a malicious application that has been granted access to a listener's data; access control is the responsibility of the producing or hosting application, not the protocol. Consumers SHOULD apply input validation to imported documents (notably to URL fields and extensions content) consistent with their platform's safe-handling guidance.

IANA considerations This document requests four IANA actions.

Media type registration IANA is requested to register the following media type per : Field Value Type name application Subtype name vnd.portcast+json Required parameters none Optional parameters none Encoding considerations binary; PortCast documents are UTF-8 encoded JSON Security considerations See of this document Interoperability cons. See of this document Published specification This document Applications that use it Podcast applications, subscription importers and exporters, listener-data synchronisation services Fragment identifier JSON Pointer syntax Restrictions on use none Provisional registration yes (until RFC publication) Author / change controller The editors of this specification Intended usage COMMON The file extension .portcast.json is the RECOMMENDED extension; the +json structured-syntax suffix indicates the underlying JSON serialization.

Well-known URI registration IANA is requested to register a new entry in the "Well-Known URIs" registry per : Field Value URI suffix portcast Change controller The editors of this specification Specification document This document () Related information The resource is a JSON object describing a PortCast API endpoint (its base URL, authentication scheme, and capability set) Status provisional

OAuth 2.0 scope registration IANA is requested to register the following OAuth 2.0 scopes per and : Scope name Description portcast.read Read subscriptions, episode state (excluding event history), queue, bookmarks, and preferences portcast.write Create, update, and delete the same entities the portcast.read scope grants visibility into portcast.history Read or write event-level playback history (). MUST be requested separately from portcast.read Change controller: the editors of this specification.

PortCast error code registry This document establishes a new IANA registry titled "PortCast Error Codes" with the following structure: Field Type / notes code A short, lowercase, underscore-separated identifier returned in API error responses () description A one-sentence summary of when the error is returned reference The document defining the code The registration policy is Specification Required . Initial contents: Code Description Reference unauthorized The request lacks valid authentication credentials This document forbidden The credentials do not grant access to the resource This document not_found The referenced entity does not exist This document conflict The request conflicts with current server state This document precondition_failed An If-Match precondition was not satisfied () This document invalid_request The request body or parameters are malformed This document unsupported_capability The client asked for a capability the server does not advertise This document rate_limited The client has exceeded a server-defined rate limit This document internal_error The server encountered an unexpected error This document

In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. This specification defines IANA registries for W3C Web Authentication (WebAuthn) attestation statement format identifiers and extension identifiers. Podcasting 2.0 Project There is a long-standing tradition in the Internet community, predating the Internet Engineering Task Force (IETF) by many years, of use of the RFC Series to publish materials that are not rooted in the IETF standards process and its review and approval mechanisms. These documents, known as "Independent Submissions", serve a number of important functions for the Internet community, both inside and outside of the community of active IETF participants. This document discusses the Independent Submission model and some reasons why it is important. It then describes editorial and processing norms that can be used for Independent Submissions as the community goes forward into new relationships between the IETF community and its primary technical publisher. This memo provides information for the Internet community. The IETF policies about rights in Contributions to the IETF are designed to ensure that such Contributions can be made available to the IETF and Internet communities while permitting the authors to retain as many rights as possible. This memo details the IETF policies on rights in Contributions to the IETF. It also describes the objectives that the policies are designed to meet. This memo obsoletes RFCs 3978 and 4748 and, with BCP 79 and RFC 5377, replaces Section 10 of RFC 2026. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document specifies the procedures by which authors of RFC Independent Submission documents grant the community "incoming" rights for copying and using the text. It also specifies the "outgoing" rights the community grants to readers and users of those documents, and it requests that the IETF Trust manage the outgoing rights to effect this result. This memo provides information for the Internet community. This specification defines the WebFinger protocol, which can be used to discover information about people or other entities on the Internet using standard HTTP methods. WebFinger discovers information for a URI that might not be usable as a locator otherwise, such as account or email URIs.

Acknowledgments PortCast builds on a long tradition of attempts to make a listener's relationship with their podcasts portable. The editors thank Dave Winer for OPML, which has carried podcast subscriptions across applications for two decades and which inspired the goal of doing the same for the rest of a listener's data. The editors also thank the Podcast Namespace project for <podcast:guid>, which makes cross-application show identity tractable, and the podcast-application development community for feedback on early drafts.