TweetFollow Us on Twitter

State Property 2

Volume Number: 21 (2005)
Issue Number: 12
Column Tag: Programming

QuickTime Toolkit

State Property 2

by Tim Monroe

Opening QuickTime Movies using Properties

In the previous QuickTime Toolkit article ("State Property" in MacTech, November 2005), we learned how to work with the QuickTime properties functions introduced in QuickTime 6.4 and considerably expanded in QuickTime 7. We saw how to get and set movie properties using those functions, and we saw how to install a property listener so that our applications can be informed about changes to some of those movie properties. Currently, only two small sets of movie properties are gettable or settable or listenable using those functions. These are a handful of visual properties (hue, saturation, brightness, and contrast) and a smaller handful of audio properties (gain, mute, and balance). So why is the header file Movies.h chock full of identifiers for other property classes and other property types within those classes?

The answer is that those additional properties are intended for use by other functions, and in particular by the NewMovieFromProperties function, which was introduced in QuickTime 7. NewMovieFromProperties is intended as a replacement for the plethora of existing "NewMovieFrom" functions, including

NewMovie, 
NewMovieFromFile, 
NewMovieFromHandle, 
NewMovieFromDataRef, 
NewMovieFromStorageOffset, 
NewMovieFromDataFork, 
NewMovieFromDataFork64, 
NewMovieFromScrap, 
and NewMovieFromUserProc. 

The basic idea is that we first specify an array of properties that we'd like our new movie to have, and then we call NewMovieFromProperties. This allows us to open a movie that has exactly the properties we desire, without having to rely on QuickTime to establish some default set of properties that we later need to override. It also allows us to specify properties that cannot be specified using the existing functions. For instance, the constant pitch audio setting (whereby the audio pitch remains constant even when the playback rate of a movie increases or decreases, thus avoiding the infamous "chipmunk" effect when fast-forwarding through a movie) must be set at the time a movie is created, and NewMovieFromProperties is the only movie-opening function that allows us to specify a setting for that property.

In this article, we'll see how to work with NewMovieFromProperties. We'll take a look at the classes of properties that we can pass to it and see how to set movie properties not otherwise settable using the existing NewMovieFrom functions. This topic might seem vaguely familiar to you, as we touched on a very similar programming model when investigating the initWithAttributes:error: method in the QTMovie class in QTKit (see "Back to the Future, Part III" in MacTech, July 2005). In fact, initWithAttributes:error: internally calls NewMovieFromProperties, as you might easily have guessed.

Input Properties

Let's begin by taking a look at the declaration of NewMovieFromProperties. In the Movies.h file shipped with QuickTime 7, we see essentially this:

OSStatus NewMovieFromProperties (
  ItemCount                        inputPropertyCount,
  QTNewMoviePropertyElement*       inputProperties,
  ItemCount                        outputPropertyCount,
  QTNewMoviePropertyElement*       outputProperties,
  Movie *                          theMovie);

As you can see, this function takes as input an array of QTNewMoviePropertyElement structures (inputProperties) and the number of elements in that array (inputPropertyCount). These properties describe how to instantiate the movie. If successful, this function returns a QuickTime movie identifier in the location pointed to by the theMovie parameter. It may also return to the caller a different array of properties (outputProperties), which provide additional information about the newly-created movie. These output properties, for instance, may indicate whether a data reference passed in the inputProperties array was changed during the process of opening the movie. (More on output properties later.)

The QTNewMoviePropertyElement structure is defined like this:

struct QTNewMoviePropertyElement {
  QTPropertyClass               propClass;
  QTPropertyID                  propID;
  ByteCount                     propValueSize;
  QTPropertyValuePtr            propValueAddress;
  OSStatus                      propStatus;
};

The first two fields of this structure are the class and the ID of a movie property; if you have read the previous two QuickTime Toolkit articles, these items should be clear enough. The third and fourth fields indicate the size and location of the value of that property.

For input properties, the final field of the QTNewMoviePropertyElement structure, propStatus, is set by NewMovieFromProperties to a status value that indicates whether the specified property was successfully set on the new movie. In general, the value of this field will be set to 0 (noErr). But occasionally a non-zero result will be returned in that field. For example, if you mistakenly pass in a data value that is not the size that QuickTime is expecting for the class and ID you specify, the value -2184 (kQTPropertyBadValueSizeErr) may be returned in that field. Similarly, if you specify a property that cannot be set, then the value -2191 (kQTPropertyReadOnlyErr) will be returned.

