Summary of Features

The Fifth Generation iPods (firmware 1.2 or later) supports the playback of .m4v files containing H.264 video encoded using one of two profiles; 320x240 Baseline profile (up to Level 1.3) with AAC-LC audio and 640x480 Low-Complexity version of the H.264 Baseline Profile with AAC-LC audio.

The iPod exporter is capable of producing .m4v files conforming to these profiles as shown in Tables 2 and 3.

The Low-Complexity version of the H.264 Baseline Profile has been defined by Apple for the iPod.

What defines the output result of an export operation using the iPod exporter are properties of the source movie passed to the exporter. Most important of these is the movie size as returned by the GetMovieBox API, or the QTMovie -attributeForKey: method using the QTMovieCurrentSizeAttribute key.

Depending on the source movie image size, the iPod export component will either produce a Low-Complexity version of the H.264 Baseline Profile .m4v file (see Table 2), or the Baseline profile .m4v file (see Table 3).

Developers adding export support for the iPod may expect to have specific output profile options presented in a configurable export dialog. It is important to note however that the iPod export component does NOT provide any user or developer configurable options.

A movie's composition and size may differ depending on the selected aperture mode. For example, if Clean Aperture mode is selected, a 4:3 DV NTSC track appears as 640x480 and a 16:9 DV NTSC track appears as 853x480. Because the represented size of a movie may differ depending on aperture mode, the output produced by the iPod exporter may also differ.

Movie Size

The iPod export component determines which profile will be used to produce the output .m4v file by inspecting the source movie's image size.

The destination movie's image size and profile is determined as shown in Table 4.

Frame Rate

The output frame rate is determined by the source movie's frame rate, limited to 30 fps using adaptive frame sampling.

Data Rate

With the destination movie size being variable, the target data rate is calculated based on the effective destination movie image size (this is the movie image size after any scaling has been applied if required).

Output data rates are as follows:

• If the effective movie image size is smaller than or equal to QVGA (320x240) the data rate is 700 kbps.

• If the effective movie image size is larger than HVGA (640x240) the data rate is 1.5 Mbps (1500 kbps).

• If the effective movie image size is in between the above two sizes, data rate is interpolated between the two end points using the formula: DR = { (nMC * 8 ) / 3 } - 100 where DR is the data rate in kbps and nMC is the number of macroblocks in the image.

The comparison of movie image sizes is done in terms of the number of macroblocks in the movie image.

Code Example

Listing 1 demonstrates one use of the iPod export component and will produce a Baseline profile .m4v file that will fit within 320x240. This is done by changing the source movie box appropriately regardless of the input movie size before passing it to the export component. Applications may want to perform an operation such as this to specifically produce a Baseline profile .m4v file from larger source media while still maintaining correct aspect ratio.

The results of using the code in Listing 1 to export a 16:9 DV NTSC 720x480 clip are shown in Figure 1 (using clean aperture mode) and Figure 2 (using classic aperture mode).

GetMovieBox will return 853x480 and we set the wanted size to 320x180.

GetMovieBox will return 720x480 and we set the wanted size to 320x213.

Listing 2 contains utility functions called by Listing 1.

Listing 1  Using the iPod export component.

// Export using the iPod export component

// In this function we specifically set the movie box to fit 320x240 regardless

// of the input movie size - this is a good demonstration as the results are

// readily apparent with 16:9 DV media

OSStatus ExportiPodMovieToDesktop(Movie inMovie, Boolean inUseCleanApertureMode)

