Export Feeds

Export Feeds

tvtimes can hand your whole line-up to another player — Jellyfin, Plex, Emby, TiviMate, Threadfin — as one merged M3U playlist and XMLTV guide. Every enabled source is combined and de-duplicated, and programme times are written already corrected for each channel's timezone and per-channel clock offset, so the downstream guide needs no further fixing.

Turn it on

1. Settings → Export feeds → Generate feed links.
2. Copy the two URLs. They carry a secret token and are shown once — rotate any time for fresh links (the old ones stop working), or Disable to close the feeds entirely.

These routes have a published OpenAPI reference: tvtimes Export API (the raw document is at openapi.json, for a client generator). It's the only documented part of the API -- everything else is the web app's own interface and may change in any release.

Once the feeds have been used, the same panel shows when they were last fetched and lists any players reporting watch state back. That's the only place a feed consumer is visible — an export token never appears on the Sessions screen, which is browser sign-ins only. See Pairing With tvdinner for the detail.

https://tv.example.com/api/exports/playlist.m3u?token=…
https://tv.example.com/api/exports/epg.xml?token=…

Wire it up

• Jellyfin → Live TV → add an M3U Tuner with the playlist URL, then an XMLTV guide source with the EPG URL.

• Plex → Live TV & DVR → "I have an XMLTV guide".

• TiviMate → add playlist (Xtream/M3U) → external EPG.

• tvdinner 1.36+ → the panel shows a third row, Open in tvdinner, carrying one URL that stands in for both feeds:

  tvtimess://tv.example.com?token=…      (tvtimes:// if you serve over http)
  

  Click it — once tvdinner has run tvdinner default-handler, the browser hands it straight over — or copy it and run tvdinner 'tvtimess://…'. tvdinner expands it back into the same playlist + guide pair, so its program guide, favorites, recording and scheduling all work against your merged line-up. A sub-path deployment keeps its base path (tvtimess://example.com/tv?token=…).

Using tvdinner? Everything below — plus watched state, favourites and the tvtimes:// source URL — is collected on one page: Pairing With tvdinner.

Recording your watchlist

The same token serves a third feed, /api/exports/watchlist.json: every upcoming airing anyone on the account has watchlisted, with corrected times and the same /stream/<id> URLs the M3U carries. It exists so a recorder can act on your watchlist without understanding tvtimes.

tvdinner 1.37+ consumes it directly:

tvdinner 'tvtimess://tv.example.com?token=…' --record-watchlist

It polls every 15 minutes and schedules a recording for each entry — so pressing Remind me (or Watch this title) here, on your phone, makes the box at home record it.

• The watchlist is per user; the export token is per account. The feed is the union across the household, de-duplicated per broadcast, so two people flagging the same film yields one recording.
• Un-watchlisting something removes its pending recording on the next poll. Recordings scheduled by hand in tvdinner are never touched.
• Only airings inside the export's guide window appear, and only on channels belonging to an enabled source.

Seeing what you've watched

POST /api/exports/watch-events, behind the same token, accepts what a player actually watched — and it's the only write that token permits. The guide grid then dims and ticks those programmes.

tvdinner 1.38+ reports it:

tvdinner 'tvtimess://tv.example.com?token=…' --report-watch-state --device-name 'living room'

• A player sends plain start/stop intervals, not programme ids. tvtimes derives which programmes those cover by overlapping them against the guide, so re-ingesting the EPG — which recreates every programme row — or correcting a channel's clock offset updates the answer with nothing re-reported and nothing left dangling.
• Watched means half the programme, or 30 minutes, whichever is less demanding. Intervals over six hours are ignored as a player left running at a dead screen.
• The write is deliberately narrow: it appends intervals for channels already on your account and nothing else. A leaked token can at worst pollute your own watched badges — it already exposes the whole line-up and streams through it. Leave --report-watch-state off and nothing is ever written.

How it works

• Channels are keyed by their tvtimes id in both files, so an East/West pair that shares a tvg-id upstream still links to the right guide data downstream.
• The M3U points playback at …/api/exports/stream/<channel_id>?token=…, which 302-redirects to the real stream. Xtream credentials are rebuilt on the server and never appear in the file.
• Stalker portal channels appear in the exported guide but don't play through the export yet.
• The routes are token-gated (matched against the token's sha256) and rate-limited (30/min). Nothing to configure server-side; expose them through the same proxy as the rest of the app.

Security

Anyone with a link can read your line-up and stream through it — treat the URLs as passwords. Rotating invalidates the previous token immediately.

Play one channel externally

You don't need the export feeds to send a single channel to another player. On any programme panel (Tonight card, guide cell, search result) press Play:

• Desktop opens a tvdinner: link, which tvdinner 1.35+ handles directly (run tvdinner default-handler once): the browser hands it over after one remembered prompt — nothing saved, no application picker. For any other player, use Download .m3u and open the file, or Copy stream URL and paste it into the player's "open network stream" box.
• Android raises the app chooser (MX Player, VLC, …); tick "always" to skip it next time. Firefox for Android falls back to the .m3u download.

That one-channel .m3u also carries a url-tvg="…" link on its #EXTM3U header, pointing at a single-channel XMLTV feed (behind the same ticket). A player that reads it — tvdinner, TiviMate, … — shows that channel's programme guide with no separate EPG setup; one that doesn't just ignores the attribute. Programme times are zone-corrected per channel, same as the full export. (New in v0.1.45; the Android hand-off passes the stream URL straight to the player, so it has no .m3u to carry the guide.)

The link carries a signed ticket scoped to that one channel — not the tenant-wide export token — and expires after 24 hours, long enough to open a .m3u you saved earlier but not a standing secret. Stalker portal channels can't produce a static URL, so Play is unavailable for them (same limitation as the export feed).