Launching an Apple TV app

parautenbach · December 26, 2021, 3:54pm

Yes, this question has been asked and there’s a feature request, but these older posts all detail remote sequences to launch apps. The ability to launch apps directly (using a command) has been added recently. I’ve been a user of both the bundled Apple TV integration and the beta integration. As of late (due to bugs and new features after the launch of tvOS 15), I’ve been using the beta integration (currently v2.2.0).

I’ve been trying to understand better what is needed in order to use this new feature and the info I could find was slim. My understanding is as follows:

You need tvOS 15 (I’m running 15.1.1).
You need to have paired as a companion (vs MRP, RAOP, Airplay).

The former is easy to check. The latter wasn’t clear to me, as within HA, I don’t think you control or know which protocol gets used.

I’ve been using the atvremote utility directly in order to understand this better. Note that I’m running HA core in a virtualenv, which means I ran source bin/activate, a typical Python venv command, to switch to the HA environtment.

I explicitly paired using the companion protocol.
You can see which apps supports this by providing the app_list command.
You can launch an app using the launch_app command.

To pair (I saved the output to a file called companion.cred):

atvremote -i <redacted> --protocol companion pair

One can check that the companion protocol is supported for your device by running a scan:

atvremote scan

Partial example output:

Services:
 - Protocol: Companion, Port: 49153, Credentials: None, Requires Password: False, Password: None, Pairing: Mandatory
 - Protocol: AirPlay, Port: 7000, Credentials: None, Requires Password: False, Password: None, Pairing: Mandatory
 - Protocol: MRP, Port: 49152, Credentials: None, Requires Password: False, Password: None, Pairing: Optional (Disabled)
 - Protocol: RAOP, Port: 7000, Credentials: None, Requires Password: False, Password: None, Pairing: Mandatory

For example, I get some apps with this:

atvremote --id <redacted> --companion-credentials `cat companion.cred` app_list

Example output:

App: Red Bull TV (com.nousguide.rbms), App: DStv (com.multichoice.dstvguideipad), App: Podcasts (com.apple.podcasts), App: Movies (com.apple.TVMovies), App: Prime Video (com.amazon.aiv.AIVApp), App: TV (com.apple.TVWatchList), App: Photos (com.apple.TVPhotos), App: Clock and Timer (com.ryanoconnor.tvclock), App: App Store (com.apple.TVAppStore), App: Arcade (com.apple.Arcade), App: NBC (com.nbcuni.nbc.portal), App: Search (com.apple.TVSearch), App: Radio Paradise (it.iltofa.RP-HD), App: Computers (com.apple.TVHomeSharing), App: YouTube (com.google.ios.youtube), App: Showmax (com.showmax.main), App: Plex (com.plexapp.plex), App: Settings (com.apple.TVSettings), App: Apple Events (com.apple.appleevents), App: Netflix (com.netflix.Netflix), App: Music (com.apple.TVMusic)

To launch an app:

atvremote --id <redacted> --companion-credentials `cat ~/companion.cred` launch_app=com.apple.TVMovies

Where com.apple.TVMovies is the bundle ID from the app_list from before (and the app name is just Movies).

At this point, you have all the information to launch an app from HA. In HA, however, don’t use the bundle ID, but rather the app name.

service: media_player.select_source
target:
  entity_id: media_player.my_living_room
data:
  source: Movies

It would be useful to know how users not running pure HA core should determine the apps, without guessing, and from within HA.

From the GitHub release log (for v2.1.0):

Support for launching apps! Use select_source or the media browser. Only works on devices running tvOS and if Companion has been paired. If apps aren’t shown, remove and add the device again and make sure that the Companion protocol is paired.

postlund · December 26, 2021, 5:51pm

As you point out, it’s a bit tricky to know if you “have what is needed” to support app launching. As long as companion credentials are available, you should be able to launch apps either via media browser or input_source (which also exposes apps to scripts for instance). There is however no easy way to know which protocols that are actually in use, something I intend to improve and expose over time. I also intend to force a reconfiguration in case a protocol is discovered which isn’t set up for a device. This would help with the current situation where people would be lacking companion credentials when migrating from pre-uplift to tvOS 15 support.

I’m not really sure what you are aiming for with this:

It would be useful to know how users not running pure HA core should determine the apps, without guessing, and from within HA.

Can you elaborate? Maybe I can enlighten you.

parautenbach · December 26, 2021, 8:48pm

Really appreciate your feedback on this, @postlund!

I just mean that I don’t know how people not running pure HA core can follow my steps, as I’m not very familiar with the other installation methods (OTOH, anybody can just install pyatv anywhere and run it, so it’s not necessary). I saw later that a newly set up configuration should have the available apps somewhere, but I wasn’t sure where to look.

postlund · December 26, 2021, 9:39pm

As this is an integration, opposed to an add-on, it is agnostic to the way you installed Home Assistant. Be it in a venv, some docker deployment or via HAOS. So it shouldn’t matter. You do need credentials for Companion to launch apps but that also gives app listing for free, so you don’t have to go elsewhere for that. If you can launch apps but input_source (or the media browser) is empty, then it’s a bug. I hope that’s not the case

For now you need to run the beta component though, it will be part of the release in February. Not sure if beta has it yet, but it will be possible to run that way as well.

parautenbach · December 27, 2021, 6:51am

True, but I was referring to running any atvremote commands.

Can one choose the protocol when installing the integration? Or is it some automatic mechanism whereby the most powerful protocol is chosen?

Mine was empty, but let me double check and perhaps reinstall the integration before I report anything.

postlund · December 27, 2021, 11:34am

Ok, sure, now I get that. From a Home Assistant perspective, I believe atvremote should not be needed at all since the functionality should be implemented with corresponding Home Assistant domain functionality. If anything is missing, we should try to implement that in Home Assistant. Catching up with functionality is something I’ve been working on lately, so most things should be in place.

The general idea with pyatv is that you have an API to do things, e.g. play, pause, metadata, launch apps, change volume, etc. Then you have protocols that implement that functionality. Generally, there’s not one protocol that supports all features. Only Companion supports app launching for instance. Internally, pyatv will pick the most appropriate protocol automatically for each feature depending on what you have set up (e.g. provided credentials for). The pairing API tells you if a particular protocol requires pairing or not. So, Home Assistant will look at all the protocols supported by a device when you add it and allow you to pair them one by one to set up as many protocols as possible. That’s how you get as much functionality out of pyatv as possible.

It should be populated, assuming you have Companion set up. If you don’t, try removing the device and add it again. The config flow will let you know when you are pairing Companion.

parautenbach · December 27, 2021, 6:01pm

Absolutely, and I personally appreciate your effort to keep this integration up to date, through Apple’s many changes.

Indeed, but as you know, the dev work can take a lot of effort and time. I thought it would be good to be able to test and debug in some way.

Thanks for clarifying.

I will try this later, thanks. EDIT: It is! Should it be sorted? Also see that everything is in there (including the “Settings” app).

nthulke · April 12, 2022, 8:14am

Is this relating to this? I have been trying to work out how to call these from a Loveace page so I can make a “remote” for my Apple TV. Has anyone worked out what service call is needed to launch these?

parautenbach · April 12, 2022, 9:53am

The guide is to provide a mechanism to understand this better technically and to debug possible issues. The guide tells you how to open an app: Use the select_source service. It’s not mentioned in the Apple TV integration docs, since it’s a media player service which is what the Apple TV is. What you see in that drop down are sources.

nthulke · April 13, 2022, 8:30am

Sensational that works! Thank you so much!