{

    // component description for the iPod exporter

    ComponentDescription cd = { MovieExportType,         // type 'spit'

                                'M4V ',                  // iPod export component

                                kAppleManufacturer,      // 'appl'

                                0,                       // any flags

                                kAnyComponentFlagsMask };

    Component aComponent = 0;

    MovieExportComponent theExportComponent = 0;

    Handle dataRef = NULL;

    OSType dataRefType = 0;

    OSType savedApertureMode = 0;

    Rect savedMovieBox = { 0 };

    OSStatus status = paramErr;

    if (NULL == inMovie) return status;

    // create a data reference for the output file

    status = QTNewDataReferenceFromFullPathCFString(

                                                CFSTR("/Volumes/MacOSX/Users/ed/Desktop/iPodMovie.m4v"),

                                                kQTNativeDefaultPathStyle,

                                                0,

                                                &dataRef,

                                                &dataRefType);

    if (status) goto bail;

    // set the aperture mode to clean -- this may change the size of the movie box

    // therefore we do this before anything else

    if (true == inUseCleanApertureMode) {

        status = SetMovieCleanApertureMode(inMovie, &savedApertureMode);

        if (status) goto bail;

    }

    // save the original movie size because we're going to mess with it

    GetMovieBox(inMovie, &savedMovieBox);

    if (status = GetMoviesError()) goto bail;

    // find the exporter -- note OpenADefaultComponent may also be an option

    aComponent = FindNextComponent(aComponent, &cd);

    if (0 == aComponent) { status = badComponentType; goto bail; };

    // open it

    status = OpenAComponent(aComponent, &theExportComponent);

    if (status) goto bail;

    // call our routine to set the movie box so the exporter will produce

    // the results we want - in this case up to 320x240 Baseline

    SetExportMovieBox(inMovie, 320, 240);

    // export to .m4v

    status = MovieExportToDataRef(theExportComponent,           // export component instance

                                  dataRef,                      // destination data reference

                                  dataRefType,                  // destination data reference type

                                  inMovie,                      // movie to export

                                  0,                            // export specific track?

                                  0,                            // start time

                                  GetMovieDuration(inMovie)); // duration

    // restore the saved movie box

    SetMovieBox(inMovie, &savedMovieBox);

bail:

    // restore original aperture mode

    if (savedApertureMode) {

        QTSetMovieProperty(inMovie,

                           kQTPropertyClass_Visual,

                           kQTVisualPropertyID_ApertureMode,

                           sizeof(savedApertureMode),

                           &savedApertureMode);

    }

    // dispose the data reference handle when you're done with it

    if (dataRef) DisposeHandle(dataRef);

    // always remember to close the component when you're done

    if (theExportComponent) CloseComponent(theExportComponent);

    return status;

}

Listing 2  Functions used by listing 1.

// Set the movie aperture mode to Clean. In this mode,

// if possible, the video will be displayed at the correct

// pixel aspect ratio, trimmed to the clean aperture

// For example, 4:3 DV media will display at 640x480 instead of 720x480

OSErr SetMovieCleanApertureMode(Movie inMovie, OSTypePtr outSavedApertureMode)

{

    OSType mode = kQTApertureMode_CleanAperture;

    Boolean hasApertureModeDimensions = false;

    OSErr err;

    // does the movie have aperture mode dimensions?

    err = QTGetMovieProperty(inMovie,

                             kQTPropertyClass_Visual,

                             kQTVisualPropertyID_HasApertureModeDimensions,

                             sizeof(hasApertureModeDimensions),

                             &hasApertureModeDimensions,

                             NULL);

    if (noErr == err) {

        if (false == hasApertureModeDimensions) {

            // update the movie to support aperture modes

            err = GenerateMovieApertureModeDimensions(inMovie);

        }

        if (noErr == err) {

            // return the original mode

            err = QTGetMovieProperty(inMovie,

                                     kQTPropertyClass_Visual,

                                     kQTVisualPropertyID_ApertureMode,

                                     sizeof(OSType),

                                     outSavedApertureMode,

                                     NULL);

            if (noErr == err) {

                // set the aperture mode property on a movie to indicate we want

                // aspect ratio and clean aperture dimensions

                err = QTSetMovieProperty(inMovie,

                                         kQTPropertyClass_Visual,

                                         kQTVisualPropertyID_ApertureMode,

                                         sizeof(mode),

                                         &mode);

            }

        }

    }

    return err;

}

