How to set up ErsatzTV

Published 28 July 2026 · Updated 31 July 2026 · SparkBox team

Turn your library into live TV channels. This guide covers how to access it, log in for the first time, configure the basics, and where its data lives so you can back it up.

1. What is ErsatzTV?

Builds always-on TV channels out of the movies and shows you already own, with a proper channel guide. Instead of picking something to watch, you turn the TV on and something is playing. Point any IPTV player — or Jellyfin's Live TV — at it.

2. How to access it

Once it's enabled, ErsatzTV runs on your SparkBox at:

http://<your-NAS-IP>:8409

Add a media source first, then build your first channel from a collection.

3. First login

No account needed — ErsatzTV opens straight into its own web interface. Anyone who can reach it on your network can change your channels, so keep it on your LAN rather than exposing it to the internet.

If it instead asks for a password you didn't set, check Settings → Passwords in your SparkBox dashboard — every auto-generated credential is listed there.

4. Tips

• Best on a box with hardware transcoding. ErsatzTV re-encodes continuously to keep a channel live, so without a GPU it will lean on your CPU.
• Build a channel from a collection first (say, every episode of one show), then add more once you can see it working.
• Add the channel guide to Jellyfin under Live TV, or point any IPTV app at it.

5. Where your data lives

ErsatzTV's config and persistent data are stored on the SparkBox host under:

/opt/sparkbox/modules/ersatztv/config/

Backups via the SparkBox dashboard's Backup tile include this directory by default, so a single restore brings ErsatzTV back to its current state on a fresh install.

6. Build your first channel

ErsatzTV needs three things before anything plays, in this order:

1. A media source. Go to Media Sources. Either add your Jellyfin server (SparkBox runs it at http://sb-jellyfin-media:8096 — that name works from inside ErsatzTV), or point it at /media to scan your files directly.
2. A collection. Under Media → Collections, group what you want on the channel. Start narrow — one show, or one director — so you can tell it is working.
3. A channel and schedule. Create the channel, then a schedule that plays your collection. Without a schedule the channel exists but shows nothing.

Give it a minute after saving. ErsatzTV builds the upcoming programme block in advance, so a brand-new channel is briefly empty before it fills in.

7. Watch it on your TV

ErsatzTV hands out a standard IPTV playlist and guide, so anything that speaks IPTV can play it:

Playlist:  http://<your-NAS-IP>:8409/iptv/channels.m3u
Guide:     http://<your-NAS-IP>:8409/iptv/xmltv.xml

To watch through Jellyfin, open Jellyfin's dashboard and go to Live TV → Tuner Devices, add an M3U Tuner with the playlist address, then add the guide address under TV Guide Data Providers. Your channels then appear in Jellyfin alongside everything else.

8. If your box gets hot

This is the one thing to understand about ErsatzTV. Jellyfin only works when somebody presses play; ErsatzTV is running a broadcast, so it can be re-encoding video continuously for as long as a channel is live.

On a box with Intel Quick Sync, turn hardware transcoding on and the GPU absorbs it — set JELLYFIN_HW_ACCEL=intel in Settings (the same switch Jellyfin uses; it covers both). Without a GPU, expect steady CPU load, and keep to one or two channels.

If the box is struggling, the fastest fix is fewer live channels rather than a bigger memory limit — the cost is in the encoding, not the RAM.

Next steps