TweetFollow Us on Twitter

September 93 - SOMEWHERE IN QUICKTIME

SOMEWHERE IN QUICKTIME

DYNAMIC CUSTOMIZATION OF COMPONENTS

BILL GUSCHWAN

[IMAGE 084-088_QuickTime_rev1.GIF]

QuickTime's component architecture lets you do a number of amazing and useful things by customizing components, which you can do by deriving one component based on another. Because QuickTime components are dynamically linked, preexisting applications can take advantage of a new, derived component without recompiling or rebooting. And because QuickTime is an extension of system software, the derived component will provide systemwide functionality.

In this column I'll describe how to use object-oriented techniques to customize components using a derived component. To illustrate, I'll show you how to customize the Apple text media handler to "speak" text tracks in movies using Apple's new Text-to-Speech Manager. You'll find the derived component on this issue's CD, along with a generic derived component that you can use as a basis for doing your own customizing. I've also supplied an application to help you debug your component. This application uses the debugging technique of registering the code inline. It's very basic and simply plays back a movie, but it gives you access to the full debugging environment of THINK C.

ABOUT THOSE OBJECT-ORIENTED TECHNIQUES
As any MacApp or class library programmer knows, there are three main steps to adding or altering functionality in an object-oriented program:

  1. Identify the class responsible for the behavior you want to alter.
  2. Identify the specific methods you need to add or override.
  3. Create a new class derived from the original class and implement the new methods or enhance the inherited methods.

Because components can be overridden much like C++ classes, these object-oriented techniques can be applied to customizing components. (For a more in-depth comparison of components and C++ classes, see the "Be Our Guest" column indevelop Issue 12.)

So, the three steps to customizing components are:

  1. Identify the component to use as a starting point.
  2. Identify the routines in the component to override.
  3. Create a derived component.

Before we get into a discussion of these steps, let's drop back and look at the nuts and bolts of QuickTime component architecture with its dynamic linking capabilities. This should give you a clearer idea of how it's possible to alter QuickTime's behavior at run time.

DYNAMIC LINKING OF COMPONENTS
The QuickTime movie file format depends on the dynamic linking capabilities of the Component Manager. To play a QuickTime movie, you need more than just the movie data (video frames, digitized audio samples, text, and such): you also need a time source, code to read/write the data, and code to act on or interpret the data. It would be impractical to store all this information in each and every QuickTime movie. Instead, the time source and code are dynamically linked in as components, while the movie data remains in a QuickTime movie file.

When a movie is opened in an application like MoviePlayer, the movie file is opened first, followed by a NewMovieXXX call (such as NewMovieFromFile). The major purpose of the NewMovieXXX call is to dynamically link to all the components listed in the movie resource and return a handle to this "new" data structure.

When a NewMovieXXX call is made, QuickTime invokes the Component Manager to load the handlers described in the media. A clock component is loaded first (type 'clok', subtype 'micr'). Then the media handler for each track is brought in (type 'mhlr'). If you have video and sound, for example, video and sound media handlers are loaded (subtypes 'vide' and 'soun', respectively).

You may notice that the media handlers open other media handlers to do chores for them. The video and sound media handlers open the standard media handler (type 'mhlr', subtype 'mhlr'), which is a private, high-throughput media handler. The text media handler, though, opens the base media handler (type 'mhlr', subtype 'gnrc'). The base media handler is a public, general-purpose media handler with a lower throughput that is nevertheless fast enough for text.

Next a data handler is loaded. Note that at present there's only one kind of data handler (type 'dhlr', subtype 'alis') supporting streams of data from HFS files. If necessary, a decompressor component is loaded for video; its type depends on the compression format.

Thus, a media handler and a data handler are loaded for each track. QuickTime movies use data handlers and media handlers to load, interpret, and manage the movie data. The alias data handler is responsible for opening and closing data files and for reading and writing sample data. It doesn't understand the format of the data but merely hands off the data to the media handler to interpret.

The media handler is the component that's responsible for interpreting data retrieved from the data handler and for scheduling the rendering of this data at the correct time during movie playback. For example, the text media handler interprets text samples and renders the text track in the movie based on the current time value of the movie. The media handler interfaces with the data handler using file offsets and with the rest of QuickTime through a time value. Thus, a major media handler chore is to convert time values into file offsets.

You now know how and why a QuickTime movie dynamically links with its media handlers. With that background on QuickTime component architecture behind us, we now embark on the process of customizing the text media handler to speak its text.

