From AwkwardTV
Revision as of 20:16, 23 October 2007 by Nito (talk | contribs) (Smart Installer)
Jump to: navigation, search


Current Version: 0.2.5b9
0.2.5b9 Download Location: direct download
0.2.5b9 Forum Discussion: awkwardTV Forum
0.2.5b9 Plugin Location: awkwardTV Plugin page
Release date: September 30th, 2007

This appliance is a front end for the popular mplayer media player ( perian and Apple's DVDPlayback.framework (if installed) You can create playlists and add files or folders of your choice. By now it should support just about any media format. Create afp, nfs and samba mounts (with bonjour support) Install the kextloader, a variety of kexts/frameworks/binaries, perian, mplayer codecs, perform the safe update and much more!

This appliance is Copyright © 2007 nito llc. All Rights Reserved.

Whats New

0.2.5b9 - As promised we have updated the wiki, i'll do some further updates pretty soon but this should be sufficient for now. The smart installer will work from network mounts, mach_kernel.prelink USB patching, file size toggling, volume blacklisting, and custom mount link paths

0.2.2 has only two changes we we're going to add more but got sidetracked making this version work with the new update that came out yesterday. The blue unplayed podcast icon is appending to the DVD that is perceived to be the longest. The other change is the upgrade compatibility. We'll have some exciting new features in the next version we promise.



The files section will list anything in your default "mountLocation". This location defaults to ~/Movies (for the uninitiated ~ == /Users/frontrow or whatever your user name is). This will list any folders and any files that are included in the "suffixes" preference. Files is where you will do the majority of your playback, any mounted DVD's (ISO or USB) or network mounts will also be in here.

Below we will list what each control button does in the Files listing.

< (click) will eject a volume or prompt to delete the current file or folder.

> (click) will add that folder or file to the playlist of your choice, the folder add will be shallow and will not recursively descend passed the chosen folder (yet)

< (hold then release) will attempt to regenerate the preview for the selected file, for mounts or folder it will have no affect. NOTE: there is a bug for regeneration of previews that exist in the same folder as the media file, it will be blank and will require an exit and re-entrace to view the new preview.

> (hold then release) shortcut to settings. It doesn't matter what kind of file or folder is selected this will always go to the settings shortcut.


Playlists are currently line delimited plain text files. They are located by default in ~/Library/Application Support/nito/playlists (this can be changed via the playlistLocation default) Playlists are either played entirely in QuickTime or mplayer, one caveat to this is some file formats will error out in QuickTime and not continue to the next, this is a design flaw that will be fixed in the future. It is also normal for the playlist facade to appear in between each file during QuickTime playlists, (will be fixed in the future) This is toggled on and off via "Playlists Use QuickTime" in settings). It is also possible to shuffle playlists, This is also set via the settings facade via "Playlist Shuffle" Currently QuickTime playlists will shuffle endlessly (possibly repeating titles) until manually exited, the same may also be true for mplayer playlists.

Below we will list what each control button does in the Playlist facade.

< (click) will remove the playlist (warning this will remove the actual playlist text file and currently cannot be un-done)


There are two "sections" in the Network facade. Bonjour mounts and custom mounts.

Bonjour Mounts

Anything above the line are computers that have been discovered via bonjour (mac users, think the "Network" section in the sidebar) These will all have "afpovertcp" to the right of them. Selecting play/pause on these items will prompt with a login type dialog, here is where you choose whether or not you have a registered account or a guest account. You must have guest access enabled on the computer for guest to work here. (NOTE: There will not be any GUI warning or error if guest access fails, you will simply be taken back to the root network facade) Upon choosing registered user you will get a prompt to put in your login then password. Upon proper authentication information you will be directed to a Volumes listing.

This is very important, in the Volumes listing you have two options, you can press play/pause to mount the volume (but no information will be saved) OR you can press > and get the mount facade. Here you MUST choose save before mounting, if you choose mount and you don't save you will lose this mount information. You may choose to turn on automounting if you desire (this will take care of mounting at startup) in addition you can choose whether or not use custom paths.

Custom Mounts

Creating custom mount points (bottom item in networking facade) Will require a little bit more legwork on the user part (well it seems like a lot more with the remote and no keyboard support). Each item will be outlined below

Mount Name: This name is only how the mount point will be displayed in the networking menu and has no other functional importance