static void SetExportMovieBox(Movie inMovie, float inWantedWidth, float inWantedHeight)

{

    Rect movieRect;

    float movieRatio, wantedRatio;

    float movieWidth, movieHeight;

    float newWidth, newHeight;

    // get the current movie box

    GetMovieBox(inMovie, &movieRect);

    // normalize movie box

    MacOffsetRect(&movieRect, -movieRect.left, -movieRect.top);

    // get the sizes

    movieWidth = movieRect.right;

    movieHeight = movieRect.bottom;

    // some simple sanity checking - requesting > 640x480 doesn't make sense

    // in cases where the movie is larger than 640 wide or 480 high

    // the iPod exporter will scale the movie to fit in 640x480 while

    // preserving aspect ratio - so don't do extra work

    if ((movieWidth >= 640 && inWantedWidth >= 640) ||

        (movieHeight >= 480 && inWantedHeight >= 480)) return;

    /** calculate a new rect so that the movie fits into the wanted rect while retaining its aspect ratio */

    movieRatio = movieWidth / movieHeight;

    wantedRatio = inWantedWidth / inWantedHeight;

    if (movieRatio > wantedRatio) {

        newHeight = (inWantedWidth * movieHeight) / movieWidth;

        newWidth = inWantedWidth;

    } else {

        newWidth = (inWantedHeight * movieWidth) / movieHeight;

        newHeight = inWantedHeight;

    }

    // set the new movie box

    MacSetRect(&movieRect, 0, 0, newWidth, newHeight);

    SetMovieBox(inMovie, &movieRect);

}

Therefore, it is important to take this into consideration when searching for and using this component. If you are currently using MovieExportFromProceduresToDataRef as your means of export, you will need to first produce an intermediate movie file then call ConvertMovieToDataRef or MovieExportToDataRef to produce the final .m4v.

Summary of Features

Apple TV has the ability to playback Main Profile (up to Level 3.1) H.264 progressive video with B-Frames up to 1280x720 (720p) at 24 fps and AAC-LC encoded stereo audio with a maximum sampling rate of 44.1kHz.

The Apple TV exporter is capable of producing .m4v files with the specifications listed in Table 6.

*Maximum  spikes may be as high as 12 Mbps.

**Maximum frame rate for 1280x720 content is 24 fps.

What defines the output result of an export operation using the Apple TV exporter are properties of the source movie passed to the component. Most important of these is the frame rate and movie size as returned by the GetMovieBox API, or the QTMovie -attributeForKey: method using the QTMovieCurrentSizeAttribute key.

The Apple TV export component will produce an .m4v file at the appropriate size and profile level depending on the source movie image size and frame rate.

Developers adding export support for the Apple TV may expect to have specific output options presented in a configurable export dialog. It is important to note however that Apple TV export component does NOT provide any user or developer configurable options.

Movie Size

The destination movie image size is determined by the source movie image size as well as the source movie frame rate as shown in Table 7. The maximum dimensions produced are 1280x720 at 24 fps and 960x540 at 30 fps.

Frame Rate

Destination frame rate is determined by source movie frame rate as well as source movie image size. The exporter will always favour maintaining frame rate, therefore if the source movie frame rate is less than or equal to 30 it is not modified (this may however cause the destination movie image size to change, for example a 1280x720 29.97 fps source movie will produce a 960x540 29.97 fps destination movie).

Data Rate

The data rate is restricted to a maximum of 5 Mbps (5000 kbps) and will vary depending on the source. It is based on the effective destination movie image size (this is the movie image size after any scaling has been applied if required) linearly interpolated between the defined movie sizes as shown in Table 8.

Additionally, within an encoded movie the data rate may spike up to a maximum of 12 Mbps.

Code Example

Listing 3 demonstrates standard use of the Apple TV export component making sure the source movie has been set to clean aperture mode before export.

Listing 3  Using the Apple TV export component.