IN SEARCH OF A BASE COMPONENT
The first step in customizing a component is to identify the base component -- the component to start with.

Not all components can be customized. There are two requirements. First, the component must implement the target request; that is, it must allow another component instance to intercept all its messages. To determine whether a particular component instance implements the target request, you can use the call

ComponentFunctionImplemented(myComponentInstance,
    kComponentTargetSelect) 
The second requirement is that a component must have a public API before it can be inherited from. When a component is called, it's passed the routine's selector in the ComponentParameters structure. The component parses this selector and jumps to the appropriate function. If there's no public API, you can't know the parameters and behavior of any of the component's routines and thus can't override them. The interface file QuickTimeComponent.h contains the APIs for all public QuickTime components.

To speak text as it streams by, we'll want to customize the Apple text media handler, which both implements the target request and has a public API. The Apple text media handler itself is a derived media handler that uses the services of the base media handler supplied by Apple. Consequently, its interface is defined in the MediaHandlers.h file. (For more on the intricacies of derived media handlers, see the "Somewhere in QuickTime" column indevelop Issue 14.)

IN SEARCH OF THE ROUTINES TO OVERRIDE
Our next step is to find the routines to override. In our example, one routine we need to override is the routine in the Apple text media handler where the text is rendered. In addition to rendering the text, we want to grab the text and speak it.

A media handler is normally called in response to a MoviesTask call. MoviesTask is the QuickTime workhorse routine that gives time to the media handler to get the data and render it. In turn, MoviesTask calls the MediaIdle routine to do the bulk of the processing in a media handler. MediaIdle is the main routine in MediaHandlers.h. Thus, MediaIdle is the main routine we want to override. Additionally, we'll need to override the MediaInitialize routine, which supplies us with an initial reference to the media.

CREATING A DERIVED COMPONENT
So far we've chosen a base component from which to derive our customized component, and we've identified the routines we want to override. Now we're ready to take the third step of writing a new component that targets the base component and overrides the identified routines. If you're curious about the design of the generic derived component, you can investigate it on the CD. I'm only going to point out a couple of things about its design before moving on to discuss what you need to do to make your own derived component.

To capture or not to capture. You have two possible approaches when deriving a component. First, you can simply open and target a component, which lets your component use the services of that component. The component is still available to other clients, but you're using an instance of it. Second, in addition to targeting the component, you can capture it. The base component will then be replaced by your component in the component registration list and will no longer be available to clients (although current connections are retained). The CaptureComponent routine returns a special ID so that the captured component can still be used by your component.

We'll use CaptureComponent because we want to replace the functionality of all instances of the text media handler (conceptually, you can think of capturing as patching). However, targeting without capturing is just as effective -- and it has a few advantages: it doesn't require you to keep track of the captured component's ID, and it allows clients looking for a specific component to be successful.

Let's walk through the steps you'd take to make your own derived component using the generic code on this issue's CD, which are the same steps used to create our text-speaking example. You need to make changes in specific places: the component resource, the global data file, the OpenComponent routine, and the override routines.

Changing the component resource. The first thing to change is the resource file for the component. The essential part of this file is the component description, which is a structure that describes the component type, subtype, manufacturer, and flags. The Component Manager looks at this information when it's handling an application's request for a component. You want the right information here so that QuickTime will grab your derived component instead of the base component.

You should change the component type and subtype to match those of the component you're inheriting from. In our example, when a QuickTime movie with a text track is opened, QuickTime asks the Component Manager for a text media handler, which has type 'mhlr' and subtype 'text'. Since we want QuickTime to grab our derived component instead, we need to make its type and subtype the same.

In our case, we have to change the component manufacturer to match that of the base component as well. This isn't the ideal situation, because it would be most desirable for each component to have a unique manufacturer. But clients may look for a component of a specific manufacturer and won't grab your derived component if its manufacturer is different. Because it would be better to be able to identify a derived component, it's strongly suggested that component clients always perform a default search, avoiding asking for specifics other than type and subtype.

You may also need to set the componentFlags field, which identifies specific functionality for a component. For example, video digitizers use componentFlags to identify the type of clipping the digitizer performs, among other things.

If you don't know how a client searches for a component, you can find out by running that application and trapping on FindNextComponent. The last parameter pushed on the stack is the component description, and you can find its values in a debugger (see "Inside QuickTime and Component-Based Managers" indevelop Issue 13). In our example, we know that QuickTime performs a simple type and subtype search for a text media handler, so we only have to change the type and subtype in the component resource.

