The goal was to have a single, flexible script. And specifically, I wanted something I could call from an AppleScript, which would place the results into a spreadsheet without lots of text parsing in AppleScript (because text parsing is tedious in AppleScript, although to be fair, everything is tedious in AppleScript.)

The script I came up with is mostly Ben Chatelain’s excellent perl script (again based on the work of Erica Sadun). To better fit my workflow, I modified Ben’s script in the following ways:

• Accepts the app ID, category, “free” or “paid”, and country name as arguments the command line.
• Returns just a number (the app’s rank in the given category), or “n/a” if it’s not ranked in the top 100 for that category/country combination.
• Arguments (except app ID) are optional — the script will assume “Top Overall”, “United States”, and “free”.)
• The script will cache the most recent data (and curl is invoked with -z). This way, if you call the script a dozen times in a row, it only pulls the page once, and the rest of the invocations use the cached data (stored in /tmp).
• To check the “Top Apps” overall rankings, pass in “Top Overall” for the category name.
• Likewise, to see the ranking for every country in the world, pass in “world” for country. The script will check the top apps for every country. In this case, the returned results are a string of “countryName: rank\n”, one per country.

You call it from the command line like this:

app_rank.pl appID categoryName free|paid countryName

rob$ app_rank.pl 300872165 News free
37

Or to see the results for the whole world (results edited for blog brevity):

rob$ app_rank.pl 300872165 News free world
Lebanon: 47
Saudi Arabia: 73
Pakistan: 74
Mexico: 71
Colombia: 61
Hungary: 89
Croatia: 19
...et cetera...

(How is my english-language not-localized North-Carolina-specific app #19 in Croatia?!?)

Here’s the AppleScript I use to populate a spreadsheet:

AppleScript to get the app rank and put it into Numbers

Here’s the spreadsheet it fills out. The AppleScript pulls the appID to look up from the first cell in each column, and then adds the timestamp and the app’s rank, so I can add new app IDs as I get them.

App rank data in Numbers

I scheduled the script to run every few hours (using Ligon) and so I’m slowly accumulating data. Of course, I can never sleep my laptop or I’ll miss some data. This concept would probably be best realized as something that runs on a server via cron. Since it’s a perl script that uses curl instead of some CPAN package it’s probably easily portable to just about anywhere. It would be simple to move this script to a server and collect the data in some other fashion.

Note that you can also use this same technique to track your app’s success against competing apps.

The script is here (3k zipped perl script).

I’m the organizer of the Raleigh iPhone Developer’s Meetup and it’s basically impossible for our group’s members to demo their apps. The “crowd people around a phone” method breaks at around four people. And our last meetup had 20 people!

Why can’t we be like Steve, using our apps on our phone, with the display projected for all to see?

I have a solution, if you’re willing to make a special build of your app that’s not meant for the app store. No jailbreaking required! Although a willingness to use private methods is.

Update: There’s a new version for iOS 4.0 here: http://www.touchcentric.com/blog/archives/123

How It Works

Inside the iPhone SDK exists a private API for video output. A class called MPTVOutWindow will display whatever it contains via the video output dock connector. (Thanks to Erica Sadun who discovered this class and figured out how to use it!)

I created a UIApplication category (that is to say, an extension to the existing UIApplication class) that uses MPTVOutWindow to mirror the device display onto the TV display. The goal was to make it seamless — drop the file into a project, recompile, and go. And it’s really just that easy, with a couple of caveats.

Caveat #1: apps that use this won’t be allowed into the App Store. That’s because it uses a couple of private APIs (the MPTVOutWindow class and UIGetScreenImage()). But since you’re already an iPhone application developer, creating a private build for your own use is normal.

Caveat #2: it doesn’t copy parts of the screen that belong to OpenGL. The class could be extended to do that, if you needed to.

Update: actually, it works fine with OpenGL. I demoed an OpenGL game using this at about 20 fps.

Getting Started

First, get a video out cable. It’s the same cable you’d use to watch videos from your iPhone on a TV using the dock connector (note: headphone-jack video cables from older iPods do not work). Apple’s official cable, Apple Component AV Cable, is $50 for composite video. A similar cable is only $14.18 at MonoPrice.com. Component cables are also available. `

How To Use

Add the file UIApplication+TVOut.m to your project. Also, you’ll need the “MediaPlayer.framework” framework, which contains references to the private API we’re using.

Somewhere in your code you need to call start. Anytime after your app’s primary window has been created, call startTVOut:

     [[UIApplication] sharedApplication] startTVOut];

That’s about all you need to do. The application category handles everything necessary to mirror the device’s display. The startTVOut method creates the MPTVoutWindow, adds the necessary subviews, rotates them to match your app’s orientation, and centers them to appear properly on the TV. A background thread copies the bits from your main display into a view in the MPTVOutWindow. (You can configure the frames per second in the #define at the top of the file. 12 fps works well for me.)

iPhone app displaying its output on a TV

In my test app, I call it from applicationDidFinishLaunching:. One thing to remember about applicationDidFinishLaunching: is that it gets called before the runloop starts, so your primary window isn’t on screen yet. I call it with a brief delay to give the runloop a chance to get going.

- (void)applicationDidFinishLaunching:(UIApplication*)application {	
// give the runloop a chance to start
    [[UIApplication sharedApplication] performSelector: @selector(startTVOut)
    withObject: nil afterDelay: .1];
}

And actually, you don’t even need to call startTVOut. The category can start itself. The code includes an override for a private method called reportAppLaunchFinished:. This undocumented method seems to get called after the app has finished loading. (Being undocumented, I’m not really sure what it does, or what the negative consequences of overriding it has. As far as I can tell, it’s only used to clean up the Default.png display.) I’ve commented out that method, since it’s a bit mysterious. But if you uncomment the method, it will automatically start the TV out display for you. No changes to your code needed!

Mirroring Other Apps?

Since this code runs as part of your app, it stops running when your app stops running. So it’s not a general purpose full-time video mirroring solution.

However, using other private methods, it’s possible to launch other apps while your app remains running, thus mirroring whatever app is in front. I’ve managed to mirror Safari (launched using the private openURL:asPanel: method). I’m sure you can figure ways to mirror other apps using some of the private app launching methods.

Not for Public Consumption!

Since this uses private methods, it would almost certainly not survive Apple’s app review process. To avoid getting your app rejected, you should remove this code from your release builds. This is pretty easy — set the current target to Release and uncheck the checkbox next to the file’s name. Also, if you call startTVOut manually, you’ll need to put some #ifdefs around that call, so it won’t get compiled into release builds.

Great, Where’s the Code?

Grab the latest code from here:

http://groups.google.com/group/iphone-developers-nc/web/UIApplication_TVOut.m

If you have any comments or questions, feel free to email me.

– Rob