TweetFollow Us on Twitter

Mar 02 QT Toolkit

Volume Number: 18 (2002)
Issue Number: 03
Column Tag: QuickTime Toolkit

Broadcast News

by Tim Monroe

Broadcasting Movies Over a Network


The key new technology introduced in QuickTime 4 was support for receiving real-time streamed data. That is to say, QuickTime-savvy applications like QuickTime Player or our own QTShell-based sample applications can receive video, audio, and other kinds of data streamed across the Internet. Real-time streaming, unlike the progressive downloading of movie files that has been available since QuickTime 3, can handle live data and does not require downloading potentially huge files onto the user's computer; this permits QuickTime playback applications to support uses such as video-on-demand and rebroadcast streaming.

The real-time streaming provided by QuickTime 4 was a client-side technology only; it did not provide any means to serve up, or transmit, the data streams. At that time, special software was required to create the streams of data that could be sent out over a network and then received and played back by QuickTime-savvy applications. As we'll see, the protocols used in transmitting the data from the server to the client conform to Internet Engineering Task Force (IETF) standards, but implementing those protocols in a transmitter application required intimate knowledge of a handful of IETF specifications, as well as a good bit of programming.

QuickTime 5 provides a set of broadcasting functions that allow us to create transmitter applications. For example, we can take the audiovisual data captured by a camcorder attached to one computer and broadcast that data to other computers on a network. Together, the transmitter technologies provided by QuickTime 5 and the receiver technologies provided by QuickTime 4 give us the complete set of tools we need to send audiovisual streams from one computer and view them on another. The good news here is that we need to know virtually nothing about the applicable IETF specifications to do all this; the really good news is that the amount of code we need to write to create a broadcasting application is surprisingly small. Indeed, we'll be able to write this application using fewer than a dozen of these new broadcasting functions.

In this article, we're going to see how to use these new APIs to build a sample application that broadcasts live data to other computers. (Let's call this application QTBroadcast.) In a previous QuickTime Toolkit article ("Captured", in MacTech December 2001), we saw how to use the sequence grabber to capture sound and video data from devices attached to our local computer; here we'll see how to send captured data to other computers located remotely on a network.

When it starts up, QTBroadcast automatically opens a monitor window, shown in Figure 1; this is modeled on the monitor window we created in the previous article, but now contains a button to start and stop the broadcasting.

Figure 1: The monitor window of QTBroadcast

