Opening a Streaming Movie

In general, opening a streaming movie is like opening any QuickTime movie. You can open a streaming movie by opening

• a movie file that contains streaming tracks

• an SDP file

• a URL

You can open a movie file that contains streaming tracks, or open an SDP file, by calling NewMovieFromFile in the usual way.

You open a movie from a URL by calling NewMovieFromDataRef with a URL data reference. The URL for a real-time streaming movie will use RTSP protocol. The following is a code sample for opening a movie from an RTSP URL:

char url[] = "rtsp://www.mycompany.com/mymovie.mov";

Handle urlDataRef;

urlDataRef = NewHandle(strlen(url) + 1);

if ( ( err = MemError()) != noErr) goto bail;

BlockMoveData(url, *urlDataRef, strlen(url) + 1);

err = NewMovieFromDataRef(&movieInfo->theMovie, newMovieActive,

    nil, urlDataRef, URLDataHandlerSubType);

DisposeHandle(urlDataRef);

It’s also possible to open a movie file from an HTTP or FTP URL, and it’s possible for that movie file to contain streaming tracks.

If you open a streaming movie from a URL or an SDP file, as shown in Figure 2-1, QuickTime will call the appropriate movie importer. If you open a movie file that contains streaming tracks, stream importers will be called.

Opening a streaming movie typically takes more time than opening a movie with purely local content. Each track in the movie on the server is transmitted as an RTP stream, so the client computer must establish a network connection with the server for each track, and often must establish a connection for RTSP control as well. This takes time, particularly if a dial-up connection must be established.

It also means that QuickTime can return connection status messages or networking errors in the process of opening a movie.

Playing A Streaming Movie

Applications that can already play QuickTime movies need to observe these cautions to play real-time streaming movies reliably:

• Open movies with high-level Movie Toolbox calls or a movie importer.

• Do not assume that the track structure of the movie you play reflects the track structure of the original movie; a streaming track can contain sound, video, text, MIDI, or all of these.

• Use a movie controller to play the movie, or use the PrePrerollMovie function to set up any streams before playing the movie.

• Display status messages returned by the movie controller.

• Be prepared to deal with network errors when your application plays a movie (see Common Streaming Error Codes).

• Be prepared for movie characteristics to change dynamically; the height, width, duration, and presence of audio or video can all change as the movie plays.

• Do not assume that the movie will begin immediately.

The following sections describe some of these factors in more detail.

Track Structure

Unlike other QuickTime movies, streaming movies consist of two distinct movie files, one on the server and the other on the client machine, that often have different track structures. You sometimes need to distinguish between the server movie and the client movie. See Figure 2-2.

The media of each track in the server movie is transmitted as a separate RTP stream. On the client side, multiple RTP streams can be combined into a single streaming track.

If you open a movie from a URL, for example, the movie importer may create a client movie that contains only a streaming ('strm') track. Unlike most other QuickTime track types, a streaming track can contain multiple media streams of different types. A streaming track in a client movie may contain the URL of a server movie with audio, video, text, and/or MIDI tracks.

The client movie file never contains audio or video media from the server movie; they are displayed and discarded. If a client movie is saved, the saved movie contains information such as the URL of the server movie and the currently-displayed movie time. The client movie can also contain local tracks and local media, but the media samples in the server movie remain on the server except when playing.

Pre-Prerolling

Before any movie is played, QuickTime needs to allocate buffers and open appropriate media handlers. This process is called prerolling the movie. Before a streaming movie can be played, additional steps need to be taken, such as establishing RTP streams between the client and the server. This setup process is called pre-prerolling. Pre-prerolling is performed automatically when a streaming movie is played using a movie controller. If your application uses movie controllers to play movies, you do not need to take any special steps to pre-preroll a streaming movie.

If you are playing movies using lower-level commands, you will need to use the PrePrerollMoviefunction to set up the network connections for a streaming movie before you can preroll or play the movie. The PrePrerollMovie function does nothing unless a movie contains streaming content, so it’s safe to call it for all movies. Here is a code sample:

    PrePrerollMovie(myMovie, 0, GetMoviePreferredRate(myMovie),

    NewMoviePrePrerollCompleteProc(MyMoviePrePrerollCompleteProc),

    (void *)0L);

PrePrerollMovie operates either synchronously or asynchronously, depending on whether you specify a completion procedure when you call it.

If called asynchronously, it returns almost immediately, even if the movie contains streaming content. This allows your application to perform other tasks while awaiting the completion of the pre-prerolling. You need to call MoviesTask periodically to grant time for the task of pre-prerolling when using it asynchronously.