The global data file. The ComponentData.h file contains the declaration of the data structure for each component instance and the global component data structure. You'll need to fill out a component description structure describing your chosen base component, which will be used to ask the Component Manager to find it.

Now you're left with defining the global data for your derived component. The generic capturing component on this issue's CD has one item that's shared across all its instances: a reference to the captured component. If you need data that's shared across instances, declare it here, but in general you shouldn't need it.

The data local to each instance is allocated in the OpenComponent routine. By default, three component instances will be kept track of: a self copy, a delegate copy, and a target copy. These instances will be stored for you, and you won't need to do any work. The target copy is the instance of a component that may capture yours. If your component calls itself, it should use this instance in case the target overrides the routine.

The other data that you allocate is specific to the type of your derived component. For our example, we'll allocate room for a speech channel, a media reference, a handle to the text to be spoken, and a StdTTSParams structure, which is filled out by the Standard Text to Speech dialog. This dialog lets the user choose voice, pitch, and modulation.

The OpenComponent routine. OpenComponent performs three major operations. First, it allocates storage for each instance. Second, it checks for QuickTime, the Text-to-Speech Manager, and other dependencies; if they're not installed, the component can't open and an error is returned. Note that software dependencies are checked here instead of in RegisterComponent to bypass possible load order conflicts. Finally, OpenComponent captures the Apple text media handler and stores a reference to it in the component globals.

The override routines. Now it's time to implement the override routines. You'll need to get the selectors for the routines from the original component's header file.

In our example, we look at MediaHandlers.h and find the MediaInitialize routine. The selector has a constant, kMediaInitializeSelect. We need to make the parameters of our override routine match those of the MediaInitialize routine.

pascal ComponentResult MediaInitialize
    (PrivateGlobals **storage,
    GetMovieCompleteParams *gmc)

MediaInitialize performs these tasks: it stores the media reference from the GetMovieCompleteParams structure in our private storage; it queries the user for a voice with the Standard Text to Speech dialog; and, with this information, it allocates and sets up the speech channel.

Next we implement the MediaIdle routine, which has a selector of kMediaIdleSelect. Our MediaIdle looks like this:

pascal ComponentResult MediaIdle
    (PrivateGlobals **storage, TimeValue
    atMediaTime, long flagsIn, long *flagsOut,
    const TimeRecord *movieTime)

This routine retrieves the media sample for the time passed in and then speaks it. The important parameter is atMediaTime, which contains the current time value of the media for the movie. We get the media sample for that time using GetMediaSample, and then we use the nifty new Text-to- Speech Manager to speak.

In this case, we'll use SpeakText, which takes three parameters: a speechChannel (allocated earlier in the OpenComponent routine), a pointer to the beginning of the text that we want to speak, and the length of the text. SpeakText is an asynchronous routine, so it won't hold up processing (or the movie) while it speaks. On the other hand, the text can't be disposed of until speaking is finished. To accommodate this requirement, a reference to the text is stored in our instance storage, and the text is disposed of when the component closes.

