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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Bid farewell to Penacony as Honkai: Star...
Penacony has been a story of twists, exciting new characters, and strong allies, and soon Honkai: Star Rail will be finishing it with a bang. Version 2.3, fittingly titled Farewell Penacony, will be launching June 19th and will feature updates to... | Read more »
HoYoverse roll out their plans for Anime...
For those who are looking to book a getaway in July, you might give some thought to Los Angeles between the 4th and 7th, which just so happens to coincide with the Anime Expo 2024. Amongst all the storied attendees is HoYoverse, who will be... | Read more »
The first rule of Brok the InvestiGator...
Mobile gamers were recently able to get their hands on BROK the InvestiGator, a point-and-click following the adventures of the titular reptile, a detective who can solve crimes through wit or brawn. If you were one that chose the latter then... | Read more »
Diablo Immortal celebrates second annive...
It has been two years since Diablo Immortal launched and despite some very valid criticism of its business model, it has done pretty well for itself. The Tempest class also gives it a lot of grace. To celebrate this anniversary, the March of the... | Read more »
Pokemon GO pulls on its jersey for a foo...
There have been a lot of jokes about this, some by me, but Pokemon Go has genuinely done a lot of good by getting people out and about.Pokemon GO Fest 2024: Madrid is fast approaching, and Niantic has set up a new area in a bit to get people to... | Read more »
Stumble Guys dials up the calamity 1000%...
Credit where it is due, Stumble Guys has had a few top-class crossovers in its’ life; Dungeons and Dragons, Rabbids and SpongeBob Squarepants to name but a few. It is such a shame, though, that all of these have now been well and truly trounced... | Read more »
You’re going to need a bigger boat as wa...
I am sure we all know that Finding Nemo quote of fish being friends and not food, however, Play Together is going in a completely opposite direction with their latest update. Introducing the Monstrous Fish, these behemoths are proving themselves... | Read more »
Supercell's hotly anticipated Squad...
If you've ever picked up a mobile, even without looking at an App storefront, you will have heard of Supercell, the massive company behind Clash of Clans, Brawl Stars, and Clash Royale. Now, the catalogue grows as Squad Busters prepares to take... | Read more »
Top Mobile Game Discounts
Every day, we pick out a curated list of the best mobile discounts on the App Store and post them here. This list won't be comprehensive, but it every game on it is recommended. Feel free to check out the coverage we did on them in the links below... | Read more »
Osseous has a bone to pick with you as t...
We recently quelled the immense threat brought about by Zemouregal and the giant dragon Vorkath in Runescape, and you might think that earnt adventurers a little break, but no. Instead, Jagex has decided it is time to face off against an equally... | Read more »

Price Scanner via MacPrices.net

Could A Smarter Siri Infused With AI (‘Apple...
FEATURE – The iPhone is already smart, but it’s about to become more intelligent. AI — short for artificial intelligence — is widely expected to be the main topic of discussion at this year’s WWDC (... Read more
Update: For WWDC, Amazon has lowered prices o...
Amazon has every configuration and color of Apple’s M3 MacBook Airs now on sale for $170-$210 off MSRP, starting at only $899 shipped, as Apple holds their annual WWDC conference this week. Their... Read more
Deal Alert! 2nd-generation Apple AirPods on s...
Amazon has 2nd generation Apple AirPods on sale right now for only $79.99 shipped. That’s $50 (38%) off Apple’s MSRP. Their price is the lowest currently available for a new set of AirPods from any... Read more
13-inch M3 MacBook Airs on sale for $150-$200...
Amazon has every configuration and color of Apple’s 13″ M3 MacBook Air on sale for $150-$200 off MSRP, now starting at only $899 shipped. Their prices are the lowest available for these Airs among... Read more
Apple is now selling 13-inch M3 MacBook Airs...
Apple has Certified Refurbished 13″ M3 MacBook Airs now in stock for $170-$230 off MSRP, Certified Refurbished. Prices start at $929. These are the cheapest M3-powered MacBooks for sale at Apple and... Read more
Amazon is offering $150-$200 discounts on 15-...
Amazon is offering a $150-$200 discount on every configuration and color of Apple’s M3-powered 15″ MacBook Airs. Prices start at $1149 for models with 8GB of RAM and 256GB of storage: – 15″ M3... Read more
Apple is now selling 15-inch M3 MacBook Airs...
Apple has Certified Refurbished 15″ M3 MacBook Airs in stock today starting at only $1099 and ranging up to $260 off MSRP. These are the cheapest M3-powered 15″ MacBook Airs for sale today at Apple.... Read more
13-inch M3 MacBook Air prices drop to record...
B&H Photo is offering discounts on new 13-inch M3 MacBook Airs ranging up to $200 off MSRP ahead of Apple’s WWDC conference next week. Prices start at only $899! These are the lowest prices... Read more
Apple HomePods on rare sale for $20-$30 off M...
Best Buy is offering a $20-$30 discount on Apple HomePods this weekend on their online store. The HomePod mini is on sale for $79.99, $20 off MSRP, while Best Buy has the full-size HomePod on sale... Read more
Base 14-inch M3 MacBook Pro on sale for $1399...
Amazon and B&H Photo both have the base 14″ M3 MacBook Pro on sale for $200 off Apple’s MSRP, only $1399. Shipping is free at both retailers (free 1-2 day shipping at B&H): – 14″ M3 MacBook... Read more

Jobs Board

*Apple* Systems Administrator - JAMF - Activ...
…**Public Trust/Other Required:** None **Job Family:** Systems Administration **Skills:** Apple Platforms,Computer Servers,Jamf Pro **Experience:** 3 + years of Read more
*Apple* Systems Administrator - JAMF - Activ...
…**Public Trust/Other Required:** None **Job Family:** Systems Administration **Skills:** Apple Platforms,Computer Servers,Jamf Pro **Experience:** 3 + years of Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Armed Security Officer - *Apple* Store - NA...
…provide services in which the client's health, safety, and security is our #1 priority. The Apple Store is located on the 2 nd floor of the 5 th Avenue Mall. Read more
Liquor Stock Clerk - S. *Apple* St. - Idaho...
Liquor Stock Clerk - S. Apple St. Boise Posting Begin Date: 2023/10/10 Posting End Date: 2024/10/14 Category: Retail Sub Category: Customer Service Work Type: Part Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.