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

iFFmpeg 6.4.0 - Convert multimedia files...
iFFmpeg is a comprehensive media tool to convert movie, audio and media files between formats. The FFmpeg command line instructions can be very hard to master/understand, so iFFmpeg does all the hard... Read more
Thunderbird 52.2.0 - Email client from M...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
Airfoil 5.6.1 - 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 Remote Desktop Client 3.9.3 - Clie...
Apple Remote Desktop Client is the best way to manage the Mac computers on your network. Distribute software, provide real-time online help to end users, create detailed software and hardware reports... Read more
jAlbum Pro 14.0 - Organize your digital...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. You can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly... Read more
jAlbum 14.0 - Create custom photo galler...
With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly, with pro results - Simply drag and drop photos into groups, choose a design... Read more
Vitamin-R 2.48 - Personal productivity t...
Vitamin-R creates the optimal conditions for your brain to work at its best by structuring your work into short bursts of distraction-free, highly focused activity alternating with opportunities for... Read more
Beamer 3.3 - Stream any movie file from...
Beamer streams to your Apple TV.... Plays any movie file - Just like the popular desktop movie players, Beamer accepts all common formats, codecs and resolutions. AVI, MKV, MOV, MP4, WMV, FLV. To... Read more
Shredo 1.2.2 - $9.99
Shredo is a beautiful, functional file-shredding and privacy scan utility. It permanently shreds files, folders, and external volumes' contents to keep information secure and impossible for anyone to... Read more
Final Draft 10.0.3 - Industry-leading sc...
Final Draft allows you to use your creative energy to focus on the content; let Final Draft take care of the style. Final Draft is the number-one selling application specifically designed for writing... Read more

Latest Forum Discussions

See All

Solve the disappearance of history’s gre...
Blue Brain Games invites you to indulge in an immersive hands-on 3D puzzle adventure in similar vein to The Room series, with its debut release The House of Da Vinci. Set during the historic period of the Italian Renaissance (when Leonardo himself... | Read more »
Age of Rivals (Games)
Age of Rivals 3.3 Device: iOS Universal Category: Games Price: $.99, Version: 3.3 (iTunes) Description: Deep civilization-building strategy in a fast-paced card game! | Read more »
Panthera Frontier (Games)
Panthera Frontier 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: | Read more »
Angry Birds Evolution beginner's gu...
Angry Birds changes things up a fair bit in its latest iteration, Angry Birds Evolution. The familiar sling-shot physics mechanics are still there, but the game now features team-based gameplay, RPG elements, and a new top-down view. With all of... | Read more »
Sega Forever is for the retro game fans
Sega is launching a new retro games service titled Sega Forever, in a move that's sure to delight games enthusiasts with a bit of nostalgia. Sega's releasing five classic games for free. The titles include Sonic the Hedgehog, Phantasy Star II,... | Read more »
The Little Acre (Games)
The Little Acre 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: | Read more »
Lovely adventure game 'The Little A...
The Little Acre makes its way from PC to iOS today and it's a real charmer. It's a lovely little adventure game set in 1950's Ireland, gorgeously animated in a style slightly reminiscent of old Disney films. The game won a lot of praise for its... | Read more »
Futurama: Worlds of Tomorrow officially...
Futurama: Worlds of Tomorrow arrives next Thursday, and it features . . . Stephen Hawking? Turns out a few of your favorite science super stars, including Bill Nye, Neil DeGrasse Tyson, and George Takei will be making an appearance alongside the... | Read more »
MU Origin’s new update offers exciting c...
MU Origin is kicking off the summer with style. Its latest update is a real doozy, offering up plenty of fresh content. New challenges, some extra help for newcomers, and new costumes are just a few of the things you will find in the new patch. | Read more »
Pokémon GO introduces Raid Battles and a...
If you were hoping to conquer any gyms today in Pokémon GO you're in for a bit of disappointment. Niantic has closed gyms in the game to prepare for a huge upcoming update that is going to complete change Pokémon GO's competitive elements. The... | Read more »

Price Scanner via MacPrices.net

Clearance 2016 MacBook Pros available for up...
B&H Photo has clearance 2016 13″ and 15″ MacBook Pros in stock today and on sale for up to $400 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: - 15″ 2.7GHz... Read more
Apple Ranks 9th In comScore Top 50 U.S. Digit...
comScore, Inc. has released its monthly ranking of U.S. online activity at the top digital media properties for May 2017 based on data from comScore Media Metrix Multi-Platform. * Entity has... Read more
10.5-inch iPad Pros available for up to $20 o...
B&H Photo has the new 2017 10.5″ iPad Pros available for up to $20 off MSRP including free shipping plus NY & NJ sales tax only: - 64GB iPad Pro WiFi: $649 - 256GB iPad Pro WiFi: $749 - 512GB... Read more
Three Off-The-Beaten-Track iOS Apps That Dese...
One of the great things about using iPads and iPhones is the vast selection of apps available for most anything you want or need to do. The three outlined in this article have been in my core app... Read more
Apple No. 1 Spot In Gartner Top 100 Vendors i...
Gartner, Inc. has unveiled the top global 100 vendors in IT in 2016 based on their revenue across IT (excluding communication services) and component market segments. In the Gartner Global Top 100:... Read more
Clearance iMacs available for up to $300 off...
B&H Photo has clearance 21″ and 27″ Apple iMacs available starting at $949, each including free shipping plus NY & NJ sales tax only: - 27″ 3.3GHz iMac 5K: $1999 $300 off original MSRP - 27″... Read more
1.4GHz Mac mini, refurbished, available for $...
The Apple Store has Apple Certified Refurbished 1.4GHz Mac minis available for $419. Apple’s one-year warranty is included, and shipping is free. Their price is $80 off MSRP, and it’s the lowest... Read more
Free Mixoo iOS Photo Editing App Gets Major U...
Button Software Technology has announced Mixoo 3.0, an important feature update to the company’s photo editor for iOS devices. Mixoo offers amazing ways to edit as well as decorate personal photo... Read more
FNable 2.0 Function Key Enabling Software Get...
Briksoftware has released FNable 2.0 With Touch Bar Support, a major new version of the function key enabling software now compatible with Touch Bar keyboards. FNable’s simplicity that allows users... Read more
Clearance 2016 12-inch Retina MacBooks, Apple...
Apple recently dropped prices on Certified Refurbished 2016 12″ Retina MacBooks, with models now available starting at $1019. Apple will include a standard one-year warranty with each MacBook, and... Read more

Jobs Board

Product Manager, *Apple* News - Apple Inc....
…on new product areas, many of which have great potential impact to Apple .Drives the definition of broad, complex, and high impact products for worldwide markets, Read more
Sr. Software Engineer, *Apple* Online Store...
…building high throughput, high performance, reliable, checkout & payment platform that support Apple online stores. You will be working with the latest in services Read more
Product Owner, *Apple* Communities - Apple...
…for managing and delivering a world-class community experience to Apple 's customers. Your primary responsibilities include developing internal-facing tools, Read more
*Apple* Customer Experience (ACE) Leader - A...
…management to deliver on business objectivesTraining partner store staff on Apple products, services, and merchandising guidelinesCoaching partner store staff on Read more
Pan Europe Market Development Manager %u2014...
…local artists across the region.* Building strong relationships with local Apple teams & collaborating on mutually beneficial projects.* Building strong Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.