Network Address: This address can be in the form of an IP address or a DNS name. DNS names may need to be added to the /etc/hosts file to work (if you are on a Mac your computer name will work, so iBook G4 would be iBook-G4.local the computer name for the macintosh is viewable in System Preferences/Sharing) No afp:// or // is necessary, for each different protocol nitoTV will accommodate the proper formatting.

User name: (will not be required for guest access) the user name you use to authenticate for this particular computer/mount.

Password: (will not be required for guest access) the password you use to authenticate for this particular computer/mount. (mac users NOTE: even if you have logins performed upon startup automatically this does NOT mean you don't have a password, just think of the password you use for authentication installations)

Volume path: This is the name of the volume path you are attempting to mount, for each protocol this may be a bit different. For afp (unless you have custom shares setup outside of the standard File Sharing preferences) you will ONLY be able to mount your root volumes or your user volume. If you want to link deeper into your volume turn on "Custom Paths" (discussed below). For nfs and smb you may have to put in full paths to the mountable volume (ie users/thatname/movies)

Auto Mount: whether or not the mount point will mount at startup (NOTE: mounts have a 15 second delay upon startup, the moment startup occurs networking isn't immediately available so we need to put in a delay before attempting to make network connections, in addition for SMB mounts to work in automount you MUST have a proper rc.local setup with the smbfs.kext getting loaded at startup for this to work)

Use Custom Path: This will toggle on or off a custom path to be linked into your mount location (where "Files" browses)

Custom Path: Only used if the above option (Use Custom Path) is toggled on. This is a nice workaround to afp limitations of only being able to mount root or user volumes. The path chosen here will be appended to the "Volume Path" and will be linked into your mountLocation. (ie Volume Path = Macintosh HD and Custom Path = Users/myname/Movies/MyMedia will link Macintosh HD/Users/myname/Movies/MyMedia into your mountLocation)

Below we will list what each control button does in the Network listing.

> (click) will edit the currently selected mount point (has no effect on bonjour points on the top)

Play/Pause: on mount points will attempt to mount and on bonjour points will take through the authentication process.

Manual Mount Edits

Here I will discuss the layout of the mounts.plist file for manual editing. This file is located at ~/Library/Application Support/nito/mounts.plist. It is a typical xml plist file, any OS X user that has edited a general plist file (all the preference files, in addition to many other configuration files are in this format). I will display the contents of a file with one mount point inside it and then explain how it works from there. I HIGHLY recommend making at least one mount point via the GUI rather than trying to make this from scratch, ONE typo can lead the file not to load or to crash the plugin.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "">
<plist version="1.0">
           <string>Media/TV Shows</string>
           <string>Macintosh HD</string>

Each mount has its own full <dict></dict> with unique key values, if you re-use a key value the plugin WILL crash. so make sure to increment for every mount value that you add. If you don't understand please don't ask, this guide isn't for novices.

autoMount: Boolean true or false

customMount: integer 0 or 1, 0 = off 1 = on

customPath: string value, explained in the section above. NEVER add a leading /

mountAddress: string value can be an IP address or a DNS address (i.e: or My-Machine.local) DO NOT APPEND // or anything else regardless if AFP, NFS or SMB.

mountName: string value, this is only how the point is displayed in the networking menu and has no other purpose

mountType: integer value, 0 = afp, 1 = nfs and 2 = smb

mountVolume: The volume name that is mounted. In AFP it can only be ONE name and not anything passed. (MacHD/userName/My Movies will NOT work with AFP, to accomplish this use custom paths)

requiresAuth: integer value, 0 = yes 1 = no

userLogin: string value, self explanatory

userPassword: string value, self explanatory

NOTE: Manual editing of these files is NOT recommended for novices, if you don't understand then DON'T attempt it. This guide is for people that are comfortable making manual edits to these kind of files. Be careful of editing these with normal text editors becaues they may append improper text formats. I have 0 experience editing these on windows machines so please don't ask.


The setting facade has several different tasks that can be accomplished, there is "Install Software" which will take you the installation manager and then various settings that have different effects on each playback mode of nitoTV. Each setting will have a corresponding icon to help delineate what it pertains to. (ie mplayer icon for mplayer settings, dvd icon for dvd settings etc...)

Install Software

Perian Installer

The perian installer will download and attempt to install all three components included in perian. Perian is used via Mixed and QuickTime playback modes. Find out more about perian here.

Additional: I have found that each time I hack the TV from its virgin 1.0 state with a Patchstick, NitoTV does not have the right permissions to run the Perian installer or add the mplayer codes. If you try to do so, the install seems to work, but media will not play. As soon as you've have Patchstick'd your Apple TV, enable SSH using the Awkward TV plugin, then fix NitoTV permissions:-

              sudo /System/Library/CoreServices/

--Simplicity 12:22, 22 October 2007 (CEST)

Install mlayer Codecs

This will install the rmvb and rm codecs in /usr/local/codecs/ all the other codecs from the essential package installer are removed because they cause conflicts and crashes.

Install Turbo's Kextloader

This installer is recommended to be run PRIOR to the smart installer. This will download and install Turbo's magic kextloader which will enable several features not enabled by default with the AppleTV (samba mounts, USB, bluetooth (dongle needed) etc...) This will download and install the kextloader in /sbin/ in addition to adding it to rc.local.

Smart Installer

The smart installer is the crown jewel of the Installation Manager. This little gem will either search mounted volumes for an intel computer (you MUST have the main root volume mounted from the source computer for intel computer installation to work) OR it will search in ~/Documents for the 10.4.9 or 10.4.10 intel combo updates (the full dmg file NOT the pkg file from inside the dmg). (you must download and put these in ~/Documents on your own) 10.4.9 combo

Once the smart installer finds the location to install from it will scan the AppleTV for any important missing kexts, frameworks or binaries (usb, udf, samba, bluetooth, dvdplayback etc) and install them in their proper location, taking care of any owners, permissions AND will add kexts necessary to load on startup to /etc/rc.local).

The smart installer will also take care of Turbo's easy USB patching (not done prior to 0.2.5b9) A reboot will be required for this to take effect.

Last but not least, the Smart Installer will fix any problems with the /etc/rc.local files not created by the prior version (b8) and add the necessary kexts and the kextloader.

Upon completion you will see a log with all of the actions performed by the smart installer.

NOTE: There have been several reports of the smart installer not working in the full 1.1 AppleTV version, we are aware of the problem but currently have no solution.

Safe Update

The safe update is another nice edition to the Installation Manager. Here you need to download the 1.1 dmg from Apple and place it in ~/Documents (your dmgLoc) Of course you need to be running 1.0 for this Safe Update to work. So if you updated via Apples software update on the AppleTV you will need to restore and repatch your AppleTV first for this to work.

This is pretty cut and dry, we will perform every step listed on either Safe Update wiki (including adding to /etc/hosts) As an added bonus we will migrate nitoTV and AwkwardTV Loader (if ATVLoader is installed) to the new 1.1 Finder, making the new transition completely painless.

Once the safe update is completed you will see a log of all the steps performed.

Cache Time

This is an mplayer setting, this is how much video will be cached before the video starts playing.

Reset Controls

This feature was added to easily remove the controls.plist file from the nito Application Support folder. This is mainly here to remove any improperly edited or corrupt control files (if you edit them and mess them up, or just want to return to the default)

mplayer log

This setting will log out EVERYTHING from mplayer's standard output, it is VERY verbose so it is only recommended if you are having trouble with mplayer playback.

DVD Import Destination

This is where the "DVD import" feature will store the DVD's that it imports.

DVD Scan Rate

This is ONLY applicable to DVDPlayback.framework, this is the scan rate that will be used when fast forwarding or rewinding. (in the future this will be performed while playing the DVD) For mplayer it has no effect.

DVD Straight to Menu

Normally when a DVD is selected in the "Files" listing it will take you to a track listing of that particular DVD. If you have the DVDPlayback.framework installed (can be installed using the Smart Installer) and this selection is toggled on we will attempt to take you straight to the DVD menu. If the DVDPlayback.framework is NOT installed this setting will have no effect (we took out libdvdnav support from mplayer because it was hindering us upgrading to a better/newer mplayer)

NOTE: This COULD take a long time to load a DVD, ESPECIALLY if there is ISO/IMG (disc images) involved. It will LOOK like the UI is locked up but it isn't, just be patient.

Playlists Use QuickTime

If this is turned on we will attempt to only use QuickTime (perian, flip4mac etc) to playback the contents of the selected playlist.

NOTE: if a file is not supported by QuickTime it will error out and the playlist will not continue, this WILL be addressed in the future.

File Playback Mode

This settings has 3 options, mplayer, QuickTime and Mixed. If you have mplayer selected it will only use mplayer to playback single Files, QuickTime just the same. The mixed mode however will play some file types in QuickTime and some in mplayer, in the future this will be added for playlists.

Cover Art Location

This is the location nitoTV will generate and look for cover art for files folders and playlists. For now the images will need to have the same name as the folder, file or playlists to be displayed. For instance Family Guy 01.avi will need Family Guy.jpg (png, tiff etc..) in your Images folder.

Playlist Shuffle

If this is turned on playlists will randomly shuffle through their contents. This mode works for both QuickTime and mplayer playback modes.

NOTE: for QuickTime it will play through the playlist until you exit manually, this means it is perfectly normal and possible for it to repeat the same file in the playlist. This will be addressed in the future. It is also perfectly normal to see the playlist facade in between each title during QuickTime playlists.

Show Metadata

For now we will look for metadata in the same location of the media files but with an .xml suffix instead. (ie Family Guy 01.avi will look for Family Guy 01.xml) For now it is possible to turn metadata support off because it is a bit buggy, it has been known to cause lockups, these bugs MIGHT be fixed but we left this option in just in case.

Show File Sizes

With this option turned on you will see the size of each media file in the Files facades. Turned off there will be nothing to the right of media files.


This section gives a long synopsis of the history and functionality of the nitoTV plugin, in addition to what is new in each update. It will be revised in the future to be more concise and have extraneous information edited out.

View Console Log

This section may show content OR could be blank. The finders console.log is a tricky beast to get under control. If the finder is not quit or does not crash in a certain period of time after startup it will not display the console log. We look for the console log in this location: /Library/Logs/Console/501/console.log. This section is useful to look for any errors or problems that arise.

Controls and Extra Arguments

controls.plist has an additional key for appending custom arguments to mplayer. Its pretty straightforward to edit

       <key>Extra Arguments</key>

to add a new argument you would just need to add <string>newargument</string> after <string>macosx</string>. Do NOT include spaces in the arguments! This could BREAK mplayer. (or at very least have it ignore your extra arguments) Each argument needs to be on its own line as illustrated above.

A good starter example for a valuable extra argument would be the addition of the following:


thus the final key for extra arguments would yield

       <key>Extra Arguments</key>

the reason this is a valuable argument set (and will subsequently be worked into future releases) is because the TV has a certain "safe" area of display that gets cut off in mplayer full screen mode without some type of border around the video area. the above code should make pretty close to adequate compensation for this problem. we'll be testing out different resolutions/tvs to make sure it works pretty universally before any hard coded implementation.

Manual Default Editing

Most of the preferences can be edited via the settings façade, but there are a few that can't be edited this way. Some aren't meant to be used and are for my debugging purposes, and others are arrays that I haven't had time to make a good UI for yet. The most important are the suffixes, mpSuffixes and qtSuffixes

Currently the suffixes are handled via 3 seperate arrays. Suffixes is an array that will differentiate which file types can to be viewed in the "Files" listings, The other two keys, mpSuffixes and qtSuffixes are both arrays that contain the file types which will be delegated to either QuickTime or mplayer. By default these are the two arrays:

   mpSuffixes: 3gp m3u pls divx xvid wmv asx asf ogm mpg mpeg mkv avc flv dv fli m2v ts vob iso img rm rmvb
   qtSuffixes: m4v divx xvid avi mov mp4 mkv flv dv

as you can see most of the suffixes attributed to mplayer are formats that will not play in QuickTime in the first place. The only exceptions would be wmv, (possibly asf), flv,dv and potentially 3gp. If you would like to edit these defaults (you need to be ssh'ed in) this is an example of slimming down some of the formats that are played back via mplayer

   defaults write mpSuffixes -array ogm mpg mpeg mkv avc m2v vob iso img rm rmvb

keeping in mind those are codecs that will only play in mplayer on the appletv (for now mpeg-2 still will not work in qt). the following could add wmv to the existing list of suffixes used in quicktime

   defaults write qtSuffixes -array m4v divx xvid avi mov mp4 mkv flv dv wmv

two things to note when editing arrays in defaults, 1) no commas, 2) you need to add ALL of the items pre-existing in the defaults for them to stay there.. so therefore the following

   defaults write qtSuffixes -array wmv

