Skip to content

M3U Playlists

Jump to bottom
Iain Smith edited this page Sep 1, 2026 · 4 revisions

M3U Playlists

The default, no-frills source: an M3U/M3U8 playlist, either fetched from a URL or read from a local file.

tvdinner https://example.com/playlist.m3u8
tvdinner ~/Downloads/my-playlist.m3u

A local file is told apart from a live channel URL by content, not extension — the first few KB are sniffed for #EXTM3U. A bare direct stream URL (no playlist wrapper at all) works too — tvdinner treats it as a single-channel playlist:

tvdinner https://example.com/stream.m3u8

What tvdinner reads from the playlist

  • Each entry's group-title becomes that channel's group in the guide and in --list output.
  • tvg-logo (if present) is used as the channel's logo; if a channel has none, tvdinner can optionally fall back to iptv-org's community logo database (--no-online-logos to turn that off).
  • The #EXTM3U header's own x-tvg-url/url-tvg attribute, if present, is used as the EPG source automatically — no --epg needed. Pass --epg URL to override it (or to supply one when the playlist doesn't carry one at all).

Picking a channel

  • --channel NAME (or a 1-based index) picks the starting channel; otherwise playback starts on the first one.
  • --list prints every channel (name, group, URL) and exits without playing — handy for finding the exact name to pass to --channel, or a channel's display name for --epg-shifts.
  • Once playing, use the program guide (g) to switch channels without restarting.

VOD from a group

By default, every entry plays as a live channel in the guide. If part of your playlist is really on-demand content dumped into one or more group-titles (a common shape for smaller IPTV providers who don't run a real Xtream/Stalker panel), pull it out into the dedicated VOD browser instead:

tvdinner playlist.m3u --vod-group Movies --vod-group "TV Shows"

See VOD Browsing & Resume for how the m browser itself works. This is opt-in and repeatable — nothing changes for an existing playlist unless you name a group.

Opening .m3u files from the desktop (Linux)

New in 1.33.0.

The .deb and .rpm install a desktop entry (/usr/share/applications/tvdinner.desktop) and an icon, registering tvdinner as an opener for .m3u / .m3u8 files. It then appears in a file manager's Open With menu, and in the "what should I do with this file?" prompt a browser shows after downloading a playlist. The MIME types covered are audio/x-mpegurl, audio/mpegurl, application/x-mpegurl and application/vnd.apple.mpegurl.

The entry is Terminal=true: tvdinner is a keyboard-driven TUI, so the desktop launches it inside your terminal emulator, with mpv's own video window alongside. Exec is tvdinner %f — the file is passed exactly as if you'd typed tvdinner /path/to/playlist.m3u.

It does not make itself the default handler — an .m3u is just as often a local music playlist for an audio player — so the first double-click still shows an application picker. To make tvdinner the default and skip that dialog (1.34.0+):

tvdinner default-handler

That runs xdg-mime default tvdinner.desktop <the M3U MIME types> for you, writing your own ~/.config/mimeapps.list (no root, nothing system-wide) and verifying the result. Undo it from a file manager's Open With dialog, or by editing that file. By hand:

xdg-mime default tvdinner.desktop audio/x-mpegurl audio/mpegurl application/x-mpegurl application/vnd.apple.mpegurl
xdg-mime query default audio/x-mpegurl      # confirm: tvdinner.desktop

Running from source instead of a package? tvdinner default-handler also drops a ~/.local/share/applications/tvdinner.desktop when it can't find an installed one. By hand:

install -Dm644 data/tvdinner.desktop ~/.local/share/applications/tvdinner.desktop
install -Dm644 data/tvdinner.svg ~/.local/share/icons/hicolor/scalable/apps/tvdinner.svg
update-desktop-database ~/.local/share/applications

A plain https://…/playlist.m3u link in a browser is still the browser's decision: it normally downloads the file, and then opening that download goes through this entry. There's no handler hook for https itself. On Android the same download-then-open path works with mpv-android (or any player registered for the M3U MIME types) as the handler.

tvdinner: links (1.35.0+)

A tvdinner: link does have a browser hook. The desktop entry claims the x-scheme-handler/tvdinner scheme, and tvdinner unwraps a URL argument of the form tvdinner:https://host/playlist.m3u to the plain URL before loading it (url-tvg guide and all). So a tvdinner:https://…/playlist.m3u link opens straight in tvdinner — the browser hands the URL over after one remembered "Open tvdinner?" prompt, nothing is saved to Downloads, and there's no application picker. tvtimes' Play button emits one of these on desktop (see tvtimes' Export Feeds). tvdinner default-handler registers the scheme along with the .m3u types.

Everything else

Once loaded, an M3U playlist behaves exactly like every other live-channel source (Xtream, Stalker, HDHomeRun) — the program guide, favorites, recording, and scheduling all work identically regardless of where the channel list came from:

An M3U URL/path also works directly as a bookmark's URL, so you don't have to retype it (or its --epg/--channel) every time.

Clone this wiki locally