The simplest possible way to call NewMovie FromProperties is to pass in no input properties and to request no output properties, like this:

err = NewMovieFromProperties(0, NULL, 0, NULL, &movie);

This is effectively the same as calling NewMovie with its flags parameter set to 0 -- not particularly useful, but sometimes necessary if you just want to create a new empty movie with all the default characteristics. We're more likely to call NewMovieFromProperties passing in a properties array that at least includes a movie location and some additional properties. Let's see how to do that.

Specifying a Movie Location

The location of a movie's data is specified by adding to the input properties array an element with the kQTPropertyClass_DataLocation class. Currently these property IDs are supported:

enum {
  kQTDataLocationPropertyID_DataReference              = 'dref',
  kQTDataLocationPropertyID_CFStringNativePath         = 'cfnp',
  kQTDataLocationPropertyID_CFStringPosixPath          = 'cfpp',
  kQTDataLocationPropertyID_CFStringHFSPath            = 'cfhp',
  kQTDataLocationPropertyID_CFStringWindowsPath        = 'cfwp',
  kQTDataLocationPropertyID_CFURL                      = 'cfur',
  kQTDataLocationPropertyID_QTDataHandler              = 'qtdh',
  kQTDataLocationPropertyID_Scrap                      = 'scrp',
  kQTDataLocationPropertyID_LegacyMovieResourceHandle  = 'rezh',
  kQTDataLocationPropertyID_MovieUserProc              = 'uspr',
  kQTDataLocationPropertyID_ResourceFork               = 'rfrk',
  kQTDataLocationPropertyID_DataFork                   = 'dfrk'
};

For example -- starting with an easy case -- we can open a new movie that uses data on the scrapbook (or Cocoa pasteboard) by using the kQTDataLocationPropertyID_Scrap ID, as shown in Listing 1.

Listing 1: Loading a movie from the scrapbook/pasteboard

QTNewMoviePropertyElement props[1] = {{0}};
Movie movie = NULL;

props[0].propClass = kQTPropertyClass_DataLocation;
props[0].propID = kQTDataLocationPropertyID_Scrap;
props[0].propValueSize = 0;
props[0].propValueAddress = NULL;

err = NewMovieFromProperties(1, props, 0, NULL, &movie);

Notice that we do not need to assign any non-zero value to the propValueAddress field, since the property ID uniquely identifies the location of the movie data. Listing 1 provides a reasonable approximation of the existing NewMovieFromScrap function.

Listing 2 shows a slightly more interesting example, which opens a movie specified by a URL, in this case a CFURL.

Listing 2: Loading a movie from a URL

QTNewMoviePropertyElement props[1] = {{0}};
Movie movie = NULL;

props[0].propClass = kQTPropertyClass_DataLocation;
props[0].propID = kQTDataLocationPropertyID_CFURL;
props[0].propValueSize = sizeof(CFURLRef);
props[0].propValueAddress = &cfurl;

err = NewMovieFromProperties(1, props, 0, NULL, &movie);

And Listing 3 shows the most general case, where the movie data location is specified by a data reference. In this case, we need to pass the address of a DataReferenceRecord, declared like this:

struct DataReferenceRecord {
  OSType              dataRefType;
  Handle              dataRef;
};

Listing 3: Loading a movie from a URL data reference

QTNewMoviePropertyElement props[1] = {{0}};
DataReferenceRecord dRefRec;
Movie movie = NULL;

dRefRec.dataRefType = URLDataHandlerSubType;
dRefRec.dataRef = url;

props[0].propClass = kQTPropertyClass_DataLocation;
props[0].propID = kQTDataLocationPropertyID_DataReference;
props[0].propValueSize = sizeof(dRefRec);
props[0].propValueAddress = &dRefRec;

err = NewMovieFromProperties(1, props, 0, NULL, &movie);

Specifying Movie Properties

So far, this should all be straightforward: for any particular movie data locator ID, we just need to set the propValueSize and propValueAddress fields appropriately. There should be at most one data locator property in the array we pass to NewMovieFromProperties. But there can also be other kinds of properties, including movie instantiation properties (whose class is kQTPropertyClass_MovieInstantiation) and new movie properties (whose class is kQTPropertyClass_NewMovieProperty). Here are the currently-defined movie instantiation input properties, which govern how QuickTime instantiates a movie:

