Turns the live TV channel list of a TechniSat receiver into a stable HDHomeRun network tuner for Plex and Jellyfin. The same channels are also available as an optional M3U playlist.
TechniSat receivers frequently change internal stream URLs and session parameters due to channel rescans, background updates, or reboots. Linking these raw URLs directly into a media center causes constant breakage, as the streams become dead ends as soon as the receiver refreshes its internal state.
TechniMapper acts as an abstraction layer to ensure your configuration remains stable:
- HDHomeRun Emulation: Plex and Jellyfin use TechniMapper directly as a network tuner below
/hdhr, no M3U file needed (see below). The tuner name is built automatically from the detected receiver, e.g.TechniSat DIGIT ISIO STC. - Dynamic Synchronization: A background cron engine crawls the receiver’s shifting UPnP structure to fetch the latest, valid stream URLs.
- Static Mapping: Maps volatile URLs to permanent, custom Channel IDs defined via the Web UI. The ID becomes the channel number.
- Automated List Fetching: Selecting a different target channel list automatically triggers an immediate Apply & Fetch cycle.
- Smart Parsing: One-click extraction automatically parses channel numbers from channel names.
- Safe by Default: If the receiver is unreachable (e.g. in standby), the last known channel list keeps being served. Strict input validation, optional Basic Auth, health endpoint, non-root container, signed multi-arch images.
- Optional M3U Playlist: The same mapped channels are available at
/playlist.m3ufor players such as VLC (see below).
TechniMapper is specifically developed and tested for the TechniSat DIGIT ISIO STC.
✅ Supported: DIGIT ISIO S / S1 / S2, DIGIT ISIO STC
❌ Not Supported: DIGIPLUS UHD S2, DIGIT ISIO S3, and newer
Note: Models not listed as supported may use different SOAP service structures which are not currently implemented.
The receiver must be reachable from the container via a private IPv4 address (10.x, 172.16–31.x, 192.168.x). For VPN/CGNAT setups set ALLOW_NON_PRIVATE_IP=true.
The container runs as the unprivileged user node (UID 1000). The examples below store /app/data in a named volume; Docker gives it the correct permissions automatically, so no setup is needed.
If you prefer a bind mount (e.g. ./data:/app/data), the directory must be writable for that user. Otherwise the container restarts in a loop (Portainer shows no IP and no ports) and the log says "Data directory ... is not writable":
mkdir -p data && chown -R 1000:1000 dataTechniMapper listens on port 9191 by default (PORT), and the examples publish it unchanged (9191:9191). The Web UI and all endpoints are then reachable at http://<YOUR-SERVER-IP>:9191. Enter the port you publish in Plex and Jellyfin. If you change PORT, change the port mapping and the address in your media center accordingly.
services:
technimapper-m3u-proxy:
image: ghcr.io/danielfranze/technimapper-m3u-proxy:latest
container_name: technimapper-m3u-proxy
ports:
- "9191:9191"
volumes:
- technimapper-data:/app/data
- /etc/localtime:/etc/localtime:ro
environment:
- TZ=Europe/Berlin
# - HDHR_FRIENDLY_NAME=Living Room
# - ADMIN_USER=admin
# - ADMIN_PASSWORD=change-me
read_only: true
tmpfs:
- /tmp
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
restart: unless-stopped
volumes:
technimapper-data:latest always points to the newest stable release (pre-releases such as 1.7.0-rc.1 never move latest, 1 or 1.7; use their exact tag to test them). If you need reproducible deployments, pin a version tag instead, e.g. ghcr.io/danielfranze/technimapper-m3u-proxy:1.6.1.
The repository also ships a ready-to-use docker-compose.yml (builds locally with build: .).
- Open your Portainer dashboard → Stacks → Add stack.
- Give it a name (e.g.,
technimapper-m3u-proxy). - Select the Web editor and paste the Compose snippet from Option A.
- The snippet uses a named volume (
technimapper-data:/app/data), which works in Portainer without any permission setup. Avoid relative bind mounts such as./datathere: Docker creates them asrootand the container cannot write to them. If you want a bind mount, use an absolute host path and runchown -R 1000:1000 <path>once.
docker run -d \
-p 9191:9191 \
--name technimapper-m3u-proxy \
-v technimapper-data:/app/data \
-v /etc/localtime:/etc/localtime:ro \
-e TZ=Europe/Berlin \
--restart unless-stopped \
ghcr.io/danielfranze/technimapper-m3u-proxy:latestYour settings and mapping live in the volume and survive updates.
- Portainer: Stacks → your stack → Update the stack with Re-pull image enabled.
- Docker Compose:
docker compose pull && docker compose up -d - Docker CLI:
docker pull ghcr.io/danielfranze/technimapper-m3u-proxy:latest, then remove the container (docker rm -f technimapper-m3u-proxy) and run the command from Option C again.
Check the CHANGELOG for breaking changes before you update.
The server now listens on port 9191 by default (it was 3000), and the examples use 9191:9191. If your stack still publishes 3000:3000 and you do not set PORT, the container is no longer reachable on that port after the update. Either change the mapping to 9191:9191 (and use http://<server>:9191 from now on) or keep your old port by setting the environment variable PORT=3000.
- Stop the container.
- If you used a single-file mount (
./mapping.json:/app/data/mapping.json), move the file into a directory:mkdir -p data && mv mapping.json data/. - Either keep the bind mount and run
chown -R 1000:1000 data, or switch to a named volume as in Option A (then re-import your settings with Export/Import in the UI). - Start the new version.
- Check the logs: invalid persisted values (e.g. a broken cron expression) are repaired automatically and reported as warnings.
Read the CHANGELOG for all breaking changes.
Everything related to the receiver (IP, port, cron schedule, channel list, mapping) is configured in the Web UI at http://<YOUR-SERVER-IP>:9191. A sync interval of */5 * * * * (the default) keeps the stream URLs fresh without stressing the receiver. Runtime behavior is controlled via environment variables:
| Variable | Default | Description |
|---|---|---|
PORT |
9191 |
Port the server listens on (inside the container). Publish the same port (9191:9191); if you change it, adjust the mapping and the address in Plex/Jellyfin. |
DATA_DIR |
/app/data |
Directory for mapping.json. Must be writable. |
REQUEST_TIMEOUT_MS |
5000 |
Idle timeout per UPnP request (hard deadline: 3×). |
ALLOW_NON_PRIVATE_IP |
false |
Allow receiver IPs outside RFC1918 (VPN/CGNAT). Loopback and link-local stay blocked. |
ADMIN_USER / ADMIN_PASSWORD |
– | Enables HTTP Basic Auth for the UI and /api/*. Set both. |
TRUST_PROXY |
– | Number of reverse-proxy hops (or true) so rate limiting sees real client IPs. |
HDHR_ENABLED |
true |
Set to false to switch off the HDHomeRun emulation below /hdhr. |
HDHR_FRIENDLY_NAME |
- |
Tuner name in Plex/Jellyfin. - (or empty) means automatic: TechniSat <detected model>, e.g. TechniSat DIGIT ISIO STC (just TechniSat until the first successful sync). Set your own name to override it. |
HDHR_DEVICE_ID |
12345678 |
8 hex digits. Must be unique per tuner in your network; change it if you run more than one instance. |
HDHR_TUNER_COUNT |
2 |
Number of tuners reported to the client (1-16). Informational only, see limitations below. |
LOG_LEVEL |
info |
error, warn or info. |
LOG_FORMAT |
text |
text or json (one JSON object per line, for log collectors). |
TZ |
– | Time zone of the container. |
| Endpoint | Auth | Description |
|---|---|---|
GET /hdhr/discover.json, /hdhr/lineup_status.json, /hdhr/lineup.json, /hdhr/stream/:id |
public | HDHomeRun emulation, see below. |
GET /playlist.m3u |
public | Optional M3U playlist. 503 + Retry-After while nothing is synced/mapped. |
GET /health |
public | Liveness/status JSON (ok or degraded, last sync, last error). |
GET /api/get-config |
Basic Auth¹ | Current settings, version, last sync, last error. |
POST /api/fetch-channels |
Basic Auth¹ | Applies settings and syncs with the receiver. |
POST /api/save-mapping |
Basic Auth¹ | Saves the channel-name → ID mapping. |
GET /api/export-config / POST /api/import-config |
Basic Auth¹ | Backup and restore of settings and mapping. |
¹ Only enforced if ADMIN_USER and ADMIN_PASSWORD are set.
TechniMapper presents itself as an HDHomeRun network tuner. Plex and Jellyfin read the channel list from the API. Which channels appear is decided by your mapping: only channels with an ID are listed, and the ID becomes the channel number.
| Endpoint | Purpose |
|---|---|
GET /hdhr/discover.json |
Device description (name, tuner count, BaseURL, LineupURL). The name is TechniSat <detected model> unless you set HDHR_FRIENDLY_NAME. |
GET /hdhr/lineup_status.json |
Tells the client that no scan is running. |
GET /hdhr/lineup.json |
The channel list built from your mapping (GuideNumber, GuideName, URL). The leading number of the receiver's channel name is dropped (001 Das Erste HD becomes Das Erste HD). |
GET /hdhr/stream/:id |
Answers with an HTTP 302 redirect to the receiver's stream URL, so the MPEG-TS stream flows directly from the receiver to the media center. |
POST /hdhr/lineup.post |
Accepted and ignored (a "scan" has nothing to do, the lineup comes from the mapping). |
The absolute URLs in the answers are built from the Host header of the request, so the emulation works with any port mapping.
Setup: add the tuner by address in Plex (Live TV & DVR) or Jellyfin (Live TV → Tuner devices → HDHomeRun): http://<server-ip>:9191/hdhr. Check the address in a browser first: http://<server-ip>:9191/hdhr/discover.json must answer with JSON. After you change the mapping, refresh the channel list in the client.
Limitations
- No automatic discovery (SSDP/UDP): the tuner has to be added by address.
- No program guide (EPG) is provided. Plex and Jellyfin need a separate guide source to show program data.
- The tuner count is only reported to the client. The number of parallel streams is limited by the receiver itself.
- Streams are redirected, not proxied. The client must be able to reach the receiver's IP address directly, and the receiver must serve the stream to that client.
- If two channels share the same ID, only the first one is listed.
- Compatibility depends on the client version: whether it accepts an address with a path (
/hdhr) and whether it follows the redirect for live streams is client behavior. This has not been verified against every Plex or Jellyfin version, so test your client first.
http://<server-ip>:9191/playlist.m3u serves the same mapped channels as an M3U playlist, for example for VLC or other IPTV players. Each entry carries tvg-id, tvg-name and tvg-chno (the channel ID). While nothing is synced or mapped yet, the endpoint answers 503 instead of an empty list, so clients that clean up missing channels never purge them by accident. The Copy M3U URL button in the Web UI copies this address.
- TechniMapper is built for trusted home/office networks. Do not expose it directly to the internet.
- Set
ADMIN_USER/ADMIN_PASSWORDand run it behind a TLS-terminating reverse proxy (setTRUST_PROXY). Basic Auth over plain HTTP is not encrypted. - The web UI is self-contained: fonts and icons are bundled (
public/fonts/), the browser makes no requests to external hosts. /hdhr/*and/playlist.m3uare public on purpose (media centers, M3U clients, container health checks) and expose your receiver's stream URLs. They are not covered byADMIN_USER/ADMIN_PASSWORD.- Report vulnerabilities as described in SECURITY.md.
Release images are multi-arch (linux/amd64, linux/arm64), include an SBOM and provenance attestation, and are signed with cosign (keyless). Verify before deploying:
cosign verify ghcr.io/danielfranze/technimapper-m3u-proxy:latest \
--certificate-identity-regexp 'https://github.com/danielfranze/technimapper-m3u-proxy/\.github/workflows/release\.yml@.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com| Symptom | Likely cause / fix |
|---|---|
Container restarts in a loop (Restarting (1)), Portainer shows no IP/ports, log: Data directory ... is not writable |
The bind-mounted data directory is owned by root. Run chown -R 1000:1000 <data-dir> or use a named volume (technimapper-data:/app/data). |
| Plex does not find the tuner | Open http://<server>:9191/hdhr/discover.json in a browser first; it must answer with JSON. Make sure the published port matches the server port (9191:9191 with the default PORT) and that you enter exactly this port in Plex. |
| Plex/Jellyfin shows no channels | Only channels with an ID are listed. Check http://<server>:9191/hdhr/lineup.json in the browser; an empty list [] means nothing is mapped yet. |
| The tuner name does not change | The name is TechniSat <detected model> until you set HDHR_FRIENDLY_NAME. The model is detected on the first successful sync; the client may cache the old name, so remove and re-add the tuner. |
/playlist.m3u returns 503 |
No sync yet, or no channel has an ID. Click Apply & Fetch, then map channels and Save. |
| No TechniSat Live-TV containers found | Wrong IP/port, receiver in standby/off, unsupported model, or no channel list configured on the receiver. |
| Invalid receiver IP | Only private IPv4 addresses are allowed. Use ALLOW_NON_PRIVATE_IP=true for VPN/CGNAT. |
| Invalid channel ID for ... | IDs may only contain letters, digits, _, -, . (max. 32 characters). |
Status degraded in /health |
Three or more consecutive failed syncs, or no playlist available. See lastError in /health or the UI tooltip on the sync badge. |
npm ci
npm test # unit tests (Node's built-in test runner)
npm run check # syntax check
npm start # http://localhost:9191server.js– HTTP API, scheduler and receiver synclib/validation.js– input validation (settings, mapping)lib/m3u.js– playlist generation and sanitizinglib/hdhr.js– HDHomeRun emulation (lineup, tuner name, host handling)test/– unit testspublic/index.html– Web UIpublic/fonts/– bundled fonts (Inter, Material Icons Outlined), seeNOTICE.md
CI (GitHub Actions) runs tests, npm audit, a Trivy image scan and a container smoke test on every push and pull request. Pushing a tag vX.Y.Z (matching package.json) builds, publishes and signs the release image and creates the GitHub release from the matching CHANGELOG.md section (## [X.Y.Z]). The tag fails fast if the version or the changelog entry is missing; tags containing a - (e.g. v1.7.0-rc.1) become pre-releases and do not move the latest image tag.
Inter and Material Icons (Outlined) are bundled in public/fonts/ together with their unmodified license texts (SIL Open Font License 1.1), see NOTICE.
This project is open-source software licensed under the MIT License. Feel free to use, modify, and distribute it.

