Member Log In  |  Sign Up

Contact Us  |  Advanced Search

Broadcast Your Application’s Content with iChat Theater

Since its introduction iChat has become the de facto Instant Messaging client on Mac OS X, allowing users to communicate using text, audio, and even video chat. The new version of iChat in Leopard opens up these capabilities to other applications on the system, allowing those applications to provide content through an iChat session. For example, a user may display a photo slide show while chatting with her parents. Or two people might collaborate on a document, talking about the details as one person makes changes and the other observes the result.

To enable you to access iChat features from within your application, Leopard ships with an expanded Instant Message framework. This framework allows you to programatically determine presence, and start iChat theater sessions to share supporting video and audio content during a video conference. In addition to the Instant Message framework, you can also access iChat's many features through AppleScript, performing such activities as initiating a video chat or responding to an iChat event.

Figure 1: You Can Add iChat Features to Your Leopard Application

In this article, we start with an overview of how to get information from iChat by using the Instant Message framework. We then discuss iChat Theater, which makes possible the sharing of video and audio from within your application. Finally, we show you some of the things you can do with iChat using AppleScript. All this adds up to unprecedented power, putting you firmly in charge of your application's ability to gather information, control iChat, and share video and audio over the network.

Using iChat Presence Information

One of the powerful capabilities that the Instant Message framework gives you is the ability to determine if a contact in a user's buddy list is online or not. You can also get the Address Book data for that contact as well as other status information. This information is collectively referred to as “presence.” And once you tap into this presence data, your application can be notified when information about a contact changes.

This information is obtained by using the IMService class. For example, the code in Listing 1 shows how to get information about a particular person. Because iChat includes support for several services, including AIM, Jabber, and Bonjour, you can use IMService to determine which of these services are available, as well as screen names for your buddies in each service. Note that .Mac screen names are listed under the AIM service. This example also registers a callback so that the application gets notified when any user's presence information changes.

Listing 1: Using the IMService Class

- (void)info
{
	// Register for notifications
	[[IMService notificationCenter]
		addObserver:self
		selector:@selector(handleInfoUpdate:)
	    name:IMPersonInfoChangedNotification object:nil];
}

- (void)handleInfoUpdate:(NSNotification *)note
{
	NSDictionary *dictionary = [note userInfo];

	NSLog(
		@"handleInfoUpdate: dictionary = %@",
		dictionary
	);
}

Now, when the user with screen name “iChatDemo” changes his or her status message, the data received in the notification looks like the following.

2007-02-12 00:55:51.784 Presence[2168:20b] handleInfoUpdate:
dictionary = {
    IMPersonAVBusy = 0; 
    IMPersonAllowedCapabilities = (
        IMCapabilityText, 
        IMCapabilityDirectIM, 
        IMCapabilityFileTransfer, 
        IMCapabilityAudioConference
    ); 
    IMPersonCapabilities = (
        IMCapabilityText, 
        IMCapabilityDirectIM, 
        IMCapabilityFileTransfer, 
        IMCapabilityAudioConference
    ); 
    IMPersonScreenName = iChatDemo; 
    IMPersonStatusMessage = "Stand by for action"; 
}

This example just scratches the surface of what you can do with IMService. You'll want to get started soon with this exciting technology. And now that you've seen a sample of using the API, let's look at what you can do with iChat Theater.

iChat Theater

iChat Theater allows applications to present audio and video content during an iChat conference. For example, your application can present a slide show, a video feed, or even 3D graphics, complete with sound, to one or more conference participants. This is made possible through the IMAVManager class at the heart of iChat Theater. It encapsulates some of iChat's most advanced features in an Objective-C class.

IMAVManager works with the other classes in the Instant Message framework to enable you to build sophisticated conferencing capabilities into your application. For example, you can use IMService to determine who is available to participate in a chat, and then use IMAVManager to setup and run the iChat Theater presentation.

iChat Theater also leverages existing Mac OS X technologies under the hood, such as Core Video for video rendering and Core Audio for processing audio data, while providing a simple programming interface for most rendering tasks.

Next we'll examine how easy it is to provide both video and audio content using iChat Theater.

Taking advantage of iChat Theater is amazingly simple for Cocoa applications: just pass a Cocoa view to the IMAVManager using the setVideoDataSource: method and you're done.

Listing 2: Registering a Video Source

IMAVManager *manager = [IMAVManager sharedManager];
[manager setVideoDataSource:myView]; 