enum {
  kQTMovieInstantiationPropertyID_DontResolveDataRefs           = 'rdrn',
  kQTMovieInstantiationPropertyID_DontAskUnresolvedDataRefs     = 'aurn',
  kQTMovieInstantiationPropertyID_DontAutoAlternates            = 'aaln',
  kQTMovieInstantiationPropertyID_DontUpdateForeBackPointers    = 'fbpn',
  kQTMovieInstantiationPropertyID_AsyncOK                       = 'asok',
  kQTMovieInstantiationPropertyID_IdleImportOK                  = 'imok',
  kQTMovieInstantiationPropertyID_DontAutoUpdateClock           = 'aucl'
};

And here are the currently defined new movie properties, which provide additional settings for a new movie:

enum {
  kQTNewMoviePropertyID_DefaultDataRef         = 'ddrf',
  kQTNewMoviePropertyID_Active                 = 'actv',        
  kQTNewMoviePropertyID_DontInteractWithUser   = 'intn'
};

These two sets of properties mirror the newMovie flags specifiable as a parameter to the NewMovie and similar functions:

enum {
  newMovieActive                       = 1 << 0,
  newMovieDontResolveDataRefs          = 1 << 1,
  newMovieDontAskUnresolvedDataRefs    = 1 << 2,
  newMovieDontAutoAlternates           = 1 << 3,
  newMovieDontUpdateForeBackPointers   = 1 << 4,
  newMovieDontAutoUpdateClock          = 1 << 5,
  newMovieAsyncOK                      = 1 << 8,
  newMovieIdleImportOK                 = 1 << 10,
  newMovieDontInteractWithUser         = 1 << 11
};

For example, to open a movie specified by a URL so that the movie data loads asynchronously and so that the resulting movie is active, we could execute the code in Listing 4.

Listing 4: Loading a movie from a URL with additional properties

QTNewMoviePropertyElement props[3] = {{0}};
DataReferenceRecord dRefRec;
Movie movie = NULL;
Boolean isActive = true;
Boolean isAsync = true;
long num = 0;

dRefRec.dataRefType = URLDataHandlerSubType;
dRefRec.dataRef = url;

props[0].propClass = kQTPropertyClass_DataLocation;
props[0].propID = kQTDataLocationPropertyID_DataReference;
props[0].propValueSize = sizeof(dRefRec);
props[0].propValueAddress = &dRefRec;
num++;

props[1].propClass = kQTPropertyClass_MovieInstantiation;
props[1].propID = kQTMovieInstantiationPropertyID_AsyncOK;
props[1].propValueSize = sizeof(isAsync);
props[1].propValueAddress = &isAsync;
num++;

props[2].propClass = kQTPropertyClass_NewMovieProperty;
props[2].propID = kQTNewMoviePropertyID_Active;
props[2].propValueSize = sizeof(isActive);
props[2].propValueAddress = &isActive;
num++;

err = NewMovieFromProperties(num, props, 0, NULL, &movie);

Output Properties

As noted earlier, NewMovieFromProperties can also return a set of properties to the caller, which indicate additional information about the newly-opened movie. Currently there are two such output properties:

kQTMovieResourceLocatorPropertyID_LegacyResID
kQTMovieResourceLocatorPropertyID_LegacyResName

These indicate the resource ID of the movie and the name of the movie resource. The resource name is generally not terribly useful, but the resource ID can be useful in determining whether the movie atom was loaded from the file's data fork (returned value is -1) or the resource fork (returned value is greater than 0), or whether there was no movie atom in the storage container (returned value is 0).

We can obtain an output property by passing in a second array of QTNewMoviePropertyElement structures, as shown in Listing 5.

Listing 5: Getting an output property

QTNewMoviePropertyElement props[3] = {{0}};
QTNewMoviePropertyElement outProps[1] = {{0}};
Movie movie = NULL;
short resID = 0;
long num = 0;

// set-up of input properties omitted

outProps[0].propClass = 
                  kQTPropertyClass_MovieResourceLocator;
outProps[0].propID = 
                  kQTMovieResourceLocatorPropertyID_LegacyResID;
outProps[0].propValueSize = sizeof(resID);
outProps[0].propValueAddress = &resID;

