From AwkwardTV
Revision as of 20:34, 25 July 2007 by Ucijoker (talk | contribs) (For further details see: [ Sapphire File Naming Conventions])
Jump to: navigation, search


Sapphire Browser is a plug-in designed to take all the hassle out of managing media collections connected to your AppleTV. Sapphire has the ability to identify TV Shows and Movies* simply by looking at the filename. Once identified, Sapphire will download show/movie* information and cover art (from TVRage /IMDB*/IMPAwards*) turning your stale file list into something worth looking at. Sapphire Browser also has the ability to filter out watched media files from several different directory trees and intuitively display them. Additionally Sapphire allows for marking favorite files that can also be viewed in a filtered menu. Media playback has also been improved allowing the user to fast-forward through shows at a constant (aggregated) rate independent of the file duration.

*Movie Support will be coming soon.

Version Information

Sapphire Beta 3 (1.0b3.1)

Sapphire Beta 2

Sapphire Beta 1

Comments and any bug reports would be greatly appreciated. Submit a Report




Beta 3


Beta 2

More screenshots of the UI can be found Here.

Gem Colors

Sapphire uses some gem icons to identify files. Here is a short description on what each color signifies:

File Gems

  • Blue Gems - Mark Unwatched files.
  • Yellow Gems - Mark Favorite files that have already been watched.
  • Red Gems - Mark files that have already been watched and are not favorites.

Directory Gems

  • Blue Gems - Mark directories containing any unwatched files.
  • Yellow Gems - Mark directories with favorite files and no unwatched files.
  • Red Gems - Mark directories that contain files that have been watched and are not favorites.

Cover Art


Sapphire now supports ATVFiles's cover art naming convention.

  • Directories will use an image with the name cover.ext
  • Files will use an image with the name <FileName>.ext

Fetch Tool

Sapphire will also attempt to download cover art (for files only) automatically from Any cover art that the fetch tool finds will be placed in a directory @ the same level of the file.


If we have the following files:

  • /TV Shows/Rome/Season 1/Rome.S01E01.avi
  • /TV Shows/Rome/Season 1/Rome.S01E02.avi
  • /TV Shows/Rome/Season 1/Rome.S01E03.avi
  • /TV Shows/Rome/Season 1/Rome.S01E04.avi
  • /TV Shows/Rome/Season 1/Rome.S01E05.avi

The Fetch tool will find and make a cover art directory with the following:

  • /TV Shows/Rome/Season 1/Cover Art/Rome.S01E01.ext
  • /TV Shows/Rome/Season 1/Cover Art/Rome.S01E02.ext
  • /TV Shows/Rome/Season 1/Cover Art/Rome.S01E03.ext
  • /TV Shows/Rome/Season 1/Cover Art/Rome.S01E04.ext
  • /TV Shows/Rome/Season 1/Cover Art/Rome.S01E05.ext

Folder Cover Art

Folder cover art for the most part works exactly as it does in ATVFiles. The only difference is that files inside a respective folder will default to the folder's cover art if it doesn't have its own specific (<filename>.ext) to display. This mechanism allows episodes to inherit cover art from two directories above itself.


If we have the following directories:

  • /TV Shows/Heroes/Season 1/cover.ext
  • /TV Shows/Heroes/Season 1/
  • /TV Shows/Lost/cover.ext
  • /TV Shows/Lost/Season 2/

Sapphire will display the respective covers if the directories don't have their own cover art. If a cover.ext doesn't exist the browser will default to the Sapphire icon.


Sapphire Fetch Tool File Formats

To get better results fetching show information from we have chosen to specifically support three typical naming schemes.

    • (REGEX IS [\. -]?S[0-9]+E[S0-9]+ )
    • Heroes.1x22.avi
    • Dead.Like.Me.203.avi

For further details see: Sapphire File Naming Conventions

Settings Menu

  • Populate Show Data - This tool is used to preform a search of your /Movies/ directory to gather meta data info.
  • Fetch TV Data - This tool is used to get episode information and episode cover art from
  • Hide "Favorite Shows" - Removes the Favorite Shows browser from the main menu.
  • Hide "Unwatched Shows" - Removes the Unwatched Shows browser from the main menu.
  • Hide "Hide UI Quit" - Removes the UI reset option from the main menu.
  • Disable Anonymous Reporting - Turns off the anonymous filename reporting (used for debugging and developing future Sapphire features)


  • 1. Download the Sapphire Plug-in Here.
  • 2. Unzip and place the Sapphire.frappliance folder inside the directory /System/Library/CoreServices/ located on your Apple TV's OSBoot partition.
  • 3. Access the Sapphire main menu using your Apple TV.
  • 4. Go to the "Settings" Menu and select "Populate Show Data". This import tool will go through your /frontrow/Movies/ directory collecting file information that is used to when browsing through Sapphire.
  • 5. Be patient. The import tool can take a considerable amount of time depending on how many mounts you are using. During testing, a fresh import on ~1 Tera byte worth of TV Shows took about 5 minutes. The import might be slower if you are using the airport.
  • 6. Once the import has finished, you might want to tag the files you have already watched, or tag your favorite files. The best way to do this is to select "Browse Shows" from the main menu. Once you have found a directory or file you wish to "Mark as Favorite" or "Mark as Watched", use the right arrow to toggle to the "Mark" mode. Select the file/directory and mark appropriately. To toggle back into "Select" mode hit the left arrow.
  • 7. If you would like to fetch TV Episode information for your media collection, this would be a good time to run it. As Sapphire fetches episode information from it might ask you to select from a list of TV show titles to match the current file being processed.
  • 8. Enjoy your fully personalized "Unwatched" and "Favorite Shows" menus packed full of Episode information!