// Simple export to ATV making sure original source movie is using clean aperture dimensions

OSStatus ExportATVMovieToDesktop(Movie inMovie, Boolean inUseCleanApertureMode)

{

    MovieExportComponent theExportComponent = 0;

    Handle dataRef = NULL;;

    OSType dataRefType = 0;

    OSType savedApertureMode = kQTApertureMode_Classic;

    OSStatus status = paramErr;

    if (NULL == inMovie) return status;

    // create a data reference for the output file

    status = QTNewDataReferenceFromFullPathCFString(

                                                CFSTR("/Volumes/MacOSX/Users/ed/Desktop/ATVMovie.m4v"),

                                                kQTNativeDefaultPathStyle,

                                                0,

                                                &dataRef,

                                                &dataRefType);

    if (status) goto bail;

    // find and open the ATV export component

    status = OpenADefaultComponent(MovieExportType, 'M4VH', &theExportComponent);

    if (status) goto bail;

    // set the aperture mode to clean -- this may change the size of the movie box

    // therefore we do this before anything else

    if (true == inUseCleanApertureMode) {

        status = SetMovieCleanApertureMode(inMovie, &savedApertureMode);

        if (status) goto bail;

    }

    // export to .m4v

    status = MovieExportToDataRef(theExportComponent,           // export component instance

                                  dataRef,                      // destination data reference

                                  dataRefType,                  // destination data reference type

                                  inMovie,                      // movie to export

                                  0,                            // export specific track?

                                  0,                            // start time

                                  GetMovieDuration(inMovie)); // duration

    // restore original aperture mode

    if (true == inUseCleanApertureMode) {

        QTSetMovieProperty(inMovie,

                           kQTPropertyClass_Visual,

                           kQTVisualPropertyID_ApertureMode,

                           sizeof(savedApertureMode),

                           &savedApertureMode);

    }

bail:

    // always remember to close the component when you're done

    if (theExportComponent) CloseComponent(theExportComponent);

    // dispose the data reference handle when you're done with it

    if (dataRef) DisposeHandle(dataRef);

    return status;

}

Therefore, it is important to take this into consideration when searching for and using this component. If you are currently using MovieExportFromProceduresToDataRef as your means of export, you will need to first produce an intermediate movie file then call ConvertMovieToDataRef or MovieExportToDataRef to produce the final .m4v.

Summary of Features

iPhone has the ability to playback H.264 Baseline Profile (up to Level 3.0) video, up to 640x480 at 30 fps and AAC-LC encoded stereo audio with a maximum sampling rate of 48kHz. iPhone will also play movies or audio files that can play on an iPod. Note that B frames are not supported in the Baseline profile.

The iPhone exporter is capable of producing .m4v files for local playback or WiFi playback where the total data rate is approximately 1 Mbps. The generated file specifications are shown in Table 10.

What defines the output result of an export operation using the iPhone exporter are properties of the source movie passed to the component. Most important of these is the movie size as returned by the GetMovieBox API, or the QTMovie -attributeForKey: method using the QTMovieCurrentSizeAttribute key. The iPhone export component will produce an .m4v file at the appropriate size and profile level depending on the source movie image size.

Developers adding export support for the iPhone may expect to have specific output options presented in a configurable export dialog. It is important to note however that iPhone export component does NOT provide any user or developer configurable options.

Therefore, it is important to take this into consideration when searching for and using this component. If you are currently using MovieExportFromProceduresToDataRef as your means of export, you will need to first produce an intermediate movie file then call ConvertMovieToDataRef or MovieExportToDataRef to produce the final .m4v.

Movie Size

The iPhone export component determines which profile will be used to produce the output .m4v file by inspecting the source movie's image size.

The destination movie's image size and profile is determined as shown in Table 11.

Frame Rate

The output frame rate is determined by the source movie's frame rate, limited to 30 fps using adaptive frame sampling.

Data Rate