err = NewMovieFromProperties(num, props, 1, outProps, 
                  &movie);

On successful completion of this code, the local variable resID will contain the resource ID of the movie resource.

Conclusion

In this article, we've learned how to use the NewMovieFromProperties function introduced in QuickTime 7 as a replacement for the array of existing NewMovieFrom functions. We've seen how to specify the location of the movie data and how to set default properties on the new movie. We've also seen how to get values of certain properties back from NewMovieFromProperties.

In the next several articles, we'll continue investigating NewMovieFromProperties. In particular, we'll take a look at the properties associated with the kQTPropertyClass_Context property class, which allows us to set media context properties of a movie. We use these properties to create movies that render into a visual context (such as an OpenGL texture buffer) or to a particular audio device.


Tim Monroe is a member of the QuickTime engineering team at Apple. You can contact him at monroe@mactech.com. The views expressed here are not necessarily shared by his employer.

 
AAPL
$97.67
Apple Inc.
+1.41
MSFT
$43.63
Microsoft Corpora
+0.89
GOOG
$511.17
Google Inc.
-13.34

MacTech Search:
Community Search:

Software Updates via MacUpdate

Coda 2.5 - One-window Web development su...
Coda is a powerful Web editor that puts everything in one place. An editor. Terminal. CSS. Files. With Coda 2, we went beyond expectations. With loads of new, much-requested features, a few... Read more
Arq 4.6.1 - Online backup to Google Driv...
Arq is super-easy online backup for the Mac. Back up to your own Google Drive storage (15GB free storage), your own Amazon Glacier ($.01/GB per month storage) or S3, or any SFTP server. Arq backs up... Read more
Airfoil 4.8.10 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
Apple iMovie 10.0.6 - Edit personal vide...
With an all-new design, Apple iMovie lets you enjoy your videos like never before. Browse your clips more easily, instantly share your favorite moments, and create beautiful HD movies and Hollywood-... Read more
OnyX 2.8.8 - Maintenance and optimizatio...
OnyX is a multifunctional utility for OS X. It allows you to verify the startup disk and the structure of its System files, to run miscellaneous tasks of system maintenance, to configure the hidden... Read more
Parallels Desktop 10.1 - Run Windows app...
Parallels Desktop is simply the world's bestselling, top-rated, and most trusted solution for running Windows applications on your Mac. With Parallels Desktop for Mac, you can seamlessly run both... Read more
Apple Keynote 6.5 - Apple's present...
Apple Keynote makes it simple to create and deliver beautiful presentations. Powerful tools and dazzling effects bring your ideas to life. You can work seamlessly between Mac and iOS devices. And... Read more
OmniPlan 2.3.7 - Robust project manageme...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Flavours 1.1.16 - Create and apply theme...
Flavours is a Mac application that allow users to create, apply and share beautifully designed themes. Classy Give your Mac a gorgeous new look by applying delicious themes! Easy Unleash your... Read more
Duplicate Annihilator 5.1.0 - Find and d...
Duplicate Annihilator takes on the time-consuming task of comparing the images in your iPhoto library using effective algorithms to make sure that no duplicate escapes. Duplicate Annihilator detects... Read more

Latest Forum Discussions

See All

