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).

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).