diora-web/docs/podcasts.md

Podcasts: Strom, Merkliste, Wiedergabeliste

The plan agreed on 2026-10-19 (with the user, from their listening history). It replaces the inbox model ("Neu" to work through, "Folgen" beside it, one queue that is both a store and the play order). Server: diora-web (podcasts/). The podcast UI is diora-android's web-native/static/native-podcast.js, copied into static/podcasts/ — built there.

Why

• The subscriptions (about 540) are a self-chosen part of the podcast world: episodes to see go by and dip into now and then — not a list to work through. "Neu" had 3360 unplayed episodes; nobody works through that.
• The queue held 74 episodes (100+ hours): a store of "want to hear some day", yet the player played it in order as if it were the play order.
• In AntennaPod "download automatically" and "add to queue automatically" were one thing for the user: a regular podcast is one whose new episodes are on the phone. diora split them (177 feeds downloading, 8 queueing).
• "Silent" subscriptions came from AntennaPod fetching every feed on the phone, slowly. The server fetches all feeds anyway now (conditional, every 15 minutes).

The lists

Wiedergabeliste — short, what plays next. The player goes through it in order and stops when it is empty (it does not take from the Merkliste). Every episode in it is downloaded. Filled by hand: ▶ on an episode (plays it, puts it first), or "In die Wiedergabeliste" from the Merkliste or the Strom.

Merkliste — long, "want to hear". It may grow; it never expires. Grouped by podcast, each podcast collapsible (newest first inside). New episodes of Stamm subscriptions land here and are downloaded; so is what the user adds with ＋. An episode played from it moves to the front of the Wiedergabeliste; finished, it leaves both.

When an episode leaves both lists (heard, removed), its download is deleted (setting delete_dequeue). Downloads follow the lists, not the subscriptions.

Subscriptions: three levels

level	new episodes	today's mapping
Stamm	into the Merkliste and downloaded (per feed: or straight into the Wiedergabeliste — an option, used by none yet)	new_episodes='queue' (8) plus the regularly heard ones (about 50, list below)
Strom (default)	in the Strom; nothing to work through, nothing downloaded	'inbox', and the former silent 'ignore' ones
Auf Abruf	not in the Strom; on the podcast's page and in search	— (for exceptions)

The per-feed "download automatically" switch goes: Stamm means it.

Fetch interval per subscription: Automatisch (by publishing rhythm, interval_days: daily publishers hourly, rare ones daily), stündlich, täglich, wöchentlich. The former silent subscriptions become Strom with täglich.

The Strom (replaces "Neu" and "Folgen")

All episodes of all Strom and Stamm subscriptions, by period (Heute, Gestern, Diese Woche, …). Within a period the podcasts are ordered by how much the user has listened to them (episodes heard): every podcast with at least one heard episode before every one without — those count for infinitely more (heard in the last 12 months, heard_365); among the never-heard ones, rarely publishing first. Each podcast appears once per period, always bundled: its newest episode, and "+n ›" for the others. Episodes new since they were last seen carry a small mark (no counts). Per episode: ▶ (Wiedergabeliste, first), ＋ (Merkliste), ★. Filters stay: Favoriten, Verlauf, Angefangen, Gehört.

Tabs: Wiedergabeliste · Merkliste · Strom · Abos.

Favourite subscriptions

★ on a subscription (PodcastFeed.favorite): a mark and a filter (Abos: only the favourites; episode lists: filter=fave_feeds), whatever its level — it puts nothing on the Merkliste by itself. Started with the Stamm subscriptions marked.

Stöbern (decided 2026-10-19)

Within the subscriptions:

