Apple TV

Your Apple TV's remote, Now Playing and links, from the keyboard

palupdated 2026-10-27MediaIn pal's registry󱔓Menu bar: Apple TV󰌹7 deep links

Open in pal

In pal's registry: the button shows it in pal, which asks before installing; the command does the same from a terminal. This page can't see what your pal has installed.

Apple TV: Now Playing: the episode on its own colour, the chapters on the position bar, speed, subtitles and audio, Up Next with its stills
Now Playing: the episode on its own colour, the chapters on the position bar, speed, subtitles and audio, Up Next with its stills
Apple TV: The remote: the clickpad and the buttons, what plays, your apps as the TV draws them on the digits, the volume
The remote: the clickpad and the buttons, what plays, your apps as the TV draws them on the digits, the volume
Apple TV: Play on Apple TV: the link just copied, the browser tab in front and every link copied before; Enter plays it on the TV
Play on Apple TV: the link just copied, the browser tab in front and every link copied before; Enter plays it on the TV
Apple TV: Copy a YouTube link and the remote offers it: l plays it on the TV, at its start time
Copy a YouTube link and the remote offers it: l plays it on the TV, at its start time
Apple TV: A song with its lyrics, the line playing lit; hold an arrow to scrub, one seek when you let go
A song with its lyrics, the line playing lit; hold an arrow to scrub, one seek when you let go
Apple TV: Guided setup: type the code the TV shows; a second code adds what is playing
Guided setup: type the code the TV shows; a second code adds what is playing
1 of 6

What it does

