ErsatzTV: A Comprehensive Guide to setting up a Private IPTV Server

The way we consume television is undergoing a major transformation. With the rise of streaming services and social media platforms, traditional TV has become more accessible than ever before. But what if you could take control of your own television experience? Enter ErsatzTV, a community driven project that aims to revolutionize the way we watch and interact with each other through decentralized, open-source video content. ErsatzTV is poised to shake up the status quo and give viewers more choice, more control, and more opportunity for connecting to streaming media.

What is ErsatzTV?

ErsatzTV is a community-driven project that allows users to stream their own video content in a decentralized manner. By empowering creators to share their work directly with viewers, it offers an innovative and diverse media landscape for both entertainment and educational purposes. With features like customizable schedules and personalized channels, ErsatzTV provides an easy-to-use platform for creating and enjoying your favorite streaming content.

Core Features

• Use local media files and optional sidecar NFO metadata; no need for a full media server
• IPTV server and HDHomeRun emulation support a wide range of client applications
• Channel-specific streaming mode (MPEG-TS or HLS) and transcoding settings
• Collection-based scheduling, with collections containing television shows, seasons, episodes and movies
• Powerful scheduling options such as chronological collection playback throughout the day or over multiple days
• Hardware-accelerated transcoding options (QSV, NVENC, VAAPI)
• Plex media and metadata
• Jellyfin media and metadata
• Emby media and metadata
• Song and music video libraries
• Pre-roll, mid-roll, post-roll filler options
• Subtitle burn-in

Why use ErsatzTV?

Have you ever ran into a self-hosted app that you never knew you needed? That's how I felt with ErsatzTV when I saw it being talked about over on the r/selfhosted subreddit. I thought to myself "why would I need that?" Then I got to reading the comments and saw someone mention a concern I had which was - what if the service keeps running in the background even when I'm not using it? It turned out to be just the opposite.

As I thought more about ErsatzTV, a question kept popping up: why do people need this app? But then I remembered my own experiences trying to find something to watch with my family, we'd all agree on nothing! That's when it clicked: ErsatzTV helps you curate your favorite content into streaming channels that play seamlessly. Just turn it on, and there's always something good playing.

You can also use ErsatzTV as a live music streaming station, home videos, YouTube videos and all sorts of other media you can think of.

Installing ErsatzTV using Docker

In my personal setup, I integrate ErsatzTV with Emby for seamless streaming. However, it's worth noting that other popular streaming apps like Plex and Jellyfin can also be used in conjunction with ErsatzTV, depending on your preferences and needs.

ErsatzTV is it's own standalone app that sees your media via a Docker volume mount. Take the following Docker Compose and change it to your needs. If you do not have Docker installed, see our guides about getting started with self-hosting.

version: '3.9'
services:
    ersatztv:
        image: jasongdove/ersatztv
        restart: unless-stopped
        volumes:
            - '/srv/tv:/tv:ro'
            - '/srv/movies:/movies:ro'
            - '/srv/docker/ersatztv:/root/.local/share/ersatztv'
        ports:
            - '8409:8409'
        environment:
            - TZ=America/Washington
        container_name: ersatztv

To set up our local media on ErsatzTV, we can create TV and Movies volumes in the compose file. It's possible to link your Emby instance by using an API key, but I encountered some permission issues and found it easier to simply mount the volumes instead. This method seems to work well for me.

Once you get Ersatz up and running via Docker, visit the web UI on port 8409.

Adding a Local Media Source

The first thing I would do when you get to the ErsatzTV web UI is add a local media source. With this, we will use TV shows as the example. Click on "Local" under the Media Sources section on the left side panel. Now find "Shows" and click edit. Here you can add the path where our TV shows are. If you recall in the Docker Compose, it is mounted to /tv within the container. So that is what we will put in the path, then click "Add Path" then "Save Changes".

This will trigger a media scan and I recommend letting it scan your media before you do anything else. You don't have to wait but I recommend it to avoid running into any issues. Once the scan is complete you should now see your TV shows listed alphabetically under localhost:8409/media/tv/shows. If it does not initiate a scan, you can go to the Libraries section under Media and initiate the scan for Shows.

If you want metadata and posters to show within Ersatz, you must have posters and NFO handling enabled in Emby. The scan in Ersatz is noticeably faster without all the metadata and posters however, it looks much nicer with it. You can enable the options in Emby and rescan your libraries.

Adding Channels, Collections, Schedules and Playouts in ErsatzTV

While the ErsatzTV documentation is very well written, I thought this part was a bit confusing. So I'll try to do my best explaining how channels are added and the process of getting them working properly. Overall, if you know the proper steps, it's not difficult.