iChat handles the generation of video frames for you, even scaling the view's contents if its dimensions do not match the ratio used by iChat Theater. Literally any NSView-based objects are supported, including QTMovieView, NSOpenGLView, QCView, even WebView. Custom views written for your application are of course supported as well.

If you prefer more fine-grained control over what is sent through iChat Theater, you have the option of setting the manager's data source to your custom object that provides the video frames. When the custom object receives a callback requesting the next frame, it draws directly into the provided buffer and the manager transmits it through iChat Theater. Depending on which callbacks the custom object implements, it can either provide frames as a CVOpenGLBuffer for OpenGL applications, or a CVPixelBuffer that you can easily use to create a Quartz CGBitmapContext then a Cocoa NSGraphicsContext.

As mentioned above, your video callbacks must support either OpenGL or raster-based rendering. The signatures for both types of callbacks look similar. Listing 3 shows the Core Video pixel buffer-based callbacks.

Listing 3: Pixel Buffer Callbacks

// Specify your pixel format
- (void) getPixelBufferPixelFormat:(OSType *)pixelFormatOut;

// Render the video frame
- (BOOL) renderIntoPixelBuffer:(CVPixelBufferRef)buffer
forTime:(CVTimeStamp *)timeStamp;

You can provide audio content to iChat Theater with an API that is just as easy to use as for video. Audio content from your application is transimitted together with the user's microphone, allowing the user to talk along with whatever content they are sharing.

Starting an iChat Theater Presentation

Initiating your iChat Theater presentation requires a few simple steps:

1. Register your data source. Call the respective methods for registering audio and video providers.
2. Register for state change notifications. IMService has its own notification center, so you need to register your callbacks through it. Since an iChat Theater presentation cannot begin until the IMAVManager is in an available state, you need to monitor these state changes.
3. Start the iChat Theater presentation. Call the - [IMAVManager start] method once the service is available.

That's all there is to it. If you have implemented callbacks for audio or video, they are invoked repeatedly from this point until either the presentation or the conference is terminated.

AppleScript Support

The Instant Message framework is not the only way to take advantage of iChat. With Leopard, iChat's scripting dictionary has been expanded to include nearly all of the iChat operations you can perform interactively with a keyboard and mouse. You can access this scripting functionality either from an application or directly from an AppleScript.

Object Model

iChat has a rich object model that gives you fine-grained control over the application. For example, the service, account, and chat classes help identify a chat participant by his or her screen name, on a particular service (such as AIM, Jabber, or Bonjour), and in a specific type of chat (text, audio, or video). This allows for sophisticated, high-level application control over iChat. Your application might run a script that starts a chat. Or you might write a script for determining if a specific person is online. Or something in-between.

For more details on the iChat object model, use the ScriptEditor application in Leopard to examine iChat's scripting dictionary.

Example: Start a Video Chat

The AppleScript in Listing 4 instructs iChat to start a video chat with a specific AIM screen name. Even if you are not familiar with AppleScript, this example should illustrate how easy it is to send a scripting command to iChat.

Listing 4: Start a Video Chat

tell application "iChat"
	make new video chat ¬
		with properties ¬
		{participants:buddy "iChatDemo"}
	set theChat to the result
	
	tell theChat
		set showing full screen to true
		request recording
	end tell
end tell 

Event Handlers

iChat supports a type of script called an event handler. An event handler looks like a regular script, but it responds to a specific iChat event rather than being general purpose. Once you write an AppleScript that responds to a particular iChat event, you then set that handler to run either globally or for a particular user. Figure 1 shows how to assign a handler to a specific user.

Example: Acknowledge a Message

The AppleScript example in Listing 5 illustrates how to use iChat's scripting dictionary to auto-respond to an incoming message. The script writes an acknowledgement back to the buddy. It can easily be modified to do something more sophisticated, such as log the incoming message.

Listing 5: Message Received Event Handler

using terms from application "iChat"
	
	on message received theMessage ¬
		from theBuddy ¬
		for theChat
		
		tell application "iChat"
			send "Thanks for the message!" ¬
				to theBuddy
		end tell
		
	end message received
	
end using terms from 

These examples just scratch the surface of what you can do with AppleScript and iChat. For more information on AppleScript, check out the AppleScript home page.

Get Started with Leopard

The next generation of the world's most advanced operating system is now available. Tap into the innovative technologies of Mac OS X Leopard and design your products with new and compelling features. With an ADC Premier or Select Membership, you have a range of developer resources from Apple engineers and experts, including ADC on iTunes, Coding Headstarts, the ADC Compatibility Labs and more. Learn how ADC Memberships provide you Apple expertise. From code to market.

Updated: 2007-10-26