Add the podcast HTTP API for the UI and the web player

/api/podcasts now lists subscriptions with counters and fetch state,
subscribes by feed URL (fetched first; nothing is stored for a URL that
is not a public feed), shows a podcast with its seasons and history,
pages and searches episodes, and runs the explicit progress actions
(start over, played, unplayed) and unsubscribe/subscribe again.

The web player gets two endpoints: playback returns the audio source
and the resume position and, when the browser starts playing, writes a
new listening session as an explicit action above the carried handoff
generation; progress stores checkpoints, pause, stop and handoff at the
session generation, a seek as an explicit action, completes the episode
once at the end or within the completion tail, and records the
listening session. Handlers delegate to podcasts::api, which the new
Postgres test drives directly.

Podcast queue items are no longer marked unavailable in browser JSON
and carry the episode artwork. The temporary dead-code allowance of the
podcast module is gone; helpers used only by tests are cfg(test) and
complete_session gave way to complete_if_current.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-20 15:12:38 +02:00
1 parent 5aaea8a8eb
commit 1778942714
13 files changed
+1998 -50

No files matched your search

+18 -9
View File
@@ -8,7 +8,10 @@
//! plus the verbatim device-sync DTO under [`WIRE_TRACK_KEY`] and its explicit
//! [`PlaybackSource`] under [`SOURCE_KEY`]. Converting back to the wire uses
//! the verbatim DTO, so such items survive browser -> server -> peers ->
//! server -> browser unchanged even though this web player cannot play them.
//! server -> browser unchanged. The web player plays podcast episodes
//! through `/api/podcasts/episodes/{id}/playback` (publisher URL or the
//! optional proxy); placeholders and unresolved federated music stay
//! unplayable here.
//!
//! Gating and Jam decisions are delegated to `music_dht::device_sync`; this
//! module only maps browser JSON onto the shared DTOs.
@@ -34,9 +37,6 @@ pub(crate) const POSITION_UNKNOWN_KEY: &str = "position_unknown";
/// Reason shown for federated music that is not in this library.
pub(crate) const FED_UNAVAILABLE_REASON: &str = "Not available on this web player yet";
/// Reason shown for podcast episodes, which this web player cannot play yet.
pub(crate) const PODCAST_UNAVAILABLE_REASON: &str =
"Podcast episodes cannot be played on the web player yet";
/// Reason shown for Jam placeholders of someone else's private item.
pub(crate) const PRIVATE_UNAVAILABLE_REASON: &str = "Private item of the Jam host";
@@ -68,13 +68,15 @@ pub(crate) fn external_track_json(
"release_id": 0,
"release_title": episode.podcast_title,
"release_year": serde_json::Value::Null,
"cover_url": serde_json::Value::Null,
// Artwork is loaded from the publisher, like the audio.
"cover_url": episode.image_url,
// The player asks `/api/podcasts/episodes/{id}/playback` for the
// audio source when it starts the episode.
"stream_url": "",
"uploader_name": "Podcast",
"audio_format": episode.mime,
"content_id": serde_json::Value::Null,
"unavailable": true,
"unavailable_reason": PODCAST_UNAVAILABLE_REASON,
"unavailable": false,
}),
Some(PlaybackSource::Private) => serde_json::json!({
"id": placeholder_track_id(Some("private"), index),
@@ -490,8 +492,15 @@ mod tests {
let mut wire = PlaybackTrack::podcast_episode(episode());
wire.play_count = 3;
let json = external_track_json(&wire, 4, None);
assert_eq!(json["unavailable"], true);
assert_eq!(json["unavailable_reason"], PODCAST_UNAVAILABLE_REASON);
// Playable on the web player (the source is resolved on play).
assert_eq!(json["unavailable"], false);
assert!(json.get("unavailable_reason").is_none());
assert_eq!(json["stream_url"], "");
assert_eq!(
json["cover_url"],
Value::Null,
"the test episode has no artwork"
);
assert_eq!(json["title"], "Episode 42");
assert_eq!(json[SOURCE_KEY]["kind"], "podcast_episode");
assert!(json["id"].as_i64().unwrap() < 0);