When the pre-prerolling is finished, PrePrerollMovie calls the completion procedure whose address you pass in the NewMoviePrePrerollCompleteProc parameter. In the simplest case, the completion procedure will want to preroll and start the movie.

If no completion procedure is specified, PrePrerollMovie returns when the pre-preroll process is complete.

Reacting to Changes in Movie Characteristics

One feature of streamed movies is that their characteristics may change dynamically during playback. For example, when you open a movie from a URL you may not know the actual height and width of the movie, its duration, how many streams it contains, whether it has a sound track, or whether it is an audio-only movie.

QuickTime will assign default values to these characteristics if they are unknown. QuickTime can notify your application when the movie characteristics become known or are changed.

In most cases, your application will want to adjust the size of the window or pane that contains the movie to reflect such changes. You make these adjustments by implementing a movie controller action filter procedure.

To do this, you first need to indicate that you want to be informed of any changes. You do this by setting a movie playback hint:

SetMoviePlayHints(myMovie, hintsAllowDynamicResize,

        hintsAllowDynamicResize);

Changes in the movie size are announced to your filter procedure by the mcActionControllerSizeChanged selector. Changes in other movie characteristics are announced through the mcActionMovieEdited selector.

Size Changes

Whenever the size of the movie changes, the associated movie controller sends the mcActionControllerSizeChanged action to your movie controller action filter procedure. You can intercept that action and respond to it as follows:

pascal Boolean MyMCActionFilterProc (MovieController theMC, short theAction, void *theParams,

long theRefCon)

{

    Movie   myMovie = MCGetMovie(theMC);

        switch (theAction) {

            // handle window resizing

            case mcActionControllerSizeChanged:

                MyResizeWindow(myMovie);

                break;

            default:

                break;

        }

        return(false);

}

Duration Changes

The duration of a streaming movie or a streaming track may not be initially known. A track or movie whose duration is not known is assigned an indefinite duration: x7FFFFFF. If you do not treat this as a special case, a streaming movie will appear to your application as a very long movie indeed.

Once the pre-preroll process is complete, QuickTime should know the actual duration of the streams. If you set an action filter procedure and call SetMoviePlayHints, your application will be called with the mcActionMovieEdited selector when QuickTime determines the actual duration.

If the movie contains live content, it may not have a specific duration. In this case, the duration remains indefinite: x7FFFFFF. You might want to set a timeout in your code that detects the fact that QuickTime has not adjusted the duration from x7FFFFFF after a few seconds of movie play. QuickTimePlayer uses such a timeout and displays a “Live Transmission” message where the slider would be for a movie with a known duration.

Sound and Video Changes

Whether a streaming movie has sound ('ears') or is sound-only (no video) may not be initially known or may change dynamically. If you set an action filter procedure and call SetMoviePlayHints, your application will be called with the mcActionMovieEdited selector when the sound or video characteristics change.

Other Playback Considerations

Streaming movies only play back at a rate of 1. Other playback rates, such as playing backward, are not supported.

Track Header Atom

The flags field of the track header atom must be 0x000000, indicating the track is inactive, and not part of the movie, preview, or poster. Hint tracks must be marked as inactive for the movie to play locally.

The creation time, modification time, and track ID fields are set as they would be for any track.

The duration field is also the duration of the media track being hinted, expressed in movie time scale.

The layer field is not used.

The alternate group field can be used to distinguish alternate language or alternate data rate tracks in streaming movies. It is not required that all servers support this feature. It is not recommended that applications attempt to make use of this feature at this time. This field is normally set to 1.

The remaining track header fields are not used for hint tracks.

Unused fields should be set to 0 when creating hint tracks and ignored when using them.

Edits Atom

The edits atom contains an edits list atom ('elst'). Edit lists can be used for hint tracks as they can for any other track type.

The fields of the edits list atom ('elst') are used as follows:

The flags field is not used, and should be set to 0.

The numEntries field is the number of list entries. Unless the hint track has been edited, it will have either 1 or 2 entries.

Each list entry consists of a duration, a media time, and a rate.

If the track should begin playing after the movie begins, there is an “empty edit” whose duration is the amount of time that passes until the track begins playing, whose media time is -1, and whose media rate is 1. No data should be sent for this track until the number of movie time units specified by the duration field has passed.

Whether or not there is an empty edit, there will typically be one entry whose duration is the media duration in movie timescale units, whose media time is 0, and whose rate is 1.

Track Reference Atom

Each hint track refers to a media track. The hint track contains a track reference atom ('tref') that contains exactly one child atom of type 'hint'. This child atom holds the track ID of the media track. The whole track reference atom has this structure:

The Track ID field of the 'hint' atom contains the track ID of the media track being hinted. The target track ID can be found in the media track’s track header atom ('tkhd'). All media sample data should be taken from the specified media track.

