25 KiB
simply-dvb
Formerly simple-dvbt – renamed because it handles more than DVB-T (DVB-T2 and DVB-C too). Moving from an old install:
sudo systemctl disable --now simple-dvbt && sudo apt remove simple-dvbt, installsimply-dvb, stop it and copy the data:sudo cp -a /var/lib/simple-dvbt/. /var/lib/simply-dvb/ && sudo chown -R simply-dvb: /var/lib/simply-dvb. Thesimple-dvbt.dbdatabase is taken over automatically and channel identifiers (UUIDs) do not change.
A lightweight DVB-T / DVB-T2 / DVB-C television server written in Rust – a simple alternative to tvheadend that is compatible with its HTTP URLs (it can replace it 1:1 in client apps). It scans multiplexes, serves channels as HLS, MPEG-TS and M3U playlists, collects EPG from the broadcast and publishes it as XMLTV, records to disk and has a fast web panel with an in-browser player. A single binary with no runtime dependencies (ffmpeg is optional – only for transcoding for browsers).
Tested with Silicon Labs Si2168 (DVB-T/T2/C) cards + Si2157 tuner.
| TV | TV guide |
|---|---|
![]() |
![]() |
![]() |
![]() |
Features
| Area | What you get |
|---|---|
| Tuners | Native Linux DVB API v5 (ioctl, no dvbv5-zap/w_scan), multiple adapters, signal strength (dBm/%), SNR (dB), error counter, one multiplex shared by many clients, kernel PID filtering (only the PIDs clients need plus EPG/SI tables are read – far less CPU than reading the whole multiplex; can be switched off in Settings), priorities (recordings > watching > background EPG), virtual adapter from .ts files |
| Scanning | DVB-T, DVB-T2 (PLP), DVB-C (symbol rate, QAM). Lists: Europe UHF 21–48 (after the 700 MHz refarming) and 21–69, VHF III + UHF, Italy, Australia (7 MHz), New Zealand, cable 114–858 MHz, custom list, rescan of saved muxes. NIT discovery (muxes announced by the network are queued automatically), LCN, automatic channel creation, background scan of saved muxes on an idle adapter (every 24 h by default; it gives way immediately when someone starts watching or recording); DVB text in every character table (ISO 6937, ISO 8859-1…16, UTF-8, UCS-2, GB2312, Big5) |
| Channels | Drag-and-drop ordering, numbering, groups, enable/disable, icons (automatic lookup in logo repositories in the background, upload, URL), manual service binding; filters (type, group, enabled, hide scrambled/broken, without icon/EPG) with bulk enable/disable/delete of the filtered list |
| Streams | Live HLS (segmented on keyframes, H.264/HEVC/MPEG-2), continuous MPEG-TS (starting at a keyframe), ffmpeg profiles: pass (original), aac (audio → AAC), h264 (HEVC/MPEG-2 → H.264 720p) |
| M3U / XMLTV | /playlist.m3u with tvg-id, tvg-chno, tvg-logo, group-title, url-tvg; /epg.xml; tvheadend paths: /playlist, /stream/channelid/<id>, /xmltv/channels, /imagecache/<id> |
| Ports | Panel/API on 9980, separate stream port 9981 (like tvheadend's HTTP, no panel – safe to expose), HTSP on 9982 (like tvheadend: Kodi HTSP client, TVHClient, PVR apps) |
| EPG | Over the air (EIT p/f + schedule, including other muxes), periodic walk over all muxes, XMLTV import from a URL (e.g. https://epg.ovh/pl.xml, .xml/.xml.gz), channel matching by id or name, id suggestions from imported sources |
| Browser | hls.js player, automatic profile selection based on the codecs the browser supports (HEVC, AC-3, MP2…) with fallback on errors, EPG grid, one-click recording |
| Sharing | Public link to a single channel (/watch/<token>) – a player page without access to other channels |
| Security | Panel login (argon2, HttpOnly sessions, CSRF protection, rate limit), administrator / viewer roles, ACL: networks with token-free stream access, networks allowed to reach the panel, access tokens (optionally limited to networks), trusted reverse proxies. ACL entries may be networks, addresses or DDNS host names (for a dynamic public IP; re-resolved every minute) |
| Recording | From the EPG (with padding) or manual; series rules (title fragment or regex, optional channel – like tvheadend's autorec) with a preview of matching programmes; .ts file + index, in-browser playback (HLS VOD with byte ranges), download, resume after restart; automatic cleanup (age, minimum free space); schedule view per day with tuner-conflict detection |
| Player | Keyboard shortcuts: ↑/↓ channel, digits – channel number, F – fullscreen, P – picture-in-picture, M – mute, space – pause, ? – help; OSD with channel number and name |
| Monitoring | Live charts on the overview (15 min history): CPU (system and process), memory, process RSS, streaming throughput, application traffic per protocol (MPEG-TS, HLS, HTSP) and from the tuners, clients/HLS sessions, temperature, load; per tuner: mux bitrate, signal strength (%/dBm), SNR, uncorrected blocks, BER, stream errors (CC/TEI), lock stages (signal/carrier/FEC/sync/lock), transmission parameters, PIDs/stuffing and hardware details (bus, driver, product, USB speed, frequency range, capabilities). Antenna meter (Tuners → Antenna meter): big live strength/SNR readout with a quality verdict and optional beeps for aligning the antenna from a phone. /metrics in Prometheus format. Active clients with protocol, device, address, access, duration and rate |
| TV app pairing | The simply-tv Android TV app shows a QR code; scanning it opens Pair a TV in the panel – after confirming, the server creates an access token for the TV and hands it over (POST /api/pair/start, GET /api/pair/poll, codes expire after 10 min) |
| Statistics | Viewing history: watch time, most watched channels, viewers, devices, protocols, time of day and per day (24 h / 7 / 30 days / year) |
| Logs | Logs page with categories (application, tuners & devices, streaming, access, EPG, recording, system), level filter, search, live follow and download; logins, denied requests, tokens and HTSP sessions are logged under access |
| Backup | Configuration export/import (muxes, services, channels, rules, tokens, settings) as JSON; full database copy from the panel or simply-dvb db backup |
| Interface | English by default, Polish included, any number of languages (langs/<locale>.json files, picker in the top bar); playback in the browser or VLC (single-channel playlist); themes: dark (default), midnight (OLED), light, system; 7 accent colours, density, scale, pinned sidebar, start page, default player profile, EPG grid zoom, clock, logos/programme progress, animations – stored in the user profile (follow you to every device). Favourite channels (★, own filter and M3U), programme reminders (notification 2 min before the start), signed-in devices with remote sign-out, mobile layout with a bottom tab bar, installable as an app (PWA, HTTPS) |
| Distribution | .deb package with a (hardened) systemd service, Docker image, compose.yml |
Quick start
.deb package (Debian / Ubuntu / Raspberry Pi OS)
One script per architecture (also meant for CI):
scripts/build-deb-amd64.sh # x86_64 (PC, server, NAS) -> dist/simply-dvb_<version>-1_amd64.deb
scripts/build-deb-arm64.sh # Raspberry Pi 3/4/5, 64-bit OS -> dist/simply-dvb_<version>-1_arm64.deb
scripts/build-deb-armhf.sh # Raspberry Pi, 32-bit RPi OS -> dist/simply-dvb_<version>-1_armhf.deb
scripts/build-deb-all.sh # all three
All of them call scripts/build-deb.sh <arch>. The build itself runs in a Docker container
(image scripts/docker/builder.Dockerfile: Rust + targets, zig, cargo-zigbuild, cargo-deb), so the host only needs
Docker. The builder image is created on the first run (cached afterwards); crates and build artefacts live in
.cache/ and target/docker/, and the packages land in dist/ owned by the current user. Cross-compiling with zig
gives a fixed glibc 2.31 baseline, so the packages run on Debian 11+, Ubuntu 20.04+ and RPi OS bullseye+.
Variables: BUILD_IN_DOCKER=0 (build directly on the host/in CI – then the tools from the builder image are
needed), BUILDER_IMAGE, DOCKER_ARGS, DOCKER_BUILD_ARGS (e.g. --network host behind a proxy),
GLIBC (default 2.31), OUT_DIR (default dist).
Install:
sudo apt install ./dist/simply-dvb_*_$(dpkg --print-architecture).deb
sudo cat /var/lib/simply-dvb/initial-admin-password.txt
Panel: http://<server>:9980/, streams: http://<server>:9981/playlist. Service configuration: /etc/default/simply-dvb,
logs: journalctl -u simply-dvb -f. The simply-dvb user is added to the video group.
Docker
The image builds natively on x86_64 and ARM (also docker buildx build --platform linux/amd64,linux/arm64 .).
docker compose up -d --build # compose.yml: /dev/dvb, video group, host networking
docker logs simply-dvb | grep password
The video group must have the same GID as on the host: VIDEO_GID=$(getent group video | cut -d: -f3) docker compose up -d.
Set TZ (e.g. TZ=Europe/Berlin) so EPG times and recordings use your local time.
From source
cargo build --release
./target/release/simply-dvb --data-dir ./data serve --listen 0.0.0.0:9980 --stream-listen 0.0.0.0:9981
Without a DVB card (demo, UI testing):
./dev.sh demo # generates 2 muxes with a test picture and EPG, runs the virtual adapter
First steps
- Tuners → check that the card is visible (e.g. Silicon Labs Si2168, DVB-T / DVB-T2 / DVB-C).
- Scanning → pick the frequency list for your region (e.g. “Europe – UHF 21–48”) → Start scan. Channels are created automatically (LCN numbers).
- Channels → reorder by dragging, “Find icons”.
- Access → copy the M3U and EPG URLs into the IPTV app on your TV.
- TV → watch in the browser.
TV (e.g. Sony / Android TV)
In an IPTV app (e.g. Kodi + PVR IPTV Simple Client, TiviMate, IPTV Smarters, OTT Navigator):
- playlist:
http://<server>:9981/playlist(tvheadend format) orhttp://<server>:9981/playlist.m3u(?format=hlsfor HLS), - EPG:
http://<server>:9981/xmltv/channels(or/epg.xml).
No token is needed on the local network (private networks are open by default – change it in Access → ACL).
From outside the LAN create a token and use …/playlist.m3u?token=<token> – the token is appended to
every URL in the playlist and EPG automatically.
tvheadend compatibility and ports
simply-dvb implements the tvheadend HTTP interface used by IPTV apps, Kodi (IPTV Simple), VLC and TVs. After scanning and arranging the list you only need to change the server address in the app:
| tvheadend | simply-dvb | Notes |
|---|---|---|
http://host:9981/playlist (/playlist/channels, .m3u, /playlist/auth/channels) |
same, line for line | #EXTINF:-1 tvg-logo=… tvg-id=<uuid> tvg-chno=…,Name |
/stream/channelid/<id>, /stream/channelnumber/<n>, /stream/channelname/<name>, /stream/channel/<uuid> |
same | continuous MPEG-TS |
/playlist/channelid/<id> |
same | single-channel playlist – e.g. “Open in VLC” |
/xmltv, /xmltv/channels |
same | channel ids = tvg-id from the playlist |
/imagecache/<id> |
same | channel logo |
JSON API /api/serverinfo, /api/channel/grid, /api/channeltag/grid, /api/epg/events/grid, /api/dvr/entry/*, /dvrfile/<uuid> |
same (on the stream port) | used by PVR Live, Sparkle TV and other Android TV “Live Channels” sources |
?auth=<code>, ?ticket=<ticket>, HTTP Basic (login/password) |
access token as auth/ticket; Basic: a panel user's login and password, or a token as the password |
|
?profile=pass, webtv-h264-aac-mpegts … |
pass; webtv profiles → h264; unknown → pass |
|
| port 9981 (HTTP) | 9981 – separate stream port (no panel or API) | panel on 9980 |
| port 9982 (HTSP) | 9982 – HTSP server | Kodi “Tvheadend HTSP Client”, TVHClient, PVR apps |
Things worth knowing:
- HTSP (9982) – tvheadend's binary protocol. Apps configured with a server address and port 9981 that then
stream over 9982 (Kodi “Tvheadend HTSP Client”, TVHClient, PVR apps on Android/Google/Sony TV) use it.
Supported: channels and tags, EPG (async updates, queries), live streaming (frames as
muxpkt, signal and queue status), recordings (list, schedule, cancel, delete, playback over HTSP), disk space, tickets for HTTP. Not supported: timeshift (pause/rewind of live TV) and recording rules over HTSP (use the panel). Authentication: open networks need no login; elsewhere enter any user name and an access token as the password (HTSP digests cannot be checked against stored panel passwords). - While tvheadend still holds port 9981 (or 9982), simply-dvb keeps running: streams are served on the panel port
and the stream port is taken over automatically (checked every 15 s) as soon as tvheadend is stopped –
no restart needed, and TV apps keep their
:9981URLs. - The stream port only serves playlists, streams (TS/HLS), EPG, icons, public
/watch/…links and metrics – no panel and no API. You can expose it via your router/reverse proxy and keep the panel on the LAN (see also Access → ACL). All of these paths also work on the panel port.
Moving the channel list from tvheadend
After scanning, scripts/import-tvheadend.py copies the channel numbers (and optionally names, groups from tags
and the enabled state) from tvheadend. Channels are matched in passes: by service (ONID/TSID/SID, or SID + frequency),
by name, by a loose name without quality/test/prefix words (“Zet” = “Radio ZET em.test.”) and by a similar name;
tvheadend duplicates (two channels for one service) are listed and skipped.
It runs a dry run first and changes nothing without --apply; only the Python 3 standard library is needed
(the .deb installs it as /usr/share/simply-dvb/import-tvheadend.py).
# tvheadend still running (HTTP API, admin user)
scripts/import-tvheadend.py --tvh http://<server>:9981 --tvh-user admin --url http://<server>:9980 --user admin
# or from tvheadend's configuration directory (also works when tvheadend is stopped)
sudo scripts/import-tvheadend.py --tvh-config /var/lib/tvheadend --url http://localhost:9980 --user admin \
--names --groups --enabled --apply
Options: --names (only names set by hand in tvheadend; --names all copies every name – these may be stale
after a broadcaster renamed a channel), --reset-names (back to the current broadcast names), --groups, --enabled,
--fuzzy 0.86 (similarity threshold, 1 = exact names only), --create (create channels for services that have none yet),
--unmatched keep|after|disable (what to do with simply-dvb channels tvheadend does not have; default: number them
after the imported ones). Both can run side by side during the migration (tvheadend on 9981, simply-dvb's panel on its own port);
after stopping tvheadend, simply-dvb takes over 9981 by itself.
HTTP endpoints
| URL | Description |
|---|---|
/playlist.m3u |
Playlist. Parameters: format=ts|hls, profile=pass|aac|h264, token= |
/epg.xml |
XMLTV for enabled channels |
/stream/<id>.ts |
Continuous MPEG-TS of a channel (optional profile=) |
/hls/<id>/index.m3u8 |
Live HLS of a channel (optional profile=) |
/watch/<share> |
Public player page (share link) |
/icons/<id>.png |
Channel icon |
/recordings/<id>/index.m3u8, /recordings/<id>/file |
Recording: HLS VOD / file (Range supported) |
/api/* |
Panel API (JSON, needs a session; state-changing requests need the X-Requested-With: simply-dvb header) |
/metrics |
Prometheus metrics (access like streams: local network, token, session) |
/healthz |
Health check |
Stream access is checked in this order: token= → share= (single channel only) → client address in
“networks without a token” → panel session → HTTP Basic (password = token).
Browser playback and profiles
The original stream (pass) is played without any transcoding whenever the browser can decode it –
hls.js repackages MPEG-TS (H.264, HEVC, MPEG audio/MP2, AAC, AC-3) in the browser, the server does no work.
What a browser can decode depends on the browser and the GPU:
| Codec | Chrome / Edge | Firefox | Safari |
|---|---|---|---|
| H.264, MP2, AAC | yes | yes | yes |
| HEVC (H.265) | only with hardware decoding (Windows/macOS/Android; Linux: VA-API) | Windows/macOS (hardware), Linux 137+ with VA-API | yes |
| AC-3 / E-AC-3 | no | no | yes |
Many DVB-T2 networks (e.g. Poland: HEVC video, MP2 + E-AC-3 audio) are fine in Safari and in Chrome/Edge with
hardware HEVC decoding: the player picks the MP2 track automatically. On Chrome for Linux, HEVC needs a VA-API
capable GPU (Intel/AMD) – check chrome://gpu (“Video Decode: Hardware accelerated”).
When the browser cannot decode a codec, the player switches to a transcoding profile – this needs ffmpeg
on the server (apt install ffmpeg). Without ffmpeg the player always tries the original stream and, if it
fails, explains why and offers Open in VLC. The TV page shows which codecs the current browser supports.
pass– unchanged,aac– video unchanged, audio transcoded to AAC (lightweight),h264– full transcoding to H.264 720p (CPU-heavy; arguments in Settings → ffmpeg, VAAPI can be enabled, e.g.-vaapi_device /dev/dri/renderD128 -vf 'format=nv12,hwupload,scale_vaapi=w=-2:h=720' -c:v h264_vaapi).
A profile can also be forced in the player or with the profile= URL parameter. TVs, VLC and Kodi decode
HEVC/E-AC-3 themselves, so the M3U playlists always use the original stream.
Languages
The interface, server messages and logs are in English; translations are JSON files in langs/
(same layout as RustProxy). The English text doubles as the translation key.
{
"meta": { "locale": "pl_PL", "name": "Polish", "native_name": "Polski", "direction": "ltr" },
"translations": { "Channels": "Kanały", "Recording scheduled": "Zaplanowano nagranie" },
"patterns": [ { "match": "^Found (\\d+) icons$", "replace": "Znaleziono $1 ikon" } ]
}
langs/en_US.jsonis required (default language and the full key catalogue);langs/pl_PL.jsonis Polish.- Adding a language = adding a file. Every
langs/*.jsonfound at build time is embedded and shows up automatically in the language picker (top bar and Settings → Appearance) – no code changes. node scripts/i18n-missing.js --new de_DE "Deutsch" "German"creates a pack with all keys; empty values fall back to English, so a language can be translated gradually.node scripts/i18n-missing.js pl_PLlists missing entries,node scripts/i18n-missing.js --sourceslists panel texts without an entry inen_US.json.patternshandle texts with values:$1inserts a group as-is,$t1translates it again.build.rsvalidates the files (valid JSON,meta.locale= file name) and embeds them in the JS bundle.
EPG over the air and from the internet
- Over the air (EIT) – collected while watching and periodically from every mux (Settings → EPG).
- From an XMLTV URL – e.g.
https://epg.ovh/pl.xml(or any other provider;.xmland.xml.gzsupported). Channels are matched by name; when names differ, pick the id in the channel's EPG ID field (suggestions come from the imported sources). XMLTV data takes precedence over EIT.
Si2168 tips
- Firmware:
firmware-linux-nonfree(Debian) /linux-firmware– thedvb-demod-si2168-*.fwfiles. No firmware = no lock; checkdmesg | grep -i si2168. - Command-line test (without starting the server):
simply-dvb adapters simply-dvb tune --freq 538 --system dvbt2 simply-dvb tune --freq 346 --system dvbc --symbol-rate 6900 --modulation qam256 - Signal strength is reported by the Si2157 tuner in dBm, SNR by the Si2168 in dB.
- DVB-T2 with multiple PLPs: set the PLP when adding a mux manually.
TV app (simply-tv)
The Android TV app simply-tv pairs with a QR code: on the TV enter the server address and choose Pair with QR code, scan the code with a phone, sign in to the panel and confirm – an access token is created and handed to the TV (also possible by typing the 6-character code in Access → Pair a TV). Endpoints: POST /api/pair/start, GET /api/pair/poll (TV), GET /api/pair/{code}, POST /api/pair/{code}/confirm (panel). /api/status/inputs?channel=<id> returns the tuner carrying a channel with signal, SNR, BER and error counters.
Command line tools
Run them on the server (as root or sudo -u simply-dvb; files created as root get the data
directory's owner). They work directly on the database, also when the panel is unreachable, and a
running server applies changed settings within a few seconds.
simply-dvb user reset-admin # forgotten password: new random password for the administrator
simply-dvb user passwd <login> [--generate] # change a password (signs the user out everywhere)
simply-dvb user list | add <login> [--role viewer] [--generate] | role <login> admin|viewer | logout <login> | delete <login>
simply-dvb access show # who may reach the panel / streams without a token
simply-dvb access reset-panel # locked out by the panel network limit? allow everywhere again
simply-dvb access open-add myhome.ddns.net # token-free streams for a network/address/DDNS name
simply-dvb token add tv --allow myhome.ddns.net --base-url http://192.168.1.10:9981 # prints ready URLs
simply-dvb token list | enable <name> | disable <name> | delete <name>
simply-dvb settings show [key] | set <key> <value> | unset <key>
simply-dvb channels list [--all] | m3u [--base-url …] [--token …] | enable 1 2 3 | disable 4
simply-dvb db backup [file] | check | vacuum | restore <file> # restore: stop the service first
simply-dvb status # version, server state, counts, next recording, adapters
simply-dvb doctor # health check: data dir, database, adapters/permissions, disk, ffmpeg
simply-dvb adapters | tune --freq 634 # tuner diagnostics
simply-dvb completions bash > /etc/bash_completion.d/simply-dvb # tab completion (bash/zsh/fish)
Personal panel preferences (language, theme, accent, filters) are stored in the user's profile and follow the account to every browser and phone.
Architecture
/dev/dvb/adapterN ──► reader thread (frontend+demux+dvr, full TS) ──► broadcast
│ │
EIT → SI collector → EPG (SQLite) ├─► service filter (PAT/PMT) ─► client TS
├─► [ffmpeg] ─► HLS segmenter ─► HLS session
└─► segmenter ─► recording file + index
src/dvb– Linux DVB ioctls, virtual adapter, scanning,src/ts– MPEG-TS: packets, PSI/SI sections with CRC, PAT/PMT/SDT/NIT/EIT/TDT, DVB text, PES, test generator,src/stream– service filter and HLS segmenter,src/tuner.rs– tuner allocation, sharing, preemption, statistics,src/hls.rs,src/pipeline.rs,src/recorder.rs,src/epg.rs,src/scanjob.rs,src/web– axum: API, streams, panel.
Panel (like RustProxy): the sources in web/css/*.css, web/js/*.js and langs/*.json (+ web/vendor/hls.min.js) are
combined at build time (build.rs) into one CSS and one JS file with unique names (app.<hash>.css,
app.<hash>.js), embedded in the binary and served with Cache-Control: immutable.
Data: <data-dir>/simply-dvb.db (SQLite), icons/, recordings/.
Development
./dev.sh check # fmt, clippy -D warnings, JS syntax, language packs
./dev.sh test # unit + end-to-end tests (virtual adapter: scan, HLS, TS, EPG, ACL, recording)
./dev.sh run # development server (./data)
./dev.sh docker # Docker image
./dev.sh deb-all # .deb for amd64, arm64 and armhf
./dev.sh dist # check + test + all .deb + docker
Runtime options (also as environment variables): --data-dir (SIMPLY_DVB_DATA_DIR),
--dev-root (SIMPLY_DVB_DEV_ROOT), --virtual-dir (SIMPLY_DVB_VIRTUAL_DIR, a directory with
<MHz>.ts files), serve --listen (SIMPLY_DVB_LISTEN, panel, default 9980), serve --stream-listen
(SIMPLY_DVB_STREAM_LISTEN, stream port, default 9981, off disables it). Users from the command line:
simply-dvb user add <login> --role admin|viewer, simply-dvb user passwd <login>.
Translations: engine in web/js/10-i18n.js, packs in langs/*.json. New UI text (in English) needs an entry in
langs/en_US.json and translations in the other packs (or a patterns entry for texts with values).
Code comments, logs and messages are English.
The player uses hls.js (Apache-2.0, web/vendor/).