A remote for your Apple TV under the keys: the clickpad on the arrows, Now Playing in full with chapters, subtitles, Up Next and lyrics, links played on the TV in one key (copy a YouTube link and pal offers it), your apps a digit away, typing into the TV's search from the keyboard, sleep and wake, users, and the menu bar. Pairs in a guided setup, no other app or hub needed.

  • The clickpad on the arrows, Enter selects, Backspace goes back, h is the TV button; swipes on shift and the arrows
  • Now Playing in full: the cover's colour behind it, chapters on the position bar, hold-to-scrub, speed, subtitles and audio, Up Next, lyrics
  • Play a link on the TV in one key: copy a YouTube link and pal offers it, or paste one at the root
  • The YouTube video in your browser carries on on the TV from where you were, and the tab pauses (Chrome with its DevTools port on; Browser Tabs' rows offer it too)
  • Your dock of apps on the digits, drawn as the TV's own tvOS icons; every app at the root: type youtube, press Enter
  • Type into the TV's search from the keyboard instead of hunting letters on screen
  • Sleep and wake, Control Center, the app switcher, the screen saver, switching users
  • A menu bar item with what plays; its popover is the remote
  • Guided setup: finds the Apple TV, takes the code it shows, and checks what works
  • In a group with your TV (Settings › Groups), the remote sets the TV's volume, switches its inputs, moves its sound (b, shift+S reconnects a soundbar) and wakes both
  • With Samsung TV installed too, o opens the TV's own remote over this one (its settings, its sound) and Escape comes back

Palettes 7

  • Apple TV Remoteremoteview

    The clickpad on the arrows, Enter selects, Backspace goes back, the TV button on h; what is playing with its cover and a seek bar, the volume, your dock of apps on the digits, and a field that types into the TV.

    • ↑or↓or←or→Move (the clickpad)
    • ⇧↑or⇧↓or⇧←or⇧→Swipe
    • ↵Select
    • ⇧↵Hold Select: more options
    • ⌫Back
    • HHome, the TV button
    • ⇥App switcher
    • CControl Center
    • spacePlay or pause
    • or.Skip back or forward
    • ⌘←or⌘→Previous or next (chapter, track)
    • - =Volume down or up
    • 1-8Open a dock app
    • NNow Playing
    • LPlay the link just copied (or pick one)
    • AAll apps
    • TType into the field the TV shows
    • PSleep or wake
    • SScreen saver
    • USwitch user
    • DSwitch Apple TV (with several paired)
    • BNext sound output (when the group's TV serves them)
    • ⇧SReconnect sound (when the group's TV offers it)
    • ⌘CCopy what is playing
    • RReconnect
  • Now Playing on Apple TVnowview

    What plays on the Apple TV in full: the cover with its colour behind it, the show, season and episode or the artist, the synopsis, a position bar split at the chapters, hold-to-scrub, speed, subtitles and audio, and a panel for Up Next, Chapters, Audio, Subtitles, Lyrics and Info.

    • spacePlay or pause
    • ←or→Scrub: hold to go faster, one seek when you let go
    • ⇧←or⇧→Scrub by the minute
    • or.Skip back or forward
    • ⌘←or⌘→Previous or next (chapter, episode, track)
    • ⇥Next panel: Up Next, Chapters, Audio, Subtitles, Lyrics, Info
    • q c a s y iOpen a panel
    • ↑or↓or↵Walk the panel; play, jump or choose
    • [ ]Slower or faster
    • LLike (music)
    • ⌘Sor⌘RShuffle, repeat
    • - =Volume
    • OThe remote
    • ⌘CCopy what is playing
  • Play on Apple TVplayinputinline

    Send a link to the TV in one key: a YouTube video (at its start time), a Netflix title or an Apple TV+ page. Lists the link just copied, the browser tab in front (a YouTube video from where it is in the tab, which pauses as the TV takes over), every link in the clipboard history and what was played before; a link typed or pasted at the root is offered there too.

    • ↵Play on the TV
    • ⌘↵Play from the start (a link with a start time)
    • ⌘OOpen in the browser
    • ⌘CCopy the link
  • Apple TV Appsappslist

    Every app on the Apple TV with its icon; Enter opens it on the TV.

    • ↵Open on the TV
    • ⌘↵Open, then show the remote
    • ⌘DAdd to or remove from the dock
    • ⌘CCopy the bundle id
  • Apple TVcommandslist

    Play or pause, sleep, wake, home, Control Center, the screen saver, skip, volume, typing and switching users or Apple TVs, as root results.

    • ↵Run
    • ⇥On Type on Apple TV: the text to type
  • Apple TV Usersuserslist

    The people signed in on the Apple TV; Enter switches to one.

    • ↵Switch to this user
  • Set Up Apple TVsetupview

    Finds the Apple TVs on the network and pairs one in two codes: the remote, then what is playing (skippable); ends with a check of what works.

    • 1-9Pair with that Apple TV
    • ↵Send the code
    • NShow a new code
    • SSkip the now playing step
    • IType an address
    • RLook again
    • XForget an Apple TV

Settings

Extension, [extensions.appletv]

device
empty text

Which paired Apple TV the remote, the root commands and the bar item control, by its name. Empty: the one paired last. d on the remote switches, and writes it here.

favorites
none list

The apps on the remote's dock, in order; each gets a digit, 1 to 8. Empty: the apps you open most. cmd+D in Apple TV Apps adds or removes one.

skip
10s number

How far , and . (and Skip Back / Forward at the root) move what plays.

wake
On boolean

With HDMI-CEC on, the TV set comes on with it.

stay
On boolean

So the menu bar item follows what plays and a key answers at once. Off, pal connects while the remote is open and lets go a minute and a half after.

Defaults shown. Change them in pal's settings window or in the config file.

The README

Everything Apple TV does, key by key, from the extension's own README.md

Apple TV

A remote for an Apple TV on the same network, spoken directly to the box: no Home Assistant, no hub, no app on the phone. Seven palettes and a bar item: the remote under the keys, Now Playing in full, links played on the TV, the TV's apps at the root, the commands at the root, its users, the guided pairing, and what plays on the bar.

Two of Apple's protocols, the ones the iPhone's own remote uses:

  • Companion (_companion-link._tcp, protocol/): the buttons (HID), swipes and taps on the touch surface, the apps (list and launch), the users, sleep and wake with the power state as events, the volume as the TV set reports it over HDMI-CEC, and the text field the TV shows (read, set, append, clear). Ported from pyatv: OPACK with its back-references, the encrypted frames, the session handshake.
  • MRP over AirPlay (_airplay._tcp, protocol/mrp.ts on node-appletv-remote's AirPlay connection): what plays (title, artist, album, show and episode, the app, the position, the cover) and the transport that needs it (seek, shuffle, repeat, chapters). Optional: the remote works without it.

Pairing

Set Up Apple TV walks four steps, the one in progress lit along the top:

  1. Find: the Apple TVs on the network over mDNS (both services, merged by host), with the model as people say it ("Apple TV 4K (3rd generation)"), the address and the tvOS version. A digit pairs one, i types an address, r looks again.
  2. Remote: the TV shows a four-digit code (HAP pair-setup over Companion); type it in the field and press Enter. A wrong code says so and the TV shows a new one by itself.
  3. Now playing: a second code, for AirPlay. s skips it.
  4. Ready: pal connects and reads what works from the TV itself: the remote, how many apps, typing, the volume (or that the TV set does not report one), what plays, the users.

The long-term keys stay in pal's storage (<data dir>/pal/storage/ appletv.json, devices); which Apple TV is current is the device setting. x forgets one; remove pal on the TV too under Settings › Remotes and Devices › Remote App and Devices.

No code appears? On the Apple TV, Settings › AirPlay and HomeKit › Allow Access should be "Everyone on the Same Network" (or "Anyone"), not "Only People Sharing This Home".

The remote

The clickpad on the arrows (each part lights for a moment when its key is pressed, and a click on it works the same), Enter selects (shift+enter holds it for the context menu), Backspace goes back, h is the TV button (tab double-presses it: the app switcher; c holds it: Control Center), space plays or pauses, , and . skip by the skip setting, cmd+left/cmd+right previous and next, - and = the volume, p sleep or wake, s the screen saver, u the users, d the next paired Apple TV, r reconnects. Shift and an arrow swipes. With the Samsung TV extension installed (it is in suggests), o opens the TV's own remote over this one (for its settings or its sound) and Escape comes back here; the Samsung remote has the same o back to this one.

In a group with the TV (Settings › Groups), the parts the TV serves are drawn here as pal's own: the volume (a slider when the TV tells its level, on a soundbar too), the inputs as chips with the one on screen lit, and where the sound plays (the TV's speakers, Q-Symphony, a soundbar) with a reconnect chip when the TV offers it. b moves the sound to the next output and shift+S reconnects it (to the TV's speakers and back, for a soundbar that came up quiet). None of it names the Samsung: any device serving outputs to the group fills the row, and without one it is not drawn.

The card shows what plays with its cover and a seek bar a click moves, or what the TV is doing (asleep, the screen saver, the app in front). The dock is the favorites setting, else the apps opened most, each on a digit. When the TV shows a keyboard, a banner says what it is asking for; t opens a field in the search row and Enter types it into the TV.

Everything the TV tells (a new item, a pause, sleep, a keyboard) pushes a new tree into the open remote and the bar popover; a playing item's position ticks every second while one is open.

Now Playing

Now Playing on Apple TV (also n on the remote, or a click on its card): the left side sits on the cover's own colour brought down to a deep tone (the dominant hue of the JPEG, image.ts): the cover (wide for a film or a show), the app, the title, the show with its season and episode or the artist and album, the year, rating and genre, a line of the synopsis. The position bar is split at the chapters when the app gives them, each part filling as it plays, the chapter's name under it. Left and right scrub: each press moves a target 10 s, 30 s once the key repeats, a minute after that (shift: a minute, then five), the bar shows where it will land, and one seek goes when the keys rest 700 ms (Enter: at once). The transport is large buttons; chips beside them set the speed ([ ]), the subtitles and the audio, like a song (l), shuffle and repeat. On the right a panel, Tab to cycle or its letter: Up Next (q, the queue with its pictures, Enter plays one), Chapters (c, Enter jumps), Audio (a) and Subtitles (s, Enter picks a track or turns them off), Lyrics (y, the line playing lit) and Info (i). What a panel shows is what the app tells the TV: YouTube gives a title and its channel, the TV app much more.

Play on Apple TV

A link sent to the TV in one key: a YouTube video (opened in the TV's YouTube app at its start time), a Netflix title or an Apple TV+ page. Not yet: a media file over AirPlay (tvOS 26.6 takes the request and never fetches the file) and Twitch (its app refuses every link form). Wherever the link is:

  • Copied: pal reads its own clipboard history every two seconds while an Apple TV is paired. A new playable link becomes the offer: the bar item comes up for 90 s ("Play on TV: "), the remote shows it as a banner (l plays, x waves it off), and the empty root's Now section leads with it for 10 minutes. The entry on the clipboard when pal starts is never offered.
  • At the root: typed or pasted, the Play on Apple TV palette answers inline with "Play on ".
  • The palette lists the offer, the browser tab in front when it plays something, every link in the clipboard history and what was played before, with titles and pictures (YouTube's oEmbed, no key). cmd+Enter plays a YouTube link from the start.
  • pal://appletv/play: the url given, else the copied link, else the browser tab in front; bind it to a key.

The other palettes

  • Apple TV Apps: every app with its icon (the App Store's for third- party apps, looked up once by bundle id at itunes.apple.com/lookup; Apple's own drawn from their marks). Enter opens it on the TV, cmd+Enter opens it and shows the remote, cmd+D adds it to the dock or takes it out. The list is kept per Apple TV, so the root finds netflix before the TV has answered.
  • Apple TV (commands, primary at the root): play or pause, wake, sleep, home, Control Center, the screen saver, skip, next and previous, the volume, Type on Apple TV (Tab, then the text), switch user, switch to another paired Apple TV, set up. While something plays, the empty root's Now section has a row for it.
  • Apple TV Users: the people signed in on the TV; Enter switches.

The bar item

playing: the TV mark (or, with the artwork setting, the app's App Store icon with rounded corners) and what plays, muted while paused (the paused rule), hidden while nothing plays or the TV sleeps (show = "always" keeps the mark). The when setting shows it whenever the TV is awake instead. A link just copied brings it up to offer it. The popover is the remote, laid out for 420 px.

States: appletv/power (on, off, screensaver, unknown), appletv/playing, appletv/app, appletv/title.

Route Params
pal://appletv/key name (up, down, left, right, select, menu, home, play_pause, volume_up, volume_down, sleep, wake, screensaver), press (tap, double, hold)
pal://appletv/launch app: a name, a bundle id, or a url the app handles
pal://appletv/power to: on, off, toggle
pal://appletv/type text, append
pal://appletv/media command (play_pause, play, pause, next, previous, skip_forward, skip_backward, seek), value (seconds)
pal://appletv/volume level: up, down, or 0 to 100
pal://appletv/play url; without it the link just copied, else the browser tab in front

Settings

Setting Default
device "" The current Apple TV by name; empty: the one paired last
favorites [] The dock's apps, by name or bundle id
skip 10 Seconds a skip moves
wake true Wake the Apple TV when the remote opens
stay true Keep the connection open for the bar item; off, it closes 90 s after the remote

Limits

  • The volume is the TV set's, over HDMI-CEC or eARC; a set that does not report it gets the buttons only.
  • An app decides what it tells: some give no cover (YouTube), some no position.
  • Typing needs a text field the TV is showing (a search, a sign-in).
  • The connection stays on the LAN; the calls out are the App Store icon lookup (by bundle id, once per app) and YouTube's oEmbed for a link's title (once per link).

Tests

test/appletv.test.ts runs the extension over the host against a stand-in TV (fake.ts, PAL_APPLETV_FAKE: the TV's state a JSON file, every command a log line). appletv-protocol.test.ts covers the wire: OPACK against pyatv's vectors, the cipher's header and nonce, the text-input archives, now playing from recorded MRP messages.