LETTING USERS LINK AND UNLINK COMPONENTS
Thanks to dynamic linking, a large number of users can easily take advantage of new functionality provided by customized components. Three methods can be used to register and unregister components. First, a component is registered at system startup if the component resides in the System Folder, or in the Extensions folder of the System Folder. To unregister this component, a user can remove it and reboot. Second, an application can dynamically register components as needed, and then unregister them when finished. Third, you can use the drag-and-drop applications Komponent Killer and Reinstaller II included on this issue's CD. Using these applications, you don't have to reboot. (Of course, your typical user won't do it this way; this method is for you, the programmer.)

EXCITING PROSPECTS
Now you know how to customize a component using a derived component, which will be dynamically linked at run time and thus can extend systemwide functionality. Just think of the possibilities! You can override the movie controller and implement an Apple event handler. And you can override other base components as well. Fiddle around with the generic derived component on the CD to get an idea of the exciting prospects before you.

REFERENCES

  • "Somewhere in QuickTime: Derived Media Handlers" by John Wang, develop Issue 14.
  • "Inside QuickTime and Component-Based Managers" by Bill Guschwan, develop Issue 13.
  • "Techniques for Writing and Debugging Components" by Gary Woodcock and Casey King, develop Issue 12.
  • "Be Our Guest: Components and C++ Classes Compared" by David Van Brink, develop Issue 12.

BILL GUSCHWAN (AppleLink ANGUS) hung out with Robert Schumann to discuss their symphonic feats. Robert: "Angus, I understand you compare your jobs to symphonies." Angus: "I guess so, though I'd rather compare operas to pasta. You know, Wagner is lasagna, Mozart is fettucine, Verdi is ravioli, . . ." Robert: "So on your opera pasta scale, how do you rate my symphonic music?" Angus: "Linguini." Robert: "Yo mama!" Angus: "Listen, Mr. Concerto Psycho Ward, at least my mother knows the meaning of life beyond success. Can't say the same about your wife." Robert: "You mean my beloved Clara." Angus: "Yep, Clara, the dogcow. Well, gotta go, I hear Symphony No. 2." Robert: "Before you go, what's the key?" Angus: "C Major." Robert: "No, what's the key?" Angus: "As Wittgenstein says, the key to life is that language is a game." Robert: "No, what's the key?" Angus: "Oh, it's the key to my new office in PIE DTS." Robert: "Then let the music begin, allegro." Angus: "Pass the parmesan." *

To see information about a track in a hierarchical manner, you can use Dumpster, a QuickTime tool that's included on this issue's CD.*

You can watch the components of a movie load if you set A-trap breaks as outlined in the section "Breaking on Common Component Manager Routines" in the article "Inside QuickTime and Component-Based Managers" in develop Issue 13.*

QuickTime 1.6 adds a new Component Manager selector, componentWantsUnregister, that you can take advantage of when you want to free a captured component. Set componentWantsUnregister in the componentRegisterFlags field. When the captured component is unregistered, your derived component can call UncaptureComponent and dispose of the global memory.*

To identify a captured component in a debugger, you can use the thing dcmd. The component ID of a captured component will begin with two periods (..). *

A version of the Text-to-Speech Manager can be found on this issue's CD. *

Thanks to Ken Doyle, Tim Schaaff, and Gary Woodcock for reviewing this column. *

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

TunnelBear 3.5.1 - Subscription-based pr...
TunnelBear is a subscription-based virtual private network (VPN) service and companion app, enabling you to browse the internet privately and securely. Features Browse privately - Secure your data... Read more
Typinator 7.4 - 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
Monosnap 3.4.9 - Versatile screenshot ut...
Monosnap lets you capture screenshots, share files, and record video and .gifs! Features Capture Capture full screen, just part of the screen, or a selected window Make your crop area pixel... Read more
Fantastical 2.4.5 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
TunnelBear 3.5.1 - Subscription-based pr...
TunnelBear is a subscription-based virtual private network (VPN) service and companion app, enabling you to browse the internet privately and securely. Features Browse privately - Secure your data... Read more
Typinator 7.4 - 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
Fantastical 2.4.5 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
Monosnap 3.4.9 - Versatile screenshot ut...
Monosnap lets you capture screenshots, share files, and record video and .gifs! Features Capture Capture full screen, just part of the screen, or a selected window Make your crop area pixel... Read more
Skim 1.4.32 - PDF reader and note-taker...
Skim is a PDF reader and note-taker for OS X. It is designed to help you read and annotate scientific papers in PDF, but is also great for viewing any PDF file. Skim includes many features and has a... Read more
ForkLift 3.1.1 - Powerful file manager:...
ForkLift is a powerful file manager and ferociously fast FTP client clothed in a clean and versatile UI that offers the combination of absolute simplicity and raw power expected from a well-executed... Read more

Latest Forum Discussions

See All

What mobile gaming can learn from the Ni...
While Nintendo might not have had things all its own way since it began developing for mobile, one thing it has got right is the release of the Switch. After the disappointment of the WiiU, which I still can't really explain, the Switch felt a... | Read more »
Programmer of Sonic The Hedgehog launche...
Japanese programmer Yuji Naka is best known for leading the team that created the original Sonic The Hedgehog. He’s moved on from the speedy blue hero since then, launching his own company based in Tokyo – Prope Games. Legend of Coin is the... | Read more »
Why doesn't mobile gaming have its...
The Overwatch League is a pretty big deal. It's an attempt to really push eSports into the mainstream, by turning them into, well, regular sports. But slightly less sweaty. It's a lavish affair with teams from all around the world, and more... | Read more »
Give Webzen’s new billiard game PoolTime...
Best known for producing hugely popular MMO titles, South Korean publisher Webzen is now taking aim at a different genre altogether. PoolTime is a realistic eight ball pool simulator, allowing you to compete in real-time matches against players... | Read more »
Let Them Come Guide - How to survive aga...
Let Them Come is all about making it as far as possible against overwhelming odds. Check out some of these tips to help you last a little longer in your unwinnable fight: [Read more] | Read more »
All the best games on sale for iPhone an...
Happy last day of the week. I hope you've been having a good one. I have. I saw ten doggos today. So because I'm in a good mood, I thought I'd round up all of the best games that are currently on sale on the App Store. [Read more] | Read more »
The very best games that came out for iP...
We're getting to the end of the first real, full, proper week of 2018. And in that time we've seen some pretty awesome games landing on the App Store. Of course, we've seen some absolute duffers as well. The sort of games that you look at and... | Read more »
Rusty Lake Paradise (Games)
Rusty Lake Paradise 1.4 Device: iOS Universal Category: Games Price: $2.99, Version: 1.4 (iTunes) Description: Jakob, the oldest son of the Eilander family, is returning to Paradise island after his mother passed away. Since her... | Read more »
Antihero Guide - Sneaky tricks to get ah...
Games of Antihero start out small and streamlined, but they quickly turn into long strategic conquests as you fight for control of the Victorian-era streets. If you find yourself struggling in the skullduggery department, here are a few things you... | Read more »
Here's why Niantic pulling Pokemon...
If there's one thing that Pokemon GO did well, it was bringing people together. I still remember seeing groups of people around the marina near where I live in the weeks after the game came out, all of them trying to grab some water Pokemon. There... | Read more »

Price Scanner via MacPrices.net

10″ iPad Pros on sale for $50-$75 off MSRP, n...
B&H Photo has 10″ and #Apple #iPad Pros on sale for up to $75 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only. Note that some sale prices are restricted to certain... Read more
Apple refurbished Mac minis available startin...
Apple has restocked Certified Refurbished Mac minis starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: – 1.4GHz Mac mini: $419 $80 off MSRP – 2.6GHz Mac... Read more
Amazon offers Silver 13″ Apple MacBook Pros f...
Amazon has new Silver 2017 13″ #Apple #MacBook Pros on sale today for up to $150 off MSRP, each including free shipping: – 13″ 2.3GHz/128GB Silver MacBook Pro (MPXR2LL/A): $1199.99 $100 off MSRP – 13... Read more
Sale: 12″ 1.3GHz MacBooks on sale for $1499,...
B&H Photo has Space Gray and Rose Gold 12″ 1.3GHz #Apple MacBooks on sale for $100 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 12″ 1.3GHz Space... Read more
Apple offers Certified Refurbished 2017 iMacs...
Apple has a full line of Certified Refurbished iMacs available for up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: – 27... Read more
13″ MacBook Airs on sale for $120-$100 off MS...
B&H Photo has 2017 13″ 128GB MacBook Airs on sale for $120 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 13″ 1.8GHz/128GB MacBook Air (MQD32LL/A): $... Read more
15″ Touch Bar MacBook Pros on sale for up to...
Adorama has Space Gray 15″ MacBook Pros on sale for $200 off MSRP. Shipping is free, and Adorama charges sales tax in NJ and NY only: – 15″ 2.8GHz MacBook Pro Space Gray (MPTR2LL/A): $2199, $200 off... Read more
21″ 3.4GHz 4K iMac on sale for $1399, $100 of...
Adorama has the 21″ 3.4GHz 4K #Apple #iMac on sale today for $1399. Their price is $100 off MSRP. Shipping is free, and Adorama charges sales tax in NJ and NY only: – 21″ 3.4GHz 4K iMac (MNE02LL/A... Read more
B&H offering 13″ Apple MacBook Pros for u...
B&H Photo has 13″ MacBook Pros on sale for up to $75-$120 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 13-inch 2.3GHz/128GB Space Gray MacBook Pro (... Read more
B&H continues to offer clearance 2016 15″...
B&H Photo has clearance 2016 15″ #MacBook Pros available for up to $800 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: – 15″ 2.7GHz Touch Bar MacBook Pro... Read more

Jobs Board

Commerce Engineer, *Apple* Media Products -...
# Commerce Engineer, Apple Media Products Job Number: 113161479 Santa Clara Valley, California, United States Posted: 01-Nov-2017 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Site Reliability Engineer, *Apple* Pay - Ap...
# Site Reliability Engineer, Apple Pay Job Number: 113356036 Santa Clara Valley, California, United States Posted: 12-Jan-2018 Weekly Hours: 40.00 **Job Summary** Read more
UI Tools and Automation Engineer, *Apple* M...
# UI Tools and Automation Engineer, Apple Media Products Job Number: 86351939 Santa Clara Valley, California, United States Posted: 11-Jan-2018 Weekly Hours: 40.00 Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.