There could theoretically be a list of track IDs for a hint track that hinted multiple media tracks, but the current hinter only references one media track per hint track.

Server Movies

You create a streaming movie for an RTP server by adding hint tracks to an existing movie. You do this by calling ConvertMovieToFile, which invokes a movie exporter component. This displays a standard dialog box that lets the user specify “Export Movie to Hinted Movie,” set the parameters for hinting the movie, select compressors, and specify a file name and directory for the hinted movie (see Figure 2-5).

The hinting is performed by media packetizer components. QuickTime selects an appropriate media packetizer for each track and routes each packetizer’s output through an Apple-provided packet builder to create a hint track. One hint track is created for each streamable track in the movie.

Hint tracks are quite small compared with audio or video tracks. A movie that contains hint tracks can be played from a local disk or streamed over HTTP, like any other QuickTime movie. The hint tracks are only used when streaming the movie over RTP.

As long as your application supports movie exporter components, it should be able to create hinted movies. If you want to bypass the standard dialog for user input, selecting “Export Movie to Hinted Movie” programmatically, you will need to modify your code by adding the appropriate selectors.

A hinted movie does not need to be self-contained (flattened). It can reference sample media contained in other files. But observe these cautions:

• Use file names that are transportable between the system that the movies are created on and the RTP server.

• The relative path from the movie file to the data files must not change after the movie is saved.

• The simplest way to ensure both of these is to use only lowercase letters in file names, without spaces, and to keep the media data files and the movie file in the same folder or directory.

• Hint tracks should be created as the last step in making a streaming movie. Any editing of the movie that adds or deletes sample data, including the flattening of a movie with edit lists, invalidates the hint track. If your application edits a hinted movie in a way that invalidates the hint tracks, delete the hint tracks and re-export the movie.

Hint tracks are marked as inactive so they do not interfere with local playback. If you call FlattenMovie with the flattenActiveTracksOnly flag, the hint tracks are deleted from the flattened movie.

This release of QuickTime supports RTP streaming of video, audio, text (including HREF Tracks), and MIDI. If your movie contains other media types, or features that rely on track references, you cannot currently export the entire movie to a hinted movie. You can either stream such movies over HTTP, or you can put some of the tracks into a client movie and stream the rest, as described in the section Compositing Streaming and Non-Streaming Tracks.

Client Movies

You incorporate streaming content in a client movie by adding at least one streaming track. The simplest form of client movie has only one track: a streaming track with the URL of a movie on a server.

A streaming track has a media type of kQTSStreamMediaType ('strm') and contains a single media sample: typically either an RTSP URL of a streaming movie or the SDP text describing a multicast.

The code example in Listing 2-1 shows how to create a streaming track, insert a sample description, and add a URL media sample.

Listing 2-1  Creating a streaming track with an RTSP URL

Handle dataRef;

long dataLength;

char url[] = "rtsp://myserver.bigcompany.com/mystreaming.mov";

dataRef = NewHandle(strlen(url) + 1);

BlockMoveData(url, *urlDataRef, strlen(url) + 1);

dataLength = GetHandleSize(dataRef);

newMedia = NewTrackMedia(newTrack, kQTSStreamMediaType,

        kQTSMediaTimeScale, handleDataRef, HandleDataHandlerSubType);

err = BeginMediaEdits(newMedia);

qtsDesc =

(QTSSampleDescriptionHandle)NewHandleClear(sizeof(QTSSampleDescription));

(**qtsDesc).descSize = sizeof(QTSSampleDescription);

(**qtsDesc).dataFormat = 'rtsp';

(**qtsDesc).dataRefIndex = 1;

(**qtsDesc).version = kQTSSampleDescriptionVersion;

duration = kQTSInfiniteDuration;

err = AddMediaSample(newMedia, dataRef, 0, dataLength, duration,

        (SampleDescriptionHandle)qtsDesc, 1, 0, nil);

err = EndMediaEdits(newMedia);

err = InsertMediaIntoTrack(newTrack, 0, 0, GetMediaDuration(newMedia),

        kQTSNormalForwardRate);

A streaming track in a client movie can point to a server movie containing audio, video, text, and MIDI tracks. Any or all of the tracks in the server movie can appear as a single streaming track in the client movie.

To sum up:

• A client-side streaming movie contains at least one streaming 'strm' track.

• A streaming track contains a single media sample, typically an RTSP URL that points to streaming content. It can also contain SDP information for a multicast.

• The streaming content can be a live stream or a stored movie on a streaming server.

• The movie on the server can contain any number of tracks; multiple tracks in the server movie may be represented in the client movie as a single streaming track.