• Search in titles and shownotes: GET /podcasts/discover/search/?q=…&stream=1 (all words, the last as a prefix; titles weigh more). SQLite FTS5 index, contentless (podcasts/discover.py), filled after every refresh; manage.py index_episodes fills it.
• Similar episodes from the other podcasts: GET /podcasts/discover/similar/<id>/.
• People (who talks, who gives a talk), from episode titles only (podcasts/people.py): GET /podcasts/discover/people/ → [{name, episodes, feeds, score}], the ones in the most listened podcasts first; GET /podcasts/discover/person/?name= → their episodes.
• Topics of the Strom's last days, chips as for the news: GET /podcasts/discover/topics/?days=7 → [{label, ids}].
• Forgotten: GET /podcasts/discover/forgotten/ → {loved: [...], rare: [...]} — unheard episodes older than 60 days of the podcasts listened to most, and of the rare ones; the same all day.

One controlled step out (Apple's episode search and fyyd; no key):

• People elsewhere: GET /podcasts/discover/elsewhere/?name= → episodes naming the person in podcasts the user doesn't have ({source, podcast, feed_url, title, audio_url, guid, pub_date, duration_seconds, artwork_url, link}). POST /podcasts/discover/take/ with such an item puts the episode on the Merkliste; its podcast becomes an Auf Abruf subscription.
• Recommendations: GET /podcasts/discover/recommend/ → podcasts like the most listened ones (fyyd), recommended for several first: {title, feed_url, artwork_url, description, link, because: [titles], count}. Subscribing: the usual feeds/add/ (then Auf Abruf or Strom).

Show search stays on Apple (best coverage).

Podcast-Radio (since 2026-10-25)

Listening without committing: one button plays the Strom like a station.

• The rule: the radio always plays the newest (publication date) Strom episode that is neither played, nor started (normally), nor done for the radio. So an episode that comes out while one plays is next (the one playing isn't interrupted); otherwise it goes back in time, without limit. Auf Abruf podcasts and audiobooks aren't in the Strom, so not in the radio.
• Mixed: several episodes of one podcast in a row are mixed with the others waiting — the next is the newest of another podcast than the one before, if there is one (within the newest 200).
• What comes next is asked anew at every end and skip (so the newest really comes next); the list fetched before is for "Danach: …" in the player and for going on offline.
• Leaves no trace: no progress (no Verlauf, no "Angefangen", no played mark, not counted in heard_365), the Wiedergabeliste and Merkliste unchanged, nothing downloaded (it streams; a downloaded file plays if there is one), the Strom's marks unchanged.
• Done for the radio: run to its end or skipped (⏭, notification, headset, car). Pausing isn't: the radio keeps its episode and place for itself, ▶ goes on there.
• Committing: in the player while the radio plays, ＋ (Merkliste) and "Normal weiterhören" (first in the Wiedergabeliste at the current place; from then on it plays as usual, with progress). Playing anything normally switches the radio off (as an audiobook does).
• Server (podcasts/radio.py): PodcastRadioHeard(user, episode, at), kept apart from progress and kept for good (pruned, an old episode would come back when the radio goes back that far). GET /podcasts/radio/?after=<playing>&skip=<ids>&limit=5 → the next episodes by the rule ({episodes: [...]}, the rows of the episode lists; after isn't among them and its podcast not first; skip: ones the device is done with whose /heard/ may still be on its way); POST /podcasts/radio/heard/ {"episode_id"}. Shared by all devices. Filter untouched (episode lists): neither played nor listened into.
• Player sync: a report carries podcast_radio: true while the radio plays (PlayerState.podcast_radio); taking it over ("Hier abspielen", a transfer) or adopting it goes on with the radio on that device.
• Clients: the web player (podcasts-web.js: an entry with radio: true, the radio's own podradio in localStorage — next ones, its place, what it was done with lately; host podcastRadio(), podcastRadioCommit(), podcastRadioLater(); playerState().radio = {next}) and Android (PodcastRadio.kt beside BookPlay.kt; RadioService's save() / markPlayed() / followQueue() leave radio items alone). UI (native-podcast.js): 📻 at the top of the Strom, "Podcast-Radio · " in the mini player and the player, there a box with "Danach: …", ＋ Merkliste and "Normal weiterhören"; ⏭ only skips.
• Later perhaps: a radio of one folder, a longest length.

Moving over

• Today's queue (74) becomes the Merkliste; the Wiedergabeliste starts empty.
• Stamm: the 8 automatic subscriptions and the regularly heard ones (≥ 8 episodes a year or ≥ 3 in 90 days, 2026-10-19): Ones and Tooze, Die Neuen Zwanziger – Der Salon, Surplus, The Deprogram, junge Welt – Tagesüberblick, Speakeasy-Bar, jwpod – Forschung, RLS Audiodokumente, The Reaction Pod, Geschichten aus der Geschichte, Märkte Mächte Emissionen, friendlyjordies, Second Thought, Neben der Spur, Forschungsquartett, GegenStandpunkt – Artikel, Hörsaal, Hakim, Marxistische Vorträge, Blätter, Kontextfenster, New Left Review, Kommunisten Kneipe, Jung & Naiv, HealthyGamerGG, Dekarldent, Daily Dose Of Dekarldent, Eine Stunde History, Übertage, Eigentlich, Zwischen Zwei Deckeln, UNFASSBAR, Über Rechts, TitosLeftLung, New Books in History, ARTEde, Irgendwas mit ARTE, Zwei wie Pech & Schwafel, Geschichte der kommenden Welten, Vollbild, Zeitfragen, Zeitfragen. Feature, Die Filmanalyse, Reaction, Wirtschaft am Mittag.
• Everything else: Strom; the silent ones with täglich.

Order of work

1. Wiedergabeliste and Merkliste (server: a second list, moving the queue over, the player's order; UI: two tabs, grouped Merkliste).
2. The three levels and the fetch interval; downloads following the lists.
3. The Strom replacing "Neu" and "Folgen".
4. Browsing — after more thought.

API (server, since 2026-10-19)

• PodcastSettings.lists_v2 turns the two lists on. POST /podcasts/lists/ {"on": true} moves the queue into the Merkliste (the Wiedergabeliste starts empty); {"on": false} puts the Merkliste back at the end of the queue. Off, everything works as before (apps not updated yet).
• Wiedergabeliste = the queue as it was: state.queue, /podcasts/queue/add|remove|reorder/. The player goes through it and stops at its end.
• Merkliste = PodcastLater: state.later (rows like the queue's, newest first, plus added_at, auto — added by a Stamm feed — and in_queue), POST /podcasts/later/add/ and /podcasts/later/remove/ {"episode_ids": [...]}. Heard (progress at the end, mark-played) and "Folge löschen" take an episode off it. Episode lists carry in_later; filter later.
• Levels: PodcastFeed.new_episodes — queue = Stamm into the Merkliste (with lists_v2; without it: the queue), play = Stamm into the Wiedergabeliste, inbox = Strom, ignore = Auf Abruf. auto_queue stays true for queue and play.
• Fetch interval: PodcastFeed.refresh_interval — '' (by rhythm: every interval_days hours, within 15 minutes and 24 hours), hourly, daily, weekly; the cron's refresh_feeds only fetches feeds that are due (views.refresh_due).
• Strom: GET /podcasts/episodes/?filter=stream (all but Auf Abruf; with folder=, sort=); episodes carry discovered_at. Per feed in state.feeds: heard_365 (episodes heard in the last 12 months: played, or listened into for more than a minute) and interval_days. POST /podcasts/stream/seen/ → {before, now}; state.stream_seen_at. An episode is marked when its discovered_at is after the time before the current look.
• Web host (static/js/podcasts-web.js, DioraPodcastHost): podcastLaterAdd(json episodes), podcastLaterRemove(json ids), podcastListsSwitch(on), podcastStreamSeen() (keeps the previous time as state.stream_seen_before for the marks).

Transcripts

An episode's Transkript tab shows one of two kinds. From the feed: <podcast:transcript> (SRT, VTT, JSON, Podlove), fetched and parsed on first use and cached in EpisodeTranscript (podcasts/transcripts.py, GET /podcasts/episodes/<id>/transcript/). Made by Whisper (since 2026-11): only when the user asks, kept on TranscriptionJob; the feed's wins when both exist. From a transcript the device can write an article that is pinned to the episode and shows in Blogs. All of that is in docs/transcription.md.