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
$112.65
Apple Inc.
+3.24
MSFT
$47.52
Microsoft Corpora
+1.78
GOOG
$511.10
Google Inc.
+6.21

MacTech Search:
Community Search:

Software Updates via MacUpdate

BBEdit 11.0.2 - Powerful text and HTML e...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
ExpanDrive 4.2.1 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Adobe After Effects CC 2014 13.2 - Creat...
After Effects CC 2014 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous After Effects customer). After Effects CS6 is still available... Read more
Command-C 1.1.7 - Clipboard sharing tool...
Command-C is a revolutionary app which makes easy to share your clipboard between iOS and OS X using your local WiFi network, even if the app is not currently opened. Copy anything (text, pictures,... Read more
Tidy Up 4.0.2 - Find duplicate files and...
Tidy Up is a complete duplicate finder and disk-tidiness utility. With Tidy Up you can search for duplicate files and packages by the owner application, content, type, creator, extension, time... Read more
Typinator 6.3 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
GraphicConverter 9.5 - Graphics editor w...
GraphicConverter is an all-purpose image-editing program that can import 200 different graphic-based formats, edit the image, and export it to any of 80 available file formats. The high-end editing... Read more
Toast Titanium 12.0.1 - The ultimate med...
Toast Titanium goes way beyond the very basic burning in the Mac OS and iLife software, and sets the standard for burning CDs, DVDs, and now Blu-ray discs on the Mac. Create superior sounding audio... Read more
QuickBooks 2015 16.0.2.1422 R3 - Financi...
Save 20% on QuickBooks Pro for Mac today through this special discount link QuickBooks Pro 2013 helps you manage your business easily and efficiently. Organize your finances all in one place, track... Read more
Remotix 3.0.6 - Access all your computer...
Remotix is a fast and powerful application to easily access multiple Macs (and PCs) from your own Mac. Features: Complete Apple Screen Sharing support - including Mac OS X login, clipboard... Read more

Latest Forum Discussions

See All

The Hit List — Simply Powerful Tasks, To...
The Hit List — Simply Powerful Tasks, To-Dos, Projects, & Reminders 2.0 Device: iOS iPhone Category: Productivity Price: $9.99, Version: 2.0 (iTunes) Description: >> LAUNCH SPECIAL: The Hit List 2 for iPhone is ONLY $9.99... | Read more »
Mahjong Journey Review
Mahjong Journey Review By Jennifer Allen on December 18th, 2014 Our Rating: :: STEADY MATCHINGiPad Only App - Designed for the iPad Aimed at the more laid back gamer, Mahjong Journey isn’t for everyone, but those looking for some... | Read more »
Emoji Type - custom keyboard with predic...
Emoji Type - custom keyboard with predictive emojis 0.4.0 Device: iOS iPhone Category: Utilities Price: $.99, Version: 0.4.0 (iTunes) Description: Emoji Type is custom keyboard for iOS 8 that auto suggests emojis as you type. ABOUT... | Read more »
Game of the Year 2014 – 148Apps Staff Pi...
The end of 2014 is almost here, which can only mean one thing. Okay it can mean a lot of things, but in this specific context it means Game of the Year lists! Which is why the 148Apps staff have all picked their favorites from the past year. And why... | Read more »
UponPixels Review
UponPixels Review By Jennifer Allen on December 18th, 2014 Our Rating: :: CREATIVE TYPOGRAPHYUniversal App - Designed for iPhone and iPad Add cool typography and objects to your photos with the easy to use UponPixels.   | Read more »
The Vikings are Coming! CastleStorm’s Ne...
The Vikings are Coming! CastleStorm’s New Update Adds a Survival Mode Posted by Jessica Fisher on December 18th, 2014 [ permalink ] | Read more »
Duet Display (Productivity)
Duet Display 0.3.3 Device: iOS Universal Category: Productivity Price: $9.99, Version: 0.3.3 (iTunes) Description: Duet Display allows you to use your iPad or iPhone as an extra display. Developed by a team of ex-Apple engineers,... | Read more »
Dragon Quest III Review
Dragon Quest III Review By Jennifer Allen on December 18th, 2014 Our Rating: :: DATED BUT NOT WITHOUT MERITUniversal App - Designed for iPhone and iPad A walk down memory lane isn’t foolproof for Dragon Quest III, but it has its... | Read more »
8 KEMCO JRPGs Are Just $0.99 in Celebrat...
8 KEMCO JRPGs Are Just $0.99 in Celebration of the Holidays Posted by Jessica Fisher on December 18th, 2014 [ permalink ] KEMCO has announc | Read more »
Brothers in Arms 3: Sons of War Review
Brothers in Arms 3: Sons of War Review By Jennifer Allen on December 18th, 2014 Our Rating: :: FUN BUT PUSHYUniversal App - Designed for iPhone and iPad Brothers in Arms 3: Sons of War could be great fun, but its plethora of... | Read more »

Price Scanner via MacPrices.net

Save up to $400 on MacBooks with Apple Certif...
The Apple Store has Apple Certified Refurbished 2014 MacBook Pros and MacBook Airs available for up to $400 off the cost of new models. An Apple one-year warranty is included with each model, and... Read more
Save up to $300 on Macs, $30 on iPads with Ap...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
iOS and Android OS Targeted by Man-in-the-Mid...
Cloud services security provider Akamai Technologies, Inc. has released, through the company’s Prolexic Security Engineering & Research Team (PLXsert), a new cybersecurity threat advisory. The... Read more
KMI MIDI K-Board Great Gift for Amateur &...
The K-Board is a MIDI Nano keyboard for music creation for iPad, Android, And computers; the easiest way to make music with iPads & Android tablets, and Mac, Windows, or Linux computers. Ultra-... Read more
Amazon offers 15-inch 2.2GHz Retina MacBook P...
 Amazon.com has the 15″ 2.2GHz Retina MacBook Pro on sale for $1699 including free shipping. Their price is $300 off MSRP. Stock is limited, so act now if you’re interested. Read more
Holiday sales continue: MacBook Pros for up t...
 B&H Photo has new MacBook Pros on sale for up to $300 off MSRP as part of their Holiday pricing. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1699... Read more
Holiday sale: Mac minis available for up to $...
 B&H Photo has new 2014 Mac minis on sale for up to $80 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 1.4GHz Mac mini: $459 $40 off MSRP - 2.6GHz Mac mini: $629 $70 off... Read more
Google Search App For iOS Gets A Major Makeov...
Google has given iOS users an early Christmas present with a substantial update of it’s not-very-often-upgraded Google Search app. Google Search has been my go-to tool for Web searches since it was... Read more
ShopKeep Apple Pay And Chip Card Reader Avail...
ShopKeep, a cloud-based technology provider to more than 10,000 small business owners to manage retail shops and restaurants with iPads, has released its new Apple Pay and chip card reader. This... Read more
Holiday sale! 27-inch 5K iMac for $2299, save...
 B&H Photo has the 27″ 3.5GHz 5K iMac in stock today and on sale for $2299 including free shipping plus NY sales tax only. Their price is $200 off MSRP, and it’s the lowest price available for... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.