TVHeadend on Apple TV

What you need

• TVHeadend running on the same home network as your Apple TV, iPhone or iPad.
• Its address: an IP address such as 192.168.1.20, or a name your router resolves. Don’t use localhost; your TV can’t reach itself through it.
• At least one channel set up in TVHeadend.

Where the addresses are

TVHeadend answers on port 9981 unless you changed it. Replace <server> with the server’s address.

The playlist builds each channel’s stream address from the address you used to open it. Use the same address in Guidevi that you would type in a browser on the same network, so the streams point to a server your TV can reach.

If TVHeadend is open to your home network, no sign-in is needed. If you closed it to anonymous access, create a persistent access code for your user in the web interface and add it to the addresses as ?auth=<code>. For the playlist, /playlist/auth/channels.m3u?auth=<code> also puts the code into each stream address. The menu names differ between versions; the TVHeadend documentation below describes the code and the URL form. Treat the code like a password.

The guide Guidevi shows is the guide TVHeadend has. If TVHeadend has no programme data yet, the XMLTV address lists your channels but no programmes, and Guidevi’s guide stays empty.

Add it in Guidevi

On Apple TV

1. Open Settings, then Sources and choose Add a Source.
2. Choose “Add on This Apple TV”. The page with the code is for adding by phone; it has no home server form (see below).
3. Choose “Home Server or Antenna”, then pick TVHeadend as the server software.
4. Enter the server’s address. The port is already filled in; change it only if you changed it on the server. Guidevi shows the generated channel list and guide addresses.
5. Choose “Test Connection”, then “Save”. The first import runs in the background.

Typing with the remote is slow. When you have an iPhone nearby, tvOS can offer its keyboard for the field.

From your iPhone instead. The page that opens when you scan the code has a Playlist URL form, not the home server form. Enter the two addresses from the table: the channel list in “Playlist URL”, the guide in “Guide (XMLTV) URL”. Both devices must be on the same home network. The M3U guide walks through it.

On iPhone and iPad

1. Open Sources: on iPhone it is in Settings (the gear button on the Live tab), on iPad in the sidebar, and choose to add a source.
2. Under Source Type, choose “Home Server”, then pick TVHeadend as the server software.
3. Enter the server’s address, then choose “Test Connection” and “Save”.

If it doesn’t work

• “No channels found”: the server answered, but its channel list is empty. Check that channels exist and are enabled in the server.
• “Different software at this address”: check that you picked the right software and port.
• The channels load, but the guide is empty or doesn’t match: see the guide doesn’t match my channels.

Server documentation

• TVHeadend documentation: playlists and XMLTV (JSON API, other functions)

Addresses checked in September 2026 against TVHeadend 4.3, ErsatzTV 26.3, Tunarr 2026.9 and Dispatcharr. Newer versions may differ.

More guides

• Add an M3U playlist on Apple TV
• Add an XMLTV guide (EPG)
• The guide doesn’t match my channels
• Tunarr on Apple TV
• ErsatzTV on Apple TV
• Dispatcharr on Apple TV
• All guides