PlexNine Client ATV
Plex Client for AppleTV FAQ
You can find the FAQ here.
Plex Client for AppleTV
This is a thin client for the Plex Media Server that makes playing media on the inexpensive AppleTV Gen 2 simple and easy. The client is currently being produced by a third-party team. You can find additional information on the Plex AppleTV 2nd Gen forum.
AppleTV Gen 3
There is no way to jailbreak your third generation AppleTV (1080p) yet. So installing Plex is not possible yet.
AppleTV Gen 2
The third-party Plex AppleTV client is available only for the 2nd generation AppleTV (black). It does not work with the 1st generation (white) AppleTV.
Does the Plex client run on the ATV2 5.2 (iOS 6.1 - 10B144b) firmware or the new AppleTV 3?
A jailbreak for the 5.2 firmware for the ATV2 has been released on the Firecore site , however Plex is NOT currently compatible with the 5.2 firmware.
There is currently no jailbreak for the ATV3.
Plex Media Server
All Plex Clients require an active Plex Media Server on the network. The Plex Media Server is available for Mac OS X, Windows and several flavours of Linux.
- Additional Reading: Plex Media Server Guide
AppleTV Gen 1
A different method to access Plex content is available for 1st generation AppleTV by using CrystalBuntu and PleXBMC. Essentially, it involves installing the CrystalBuntu OS on the device, running the XBMC client, and then using the PleXBMC plugin within the client to access your Plex Media Server.
These methods are unsupported.
Installing the Plex Client for Apple TV Gen 2
Supported AppleTV Firmware version
The current release has been tested on FW 4.3 and 4.4. Older firmware versions are not supported so we recommend you upgrade to one of these versions.
Because Apple don't allow apps to be installed on the AppleTV, you must first Jailbreak the AppleTV to change this. The process is not illegal, but Apple regularly changes the AppleTV firmware to disallow Jailbreak methods. There are various resources available to help you through this process:
There are several discussions on Jailbreaking your AppleTV at the Plex Forums.
Initial AppleTV configuration
It's best to complete the initial configuration of the AppleTV and confirm it's working properly before the jailbrake. We recommend:
- An Ethernet connection as streaming HD media can very quickly saturate a WiFi network
- A static IP address so you always know the IP when SSHing to the AppleTV
- Don't do a Software Update until you've decided on the Jailbreak method and are sure you need it
- Configure other options as you like
Note: It's best not to do a Software Update for the AppleTV until you've researched the Jailbreak method you're going to use. See later.
Jailbreak the AppleTV
Once you've completed the initial AppleTV setup, it's time to do the jailbreak. The process can be quite touchy but be patient and follow the jailbreak instructions closely. Once jailbroken, you should see an extra menu on the AppleTV home screen. The menu you see will vary according to the jailbreak you used. You may like to install some utilities that enhance the AppleTV. A useful tool to install is NitoTV, a collection of apps that offers SSH access, Overflow and other useful things.
Install the Plex Client for AppleTV
Installing the Plex Client for AppleTV v0.10 or higher
There are 2 methods available when installing the client
- Using the Installer script (Mac OS X or Linux only)
- Manually by SSHing into the AppleTV (All platforms)
Using the Installer script
To install the client with the installer script:
- Download the installer: Click to Download
- Unzip it and place it somewhere appropriate on your computer
- On a Mac of Linux PC, open your Terminal application
- Change to the plex-atv-installer directory
- If you have an older version (0.90 or earlier), you should remove it. To do this, type:
- Now, you can install the 0.10 version. Type:
./plex-atv-installer.py -b beta install
- Note if your Apple-TV is not named 'Apple-TV.local' or if you have changed the root password, you need to check the usage of Plex ATV Installer here.
- Windows users need to use the manual SSH installation method - see next.
To upgrade to the latest version, type:
Manually (Windows users should use this procedure)
If you're a Windows user, or want to install the client manually:
Open the Terminal application
To install the Plex Client for AppleTV manually, you need to SSH into the AppleTV:
- On a Mac OS X or Linux PC, open the Terminal application
- On a Windows PC, you need to install a TTY application like PuTTY
SSH into the AppleTV
- If you have changed the name of the AppleTV, use that instead of Apple-TV
- You can substitute Apple-TV with the IP address of the AppleTV
- You will be prompted for a password. If you haven't changed it, the password is alpine. If you have changed the root password, enter that
If all goes well, you'll end up at the AppleTV's command line
Install the Client
At the command line, type:
dpkg -i com.plexapp.repo.beta_1.0_iphoneos-arm.deb
If you have an older version (0.9 or earlier) installed, remove it. Type:
dpkg -r com.plex.client-plugin
Now, install the Client. Type:
apt-get install com.plex.client-plugin
If all went well, the AppleTV should now show the Plex menu.
Upgrade the Client
To upgrade the client manually, at the command line type (or copy/paste from here):
Installing Plex Client for AppleTV v0.09 or older
You can still install older versions of the Plex Client for AppleTV. However, v0.10 is the most stable release available and we recommend you use it rather than older versions. If you have special reasons for using an older version, you can install it using these instructions.
- Additional Reading: Install an older Plex Client for AppleTV
You may find some bugs or other issues when using the client. To help us fix these bugs, logs are needed as well as a description of the problem. Please use the Lighthouse App for Bug Reports. If you have playback problems we NEED the Plex Media Server logs as well.
Getting logs when using Mac OS X is now much easier than before. The client now uses NSLogger for log capture. When capturing logs, it's important to send both the AppleTV client and the matching Plex Media Server.log. The ideal way to capture the "best" logs to help diagnose issues is:
- Quit the Plex Media Server, then restart it. This starts a fresh log.
- Start NSLogger if you're on a Mac
- On the AppleTV, perform the actions that show the problem
- If you're using NSLoger, save the log file
- If you're not using NSLogger, fetch the Plex Client for AppleTV log
- Fetch the matching Plex Media Server.log file
Check here for the Plex Media Server log location for your platform.
Using NSLogger on Mac OS X
To capture logs, download the NSLogger Mac OS X Client from the NSLogger site Once installed:
- Launch the NSLogger Client
- A window will open automatically with the log output from the Plex Client for AppleTV
If you're capturing a log to help diagnose a problem:
- Perform the actions on the AppleTV client that show the issue
- In the NSLogger client, save the log output to an NSLogger file
- Fetch the matching Plex Media Server.log
Zip the two files up and create a post on the AppleTV Lighthouse
Capturing Logs from Windows or Linux PC's
NSLogger isn't available for log capture on Windows or Linux PC's. If you want to capture a log:
- SSH into the AppleTV
- Type the following - the log output will be written to a logfile on the AppleTV
plexdefaults write PreferencesGeneralLogToFile int 1
Log output is now written to the XXXXX file on the AppleTV
Fetching the Log file
To fetch the log file:
- Perform the actions on the AppleTV client that shows the issue
- HOW TO GET THE FILE
- Fetch the matching Plex Media Server.log
Zip the two files up and create a post on the AppleTV Lighthouse
Using the Plex Client for AppleTV Gen 2
Once installed, you will see the Plex menu on the AppleTV. Select it and the Plex menus are displayed. You will notice various items in the menu:
- Selected Content in the Top Shelf
- myPlex Queue
- myPlex Sections
- Local Sections
- Server List
To navigate the menus, use the Up, Down Left Right button to select an item, press the center button to select it. To configure the Plex Client, choose Settings.
Select and enter the Settings menu. You'll see a number of options are available.
Manage Server List
This menu lets you manually add a server, or change the visibility of existing servers. When you first enter this menu, you'll see listed:
- currently active Plex Media Servers - noted with a green icon
- previously active Plex Media Servers - noted with a red icon
Add a Server
If you want to manually add a server - perhaps one on a different network - choose Add a Server then enter a:
- Name for the server (optional)
- Username (if secure access has been enabled)
- Server IP address
- Port number for the connection
After the details have been entered, a connection to the server is attempted. If successful, the server is added to the list.
Change Server Settings
Settings can be changed for existing servers. To change a server's settings, select it from the list. The following actions can be done:
- Server Name: change the server's name within the AppleTV Client. This does not change the server's actual name
- Username: enter or change the username if Secure access is required
- Password: enter or change the password if secure access is required
- List Status: sets the server to appear in lists or not. If this option is set to Include the server's sections will appear on the Plex main menu. If set to Exclude they will not
There are a number of actions that can be carried out on a Server:
- Tell server to refresh all sections: Choosing this option forces the Plex Media Server to quick-scan all Sections. This is useful if you've just added some new media and it hasn't yet been picked up
- Remove server form list: removes the Server from the Plex Client lists. You can re-add the servers later if you want
- Add a connection: lets you add a Plex Media Server. to do this, enter the IP address, then the port number. It's best to use the default port number of 32400
The Plex Client for AppleTV has several different views when browsing media. You can control which view to use with the View Settings:
- View type for movies: Choose either List or Grid view for Movie sections
- View type for TV Shows: Choose between List, Grid or Bookshelf view for TV Show sections
In the image below, left is List, middle is Grid and right is Bookshelf view
- Theme music: enable or disable TV Show theme music playing when a TV Show is selected
- Theme music looping: enable or disable looping TV Show theme music
- Poster zoom: enable or disable the poster zoom effect when a show is selected
- Fanart: enable or disable the fan art background
- Hide summary on unseen episodes: enable or disable hiding the plot summary on unseen episodes. Useful to avoid spoilers!
You can control the sound and video quality with the Playback settings.
If you have a Surround Sound capable amp connected, there are a couple of settings that need to be made to enable Surround Sound:
In the AppleTV Settings:
- Set Audio & Video > Dolby Digital Out to On (do not use the "Auto" setting as it may cause playback issues)
In the Plex Client:
- Choose Settings > Playback settings
- Set Dolby AC3 capable receiver to Yes
- Set Direct Streaming to Enabled
Note: The Plex Client for AppleTV is not able to directly playback DTS soundtracks. If your show has a DTS audio track, the Plex Media Server will automatically transcode the DTS track to AC3.
Audio Boost is useful to boost the sound of some audio tracks that playback quietly. Enable this if necessary.
There are several settings that determine how media is played on the Plex Client for AppleTV.
The Quality Profile determines how the Plex Media Server transcodes media for the client. This is useful if you're trying to playback high bitrate media that the AppleTV can't natively handle. There are 2 Quality Profile settings:
- Local Content: media that's on your local Plex Media Server
- Remote Content: media that's located on a remote server
Generally, you should set the Local Content Quality Profile to 4Mbps (720p) which is the AppleTV's native playback quality. If your media plays back without issues at higher quality settings, use that setting. If you experience problems playing media, set this to a lower Quality Profile setting.
You can control the size of subtitles with this setting.
You can control Direct Play and Direct Stream settings. This can be useful if you want to force the Plex Media Server to transcode all media or not. The options are:
DirectPlay: Enabled allows the Plex Media Server to send media using DirectPlay. Disabled forces all DirectPlay compatible media to be transcoded regardless
DirectPlay Quality Profile: Determines how the Plex Client for AppleTV reports it's Quality capabilities to the Plex Media Server. For example, if you set this to 720p, 720p compatible material will be DirectPlayed whereas 1080p compatible media will be transcoded
DirectStream: Enabled allows the Plex Media Server to send media using DirectStream. Disabled forces all DirectStream compatible media to be transcoded regardless
About DirectPlay and DirectStream
The AppleTV natively will only playback media at 720p. It is possible to select 1080p in the playback settings, but 1080p video will be down-sized to 720p. So, what is the benefit of having a 1080p setting? Plex allows Direct Streaming and Direct Play of your media. This means that the media being played is sent to the Client in the most direct way possible. If a client can play the video stream codec and resolution, the Plex Media Server will send it Direct Play to the client which plays it immediately. If the codec or resolution is incompatible, the Plex Media Server will transcode the media into a format that is acceptable to the client. Transcoding media means the Plex Media Server computer needs to 'do stuff' to the media before it can be played on the Client. This means:
- The Plex Media Server needs to have a reasonable powered CPU
- There will be a delay of several seconds before playback begins on the Client as the first part of the show is transcoded
Additional Reading: Direct Stream and Direct Play
The Plex Client for AppleTV v0.10 includes a new utility that can be used from the command line, called plexdefaults. This makes it possible to change some advanced settings. To change the settings, SSH into the AppleTV and then:
Start logging to a file:
plexdefaults write PreferencesGeneralLogToFile int 1
Disable the top shelf:
plexdefaults write PreferencesViewTopShelfEnabled int 0
Disable badges in the grid view:
plexdefaults write PreferencesViewBadgesOnShowsEnabled int 0
After you have changed something you need to restart AppleTV process:
Selecting the media to play
Playing media is done by choosing a section, then the show to play. The view is determined by the View Settings chosen at setup. To choose a show:
- Select the Section
- Navigate to the show
- Press the center Select button - the Media Preplay screen is shown or
- Press the Play/Pause button to immediately play the show, by-passing the pre-play screen
Using the Pre-play screen
If you pressed the center Play button, the Pre-play screen is shown. There are several options available in the Pre-play screen.
Selecting the Audio and Sub-title track
To select an audio or sub-title track:
- Choose Audio/subs
- Select the Audio or Subtitle track to use
There are several other options available. To set these:
- Choose More
- Select to mark the show as Watched or un-watched
Select another show
You can select another show to play from either the button set or bottom shelf. To do this:
- If Play, Audio/Subs or More is selected, click the Right or Left button until you reach the end
- Click once more - the next show is selected
- Press the Down Arrow button on the Apple Remote
- Choose the show to play
- Press either the center Play or Play/Pause button
- Either the pre-play screen for that show is shown or the show plays immediately
The Plex Client for AppleTV offers full myPlex support. myPlex is a free service that lets you bookmark video clips from websites and watch them later on your home TV. You can also share content with other myPlex friends. To use myPlex on the AppleTV, you need to have first set up a myPlex account.
- Additional Reading:The myPlex Wiki page
Configuring myPlex on the AppleTV Client
Once you have created your myPlex account, all that is needed is to log the Plex Client for AppleTV onto the service. To do this:
- Choose Settings > myPlex settings
- Choose Sign-in
- Enter your username and password
The client will log into the myPlex service.
Using the myPlex Queue
Once logged into myPlex, the Queue item will appear in the main menu. To view your myPlex queue:
- Select the Queue menu item
- Your myPlex Queue is loaded
- Select media to play as normal
myPlex lets you share your Library over the internet with your friends. To use a myPlex Shared Server:
- Choose Server Listing from the Main Menu
- The myPlex Shared Server will appear in the list
- Choose the shared server - it's available content will appear
- Playback media as normal