Step 1: Add a Channel

The default FFmpeg profile should work for you but will work better if you use a GPU. I do not have a GPU in this particular server however, you can use what's called HTTP Live Streaming also known as HLS Direct. It does not transcode content and can perform better on low power systems, but does not support watermarks and some clients will have issues at program boundaries. Keep in mind that if you use the default MPEG-TS Streaming Mode, it WILL use your CPU or GPU. You can try both modes to see which you prefer but make sure to give the system time to idle down your CPU or GPU before trying each option. It can take a couple minutes.

Adding a channel is pretty basic. You should already have an idea of what type of content you will be streaming on this channel. As an example, I will create one called Family.

I have 4 other channels already so for this example I will use number 5 as the channel number. From here, I name it Family, change the Streaming Mode to HLS Direct and everything else stays as is. You can change things but this is bare minimum setup to get your channel going. Upload a logo of your choice and hit "Add Channel".

Step 2: Create a Collection

Collections are used as groups for the media you want to stream on a schedule. Once you create a collection you need to add media to that collection. Since we are making a Family channel, I'll add shows like Full House, Home Improvement, Step by Step etc. You can also add single episodes rather than the whole series if you wish. You can add media to a collection by browsing to TV Shows under Media on the left side panel. You can either use the search bar at the top or the alphabet index on the right side to make the process quicker.

Step 3: Add a Schedule

The schedule is what tells the channel how often it will play.

To create a new schedule, start by clicking "Add Schedule." For this example we will use the Shuffle Schedule option. You can change this as you get more used to how the application works. Again, naming the schedule "Family" to keep everything organized and so I know which collections, schedules and playouts go together.

Then, you can proceed to add a new Schedule Item. To do this, click on the relevant button and enter the Collection name in the provided field. It will auto populate with the collections you have if you type the name correctly. Once you've saved your item, the schedule will know which media is being scheduled for playback. For now, everything else stays as default. Make sure you save the changes.

Step 4: Add a Playout

The final stage is adding the playout. Playouts are essential components in ErsatzTV, as they assign schedules to specific channels and track their individual playback of collection items. When using the same schedule across multiple channels (playouts), it's important to note that the content may not necessarily play simultaneously on all channels due to differences in timing or other factors. This ensures a more personalized viewing experience for each channel, tailored to its unique audience and preferences.

Under "Schedule" on the left panel, click Playouts and add a new one.

Add the name of the channel and schedule we created then click "Add Playout". Now you can view your playout and see the media that is shuffled in the list to be streamed. You can reshuffle the order by clicking the the circle with an arrow icon. Keep in mind, if you reshuffle, it may take a while to change in the Emby guide, or you can manually update/refresh the guide.

Adding the IPTV link and Guide to Emby

To implement the stream into Emby it is very simple. In the upper right corner on ErsatzTV web UI, you should see the M3U link. Right click that link and copy to your clipboard. Now navigate into Emby in the server dashboard to Live TV.

Add a new TV Source as a M3U tuner then paste the link in your clipboard.

Scroll down and click save. Now go back to your ErsatzTV web UI and right click the XMLTV link and copy that to your clipboard. Back on the Emby Live TV page, add a Guide Data Source, choose your country and select XMLTV. Click next and paste the link into the url input from your clipboard.

Now if we should be able to find our "Family" channel by searching for it in Emby.

When you click on a channel in Emby, you can view the list of collection items that are scheduled to play. This makes it easy to keep track of what's currently streaming and plan your viewing accordingly. And with the ability to customize each channel's schedule in ErsatzTV, you can create a truly personalized media experience for every member of your family.

Final Notes and Thoughts

I'm running ErsatzTV on an i7 8700k CPU without a GPU and it seems to run great using the MPEG-TS Stream Mode, however it does run up the cores pretty good. But that's ffmpeg for you.

Running it using the HLS Direct Streaming Mode uses... no resources? I'm not sure what this sorcery is but I like it ALOT!

It may take a while for the channels to start streaming on your devices when using HLS Direct but maybe it's worth it if you are using a lower powered machine.

Here's an interesting tidbit, the man behind ErsatzTV, Jason Dove, happens to be the lead developer for Disney Streaming! Isn't it ironic that he's helping to create a platform that competes with his own employer? It just goes to show that innovation and creativity often come from unexpected places.

If you enjoy this app, be sure to swing by the ErsatzTV Github repo and give it a star. Maybe consider becoming a sponsor of the project! I would also ask that you ask any support related questions for Ersatz there on the Github issue tracker.

Check us out on Discord and join over 1,200 members who self-host apps like this!