My Very Hungry Caterpillar (Education)
My Very Hungry Caterpillar 1.0.0 Device: iOS Universal Category: Education Price: $3.99, Version: 1.0.0 (iTunes) Description: Care for your very own Very Hungry Caterpillar! My Very Hungry Caterpillar will captivate you as he crawls... | Read more »
Dungeon Dick (Games)
Dungeon Dick 1.1 Device: iOS Universal Category: Games Price: $.99, Version: 1.1 (iTunes) Description: Dungeon Dick is a fantasy adventure where you must discover the wicked plot to destroy the lands . 'Fling' at your foes and land... | Read more »
Here’s How the Apple Watch Could Transfo...
With the Apple Watch’s generic release date of, “early 2015” hovering on the horizon, it’s only a matter of time before gamers begin to ask “What’s in it for us?” The obvious choice would be to place entire games directly on the face of the watch,... | Read more »
Republique Episode 3: Ones & Zeroes...
Republique Episode 3: Ones & Zeroes is Available Now Posted by Rob Rich on October 17th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Loot Raiders Review
Loot Raiders Review By Campbell Bird on October 17th, 2014 Our Rating: :: PRESS BUTTON, GET LOOTUniversal App - Designed for iPhone and iPad This menu-based loot game is suitable to compel those with pretty extreme loot lust.   | Read more »
Angry Birds are Crashing Puzzle & Dr...
Angry Birds are Crashing Puzzle & Dragons Next Week Posted by Rob Rich on October 17th, 2014 [ permalink ] Next week, Puzzle & Dragons is getting a little angry. Because, you know, Angry Birds. It’s a… a pun. I thought… never mind. | Read more »
Incandescence Review
Incandescence Review By Andrew Fisher on October 17th, 2014 Our Rating: :: ALL TAPPED OUTUniversal App - Designed for iPhone and iPad Incandescence promises intense tapping action, but isn’t particularly fun.   | Read more »
Lion Pig (Games)
Lion Pig 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: "Leaving aside the biology of how a pig and a lion might meet, fall in love, and create this curious cross-breed, Lion Pig is a... | Read more »
Zero Lives (Games)
Zero Lives 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Zero Lives is a puzzle game. Simple and elegant at its core but deep and captivating the more you play. Each puzzle will challenge... | Read more »
#SUPERHYPER (Games)
#SUPERHYPER 001 Device: iOS Universal Category: Games Price: $.99, Version: 001 (iTunes) Description: "This is a game that fans of challenging minimalist arcade games, not to mention pixel art, should keep an eye on" - Touch Arcade "... | Read more »

Price Scanner via MacPrices.net

Belkin Announces Full Line of Keyboards and C...
Belkin International has unveiled a new lineup of keyboard cases and accessories for Apple’s newest iPads, featuring three QODE keyboards and a collection of thin, lightweight folios for both the... Read more
Verizon offers new iPad Air 2 preorders for $...
Verizon Wireless is accepting preorders for the new iPad Air 2, cellular models, for $100 off MSRP with a 2-year service agreement: - 16GB iPad Air 2 WiFi + Cellular: $529.99 - 64GB iPad Air 2 WiFi... Read more
Price drops on refurbished Mac minis, now ava...
The Apple Store has dropped prices on Apple Certified Refurbished previous-generation Mac minis, with models now available starting at $419. Apple’s one-year warranty is included with each mini, and... Read more
Apple refurbished 2014 MacBook Airs available...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available for up to $180 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
Refurbished 2013 MacBook Pros available for u...
The Apple Store has Apple Certified Refurbished 13″ and 15″ MacBook Pros available starting at $929. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros (4GB RAM/... Read more
WaterField Designs Unveils Outback iPad Slip...
Fresh on the heels of Apple’s announcement Thursday, WaterField Designs unveils its new Outback Slip Case for the iPad Air 2 and iPad mini 3 — a custom-fitted case for the just-announced Apple iPads... Read more
Apple Introduces iPad Air 2 & iPad mini 3...
Apple on Thursday introduced iPad Air 2, slimmed down again to just 6.1 mm, and weighing less than a pound. iPad Air 2 also features an improved Retina display claimed to deliver enhanced contrast... Read more
OS X Yosemite Available Now as a Free Upgrade
Apple on Thursday announced that OS X 10.10 Yosemite is available as a free upgrade for Mac users from the Mac App Store, introducing ontinuity features that make it easy to hand off activities... Read more
Apple Pay Supporting Mobile Payments Availabl...
Apple on Thursday announced that customers can start making payments with the touch of a finger on Monday, October 20, when Apple Pay becomes available in the US. Apple Pay offers an easy, secure and... Read more
Apple drops prices on refurbished iPad Air an...
Apple has dropped prices on Apple Certified Refurbished iPad Airs and iPad mini 2s, with models now available starting at $249. Apple’s one-year warranty is included with each model, and shipping is... Read more

Jobs Board

Position Opening at *Apple* - Apple (United...
**Job Summary** At the Apple Store, you connect business professionals and entrepreneurs with the tools they need in order to put Apple solutions to work in their Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** The Apple Store is a retail environment like no other - uniquely focused on delivering amazing customer experiences. As an Expert, you introduce people Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** As businesses discover the power of Apple computers and mobile devices, it's your job - as a Solutions Engineer - to show them how to introduce these Read more
Position Opening at *Apple* - Apple (United...
…Summary** As a Specialist, you help create the energy and excitement around Apple products, providing the right solutions and getting products into customers' hands. You Read more
Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.