Automation and remote control
Connect JellyTV to Home Assistant, control Jellyfin sessions and use optional playback callbacks.
Last reviewed:
On this page
Connect JellyTV to Home Assistant, control Jellyfin sessions and use optional playback callbacks.
Home Assistant: webhook to Apple TV
Home Assistant receives the HTTP request, then its Apple TV integration opens JellyTV. JellyTV has no built-in webhook server. This advanced example starts a fixed media item and ignores the request body.
Set up the automation
- Install JellyTV 1.3.17 or later on Apple TV and connect your server. For the first test, keep Apple TV awake and select a profile allowed to play the item.
- In Home Assistant, open Settings → Devices & services → Add integration → Apple TV. Complete pairing and find your Apple TV’s media_player entity.
- Create an empty automation under Settings → Automations & scenes, then choose Edit in YAML. Paste the block below without adding an automation: key.
- Replace the Apple TV entity, ITEM_ID with your Jellyfin server’s item ID (not TMDB), and REPLACE_WITH_LONG_RANDOM_SECRET with a long, random, unique secret. Save and enable the automation.
alias: JellyTV - Apple TV
triggers:
- trigger: webhook
webhook_id: REPLACE_WITH_LONG_RANDOM_SECRET
allowed_methods:
- POST
local_only: true
conditions: []
actions:
- action: media_player.play_media
target:
entity_id: media_player.living_room_apple_tv
data:
media_content_type: url
media_content_id: "jellytv://play/ITEM_ID?start=60&audio=fr&subtitle=off"
mode: singleTrigger and verify
Run this command from a device on your local network using the same secret. Replace the address with Home Assistant’s address, not Apple TV’s; use HTTPS if your installation requires it. The link starts at 60 seconds, requests French audio and disables subtitles.
curl --request POST 'http://homeassistant.local:8123/api/webhook/REPLACE_WITH_LONG_RANDOM_SECRET'If nothing happens, inspect the automation traces. Also test media_player.play_media in Developer tools → Actions with the same data to distinguish a webhook issue from an Apple TV issue.
Limits and security
- Home Assistant must remain available and Apple TV reachable and paired. This example does not wake the device: configure and test waking separately through the Apple TV integration if needed.
- The profile, its PIN and system confirmation prompts may require interaction. Links do not bypass these protections. You can add profile= or userId= to the playback link using the rules in the deep links guide.
- The webhook needs no authentication token: its ID is the secret. Keep local_only: true, do not share the URL and never reuse a public example’s secret. This command targets your local network; remote access needs separate configuration.
- A successful HTTP response or a dispatched action does not confirm that the first frame appeared. No callback is used here; x-error opens a URL on Apple TV and is not a return HTTP webhook.
- This example follows Home Assistant’s documented interfaces but has not been tested end to end on your installation and a physical Apple TV.
Jellyfin remote controlRequires 1.3.17 or later
These are Jellyfin session commands, not additional jellytv:// URLs. Home Assistant or another Jellyfin client can control the active JellyTV session using the existing authenticated server connection. No Jellyfin server modification is required.
- Play / PlayNow — Play an ordered item queue, optionally choosing the starting item, position, media source and tracks. PlayNext and PlayLast are not supported.
- Playstate — Pause, Unpause, PlayPause, Stop and Seek (SeekPositionTicks). Seeking is unavailable for live streams.
- DisplayContent — Open details with ItemId, either directly or via GeneralCommand (Name: DisplayContent, Arguments.ItemId).
Now Playing informationRequires 1.3.17 or later
On iOS and tvOS, JellyTV publishes the title, duration, position, playback rate and artwork. Episodes also include series, season and episode information: for example, Bluey – S02E03 • Episode title. Series is published as the album, episode as the track number and season as the disc number.
Home Assistant decides how it displays this information. Its field mapping and behavior on a physical Apple TV still need end-to-end verification; these app changes do not modify Home Assistant.
Advanced: playback callbacks (optional)
Receive a success or error callbackRequires 1.3.17 or later
A callback is a return link to your automation app. Use it to continue a workflow after video starts or display a message if the request fails. The receiving app decides what to do next; JellyTV does not create that workflow for you.
- Continue a workflow once the video has actually started, provided returning to the automation app suits your workflow.
- Display an error message or offer another action if playback does not start.
- Match the result to the right request by keeping your identifier in the return URL, such as request=demo-42 in the example below.
On play links, x-success and x-error contain percent-encoded callback URLs. JellyTV opens the success URL after the requested media displays its first frame; local intros do not count. Before that, a failure opens the error URL with errorCode and errorMessage. Each playback request triggers at most one callback.
x-success confirms that the video actually started, not that it finished. The success URL is opened unchanged, without added result parameters. After success, no x-error is sent for later playback errors or stopping. If no URL is provided for the outcome, no return link is opened.
- Prepare a success URL and/or an error URL in the receiving app. Each parameter is optional: use only x-error to return to the automation only on failure.
- Encode each return URL once as a query parameter value. For example, myautomation://error?request=demo-42 becomes myautomation%3A%2F%2Ferror%3Frequest%3Ddemo-42. Do not encode the entire jellytv://play/… link; its top-level & characters remain separators.
- Add the encoded values to the play link, replace ITEM_ID and open it on the device with JellyTV installed. The callback destination must also be available on that device.
jellytv://play/ITEM_ID?x-success=myautomation%3A%2F%2Fsuccess&x-error=myautomation%3A%2F%2FerrorIllustrative callback targets: myautomation://success and myautomation://error. Replace them with URLs supported by your automation app; myautomation is not a built-in service. The target app must be installed and able to handle its URL scheme.
Understand the result
Example with an identifier chosen by your automation to recognize its request. Only an error callback is requested:
jellytv://play/ITEM_ID?x-error=myautomation%3A%2F%2Ferror%3Frequest%3Ddemo-42If startup fails, JellyTV preserves request=demo-42 and adds errorCode and errorMessage to the return URL:
myautomation://error?request=demo-42&errorCode=playback_failed&errorMessage=Playback%20could%20not%20be%20started.- invalid_request — The play link or its parameters are invalid. A return is possible only if x-error itself is valid.
- profile_unavailable — The requested profile cannot be used, or a different profile was selected.
- server_changed / account_changed — The active server or account changed before the request ran.
- playback_busy — Another playback request is already being prepared.
- playback_failed — The player could not start the requested media.
- replaced / cancelled — The request was replaced or cancelled before success.
Error messages are generic and do not include server credentials or media details. Callback URLs must be absolute and contain no credentials. jellytv, file, data, javascript and about schemes are rejected. HTTP(S) callbacks require a host.