# simply-dvb [Polski](README.pl.md) > 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`, > install `simply-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`. > The `simple-dvbt.db` database 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. ![Overview](docs/images/overview.png) | TV | TV guide | |---|---| | ![TV](docs/images/tv.png) | ![EPG](docs/images/epg.png) | | ![Channels](docs/images/channels.png) | ![Tuners](docs/images/tuners.png) | ## 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/`, `/xmltv/channels`, `/imagecache/` | | 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/`) – 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 | | 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/.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): ```bash scripts/build-deb-amd64.sh # x86_64 (PC, server, NAS) -> dist/simply-dvb_-1_amd64.deb scripts/build-deb-arm64.sh # Raspberry Pi 3/4/5, 64-bit OS -> dist/simply-dvb_-1_arm64.deb scripts/build-deb-armhf.sh # Raspberry Pi, 32-bit RPi OS -> dist/simply-dvb_-1_armhf.deb scripts/build-deb-all.sh # all three ``` All of them call `scripts/build-deb.sh `. **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: ```bash sudo apt install ./dist/simply-dvb_*_$(dpkg --print-architecture).deb sudo cat /var/lib/simply-dvb/initial-admin-password.txt ``` Panel: `http://:9980/`, streams: `http://: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 .`). ```bash 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 ```bash 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): ```bash ./dev.sh demo # generates 2 muxes with a test picture and EPG, runs the virtual adapter ``` ## First steps 1. **Tuners** → check that the card is visible (e.g. *Silicon Labs Si2168*, DVB-T / DVB-T2 / DVB-C). 2. **Scanning** → pick the frequency list for your region (e.g. “Europe – UHF 21–48”) → *Start scan*. Channels are created automatically (LCN numbers). 3. **Channels** → reorder by dragging, “Find icons”. 4. **Access** → copy the M3U and EPG URLs into the IPTV app on your TV. 5. **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://:9981/playlist` (tvheadend format) or `http://:9981/playlist.m3u` (`?format=hls` for HLS), * EPG: `http://: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=` – 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= tvg-chno=…,Name` | | `/stream/channelid/`, `/stream/channelnumber/`, `/stream/channelname/`, `/stream/channel/` | same | continuous MPEG-TS | | `/playlist/channelid/` | same | single-channel playlist – e.g. “Open in VLC” | | `/xmltv`, `/xmltv/channels` | same | channel ids = `tvg-id` from the playlist | | `/imagecache/` | same | channel logo | | JSON API `/api/serverinfo`, `/api/channel/grid`, `/api/channeltag/grid`, `/api/epg/events/grid`, `/api/dvr/entry/*`, `/dvrfile/` | same (on the stream port) | used by PVR Live, Sparkle TV and other Android TV “Live Channels” sources | | `?auth=`, `?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 `:9981` URLs. * 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`). ```bash # tvheadend still running (HTTP API, admin user) scripts/import-tvheadend.py --tvh http://:9981 --tvh-user admin --url http://: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/.ts` | Continuous MPEG-TS of a channel (optional `profile=`) | | `/hls//index.m3u8` | Live HLS of a channel (optional `profile=`) | | `/watch/` | Public player page (share link) | | `/icons/.png` | Channel icon | | `/recordings//index.m3u8`, `/recordings//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. ```json { "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.json` is required (default language and the full key catalogue); `langs/pl_PL.json` is Polish. * **Adding a language = adding a file.** Every `langs/*.json` found 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_PL` lists missing entries, `node scripts/i18n-missing.js --sources` lists panel texts without an entry in `en_US.json`. * `patterns` handle texts with values: `$1` inserts a group as-is, `$t1` translates it again. * `build.rs` validates 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; `.xml` and `.xml.gz` supported). 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` – the `dvb-demod-si2168-*.fw` files. No firmware = no lock; check `dmesg | grep -i si2168`. * Command-line test (without starting the server): ```bash 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. ## 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. ```sh simply-dvb user reset-admin # forgotten password: new random password for the administrator simply-dvb user passwd [--generate] # change a password (signs the user out everywhere) simply-dvb user list | add [--role viewer] [--generate] | role admin|viewer | logout | delete 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 | disable | delete simply-dvb settings show [key] | set | unset simply-dvb channels list [--all] | m3u [--base-url …] [--token …] | enable 1 2 3 | disable 4 simply-dvb db backup [file] | check | vacuum | restore # 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..css`, `app..js`), embedded in the binary and served with `Cache-Control: immutable`. Data: `/simply-dvb.db` (SQLite), `icons/`, `recordings/`. ## Development ```bash ./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 `.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 --role admin|viewer`, `simply-dvb user passwd `. 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](https://github.com/video-dev/hls.js) (Apache-2.0, `web/vendor/`).