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

Viber 11.9.1 - Send messages and make fr...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
Vallum 3.3.2 - $15.00
Vallum is a little tool that helps you monitor and block apps connections and throttle apps bandwidth. It is able to intercept connections at the application layer, and hold them while you decide... Read more
Microsoft OneNote 16.31 - Free digital n...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more
Apple Pages 8.2.1 - Apple's word pr...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices, and... Read more
Numbers 6.2.1 - Apple's spreadsheet...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
f.lux 39.9873 - Adjusts the color of you...
f.lux makes the color of your computer's display adapt to the time of day, warm at night and like sunlight during the day. Ever notice how people texting at night have that eerie blue glow? Or wake... Read more
Deeper 2.5.0 - Enable hidden features in...
Deeper is a personalization utility for macOS which allows you to enable and disable the hidden functions of the Finder, Dock, QuickTime, Safari, iTunes, login window, Spotlight, and many of Apple's... Read more
NTFS 15.5.71 - Provides full read and wr...
NTFS breaks down the barriers between Windows and macOS. Paragon NTFS effectively solves the communication problems between the Mac system and NTFS. Write, edit, copy, move, delete files on NTFS... Read more
MTR 5.3.0.0 - The Mac's oldest and...
MTR (was MacTheRipper)--the Mac's oldest and smartest DVD-backup app. MTR - the complete toolbox, not a one-trick, point-and-click extractor. MTR is intended for making fair-use, backup copies of... Read more
Keynote 9.2.1 - Apple's presentatio...
Easily create gorgeous presentations with the all-new Keynote, featuring powerful yet easy-to-use tools and dazzling effects that will make you a very hard act to follow. The Theme Chooser lets you... Read more

Latest Forum Discussions

See All

Black Desert Mobile gets an official rel...
Pearl Abyss has just announced that its highly-anticipated MMO, Black Desert Mobile, will launch globally for iOS and Android on December 11th. [Read more] | Read more »
Another Eden receives new a episode, cha...
Another Eden, WFS' popular RPG, has received another update that brings new story content to the game alongside a few new heroes to discover. [Read more] | Read more »
Overdox guide - Tips and tricks for begi...
Overdox is a clever battle royale that changes things up by adding MOBA mechanics and melee combat to the mix. This new hybrid game can be quite a bit to take in at first, so we’ve put together a list of tips to help you get a leg up on the... | Read more »
Roterra Extreme - Great Escape is a pers...
Roterra Extreme – Great Escape has been described by developers Dig-It Games as a mini-sequel to their acclaimed title Roterra: Flip the Fairytale. It continues that game's tradition of messing with which way is up, tasking you with solving... | Read more »
Hearthstone: Battlegrounds open beta lau...
Remember earlier this year when auto battlers were the latest hotness? We had Auto Chess, DOTA Underlords, Chess Rush, and more all gunning for our attention. They all had their own reasons to play, but, at least from where I'm standing, most... | Read more »
The House of Da Vinci 2 gets a new gamep...
The House of Da Vinci launched all the way back in 2017. Now, developer Blue Brain Games is gearing up to deliver a second dose of The Room-inspired puzzling. Some fresh details have now emerged, alongside the game's first official trailer. [Read... | Read more »
Shoot 'em up action awaits in Battl...
BattleBrew Productions has just introduced another entry into its award winning, barrelpunk inspired, BattleSky Brigade series. Whilst its previous title BattleSky Brigade TapTap provided fans with idle town building gameplay, this time the... | Read more »
Arcade classic R-Type Dimensions EX blas...
If you're a long time fan of shmups and have been looking for something to play lately, Tozai Games may have just released an ideal game for you on iOS. R-Type Dimensions EX brings the first R-Type and its sequel to iOS devices. [Read more] | Read more »
Intense VR first-person shooter Colonicl...
Our latest VR obsession is Colonicle, an intense VR FPS, recently released on Oculus and Google Play, courtesy of From Fake Eyes and Goboogie Games. It's a pulse-pounding multiplayer shooter which should appeal to genre fanatics and newcomers alike... | Read more »
PUBG Mobile's incoming update bring...
PUGB Mobile's newest Royale Pass season they're calling Fury of the Wasteland arrives tomorrow and with it comes a fair chunk of new content to the game. We'll be seeing a new map, weapon and even a companion system. [Read more] | Read more »