The Test menu of QTBroadcast is shown in Figure 2; as you can see, it contains items that allow the user to select an SDP file (which we'll describe later) and to configure the broadcasting settings.

Figure 2: The Test menu of QTBroadcast

We'll begin by surveying the various streaming capabilities provided by QuickTime, and we'll take a brief look at the protocols that underlie those capabilities. Then we'll consider the code we need to add to our basic application shell to allow it to broadcast live data streams. Note that QuickTime's broadcasting APIs are currently available only on Macintosh operating systems (Mac OS 8 and 9, and Mac OS X).

QuickTime Streaming

Streaming is the process whereby one computer (the transmitter) chops a file or sequence of bytes up into discrete chunks (called packets) and sends them across a network to another computer (the receiver or client). The client's job is to reassemble the packets and do the right thing with them. The series of packets is a stream. For present purposes, we are interested only in streams of audiovisual data that can be reassembled and played back as a QuickTime movie.

It's important to keep in mind that QuickTime has supported a kind of streaming, called HTTP streaming or progressive downloading, ever since QuickTime 3 was released in 1998. QuickTime's HTTP streaming allows the QuickTime browser plug-in to begin playing a movie embedded in a web page before the entire movie has downloaded to the local computer. HTTP streaming is essentially a file transfer protocol, in the sense that the entire movie is downloaded to the user's computer. One key advantage of QuickTime's HTTP streaming is that a user can begin interacting with web-based content before the entire movie arrives on the user's computer. As we saw in an earlier article, the movie file embedded on the web page is a standard QuickTime movie file saved in Fast Start format (where the movie atom is the first atom in the movie file).

QuickTime 4 introduced a different kind of streaming, called real-time streaming. With real-time streaming, packets are sent out over the network in real time (so that, for instance, a 10-minute movie would take 10 minutes to download). When packets are received by the client application (for instance, by QuickTime Player), they are reassembled into a QuickTime movie and played for the user. In general, packets are discarded as soon as they have been played, so no file is ever created on the user's local storage devices.

QuickTime's real-time streaming uses an open IETF streaming protocol known as the Realtime Transport Protocol (RTP) to send the packets of video and audio data. For control information, such as establishing a connection between the client and server or telling the server to jump to a new time in a video-on-demand movie, QuickTime uses a different protocol known as the Realtime Streaming Protocol (RTSP). Figure 3 shows the basic network protocols used by QuickTime's streaming architecture. RTSP uses the TCP/IP transport layer, while RTP uses the lower-level UDP/IP transport layer.

Figure 3: The basic QuickTime streaming protocols

Because RTP uses UDP/IP, it does not guarantee delivery of packets. So it's possible for some packets to get lost in transit and never arrive at the client computer. This packet loss can result in some degradation of the video and sound when the movie is played back on the client computer. If you need guaranteed delivery of packets, you should use HTTP streaming, which uses TCP/IP to ensure that all transmitted packets are in fact received (by retransmitting any lost packets).

QuickTime supports streaming of video, audio, and text data in any of the formats that can be played locally by QuickTime, including AVI, Sorenson, QDesign, MP3, and MIDI. It cannot currently stream movies that contain sprite tracks or that incorporate features that depend on track references, such as QuickTime video effects, chapter lists, and some tweening effects. To handle these sorts of movies, you can either use HTTP streaming or you can create movies that store some data locally and combine that data with data received via RTP streaming. You can even create movies some of whose tracks are delivered via HTTP streaming and some via RTP streaming.

The files that reside on the streaming server are standard QuickTime movie files, with one important addition: each track in the movie that is to be streamed across the network must be accompanied by a hint track. The hint track contains information that tells the server software how to packetize the corresponding streamed track. In other words, the hint track is a sort of blueprint for creating streams of data. Without the hint track, the server software would have to know a great deal about the particular audio or video format contained in the streamed track, so that it would know how best to chop the data up into packets (for instance, possibly duplicating some of the packets to protect against losing important frames of video). The hint track insulates the server software from having to know anything about the actual video or audio data it's serving.

This is especially important because it allows streaming servers to run on operating systems that don't even run the QuickTime client software. Indeed, the first commercially available QuickTime server application, Apple's QuickTime Streaming Server (QTSS), debuted on machines running the Mac OS X Server software. Moreover, Apple has released the source code for the QuickTime Streaming Server under the Apple Public Source License, which conforms to the Open Source community guidelines. Versions of QTSS currently run under Windows and various flavors of UNIX, including Linux.

QuickTime Broadcasting

The broadcasting APIs introduced in QuickTime 5 allow us to create broadcasting applications (or, more simply, broadcasters). A broadcaster is an application that takes data from a source other than a hinted movie, compresses that data (if necessary), packetizes that data into streams, and then sends the streams out over a network. In the simplest case, the streams are targeted at a single specific client on the network. This type of serving is called unicasting. It's also possible to target a set of streams at more than one client on the network, using a special reserved address; this type of serving is called multicasting.

The QuickTime broadcasting APIs support both unicasting and multicasting. Some routers, however, are not configured to allow multicast streams. In this case, we still need to use a streaming server (such as QTSS). We can transmit the streams to a machine running QTSS, which then unicasts distinct streams to any number of remote clients.

The broadcasting APIs can be divided into two general categories, which we'll call the sourcer APIs and the presentation APIs. We can use the sourcer APIs to select and configure a source for the broadcast data. (A sourcer component, or sourcer, is a component that can read data from a specific kind of source.) Currently QuickTime supports broadcasting data from any of these kinds of sources:

  • Data captured using a sequence grabber component from audiovisual devices
  • Movie files stored locally on the transmitter
  • Precompressed media data that is not stored in a movie file

This last kind of source allows us to broadcast virtually any kind of media data; we simply need to pass the appropriate data, a sample description for that data, and (optionally) a timestamp and duration. Keep in mind, however, that the client receiving the broadcast needs to have a media handler for that kind of data. Also, some kinds of data (for instance, sprite media data or Flash media data) do not respond well to packet loss and hence are currently not good candidates for broadcast streaming.

We use the presentation APIs to present (or broadcast) the data provided by a sourcer. A presentation is a collection of one or more streams of data, which can consist of packets of audio, video, text, or other data. You might think of a presentation as the streaming equivalent of a movie and the streams within the presentation as the streaming equivalent of a movie's tracks. The client application receives the presentation and reassembles it into a movie, which it plays back in exactly the same way it plays a local movie.

The sourcer and presentation APIs are a marvel of simplicity. As I mentioned earlier, we will be able to develop a broadcasting application using fewer than a dozen broadcasting functions. In fact, for the moment we won't need to use any of the sourcer functions at all, since we'll rely on QuickTime's default behavior of using the sequence grabber as the source for the broadcast data. So let's get started.

Setting Up For Broadcasting

Before we can begin broadcasting live audio and video data captured from an audiovisual device attached to our computer, we need to initialize our application for broadcasting and then create a presentation. As we've seen, a presentation is analogous to a movie: it consists of one or more streams of data targeted at one or more remote computers. In QTBroadcast, we shall allow at most one active presentation at a time, and the data being broadcast will be displayed in the monitor window (see Figure 1 again), which also contains a button that can be used to start and pause the broadcast. To keep track of the presentation and the monitor window, we'll use these global variables:

QTSPresentation            gPresentation = kQTSInvalidPresentation;
QTSNotificationUPP      gNotificationUPP = NULL;
DialogPtr                  gMonitor = NULL;
UserItemUPP               gMonitorUserItemProcUPP = NULL;
Boolean                     gBroadcasting = false;

The gPresentation global variable is an identifier for the single presentation supported by QTBroadcast; as you can see, it's of type QTSPresentation and is initialized to the value kQTSInvalidPresentation. Associated with the presentation is a presentation notification procedure, which we identify using the gNotificationUPP global variable. Our notification procedure is called on specific events involving the presentation, such as when a presentation is first created and when a connection to the client machine occurs.

We use the gMonitor and gMonitorUserItemProcUPP global variables to keep track of the monitor window and the user item in that window (where we draw the video data that's being broadcast). Finally, we'll use the gBroadcasting global variable to keep track of whether we're currently broadcasting data or not.

When QTBroadcast starts up, it calls the QTBC_Init function, defined in Listing 1, to create the monitor window and to allocate the universal procedure pointers gNotificationUPP and gMonitorUserItemProcUPP.

Listing 1: Initializing for broadcasting

OSErr QTBC_Init (void)
   OSErr         myErr = noErr;

   // allocate global storage
   gNotificationUPP = (QTSNotificationUPP)
   if (gNotificationUPP == NULL) {
      myErr = paramErr;
      goto bail;

   gMonitorUserItemProcUPP = NewUserItemUPP
   if (gMonitorUserItemProcUPP == NULL) {
      myErr = paramErr;
      goto bail;

   // open the monitor window
   gMonitor = QTBC_CreateMonitorWindow();
   if (gMonitor == NULL) {
      myErr = memFullErr;
      goto bail;

   // if an error occurred, clean up
   if (myErr != noErr)


QTBC_Init calls NewQTSNotificationUPP and NewUserItemUPP to create the two UPPs, and it calls the application function QTBC_CreateMonitorWindow to create and display the monitor window. We'll consider QTBC_CreateMonitorWindow in depth a bit later (Listing 9); for the moment, it's sufficient to know that it calls GetNewDialog to create a dialog window from information in the application's resources.

If any error occurs in QTBC_Init, we don't want to continue. In that case, we'll call the QTBC_Stop function, which is defined in Listing 2. QTBC_Stop simply deallocates the two UPPs created by QTBC_Init and disposes of the monitor window.

Listing 2: Shutting down broadcasting

void QTBC_Stop (void)
   // deallocate any global storage
   if (gNotificationUPP != NULL) {
      gNotificationUPP = NULL;
   if (gMonitorUserItemProcUPP != NULL) {
      gMonitorUserItemProcUPP = NULL;

   // close the monitor window
   if (gMonitor != NULL)

We also call QTBC_Stop just before QTBroadcast terminates; at that time we will also call the QTBC_StopBroadcasting function, which calls QTSDisposePresentation to dispose of the presentation gPresentation. (QTBC_StopBroadcasting is defined later, in Listing 7.) It's important to dispose of the UPPs and the monitor window only after we dispose of the presentation itself; accordingly, our application-specific shutdown routine, QTApp_Stop, contains these two lines of code:


Creating a Presentation

If QTBC_Init completes successfully, the monitor window is displayed on the screen but it contains no image and the Start button is inactive (as shown in Figure 4).

Figure 4: The monitor window on application launch

Before we can begin broadcasting data, we need to create a presentation. We do this by calling the QTSNewPresentation function, like this:

myErr = QTSNewPresentation(myPresParamsPtr, &gPresentation);

The second parameter is the address of our global variable gPresentation; if QTSNewPresentation completes successfully, it returns an identifier for the new presentation in that variable. The first parameter is the address of a new presentation parameters structure, which is defined like this:

struct QTSNewPresentationParams {
   OSType                        dataType;
   const void *               data;
   UInt32                        dataLength;
   QTSEditListHandle         editList;
   SInt32                        flags;
   TimeScale                  timeScale;
   QTSMediaParams *         mediaParams;
   QTSNotificationUPP      notificationProc;
   void *                        notificationRefCon;

So before we can call QTSNewPresentation, we need to allocate a new presentation parameters structure and fill in most of its fields. We allocate this structure by calling NewPtrClear:

myPresParamsPtr = (QTSNewPresentationParams *)

The first three fields of the new presentation parameters structure contain information about some of the network settings to be used by the presentation, such as the destination IP address for the broadcast and the ports to use for the data streams. The IETF has defined a standard format for this information, called the session description protocol (SDP). An SDP file (that is, a file that conforms to the SDP) is used by clients and servers for initiating a network connection and transfer of multimedia streams between a server and its clients. This file describes the types and formats of the media to be transferred, the transport protocols, and the addresses to which the media are to be streamed. Here's a sample SDP file:

c=IN IP4
m=audio 1000 RTP/AVP 12
m=video 2000 RTP/AVP 101
a=rtpmap:101 H263-1998

The line beginning with "v=" specifies the protocol version, which currently is 0. The line beginning with "c=" specifies the connection information, which consists of a network type and address type (here, "IN IP4" for IP version 4 addressing on the Internet), the destination address (here, "", which is an address reserved for multicasting), a time-to-live value (here, 15), and the number of contiguous multicast addresses (here, 1). The lines beginning with "m=" indicate which transport protocols and ports to use for specific media types. In the file shown above, the audio data is to be sent via RTP to port 1000 and the video data is to be sent via RTP to port 2000. Finally, the line beginning with "a=" specifies media attributes. In this case, the rtpmap attribute provides information about dynamic payload binding.

In our sample application QTBroadcast, the user selects an SDP file using the first menu item in the Test menu (namely, "Select SDP File..."). In response to menu item, we call the QTBC_SetupPresentation function, which in turn uses our standard framework function QTFrame_GetOneFileWithPreview to allow the user to select an SDP file. QTFrame_GetOneFileWithPreview returns a file system specification for that file. We can then fill in the relevant fields of the new presentation parameters structure like this:

myPresParamsPtr->dataType = kQTSFileDataType;
myPresParamsPtr->data = &myFSSpec;
myPresParamsPtr->dataLength = sizeof(myFSSpec);

QuickTime also supports SDP information stored in memory (in which case the dataType field should be set to kQTSSDPDataType). In QTBroadcast, we'll restrict our attention to SDP files only.

The editList field of the new presentation parameters structure is a handle to a QTSEditList structure, which holds information about edits for stored streams. For live broadcasting, we can ignore that field.

The flags field of the new presentation parameters structure contains information for the presentation we are about to create. Currently these flags are defined:

enum {
   kQTSAutoModeFlag                  = 0x00000001,
   kQTSDontShowStatusFlag            = 0x00000008,
   kQTSSendMediaFlag                  = 0x00010000,
   kQTSReceiveMediaFlag               = 0x00020000

The kQTSAutoModeFlag flag indicates that the presentation should be automatically configured to its default settings; most importantly, this means that the default sourcer is to be used, which is the sequence grabber. The kQTSDontShowStatusFlag flag indicates that we do not want QuickTime to create a streaming status handler for the presentation; if we request a status handler, it displays connection and status information in the monitor window (that is, in the window associated with the sequence grabber). For instance, when we first create a presentation, QuickTime attempts to connect to the specified target or targets and displays the status message shown in Figure 5.

Figure 5: The status message while connecting

When the presentation is ready and the requisite network connections have been established, we'll see the message shown in Figure 6. (Keep in mind that these status messages appear on the transmitter only; the broadcasting client also displays some status information while establishing a connection to the transmitter, which we'll encounter later.)

Figure 6: The status message when ready

The remaining two flags, kQTSSendMediaFlag and kQTSReceiveMediaFlag, indicate whether we want to send or receive data with the presentation we're creating. In QTBroadcast, we set our flags like this:

myPresParamsPtr->flags = kQTSAutoModeFlag | 
            kQTSDontShowStatusFlag | kQTSSendMediaFlag

The timeScale field of the new presentation parameters structure is currently unused (as far as I can determine); in QTBroadcast, we set that field to 0.

The mediaParams field holds a pointer to a media parameters structure, of type QTSMediaParams:

struct QTSMediaParams {
   QTSVideoParams            v;
   QTSAudioParams            a;

As you can see, this structure contains a video parameters structure and an audio parameters structure (of types QTSVideoParams and QTSAudioParams respectively); these structures contain information about the video and audio media data being previewed locally — that is, the data being displayed in the monitor window and the sound played through the computer's speakers. In QTBroadcast we want to leave the audio settings at their default values, but we want to configure the video settings so that the preview draws in the correct location in the monitor window. We begin by allocating a new media parameters structure:

myMediaParamsPtr = (QTSMediaParams *)
myPresParamsPtr->mediaParams = myMediaParamsPtr;

At this point we want to call the QTSInitializeMediaParams function, which initializes the media parameters structure to some default values:

myErr = QTSInitializeMediaParams(myMediaParamsPtr);

Now let's configure the video previewing. The video parameters structure looks like this:

struct QTSVideoParams {
   Fixed                        width;
   Fixed                        height;
   MatrixRecord               matrix;
   CGrafPtr                     gWorld;
   GDHandle                     gdHandle;
   RgnHandle                  clip;
   short                        graphicsMode;
   RGBColor                     opColor;

Notice (in Figure 1, once again) that the preview images are drawn in the user item rectangle, which is 176 pixels wide and 144 pixels high and is offset from the window origin by 10 pixels vertically and horizontally. So we'll use these lines of code to place the images in the proper location:

myPresParamsPtr->mediaParams->v.width = Long2Fix(176);
myPresParamsPtr->mediaParams->v.height = Long2Fix(144);
            Long2Fix(10), Long2Fix(10));

And we'll set the port and graphics device like this:

myPresParamsPtr->mediaParams->v.gWorld = 
myPresParamsPtr->mediaParams->v.gdHandle = NULL;

Finally, the notificationProc and notificationRefCon fields of the new presentation parameters structure specify the notification procedure and a reference constant that is passed to the notification procedure.

myPresParamsPtr->notificationProc = gNotificationUPP;
myPresParamsPtr->notificationRefCon = 0L;

At long last, we are ready to call QTSNewPresentation and QTSPresPreview:

myErr = QTSNewPresentation(myPresParamsPtr, &gPresentation);
myErr = QTSPresPreview(gPresentation, kQTSAllStreams, NULL, 
            kQTSNormalForwardRate, 0);

Listing 3 gives the complete definition for QTBC_SetupPresentation.

Listing 3: Setting up a presentation

OSErr QTBC_SetupPresentation (void)
   QTSNewPresentationParams   *myPresParamsPtr = NULL;
   QTSMediaParams                  *myMediaParamsPtr = NULL;
   FSSpec                              myFSSpec;
   OSType                            myTypeList[] = {kQTFileTypeText};
   short                              myNumTypes = 1;
   QTFrameFileFilterUPP         myFileFilterUPP = NULL;
   OSErr                              myErr = noErr;

   myNumTypes = 0;

   // create a new presentation parameters structure
   myPresParamsPtr = (QTSNewPresentationParams *)
   if (myPresParamsPtr == NULL) {
      myErr = MemError();
      goto bail;

   // create a new media parameters structure
   myMediaParamsPtr = (QTSMediaParams *)
   if (myMediaParamsPtr == NULL) {
      myErr = MemError();
      goto bail;

   // initialize the media parameters to default values
   myErr = QTSInitializeMediaParams(myMediaParamsPtr);
   if (myErr != noErr)
      goto bail;

   // elicit an SDP file from the user
   myFileFilterUPP = QTFrame_GetFileFilterUPP
   myErr = QTFrame_GetOneFileWithPreview(myNumTypes, 
            (QTFrameTypeListPtr)myTypeList, &myFSSpec, 
   if (myErr != noErr)
      goto bail;

   // start broadcasting from an SDP file
   myPresParamsPtr->dataType = kQTSFileDataType;
   myPresParamsPtr->data = &myFSSpec;
   myPresParamsPtr->dataLength = sizeof(myFSSpec);

   // set the presentation flags: use Sequence Grabber, don't display blue Q movie, 
   // and send data
   myPresParamsPtr->flags = kQTSAutoModeFlag | 
            kQTSDontShowStatusFlag | kQTSSendMediaFlag;

   myPresParamsPtr->timeScale = 0;
   myPresParamsPtr->mediaParams = myMediaParamsPtr;

   // fill these in to get status notifications
   myPresParamsPtr->notificationProc = gNotificationUPP;
   myPresParamsPtr->notificationRefCon = 0L;

   // define the display size and the default transmission size
   myPresParamsPtr->mediaParams->v.width = Long2Fix(176);
   myPresParamsPtr->mediaParams->v.height = Long2Fix(144);
            Long2Fix(10), Long2Fix(10));

   // set the window that Sequence Grabber will draw into
   myPresParamsPtr->mediaParams->v.gWorld = 
   myPresParamsPtr->mediaParams->v.gdHandle = NULL;

   // create a new presentation
   myErr = QTSNewPresentation(myPresParamsPtr, 
   if (myErr != noErr)
      goto bail;
   myErr = QTSPresPreview(gPresentation, kQTSAllStreams, 
            NULL, kQTSNormalForwardRate, 0);

   if (myPresParamsPtr != NULL)

   if (myMediaParamsPtr != NULL)

   if (myFileFilterUPP != NULL)


Notice that we dispose of the new presentation parameters structure (myPresParamsPtr) and the media parameters structure (myMediaParamsPtr) before returning from QTBC_SetupPresentation. QTSNewPresentation takes care to copy all the information we pass it, including any blocks of memory referenced in the new presentation parameters structure. If we had allocated any other information (for instance, a clip region), we should also dispose of that memory too.


Now we've created a presentation and requested that the video data that is to be broadcast be previewed in the monitor window. In order for the previewing and subsequent broadcasting to proceed, we need to grant QuickTime some time to process the presentation. We do this by calling the QTSPresIdle function periodically. As usual, we'll add some code to our application's QTApp_Idle function, which is called whenever we receive a null event:

if (gPresentation != kQTSInvalidPresentation)
   QTSPresIdle(gPresentation, NULL);

This just says: if we have an active presentation, grant it some processor time.

Starting the Broadcast

So far, however, no broadcasting is happening. In QTBroadcast, we wait until the user clicks the Start button in the monitor window to begin that process. When the user clicks that button, QTBroadcast calls the QTBC_StartBroadcasting function, defined in Listing 4. (Later we'll take a look at the code that handles those button clicks.)

Listing 4: Starting broadcasting

OSErr QTBC_StartBroadcasting (void)
   // stop the preview
   QTSPresPreview(gPresentation, kQTSAllStreams, NULL, 
            kQTSStoppedRate, 0);

   return(QTSPresPreroll(gPresentation, kQTSAllStreams, 0, 
            (Fixed)kQTSNormalForwardRate, 0L));

QTBC_StartBroadcasting first calls QTSPresPreview with a rate of kQTSStoppedRate to stop previewing the data; then it calls QTSPresPreroll, which readies the media for subsequent broadcasting and performs any necessary handshaking between the transmitter (that is, the broadcasting computer) and the client computer or computers. (As you've probably guessed, prerolling a presentation with QTSPresPreroll is analogous to prerolling a movie with PrerollMovie.)

QTSPresPreroll returns fairly quickly, as some of its operations involve establishing network connections and hence should occur asynchronously. We get informed of the success of the prerolling in our presentation notification procedure, by receiving a notification message of type kQTSPrerollAckNotification. Once we receive this acknowledgement, we can then begin actually broadcasting data by calling the QTSPresStart function. Listing 5 shows our complete presentation notification procedure.

Listing 5: Handling notification messages

static PASCAL_RTN ComponentResult QTBC_NotificationProc 
            (ComponentResult theErr, OSType theNotificationType, 
               void *theNotificationParams, void *theRefCon)
#pragma unused(theErr, theNotificationParams, theRefCon)
   QTSPresentation      myPresentation = kQTSInvalidPresentation;
   ComponentResult      myErr = noErr;

   switch (theNotificationType) {

      case kQTSNewPresentationNotification:
         // when we get this notification, the presentation has been created 
         // and is sent to us in theNotificationParams;
         // if we needed it, we could retrieve it as follows:
         myPresentation = 

      case kQTSPrerollAckNotification:
         myErr = QTSPresStart(gPresentation, kQTSAllStreams, 

      case kQTSStartAckNotification:
      case kQTSStopAckNotification:



As you can see, we ignore most of the notification messages. We handle the kQTSPrerollAckNotification message, to start broadcasting once the prerolling is complete. We also handle the kQTSNewPresentationNotification message, which is sent whenever a new presentation is created; in this case, the identifier for the new presentation is passed in the theNotificationParams parameter. (We don't actually do anything with that identifier; this code is provided to illustrate how to retrieve it if you need it.)

Finally we're off and running. We've created a presentation, prerolled it, and (hopefully) received a notification that the prerolling was successful — in which case we've called QTSPresStart to start broadcasting data. Now it's up to the client to start receiving the data we're transmitting. This can happen in one of several ways. The easiest way is to provide the client with a copy of the SDP file that we used to initiate the broadcast session. If the user opens this file with a QuickTime-savvy application, then QuickTime's SDP importer is called to convert the SDP data into a movie. When the application opens that movie, QuickTime connects to the server, requests that it start sending it data, and then receives the data into a local buffer; while this buffering is happening, the user will see a connection status display like the one shown in Figure 7.

Figure 7: A client status message

The user can then save the movie into a new file; in this case, the new file is a QuickTime movie file that contains a streaming track; the media data for this track is just the text data in the original SDP file. Subsequently opening the movie file is pretty much identical to opening the SDP file.

Controlling the Broadcast

So we now see how to start broadcasting from a transmitter and how to receive the broadcast stream on a client. If we want to pause the broadcasting, we can call the QTBC_PauseBroadcasting function defined in Listing 6. This function calls QTSPresStop to stop the presentation and then QTSPresPreview with a rate of kQTSNormalForwardRate to resume previewing in the monitor window.

Listing 6: Pausing broadcasting

OSErr QTBC_PauseBroadcasting (void)
   OSErr      myErr = noErr;

   myErr = QTSPresStop(gPresentation, kQTSAllStreams, 0L);
   if (myErr != noErr)
      goto bail;

   // restart the preview
   myErr = QTSPresPreview(gPresentation, kQTSAllStreams, NULL, 
            kQTSNormalForwardRate, 0);


After pausing a broadcast by calling QTBC_PauseBroadcasting, we could later resume the broadcast by calling QTBC_StartBroadcasting once again. If we want to stop broadcasting for good (perhaps because the application is shutting down), we can call the QTBC_StopBroadcasting function defined in Listing 7. This function calls QTSPresStop to stop broadcasting and then QTSDisposePresentation to dispose of the presentation. Notice that we also set the global variable gPresentation to kQTSInvalidPresentation, so that QTSPresIdle is no longer called in QTApp_Idle.

Listing 7: Stopping broadcasting

OSErr QTBC_StopBroadcasting (void)
   OSErr      myErr = noErr;

   if (gPresentation != kQTSInvalidPresentation) {
      myErr = QTSPresStop(gPresentation, kQTSAllStreams, 0L);

      if (myErr != noErr)
         myErr = QTSDisposePresentation(gPresentation, 0L);

      gPresentation = kQTSInvalidPresentation;


Broadcast Settings

Once we've created a new presentation based on an existing SDP file, we want to allow the user to view and configure the presentation's settings. QTBroadcast provides the "Configure Settings..." menu item in its Test menu; when the user selects this item and a presentation is underway, QTBroadcast displays the Transmission Settings dialog box shown in Figure 8.

Figure 8: The Transmission Settings dialog box

This dialog box shows the source, compression algorithm, and packetizer currently being used for the audio and video streams, and also displays the current data rate for each stream. Notice that there is no way for the user to modify any of these settings, since the broadcast has already begun.

If a presentation is not underway, then when the user selects the "Configure Settings..." menu item, QTBroadcast displays the Transmission Settings dialog box shown in Figure 9.

Figure 9: The Transmission Settings dialog box (modifiable)

As you can see, the dialog box now contains some buttons that allow the user to modify various broadcast settings. For instance, if the user clicks the "Source..." button associated with the video stream, the dialog box shown in Figure 10 appears.

Figure 10: The video stream Sourcer Settings dialog box

And if the user clicks the "Packetizer..." button associated with the video stream, the dialog box shown in Figure 11 appears.

Figure 11: The video stream Packetizer dialog box

It's actually quite simple to display all these dialog boxes; indeed, we need to call only a single function, QTSPresSettingsDialog, as shown in Listing 8 (which lists the code we execute in response to the "Configure Settings..." menu item).

Listing 8: Handling the "Configure Settings..." menu item

   if (gPresentation != kQTSInvalidPresentation)
      myErr = QTSPresSettingsDialog(gPresentation, 
            kQTSAllStreams, 0, NULL, 0L);

   if (myErr != noErr)
   myIsHandled = true;

Monitor Window Control

We're just about finished learning how to use QuickTime to broadcast data across a network. We've worked with all the basic functions we need to use to create and preroll presentations, start and stop previewing, and actually start sending streams of data to a remote client. Let's finish off quickly by taking a look at the code we use to create and manage the monitor window.

We create a single monitor window at application launch time by calling the QTBC_CreateMonitorWindow function, defined in Listing 9. This function calls GetNewDialog to open a dialog box whose attributes and items are defined by a ‘DLOG' resource of ID kMonitorDLOGID.

Listing 9: Creating the monitor window

DialogPtr QTBC_CreateMonitorWindow (void)
   DialogPtr   myDialog = NULL;

   myDialog = GetNewDialog(kMonitorDLOGID, NULL, 

   if (myDialog != NULL) {
      short      myItemKind;
      Handle      myItemHandle = NULL;
      Rect         myItemRect;


      // set the user item drawing procedure
      GetDialogItem(myDialog, kMonitorUserItemID, &myItemKind, 
            &myItemHandle, &myItemRect);   
      SetDialogItem(myDialog, kMonitorUserItemID, myItemKind, 
            (Handle)gMonitorUserItemProcUPP, &myItemRect);

      QTBC_UserItemProcedure(myDialog, kMonitorUserItemID);


QTBC_CreateMonitorWindow also sets the user item procedure for the user item in the monitor window to be the function QTBC_UserItemProcedure, defined in Listing 10. This user item procedure draws a frame around the user item and also sets the state of the Start/Pause button; if no presentation is active, we want to disable the button so that it cannot be pressed.

Listing 10: Drawing the user item in the monitor window

PASCAL_RTN void QTBC_UserItemProcedure (
            DialogPtr theDialog, short theItem)
   short               myItemKind;
   Handle               myItemHandle = NULL;
   Rect                  myItemRect;
   GrafPtr            mySavedPort;
   OSErr               myErr = noErr;


   if (theItem != kMonitorUserItemID)
      goto bail;

   // draw a frame around the user item rectangle
   GetDialogItem(theDialog, kMonitorUserItemID, &myItemKind, 
            &myItemHandle, &myItemRect);
   InsetRect(&myItemRect, -1, -1);

   // enable the Start/Stop button in the monitor window
   GetDialogItem(theDialog, kMonitorButtonID, &myItemKind, 
            &myItemHandle, &myItemRect);
   if (myItemHandle != NULL) {
      if (gPresentation == kQTSInvalidPresentation)
         HiliteControl((ControlHandle)myItemHandle, 255);
         HiliteControl((ControlHandle)myItemHandle, 0);


We handle clicks on the button in the QTBC_HandleMonitorWindowEvents function (Listing 11), which is called by QTApp_HandleEvent for any events targeted at a dialog box.

Listing 11: Handling events in the monitor window

void QTBC_HandleMonitorWindowEvents 
            (DialogPtr theDialog, DialogItemIndex theItemHit)
   short         myItemKind;
   Handle         myItemHandle = NULL;
   Rect            myItemRect;

   if ((theDialog == gMonitor) && 
            (theItemHit == kMonitorButtonID)) {

      GetDialogItem(theDialog, kMonitorButtonID, &myItemKind, 
            &myItemHandle, &myItemRect);   
      if (gBroadcasting) {
      } else {

      gBroadcasting = !gBroadcasting;


The broadcasting support included in QuickTime 5 allows us to write applications that transmit data captured or stored on a local server to a client (or set of clients) located remotely on a network. It's important to remember that the streams of media data transmitted by QuickTime's broadcasting components conform to the IETF protocols (principally, RTP and RTSP) and hence can be received by any standards-compliant client application. As we've seen, QuickTime 4 provided support for receiving those kinds of streams, so we can use QuickTime APIs to develop both the transmitter and the receiver.


Thanks are due to Kevin Marks for reviewing this article and providing some comments, and to Anne Jones for providing some helpful background information.

Tim Monroe is a member of the QuickTime engineering team at Apple. You can contact him at


Community Search:
MacTech Search:

Software Updates via MacUpdate

Bookends 12.8 - Reference management and...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
Apple iTunes 12.6 - Play Apple Music and...
Apple iTunes lets you organize and stream Apple Music, download and watch video and listen to Podcasts. It can automatically download new music, app, and book purchases across all your devices and... Read more
Default Folder X 5.1.4 - Enhances Open a...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click on... Read more
Amazon Chime 4.1.5587 - Amazon-based com...
Amazon Chime is a communications service that transforms online meetings with a secure, easy-to-use application that you can trust. Amazon Chime works seamlessly across your devices so that you can... Read more
CrossOver 16.2 - Run Windows apps on you...
CrossOver can get your Windows productivity applications and PC games up and running on your Mac quickly and easily. CrossOver runs the Windows software that you need on Mac at home, in the office,... Read more
Adobe Creative Cloud - Access...
Adobe Creative Cloud costs $19.99/month for a single app, or $49.99/month for the entire suite. Introducing Adobe Creative Cloud desktop applications, including Adobe Photoshop CC and Illustrator CC... Read more
MegaSeg 6.0.2 - Professional DJ and radi...
MegaSeg is a complete solution for pro audio/video DJ mixing, radio automation, and music scheduling with rock-solid performance and an easy-to-use design. Mix with visual waveforms and Magic... Read more
Bookends 12.8 - Reference management and...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
Adobe Creative Cloud - Access...
Adobe Creative Cloud costs $19.99/month for a single app, or $49.99/month for the entire suite. Introducing Adobe Creative Cloud desktop applications, including Adobe Photoshop CC and Illustrator CC... Read more
Default Folder X 5.1.4 - Enhances Open a...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click on... Read more

The best deals on the App Store this wee...
Deals, deals, deals. We're all about a good bargain here on 148Apps, and luckily this was another fine week in App Store discounts. There's a big board game sale happening right now, and a few fine indies are still discounted through the weekend.... | Read more »
The best new games we played this week
It's been quite the week, but now that all of that business is out of the way, it's time to hunker down with some of the excellent games that were released over the past few days. There's a fair few to help you relax in your down time or if you're... | Read more »
Orphan Black: The Game (Games)
Orphan Black: The Game 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Dive into a dark and twisted puzzle-adventure that retells the pivotal events of Orphan Black. | Read more »
The Elder Scrolls: Legends is now availa...
| Read more »
Ticket to Earth beginner's guide: H...
Robot Circus launched Ticket to Earth as part of the App Store's indie games event last week. If you're not quite digging the space operatics Mass Effect: Andromeda is serving up, you'll be pleased to know that there's a surprising alternative on... | Read more »
Leap to victory in Nexx Studios new plat...
You’re always a hop, skip, and a jump away from a fiery death in Temple Jump, a new platformer-cum-endless runner from Nexx Studio. It’s out now on both iOS and Android if you’re an adventurer seeking treasure in a crumbling, pixel-laden temple. | Read more »
Failbetter Games details changes coming...
Sunless Sea, Failbetter Games' dark and gloomy sea explorer, sets sail for the iPad tomorrow. Ahead of the game's launch, Failbetter took to Twitter to discuss what will be different in the mobile version of the game. Many of the changes make... | Read more »
Splish, splash! The Pokémon GO Water Fes...
Niantic is back with a new festival for dedicated Pokémon GO collectors. The Water Festival officially kicks off today at 1 P.M. PDT and runs through March 29. Magikarp, Squirtle, Totodile, and their assorted evolved forms will be appearing at... | Read more »
Death Road to Canada (Games)
Death Road to Canada 1.0 Device: iOS Universal Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: Get it now at the low launch price! Price will go up a dollar every major update. Update news at the bottom of this... | Read more »
Bean's Quest Beginner's Guide:...
Bean's Quest is a new take on both the classic platformer and the endless runner, and it's free on the App Store for the time being. Instead of running constantly, you can't stop jumping. That adds a surprising new level of challenge to the game... | Read more »

Price Scanner via

2.6GHz Mac mini on sale for $559, $140 off MS...
Guitar Center has the 2.6GHz Mac mini (MGEN2LL/A) on sale for $559 including free shipping. Their price is $140 off MSRP, and it’s the lowest price available for this model. Read more
SSD Speeder RAM Disk SSD Life Extender App Fo...
Fehraltorf, Switzerland based B-Eng has announced they are making their SSD Speeder app for macOS publicly available for purchase on their website. SSD Speeder is a RAM disk utility that prevents... Read more
iPhone Scores Highest Overall in Smartphone D...
Customer satisfaction is much higher among smartphone owners who use their device to operate other connected home services such as smart thermostats and smart appliances, according to the J.D. Power... Read more
Swipe CRM Free Photo-Centric CRM Sales DEal C...
Swipe CRM LLC has introduced Swipe CRM: Visual Sales 1.0 for iPad, an app for creating, managing, and sharing visually stunning sales deals. Swipe CRM is targeted to small-and-medium creative... Read more
13-inch 2.0GHz Apple MacBook Pros on sale for...
B&H has the non-Touch Bar 13″ 2.0GHz MacBook Pros in stock today and on sale for $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz MacBook Pro Space Gray (... Read more
15-inch Touch Bar MacBook Pros on sale for up...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
Apple’s iPhone 6s Tops Best-Selling Smartphon...
In terms of shipments, the iPhone 6s from Apple bested all competitors for sales in 2016, according to new analysis from IHS Markit, a world leader in critical information, analytics and solutions.... Read more
Logitech Rugged Combo Protective iPad Case an...
Logitech has announced its Logitech Rugged Combo, Logitech Rugged Case, and Logitech Add-on Keyboard for Rugged Case for Apple’s new, more affordable $329 9.7-inch iPad, a complete solution designed... Read more
T-Mobile To Offer iPhone 7 and iPhone 7 Plus...
T-Mobile has announced it will offer iPhone 7 and iPhone 7 Plus (PRODUCT)RED Special Edition in a vibrant red aluminum finish. The introduction of this special edition iPhone celebrates Apple’s 10... Read more
9-inch 128GB iPad Pros on sale for $50-$70 of...
B&H Photo has 9.7″ 128GB Apple WiFi iPad Pros on sale for up to $70 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 9″ Space Gray 128GB WiFi iPad Pro: $649 $50... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Fulltime aan de slag als shopmanager in een h...
Ben jij helemaal gek van Apple -producten en vind je het helemaal super om fulltime shopmanager te zijn in een jonge en hippe elektronicazaak? Wil jij werken in Read more
Starte Dein Karriere-Abenteuer in den Hauptst...
…mehrsprachigen Teams betreust Du Kunden von bekannten globale Marken wie Apple , Mercedes, Facebook, Expedia, und vielen anderen! Funktion Du wolltest schon Read more
*Apple* Retail - Multiple Positions- Chicago...
SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Fulltime aan de slag als shopmanager in een h...
Ben jij helemaal gek van Apple -producten en vind je het helemaal super om fulltime shopmanager te zijn in een jonge en hippe elektronicazaak? Wil jij werken in Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.