The television is usually the one screen a smart home never quite reaches. Lights dim for a film, blinds come down, and the TV still needs a remote. This guide connects IPTV to Home Assistant through OneTV Connect on Apple TV: your channels become a proper media_player, the TV guide becomes sensors, and a channel change can trigger — or be triggered by — anything else in the house.
It takes about five minutes, runs entirely on your local network and costs nothing: the integration is open source and does not need a OneTV Pro subscription. It works with whatever source you already use in the app — Xtream Codes, an M3U playlist, a Stalker portal, Plex, Jellyfin or Emby.
What you need
- An Apple TV with OneTV Connect and at least one source added. OneTV Connect is a player: it provides no channels of its own.
- Home Assistant 2024.1 or later, with HACS installed.
- Both on the same local network. Discovery uses Bonjour (mDNS), which does not cross VLANs or guest networks unless your router relays it.
- Optional but recommended: Home Assistant’s own Apple TV integration, so Home Assistant can wake the box and open the app for you.
Step 1 · Turn it on in the app
On the Apple TV, open OneTV Connect and go to Settings › Integrations › Control & Home Automation.
- Open Home Assistant and switch on Enable Home Assistant. The screen shows the server port, 8766 by default.
- Leave Enable iOS Remote on as well. Home Assistant finds the Apple TV through the same network announcement the iPhone remote uses, and that announcement carries the access key — which is why you never have to type one.
Nothing leaves your network. The key only lets devices on your own Wi-Fi talk to the app.
Step 2 · Install the integration from HACS
- In Home Assistant, open HACS, then the ⋮ menu in the top-right corner, then Custom repositories.
- Paste
https://github.com/Seidel76/noopy-tv-homeassistant, choose the type Integration and click Add. - Search HACS for OneTV, open it and click Download.
- Restart Home Assistant completely (Settings › System › Restart). Reloading the integration is not enough after an install or an update.
If you prefer not to use HACS, copy the custom_components/noopy_tv folder from the repository into your config/custom_components/ directory and restart.
Step 3 · Add the Apple TV
After the restart, open Settings › Devices & services. The Apple TV appears under Discovered with the name you gave it in tvOS. Click Add, confirm, and the device and its entities are created. There is no token or password to copy: the key arrives with the discovery.
If nothing shows up, add it by hand: Add integration › OneTV, then enter the Apple TV’s IP address (tvOS shows it in Settings › Network) and the port displayed in OneTV Connect. Giving the Apple TV a fixed address in your router saves trouble later.
Step 4 · Let Home Assistant start the app
tvOS only lets an app’s server run while the app is open, and an app cannot start itself. So when OneTV Connect is closed, its entities show as unavailable. The integration solves this with the Apple TV integration you may already have:
- Open Settings › Devices & services › OneTV › Configure.
- Choose your Apple TV entity under Paired Apple TV. Leave App name on the Apple TV set to OneTV Connect.
From then on, media_player.turn_on wakes a sleeping Apple TV and opens the app, and a play_channel sent while it is closed launches it first. The same options screen sets the polling interval (5 to 300 seconds, 10 by default) — mostly a safety net, since the app pushes its changes as they happen.
What appears in Home Assistant
| Entity | What it gives you |
|---|---|
media_player | Play, pause, stop, next and previous channel, source list (your channels, in playlist order), volume and mute, artwork, programme title, position. Seeking works on films and episodes. |
| Now playing (sensor) | The channel, film or episode on screen, and whether it is playing, paused or buffering. |
| Progress (sensor) | On live TV: the programme, its start and end, minutes left and synopsis. On a film: position, duration, time remaining. |
| Channel selects | One select with every channel, and one per category if you keep that option on. |
| Audio track, Subtitles | Selects for the tracks of whatever is playing. |
| App reachable | A binary sensor that tells you whether OneTV Connect is open and answering. |
| Back to live | A button that appears when you are watching behind the live edge. |
The entity names are created in French by the current version, so the IDs look like sensor.onetv_lecture_en_cours. Check yours under Settings › Entities and rename them if you like — automations below use media_player.onetv, which you may need to adjust.
The media browser works too: Media in the sidebar lists Resume, Favourites, channels by category, Movies and Series.
Five automations worth copying
These use the current Home Assistant syntax (triggers / actions). Paste them in Settings › Automations › Create › Edit in YAML and replace the entity IDs with your own.
1. Pause when the doorbell rings
alias: "Pause the TV when someone rings"
triggers:
- trigger: state
entity_id: binary_sensor.doorbell
to: "on"
conditions:
- condition: state
entity_id: media_player.onetv
state: playing
actions:
- action: media_player.media_pause
target:
entity_id: media_player.onetv2. Dim the lights when the match channel comes on
media_artist carries the channel name, so you can react to one channel in particular.
alias: "Match lighting"
triggers:
- trigger: state
entity_id: media_player.onetv
attribute: media_artist
to: "Sky Sports Main Event"
actions:
- action: light.turn_on
target:
entity_id: light.living_room
data:
brightness_pct: 25
transition: 33. Put the six o’clock news on
The wait makes sure the app is up before the channel is requested. The binary sensor ID depends on your install.
alias: "Six o’clock news"
triggers:
- trigger: time
at: "17:58:00"
conditions:
- condition: time
weekday: [mon, tue, wed, thu, fri]
actions:
- action: media_player.turn_on
target:
entity_id: media_player.onetv
- wait_template: "{{ is_state('binary_sensor.onetv_application_accessible', 'on') }}"
timeout: "00:02:00"
- action: noopy_tv.play_channel
data:
channel_id: "BBC One"4. End the cartoons at bedtime
turn_off stops playback. tvOS does not let an app close itself, so the app stays open on its home screen.
alias: "Cartoons end at bedtime"
triggers:
- trigger: time
at: "20:30:00"
conditions:
- condition: state
entity_id: media_player.onetv
attribute: media_artist
state: "CBBC"
actions:
- action: media_player.turn_off
target:
entity_id: media_player.onetv5. Voice control through Alexa or Google
Voice assistants cannot select a channel by name as a source. The reliable way is one short script per channel, exposed to your assistant through Home Assistant Cloud or your own bridge. play_channel ignores case and accents, and also accepts the channel’s ID.
script:
onetv_bbc_one:
alias: "BBC One"
sequence:
- action: media_player.turn_on
target:
entity_id: media_player.onetv
- action: noopy_tv.play_channel
data:
channel_id: "BBC One"The other actions follow the same pattern: noopy_tv.play_movie and noopy_tv.play_episode start something from the catalogue (IDs are visible in the media browser), and noopy_tv.send_command covers pause, seek, back to live, tracks and volume.
A dashboard card
A media control card plus the channel and track selects makes a complete remote in two cards:
type: vertical-stack
cards:
- type: media-control
entity: media_player.onetv
- type: entities
entities:
- select.onetv_toutes_les_chaines
- select.onetv_piste_audio
- select.onetv_sous_titresThe volume slider controls OneTV Connect’s own playback level. The television or receiver volume goes through HDMI-CEC and the Siri Remote, which no tvOS app can reach.
When something does not work
- The Apple TV is never discovered. Check that both devices are on the same subnet, that Enable iOS Remote is on, and that mDNS is not filtered between VLANs. Otherwise add it manually with its IP address.
- The entities are unavailable. OneTV Connect is closed or the Apple TV is asleep. Pair the Apple TV entity (step 4) so Home Assistant can open it, and base your automations on the “App reachable” sensor rather than on the Apple TV’s own state.
- New entities are missing after an update. Restart Home Assistant completely; a reload keeps the old code in memory.
- A channel cannot be found. Use the name as it appears in the
media_playersource list, or the channel ID. - The setup fails when Home Assistant starts. The app must answer during setup. Open OneTV Connect, then reload the integration.
Still stuck? The integration page has a Download diagnostics button (the access key is removed from the file). Send it to us from the support page, or open an issue on GitHub.
Questions people ask
Is there an IPTV integration for Home Assistant?
Yes. OneTV Connect on Apple TV has a Home Assistant integration, installed from HACS. It exposes your IPTV channels as a media_player with artwork, TV guide sensors, channel selects and actions such as play_channel.
Does it need a paid subscription?
No. The integration is free and open source, and it does not require OneTV Pro. You need OneTV Connect on an Apple TV, your own IPTV source and Home Assistant 2024.1 or later.
Which IPTV sources work?
Any source added to OneTV Connect: Xtream Codes, M3U playlists, Stalker portals, as well as Plex, Jellyfin and Emby. Home Assistant sees the same channels and guide as the app.
Does it work on iPhone or Android?
The integration targets OneTV Connect on Apple TV, which is what sits on the television. The iPhone app is not meant to be controlled from Home Assistant.
Does Home Assistant need internet access for this?
No. Everything happens on the local network: discovery by Bonjour, commands and the event stream over HTTP between Home Assistant and the Apple TV.