would remove all the old formats and just input wmv. FYI to get wmv to work in QuickTime you will need the flip4mac component, and it WILL load any wmv content absurdly slow, especially over the network.


During playback you can toggle between keymaps for the controller by pressing and holding menu.

The current keymaps are as follows (during playback)

(NOTE: this only applies to mplayer playback)

keymap 1:

left : rewind 10 seconds
right : fast forward 10 seconds
hold left : previous item in the playlist (if applicable)
hold right : next item in the playlist (if applicable)
up : increase volume
down : decrease volume
play/pause : play or pause

keymap 2:

left : rewind 60 seconds
right : fast forward 60 seconds
hold left : rewind 600 seconds
hold right : fast forward 600 seconds
up : move a subtitle up
down : move a subtitle down
play/pause : toggle on screen display

keymap 3:

left : sub_delay -0.1
right : sub_delay +0.1
hold left :sub_select
hold right : switch_audio
up : audio_delay +0.100
down : audio_delay -0.100
play/pause : show file name

There will be a graphical editor later for the keymaps. And i'll be updating this wiki to include more information about customization as well. Just wanted to get it started.

Known Issues

It is perfectly normal for the Apple logo to appear before a video is played back this will be displayed while the file is caching, followed by a green screen and then the video playing. (in mplayer only)