With the destination movie size being variable, the target video data rate is calculated based on the effective destination movie image size (this is the movie image size after any scaling has been applied if required).

Output data rates are as follows:

• If the effective movie image size is smaller than or equal to 320x240 the data rate is 700 kbps.

• If the effective movie image size is larger 480x360 the data rate is 900 kbps.

• If the effective movie image size is in between the above two sizes, the data rate is linearly interpolated between the two end points.

The comparison of movie image sizes is done in terms of the number of macroblocks in the movie image.

Code Example

Listing 4 demonstrates how easy it is to use QTKit to create content for the iPhone.

Listing 4  Using QTKit to export to iPhone.

- (void)exportMovieToiPhone:(NSString *)inFile

{

    NSError *error = nil;

    // create the attributes dictionary for movieWithAttributes

    NSDictionary *attrs = [NSDictionary dictionaryWithObjectsAndKeys:

                              (id)inFile,                    QTMovieFileNameAttribute,

                              [NSNumber numberWithBool:NO],  QTMovieOpenAsyncOKAttribute,

                              QTMovieApertureModeClean,      QTMovieApertureModeAttribute,

                              [NSNumber numberWithBool:YES], QTMovieIsActiveAttribute,

                              nil];

    // create a QTMovie from the file

    QTMovie *aMovie = [QTMovie movieWithAttributes:attrs error:&error];

    if (aMovie && nil == error) {

        // do export

        //'M4VP' is the FourCC for the iPhone export component

        NSDictionary *dictionary = [NSDictionary dictionaryWithObjectsAndKeys:

                                      [NSNumber numberWithBool:YES],    QTMovieExport,

                                      [NSNumber numberWithLong:'M4VP'], QTMovieExportType,

                                      nil];

        // export the movie using the specified exporter

        BOOL status = [aMovie writeToFile:@"/Users/Shared/myiPhoneMovie.m4v" withAttributes:dictionary];

        if (NO == status) {

            // something didn't go right during the export process

            NSLog(@"%@ encountered a problem when exporting.\n", [inFile lastPathComponent]);

        }

    } else {

        // couldn't open the movie

        NSAlert *alert = [NSAlert alertWithError:error];

        [alert runModal];

    }

}

Summary of Features

iPhone has the ability to playback H.264 Baseline Profile (up to Level 3.0) video, up to 640x480 at 30 fps and AAC-LC encoded stereo audio with a maximum sampling rate of 48kHz. iPhone will also play movies or audio files that can play on an iPod. Note that B frames are not supported in the Baseline profile.

The iPhone (Cellular) export component produces .3gp files playable through the EDGE/3G network (via progressive download) where the total data rate is 80kbps. The generated file specifications are listed in Table 13.

What defines the output result of an export operation using the iPhone (Cellular) exporter are properties of the source movie passed to the component. Most important of these is the movie size as returned by the GetMovieBox API, or the QTMovie -attributeForKey: method using the QTMovieCurrentSizeAttribute key. The iPhone (Cellular) component will produce .3gp files at the appropriate size depending on the source movie image size.

Developers adding export support for the iPhone and using the iPhone (Cellular) exporter may expect to have specific output options presented in a configurable export dialog. It is important to note however that iPhone (Cellular) export component does NOT provide any user or developer configurable options.

Therefore, it is important to take this into consideration when searching for and using this component. If you are currently using MovieExportFromProceduresToDataRef as your means of export, you will need to first produce an intermediate movie file then call ConvertMovieToDataRef or MovieExportToDataRef to produce the final .3gp.

Movie Size

The iPhone (Cellular) export component determines output image size by inspecting the source movie's image size and always attempts to fit within 176x144 preserving aspect ratio.

The destination movie's image size is determined as shown in Table 14.

Frame Rate

The output frame rate is always 15 fps regardless of the source frame rate.

Data Rate

The target video data rate is always 56 Kbps and as the movie size is almost always 176x144 no data rate interpolation is performed.