Price Scanner via MacPrices.net

New 2019 16″ MacBook Pros on sale for $100 of...
Apple Authorized Reseller Adorama has new 2019 16″ MacBook Pros on sale today for $100 off Apple’s MSRP, each including free shipping. In addition, Adorama charges sales tax for NY & NJ residents... Read more
Apple Watch Series 3 GPS models on sale for l...
Amazon has Apple Watch Series 3 GPS models on sale starting at only $179. There prices are the lowest we’ve ever seen for these models from any Apple reseller. Choose Amazon as the seller rather than... Read more
iOS Bug In Facebook News Feed Lets Device Ca...
NEWS: 11.15.19- Users of the Facebook social media platform’s mobile app running on iOS devices won’t, like, this piece of news one bit in where a bug in the News Feed gave access to the camera... Read more
16″ MacBook Pros on sale! Preorder at Amazon...
Apple’s new 16″ MacBook Pros were only introduced yesterday, but Amazon is already offering a $100 discount on preorders. Prices for the base 6-Core 16″ MacBook Pros start at $2299: – 2019 16″ 2.6GHz... Read more
Use our exclusive MacBook Price Trackers to f...
Our Apple award-winning MacBook price trackers are the best place to look for the best sales & lowest prices on new and clearance MacBook Airs and MacBook Pros–including Apple’s new 16″ MacBook... Read more
New November Verizon iPhone deal: Get an iPho...
Verizon has the 64GB iPhone Xr on sale for 50% off for a limited time, plus they will include a free $200 prepaid MasterCard and a free Amazon Echo Dot. That reduces their price for the 64GB iPhone... Read more
Apple cuts prices on clearance, refurbished 2...
Apple has clearance 2018 15″ 6-Core Touch Bar MacBook Pros, Certified Refurbished, now available starting at only $1829. Each model features a new outer case, shipping is free, and an Apple 1-year... Read more
Up to $450 price drop on clearance 15″ MacBoo...
B&H Photo has dropped prices Apple’s 2019 15″ 6-Core and 8-Core MacBook Pros by $400-$450 off original MSRP, starting at $1999, with free overnight shipping available to many addresses in the US... Read more
Here’s how to save $200 on Apple’s new 16″ Ma...
Apple has released details of their Education discount associated with the new 2019 16″ 6-Core and 8-Core MacBook Pros. Take $200 off the price of the new 8-Core model (now $2599) and $200 off the 16... Read more
Price drop! 2019 15″ 2.6GHz 6-Core MacBook Pr...
Focus Camera has dropped their price for clearance 2019 15″ 2.6GHz 6-Core Space Gray MacBook Pros by $400 to $1999 shipped. Apple’s original MSRP for this model was $2399. Focus charges sales tax for... Read more

Jobs Board

Best Buy *Apple* Computing Master - Best Bu...
**746655BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Store NUmber or Department:** 002518-Atlantic Center-Store **Job Description:** Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**744973BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000949-Rochester Hills-Store **Job Description:** Read more
AV Systems Engineer at *Apple* - Theorem, L...
Job Summary Apple Retail Technology is looking for an Audio Visual Systems Engineer to design and implement scalable, next-generation A/V solutions for Apple ?s Read more
Nurse Practitioner - Field Based (San Bernard...
Nurse Practitioner - Field Based (San Bernardino, CA, Apple Valley, Hesperia) **Location:** **United States** **New** **Requisition #:** PS30312 **Post Date:** 3 Read more
Best Buy *Apple* Computing Master - Best Bu...
**746510BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Store NUmber or Department:** 001407-Milford-Store **Job Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.