A menu bar will appear while mplayer is playing (don't worry it appears behind the fullscreen). Eventhough it has a application menu called nitoTV it is the mplayer menu. This is normal as well.

DVD images 4.3 GB and larger have been reported to have issues on samba and NFS mounts, haven't tested for AFP but it possibly could lead to the same issues. (no playback and truncated size listing) A workaround is to use VIDEO_TS folders instead of ISO.

Sometimes files don't show up for no discernible reason from AFP mounts, no known solution yet.

The screen does not release or flickers when using mplayer or DVD playback (which can yield video behind the scenes with only audio being heard), the only solution is lower the AppleTV resolution from 720p to 1080i or lower. (for now)

No 5.1 AC-3 passthrough in DVD or mplayer (will be addressed in the future, not sure how soon though)

No indication of success or failure of mounting, only returns to Files menu: This isn't really a "known issue" per-say. just a lack of polish, eventually this will be changed to go into the Files section OR show some type of ui error on why the mounting failed.

Metadata lockup/crash. Sometimes when attempting to load metadata nitoTV will lockup or crash, this problem MAY have been solved (not 100% certain) It's the main reason that metadata display can be toggled on and off in the Settings facade.

Smart Installer fails on 1.1 full. Only getting message about "already mounted read write" and nothing after in the followup log. Not sure what the problem is here, and may or may not find a solution because we'll never be running full 1.1

Install Howto

To install it, you will need to copy the NitoTV folder from into your AppleTV. You can copy it to the home folder of the 'frontrow' user if you wish, although its location doesn't really matter.

Next, you need to open an SSH connection to your AppleTV, like so:

ssh -1 frontrow@AppleTV.local

When prompted for a password, enter 'frontrow'.

Now go to the directory where you placed this folder on your AppleTV and type the following command:

sudo ./installme

When prompted for a password, enter 'frontrow' again

Fixing Helper Permissions

ssh -1 frontrow@AppleTV.local

When prompted for a password, enter 'frontrow'.

sudo /System/Library/CoreServices/

When prompted for a password, enter 'frontrow' again

Revision History

0.1: Initial Release

0.11: Fixed screen saver issues and added ISO support for DVD

0.2: Copy controls.plist to nito application support folder for easier access. Added Settings and About. Ability to toggle cache time. Added core video settings to mplayer. Fixed a major bug/conflict with other 3rd party plugins.

0.2.1: Initial DVD menu support. Extra commands appended to mplayer. Reset controls in settings. Turn on mplayer logging. Various bug fixes

0.2.5 betas: DVDPlayback.framework support, mounting smb, nfs, afp from the ui, automounting, kext/framework installation, perian support, perian installation, kexxtloader installation, various settings, shuffle playlists, quicktime playlists, mixed playback, metadata, covertart and much much more

Useful Terminal Commands

This section is just going to be a documentation for easy reference of important terminal commands. For now I'm just adding this but there will be more later.

If you don't have killall installed here is the easiest way to restart the Finder

kill `ps awwx | grep [F]inder | awk '{print $1}'`

Future Plans

Resume from previous played destinations in files, playlists and DVDs.

DVD OSD (on screen display) for chapter numbers, elapsed time, etc.

Played/unplayed markers

HTML scraping (fetching metadata and coverart) from imdb and

music playback

photo streaming

Special Thanks

Alan Quatermain AK2007 datafrog turbo maraklov therealkerni mplayer team ffmpeg team

entire community for making this all possible!

Legal Info

nitoTV Copyright © 2007 nito llc.

SSE3 emulator © 2007 by Mike Byrne (

Portions Copyright © 2007 Alan Quatermain

All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, publish, and/or distribute copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.