Scirius Development

Simsonstraße 5
04107 Leipzig, Germany

This documentation and the xtra are continuously improved.
Please visit http://www.scirius.com for updates of the documentation and the xtra on a regular basis.

Additional information can be found at the support forum: http://www.forum.scirius.info

Last updated: 2008-06-14

QTMovieXtra, Version 1.1

What is new in this release?

Version 1.1 has undergone major internal changes to support Adobe Director 11 while maintaining the compatibility with previous versions of Director.
Therefor this version is not a free upgrade for owners of previous versions. These customers need to obtain a new serial number.

• Support for Director 11 (requires QuickTime 7)
• the versions for Director 8.5 - 10.1 now require Quicktime 6 or above
• dropped support for the Classic MacOS (System 9)
• added support for every installed export component, including third party exporters (like FLV)
• support for hi resolution audio export (D11 versions only)

What is QTMovieXtra?

QTMovieXtra is a cross platform scripting xtra for Adobe/Macromedia Director™ for creating, editing and manipulating QuickTime™ movies.

It combines the power of QuickTime™ editing with the flexibility of LINGO™.

What you can do:

• Create QuickTime movies complete under LINGO control
• Combine existing Quicktime segments on the fly for flawless playback
• Delete, add or switch tracks on the fly
• Create your own simple video editing tools
• Create your own highly customizable batch converting tools
  

System Requirements

Director 8.5 or higher (including Director MX 2004)
QuickTime 6 or higher
Windows XP or higher, MacOS X 10.3 or higher

Director 11
QuickTime 7 or higher
Windows XP or higher, MacOS X 10.4 or higher

Note:

QuickTime Pro is not required, QTMovieXtra works with the standard version of QuickTime.
However, I recommend QuickTime Pro for you as director developer. With QuickTime Pro
you'll get a better understanding of the power of QuickTime and you'll have a tool to
examine your movies created with QTMovieXtra.

Where to buy QTMovieXtra?

All orders are processed by shareit on a secure ordering system. You may want to visit their web site first. Many other xtra developers sell their products there.
You have a wide variety of payment options there, including all major credit cards and checks.

The full version of QTMovieXtra (150 €) can be purchased at the following link: http://www.shareit.com/product.html?cart=1&productid=198007

If you have already a serial number of QTMovieXtra you can purchase the upgrade (50 €) at: http://www.shareit.com/product.html?cart=1&productid=300261551

Please note that you have to enter a valid serial number to order the upgrade.

General Notes

Timescale

QTMovieXtra uses a timescale of 1/600 of a second.
Whenever a time value is to be specified, use this timescale.

Filepaths

You have to provide the full path to a file which does not already exists, i.e. a file you want to create.
That's true for all export functions, new and CreateEmptyMovie. (argument placeholder nf )

For existing files you can use the full path, relative paths with the "@" operator or just the filename.
In the latter case the file has to be in the same folder as the director movie, if not, the searchpaths property
is evaluated to find the file. (argument placeholder f or df )

Reference Movies

If you use the authoring or editing functions so called reference movies are created, i.e. movies which contain references to other files.
To resolve these dependencies to the other files you should use any of the export functions to make the movie self-contained.

Volume

The volume range is from 0 (silent) to 255 (full volume).
If you wish, however higher values are supported. Be aware, that audible distortions may appear.

The Functions

General Functions

register

qtmAbout

Utility Functions

Discussion

qtmGetCodecList

qtmGetCodecNames

qtmGetMovieDuration

qtmGetTrackInfos

qtmGetTrackInfo (new in version 1.0.4)

qtmGetTrackCount (new in version 1.0.4)

qtmGetProgFunction

qtmSetProgFunction

qtmSelectFileDialog

qtmGetQuickTimeVersion

qtmGetXtraVersion (new in version 1.0.6)

qtmCheckInstalled (new in version 1.0.6)

qtmDeleteFile (new in version 1.0.1)

qtmGetMovieFrameCount (new in version 1.0.3)

qtmGetMovieFrameRate (new in version 1.0.3)

qtmGetMovieBox (new in version 1.1)

Authoring Functions

Discussion

new

qtmAddFrame (enhanced in version 1.0.6)

qtmAddSound

qtmSave

Export Functions

Discussion

qtmFlatten

qtmExport

qtmExportAIFF

qtmExportWAVE

qtmExportMovie

qtmExportDV (new in version 1.0.1)

qtmMoviePictToMember (new in version 1.0.1)

qtmMoviePictToImage (new in version 1.0.6)

qtmAskExportSettings (new in version 1.0.2, enhanced in version 1.1)

qtmLoadExportSettings (new in version 1.0.2)

qtmSaveExportSettings (new in version 1.0.2)

qtmDoExportWithSettings (new in version 1.0.2)

qtmGetExportTypeList (new in version 1.1)

Editing Functions

Discussion

qtmCreateEmptyMovie

qtmInsertMovieSegment

qtmDeleteMovieSegment

qtmAddTrackSegment

qtmInsertTrackSegment (new in version 1.0.4)

qtmDeleteTrackSegment

qtmScaleTrackSegment

qtmScaleMovieSegment (new in version 1.1)

qtmDeleteTrack

qtmSetTrackOffset

qtmSetTrackEnabled

qtmSetTrackDimensions

qtmSetTrackName

qtmSetTrackVolume

qtmSetTrackBalance (new in version 1.0.1)

qtmSetTrackLayer (new in version 1.0.1)

qtmSetTrackGraphicsMode (new in version 1.0.1)

qtmFadeSoundTrack (new in version 1.0.4)

qtmSetTrackQuality (new in version 1.0.6)

qtmSetCopyMode (new in version 1.0.9)

qtmSetMovieBox (new in version 1.1)

Matrix Functions

Discussion

qtmResetTrackMatrix (new in version 1.0.1)

qtmTranslateTrackMatrix (new in version 1.0.1)

qtmRotateTrackMatrix (new in version 1.0.1)

qtmScaleTrackMatrix (new in version 1.0.1)

qtmSkewTrackMatrix (new in version 1.0.1)

qtmGetTrackDisplayBounds (new in version 1.0.1)

qtmSetTrackMatrix (new in version 1.0.9)

Edit Session Functions

Discussion

qtmOpenEditSession (new in version 1.0.4)

qtmCloseEditSession (new in version 1.0.4)

User Data Functions

Discussion

qtmSetUserData (new in version 1.0.8)

qtmGetUserData (new in version 1.0.8)

Tweening Functions

Discussion

qtmAddTweenTrack (new in version 1.0.9)

qtmGetTweenTracks (new in version 1.0.9)

qtmGetTweenData (new in version 1.0.9)

Matrix Calculation Functions

Discussion

qtmGetNewMatrix (new in version 1.0.9)

qtmRectToRectMatrix (new in version 1.0.9)

qtmRectToQuadMatrix (new in version 1.0.9)

qtmTranslateMatrix (new in version 1.0.9)

qtmScaleMatrix (new in version 1.0.9)

qtmRotateMatrix (new in version 1.0.9)

qtmSkewMatrix (new in version 1.0.9)

Effect Functions

Discussion

qtmAskEffectSettings (new in version 1.0.9)

qtmLoadEffectSettings (new in version 1.0.9)

qtmSaveEffectSettings (new in version 1.0.9)

qtmGetEffectInfo (new in version 1.0.9)

qtmCreateEffectTrack (new in version 1.0.9)

Timecode Functions

Discussion

qtmGetTimeCode (new in version 1.1)

qtmCreateTimeCode (new in version 1.1)

Error Codes

General Functions

register

+ Register object xtraRef, string name, string serialnumber

Example:

register(xtra "QTMovieXtra", "your company", "the serialnumber")

Note:

You can try QTMovieXtra first before you decide buying it. The unregistered version is fully functional except the "about box" is shown every few minutes and movies created with the addFrame command are marked by red diagonal lines.

There are several free functions in QTMovieXtra you may find useful and can be used without registration:

qtmGetCodecList

qtmGetCodecNames

qtmSelectFileDialog

qtmGetQuickTimeVersion

qtmAbout

*qtmAbout

This command shows the about box of the xtra.

Utility Functions

The Utility functions are useful for getting information about the installed codecs, other movies or files.

qtmGetCodecList

*qtmGetCodecList

Example:

put qtmGetCodecList()

-- ["rle ","WRLE","cvid","yuv2","dvcp","dvc ", ... ,"SVQ1"]

Note:

Every codec identifier has a length of four characters. Some of them have a trailing space character, like "rle ".

qtmGetCodecNames

*qtmGetCodecNames

Example:

put qtmGetCodecNames()

-- ["Animation", "BMP", "Cinepak", "Component Video", "DV - PAL",
 "DV/DVCPRO - NTSC", ... ,"Sorenson Video"]

qtmGetTrackInfos

*qtmGetTrackInfos string f, symbol type

The following symbols are defined:

#type

returns the type of all tracks of the file specified.

#sound

#video

#text

#mpeg

#music

#timecode

#sprite

#flash

#movie

#tween

#basemedia

#QD3D

#unknown

#offset

Returns a list of all track offsets of the movie, i.e. the time after the track starts.

#duration

Returns a list of all track durations of the movie.

#enabled

Returns a list of enabled flag of all tracks of the movie.
Enabled tracks have a value of 1, disabled track a value of 0.

#name

Returns a list of all track names of the movie.
If a track has no custom name assigned, an empty string is returned for that track.

#width

Returns a list of all track widths of the movie.
If a track is no visual track (i.e. a sound track for example), 0 is returned for that track.

#height

Returns a list of all track heights of the movie.
If a track is no visual track (i.e. a sound track for example), 0 is returned for that track.

#volume

Returns a list of all track volumes of the movie.
If a track is no audio track (i.e. a video track for example), 0 is returned for that track.

#balance

Returns a list of the balance settings of all tracks in a movie.
The value can range between -127 and 127. Negative values emphasize the left sound channel, and positive values emphasize the right sound channel; a value of 0 specifies neutral balance.
If a track is no audio track (i.e. a video track for example), 0 is returned for that track.

#layer

Returns a list of the track layers in a movie.
Layers are numbered from -32,768 through 32,767. Tracks with smaller layer numbers are in front of the others.

#graphicsmode

Returns a list of the track graphicsmodes in a movie.
The returned value for every track itself is a linear list containing an integer for the graphicsmode in the first index and a color object in the second.

If the track can't have a grahicsmode an empty list is returned.

#codec

Return a list of the codec used of every track in the movie.
The codec is returned as a four char string. See qtmGetCodecList.

Usually every track of QuickTime movie is encoded with one codec. However, it is possible, that a single track
of a QuickTime movie uses different codecs at different times. In these cases the first codec used is returned.

Some other values for the codec selector:

"m1a "

"m1v "

"m1s "

"m2v "

"m2s "

"mp4v"

"mp4a"

"drms"

"raw "

"twos"

"sowt"

".mp3"

"musi"

#quality

Returns the quality settings of all tracks in a movie.

Notes:

You can check not only movie files. Actually every file type Quicktime can handle as a movie is supported.
That includes sound files (AIFF, WAVE, mp3...), image files (JPEG, PICT, BMP...), text files,
MIDI-files, SWF, MPEG...

Tip:

Use this function to determine if a file contains data which can be handled by QuickTime directly.

Examples:

put qtmGetTrackInfos("test.aif",#type)

-- [#sound]

The file "test.aif" consists of only a sound track.

put qtmGetTrackInfos("@:movies:test.mov",#type)

-- [#video,#sound,#sound]

The movie "test.mov" consists of 3 tracks. The first track is a video track, the other two are soundtracks.

put qtmGetTrackInfos("@:movies:test.mov",#duration)

-- [6000,6000,3000]

The movie "test.mov" consists of 3 tracks.
The first two tracks have a duration of one second, the third track a duration of half a second.

put qtmGetTrackInfos("@:movies:test.mov",#width)

-- [320,0,0]

The movie "test.mov" consists of 3 tracks.
The first track has a width of 320 pixels, the other tracks have no width.

qtmGetTrackInfo

*qtmGetTrackInfo string f, integer trkNum, any typeList

Discussion:

This function returns a property list of information regarding a single track of QuickTime movie.
See qtmGetTrackInfos for supported info types. You have to provide a linear list of info types you are interested in.
At least one type symbol must be provided.

Note:

Make sure that you provide a valid track number. Use qtmGetTrackCount to determine the number of tracks in a movie.

Example:

put qtmGetTrackInfo("myMovie", 2, [#width,#height])

-- [#width:320, #height:240]

myInfo = qtmGetTrackInfo(fn, 1, [#codec,#duration,#type,#balance,#volume,#offset,#enabled,#size,#width,#height,#name,#layer,#graphicsmode]) 

qtmGetTrackCount

*qtmGetTrackCount string f

Discussion:

This function returns the number of tracks in a QuickTime movie.

Example:

put qtmGetTrackCount("myMovie")

-- 3

qtmGetProgFunction

*qtmGetProgFunction

qtmSetProgFunction

*qtmSetProgFunction symbol func

Discussion

Some export functions can take a long time to execute. To provide your users with feedback about the progress of this operation you can provide a progress function.
With the qtmSetProgFunction you can tell the QTMovieXtra what kind of progress indicator you want to be shown during long operations.

The following symbols are currently defined:

#none

Don't show a progress indicator at all

#standard (the default) 

This shows the built in progress function

#custom

This symbol is currently not implemented yet, but is reserved for future versions of QTMovieXtra

#lingoProgress

Experienced LINGO developers can also write a customized progress function entirely in LINGO.
See the example movie "QTMExport.dir" for an example.

qtmGetMovieDuration

*qtmGetMovieDuration string f

Discussion:

This function returns the duration of the movie in 1/600 seconds.

qtmSelectFileDialog

*qtmSelectFileDialog

qtmGetQuickTimeVersion

*qtmGetQuickTimeVersion

Note:

This is the only function of QTMovieXtra which works with all QuickTime versions installed. All other functions are disabled and will return an error code of -1 if the installed QuickTime is of a version less than 6.0 (Director 8.5-10.1) or less than version 7.0 (Director 11 and above). It is always a good idea to check the version of QuickTime before using any of the other functions of QTMovieXtra.

Example:

put qtmGetQuickTimeVersion()

-- "0730"

In this example we have QuickTime in version 7.3.0 installed.

on startMovie
   if qtmGetQuickTimeVersion()<"07" then
      alert "Please install Quicktime 7"
      halt
   end if
end

qtmGetXtraVersion

*qtmGetXtraVersion

Example

put qtmGetXtraVersion

-- "1.1.0"

qtmCheckInstalled

*qtmCheckInstalled symbol what

Discussion

Windows users have the option to choose a minimal Quicktime installation, i.e. only suited for playback movies.
However, to use all functions of QTMovieXtra the user should install the "recommended setup".

With the function qtmCheckInstalled you can check the presence of needed components.

The following selectors are currently defined:

#export -- the authoring extras and most of the codecs are available
#dv        -- DV export available

Example

if qtmCheckInstalled(#export)=0 then
   alert "Please re-install Quicktime"
   halt
end if

-- 1
 

qtmDeleteFile

*qtmDeleteFile string f

Discussion:

A function to delete any file.

Example:

qtmDeleteFile("a movie.mov")

qtmGetMovieFrameCount

*qtmGetMovieFrameCount string f

Discussion

This function returns the frame count of a movie file.

Note

This function is only usefull for files with visual media.

Example

put qtmGetMovieFrameCount("Flower.jpg")

-- 1

No surprise, the JPEG file "Flower.jpg" consists of only one frame.

qtmGetMovieFrameRate

*qtmGetMovieFrameRate string f

Discussion

This function returns the average frame rate of a movie file.

Note

This function returns the average frame rate of the first video track in the movie. If the movie contains more than one video track or the movie has a variable frame rate the result may not be very useful.

Example

put qtmGetMovieFrameRate("test.mov")

-- 25.000

The "movie test.mov" has an average frame rate of 25 frames per second.

qtmGetMovieBox

*qtmGetMovieBox string f

Discussion

This function returns the movie box of a movie file enclosing all tracks and taking all matrix transformations into account.

Example

put qtmGetMovieBox("test.mov")

-- rect(0,0,640,480)

Authoring Functions

Discussion

To create a completely new QuickTime movie use the authoring functions provided by QTMovieXtra.

The authoring functions are the only functions of the xtra which need the creation of an instance
of QTMovieXtra. All other functions are global functions are ready to use whenever you want.

new

new object me, string nf, integer w, integer h, float fr, string codec, integer quality

Examples:

gQTM = new(xtra "QTMovieXtra",the moviepath& "test.mov", 320, 240, 12.5, "rle ", 1024)  

In this example we are creating a QuickTime movie under the name "test.mov", The movie is stored in the same
directory as the director movie. We want a width of 320 pixels, a height of 240 pixels and a framerate of 12.5 frames per second.
Note that the framerate parameter is a float value. Our codec is "rle ", that is the "Animation" codec. Finally we want the highest compression quality.

Tip:

If you plan to recompress your movie later use a codec with high quality and quality setting of 1024.

Note:

You have to provide the framerate parameter always as float value (25.0)

qtmAddFrame

qtmAddFrame object me, any memberOrFile

Note:

The images added to your QuickTime movie are always scaled to fit the dimensions specified in the new command of the xtra if they are not the same dimension.
Use Imaging LINGO to scale or crop your images accordingly, if needed.

Alpha channels

Starting with version 1.0.3 of QTMovieXtra alpha channels are full supported.

If you have a bitmap cast member with alpha channel and the useAlpha property of that cast member is turned on the alpha channel is included, otherwise the alphaChannel is not used. On Macintosh computers the alpha channel is always included regardless of the useAlpha property.

For image files with alpha channel information the alpha channel is included in the resulting movie, provided the codec supports alpha channels.

To use the alpha channel in the movie you have to set the graphics mode of the track accordingly. See qtmSetTrackGraphicsMode.

New

Starting with version 1.0.6 of QTMovieXtra you can also pass an image object directly.
In fact this is now the recommended way to add frames to a QuickTime movie.
Using the image is the fastest method, it's usually 2 times faster than using the member.

Examples:

gQTM.qtmAddFrame(member "Bitmap")  -- a member
gQTM.qtmAddFrame(member(12,2))     -- a member
gQTM.qtmAddFrame("Bild1")          -- a file
gQTM.qtmAddFrame("@:Bilder:Bild1") -- a file
gQTM.qtmAddFrame(member("Bitmap").image)  -- the image object of a member (faster than just the member)
gQTM.qtmAddFrame(gImage)                  -- an image object stored in a global

qtmAddSound

qtmAddSound object me, string f, integer srctrk, integer st, integer dur, integer dt, integer vol

Discussion:

This function adds a sound to your new movie.

The source file can be another QuickTime movie or any of the sound formats QuickTime can handle. That includes WAVE, AIFF, mp3.
If you use a regular sound file as the source, the source track is always 1, since these "movie" files won't have any other tracks.

Tip:

Use qtmGetTrackInfos(f,#type) to determine which track(s) of a particular file is/are actually sound track(s) to be used.

Note:

The sound media is not inserted in the movie, just a reference to the original file. That is very fast and doesn't waste any space on your hard drive, however, you need to call any of the export functions to make the movie self contained for distribution.

qtmSave

qtmSave object me

Discussion:

This command saves your new without ending your current authoring session.
This allows you to play back or export the movie in the current state of authoring without ending the authoring session.

After the qtmSave command you can continue adding frames or sounds with the qtmAddFrame or qtmAddSound commands.

Note:

If you are completely finished with your authoring set the xtra object return by the new function to 0. That will end your authoring session.

Tip:

It is good practice to issue the qtmSave command on a regular basis.

Export Functions

Discussion

After authoring or editing the Quicktime movie your movie will be a reference movie in most cases.
Now it's time to make the movie self-contained or recompress it to a final delivery format.

The Export functions of QTMovieXtra let you do this.

All of the export functions use the progress function set by qtmSetProgFunction. The default is using a standard progress indicator.

qtmFlatten

*qtmFlatten string f, string nf

Note:

This function is exactly the same as in QuickTime Pro if you would select "Save as..." with the "make movie self-contained" option selected.

Example:

qtmFlatten("myMovie.mov", the moviepath & "final movies:flattened.mov")

qtmExport

*qtmExport string f

The following or similar standard export dialog is shown.
You can choose the location for the new file as well as any export format and any options Quicktime allows for your particular source movie.
Depending on your source movie the supported formats may vary.

Note:

This Export function is exactly the same as in QuickTime Pro.

qtmExportAIFF

*qtmExportAIFF string f, string nf, integer bits, integer rate, integer channels, symbol comp, integer showsettings

f

The file you want to export. It can be any file containing sound, as long as QuickTime can handle it.
You can use relative paths here.

nf

The full path to the AIFF file.

bits

The desired sample size. Use 8 for 8 bits per sample or 16 for 16 bits per sample. Any other value will result in a parameter error.

rate

The desired sample rate

channels

The number of channels in the AIFF file. 1 for mono, 2 for stereo.

comp

The compression to use

#none --> uncompressed

#alaw --> ALaw 2:1

#ulaw --> µLaw 2:1

#ima4 --> IMA 4:1

showsettings

The parameter showsettings controls the level of settings shown to the user.
In version 1.0 of QTMovieXtra this parameter can be 0, 1 or 2.

A value of 0 exports with the settings provided without any user interaction. This silent export is very useful for batch processing or if you don't want your users to change any of the settings.

A value of 1 shows a standard sound settings dialog similar to the picture below.
The other settings you provided are then treated as default values, preselected in the dialog.
The path to the destination file, however cannot be changed by the user.

A value of 2 shows the standard file export dialog as in the qtmExport function with one difference:

The general export format can't be changed from "Sound to AIFF". Any other options, as well the file location can be changed by the user.

qtmExportWAVE

*qtmExportWAVE string f, string nf, integer bits, integer rate, integer channels, integer showsettings

The parameter showsettings controls the level of settings shown to the user.
In version 1.0 of QTMovieXtra this parameter can be 0, 1 or 2.

A value of 0 exports with the settings provided without any user interaction. This silent export is very useful for batch processing or if you don't want your users to change any of the settings.

A value of 1 shows a standard sound settings dialog similar to the picture below.
The other settings you provided are then treated as default values, preselected in the dialog.
The path to the destination file, however cannot be changed by the user.

A value of 2 shows the standard file export dialog as in the qtmExport function with one difference:
The general export format can't be changed from "Sound to WAVE". Any other options, as well the file location can be changed by the user.

Example:

qtmExportWave("myMusic.mp3", the moviepath & "myMusic.wav",    8, 11025,1,0)

This exports the file "myMusic.mp3" to the file "myMusic.wav" with a bitdepth of 8 Bit, a sample rate of 11.025 kHz a a mono sound
without interacting with the user.

qtmExportMovie

*qtmExportMovie string f, string nf, any vSetList, any sSetList, integer showsettings

vSetList

The parameter vSetList controls the video settings for the export. The format is a property list with the following properties:

Discussion

The parameter vSetList is property list, that means, you can use any of the properties in any order. If you set this parameter to an empty property list ([:]) the default values are used. In other words, you just have to provide the properties you actually want to override.
Please note, that not all codecs support all of the settings.

If you set the vSetList parameter to 0, the video export is disabled.

sSetList

The parameter sSetList controls the sound settings for the export. The format is a property list with the following properties:

showSettings

As with the functions qtmExportAIFF or qtmExportWAVE the showSettings parameter controls the type of settings shown before the export starts.

A value of 0 does not show any settings dialog.

The value 1 shows the standard Movie Settings dialog as shown in the picture below.

A value of 2 shows the standard file export dialog as in the qtmExport function with one difference:

The general export format can't be changed from "Movie to Quicktime Movie". Any other options, as well the file location can be changed by the user.

Important Note

Modern codecs like H.264 have a lot more settings than this function can provide. It is not recommended to use qtmExportMovie with these codecs.
You should use qtmAskExportSettings to create a valid settings container and save it for later use with qtmSaveExportSettings.

qtmExportDV

*qtmExportDV(string f, string nf, integer NTSC, integer audioLock, integer rate, integer showsettings)

The parameter showsettings controls the level of settings shown to the user.
In version 1.0 of QTMovieXtra this parameter can be 0, 1 or 2.

A value of 0 exports with the settings provided without any user interaction. This silent export is very useful for batch processing or if you don't want your users to change any of the settings.

A value of 1 shows a standard DV settings dialog similar to the picture below.
The other settings you provided are then treated as default values, preselected in the dialog.
The path to the destination file, however cannot be changed by the user.

A value of 2 shows the standard file export dialog as in the qtmExport function with one difference:

The general export format can't be changed from "Movie to Quicktime Movie". Any other options, as well the file location can be changed by the user.

qtmMoviePictToMember

qtmMoviePictToMember(string f, integer time, any member)

Discussion

This function retrieves the picture of a QuickTime movie at the specified time and stores it into a bitmap cast member.

The retrieval of the image is done behind the scenes, that is no video has to be shown.

Note

The cast member must be a valid member of type #bitmap. Use new(#bitmap, member(x)) to create an empty bitmap member first.
The media of the original member is replaced.

Example

qtmMoviePictToMember("test.mov", 120, member("Temp_Image"))

get the picture of movie "test.mov" at a time of two seconds after the beginning and store into member "Temp_Image".

qtmMoviePictToImage

qtmMoviePictToImage(string f, integer time)

Discussion

This function retrieves the picture of a QuickTime movie at the specified time and returns it as an image.

The retrieval of the image is done behind the scenes, that is no video has to be shown.

Note

This function is faster than the qtmMoviePictToMember function.

Example

result = qtmMoviePictToImage("test.mov", 120)
	if integerp(result) then
	   alert("The image could not be retrieved!")
	else
	   member("Test").image = result
	end if

get the image of movie "test.mov" at a time of two seconds after the beginning and store into member "Test".

qtmAskExportSettings

*qtmAskExportSettings string f, string type

Discussion

This functions shows the settings dialog for the export type of your choice. After adjusting your settings and hitting the OK button these settings are stored internally for later use with the qtmDoExportWithSettings or the qtmSaveExportSettings functions. If the user hit the Cancel button the error code -128 is returned and no new settings are stored.

You have to provide a valid QuickTime movie which fits the type of export to be able to adjust the settings, i.e. if you want to set the audio format the movie must have at least one sound track.

Note

Only one setting is stored internally. Previous settings are replaced. Use qtmSaveExportSettings to save for later reuse.

The following export types are defined:

Note

Starting with version 1.1 of QTMovieXtra you can also provide a "TypeCode" to specify the exporter to use.
The "TypeCode" is a unique identifier describing the export component to be used. You can use the qtmGetExportTypeList function to retrieve the TypeCode for any of the installed exporters.

Examples

qtmAskExportSettings ("Baba O'Riley.mp3","AIFF")

qtmAskExportSettings ("Test.mov","movie")

qtmAskExportSettings ("Another.mp4","WAVE")

qtmAskExportSettings ("Test.mov","Sequence")

Important Note about AAC on Windows

QTMovieXtra can't encode MPEG4 audio (AAC) under Windows. This affects all exporters using AAC, like iPod, AppleTV.
There would be a license from Via Licensing required to use AAC encoding.

See http://www.vialicensing.com/licensing/MPEG4_fees.cfm?product=MPEG-4AAC

qtmLoadExportSettings

*qtmLoadExportSettings string f

Discussion

This function loads the export settings from a file previously created by qtmSaveExportSettings.
The newly loaded settings are stored internally for later use with the qtmDoExportWithSettings function.

Note

Any previously stored settings are replaced by the new loaded settings.

You can use settings created by earlier versions of QTMovieXtra in version 1.1, but not the other way around.

Example

qtmLoadExportSettings("@:Settings:AIFFSettings.set")

qtmSaveExportSettings

*qtmSaveExportSettings string nf

Discussion

This function saves the export settings from a previous call to qtmAskExportSettings in a file.
The file format for these settings is cross platform. You can use a settings file created on a Mac under Windows and vice versa.

Important Note

The format of the settings is completely private to the export components and codecs involved. It is possible that this format is not valid for different versions of QuickTime.

qtmDoExportWithSettings

*qtmDoExportWithSettings string f, string nf

Discussion

This function allows you to export files with settings adjusted by a previous call to qtmAskExportSettings or loaded from a file with qtmLoadExportSettings.
That is very useful for batch converting tools, since the settings have to be adjusted only once.

Example

err=qtmAskExportSettings ("Baba O'Riley.mp3","AIFF") --    ask for the settings of the AIFF exporter
if err=0 then
   -- now use these settings multiple times
   qtmDoExportWithSettings("Baba O'Riley.mp3", "HD:Music:The Who:Baba O'Riley.AIF")
   qtmDoExportWithSettings("Bargain.mp3", "HD:Music:The Who:Bargain.AIF")
   qtmDoExportWithSettings("Behind Blue Eyes.mp3", "HD:Music:The Who:Behind Blue Eyes.AIF")
end if

qtmGetExportTypeList

*qtmGetExportTypeList string fn

Discussion:

This function returns a linear list of information about available export components. Every entry in this list consists of a property list with the following properties:

You can use this function to build your own interface or simply to check if an export component is available. Use the #typecode to create the settings for one of exporters with the qtmAskExportSettings function.

If you provide a valid filename to a file, only exporters are listed suited for this kind of file. To get a list of all installed exporters you can pass an empty string as the filename.

Example:

myExporters=qtbgGetExportTypeList(the moviepath & "test.mov")

Note:

This function list every export component known to Quicktime but not every one of that will actually work.
For example there could be an MP3-encoder listed but that one will never work. Obviously that one is only accessible by iTunes.
(current versions of Quicktime correctly omit these exporters)

Editing Functions

Discussion

The Editing Functions lets you edit existing QuickTime movies.

qtmCreateEmptyMovie

*qtmCreateEmptyMovie string nf

Discussion:

This command creates a new empty movie with no tracks at all. You can later use this movie as destination for commands like AddTrackSegment or InsertMovieSegment.

Note:

This is a great starting point for "on the fly" editing since you don't have to alter your original material.

qtmInsertMovieSegment

*qtmInsertMovieSegment string f, string df,integer st, integer dur,integer dt

Discussion:

This command takes a segment of the source movie starting at st with a duration of dur and inserts it in the destination movie at the time dt.
Only enabled tracks of the source movie are inserted. Use qtmSetTrackEnabled to control which tracks are copied.

All tracks of the destination movie after the destination time are shifted forward in time making room for the segment being inserted.

Examples:

qtmInsertMovieSegment("@:sources:movie1.mov", "@:final:theMovie.mov",    0, -1, 0)

That would insert the entire movie "movie1.mov" (we have passed -1 for the duration) at the beginning of movie "theMovie.mov".

qtmInsertMovieSegment("@:sources:movie1.mov", "@:final:theMovie.mov",    1200, 2400, -1)

This command would insert a segment of the movie "movie1.mov" starting at 2 seconds with a duration of 4 seconds at the end of movie "theMovie.mov".

Note:

The functionality is the same as in Quicktime Pro using the following steps:

1. open the source movie (f)
2. select the movie segment (st, duration)
3. copy the selection
4. open the destination movie (df)
5. position the insertion point (dt)
6. paste the copied movie segment into the destination movie
7. save the destination movie

qtmDeleteMovieSegment

*qtmDeleteMovieSegment string f,integer st, integer dur

Discussion:

This command deletes a segment from a movie.

Example:

qtmDeleteMovieSegment("myMovie.mov",0,1200)

Here we delete the first two seconds of the movie "myMovie.mov".

qtmAddTrackSegment

*qtmAddTrackSegment string f, string df,integer srctrk, integer st, integer dur,integer dt

Discussion:

This command adds a segment of track to a movie. By default the media of the source track remains in the source file.
You can also copy the media to the destination movie by setting the copyMode to true (qtmSetCopyMode).

Note:

This function always add a new track to the destination movie.

Example:

qtmAddTrackSegment("Music.aif",the moviepath &"myMovie.mov",1,0,-1,0)

qtmInsertTrackSegment

*qtmInsertTrackSegment string f, string df,integer srctrk,integer dsttrk, integer st, integer dur,integer dt

Discussion:

This function inserts a segment of track into an existing track of a movie.
By default the media of the source track remains in the source file.
You can also copy the media to the destination movie by setting the copyMode to true (qtmSetCopyMode).

Note:

Source and destination track must be of the same type.

qtmDeleteTrackSegment

*qtmDeleteTrackSegment string f, integer trk, integer st, integer dur

Discussion:

This command deletes a segment from a track.

Example:

qtmDeleteTrackSegment("myMovie.mov",3,600,1200)

Here we delete two seconds of track 3 of the movie "myMovie.mov" starting at a time of one second.

qtmScaleTrackSegment

*qtmScaleTrackSegment string f, integer trk, integer st, integer dur, integer newdur

Discussion:

This command changes the duration of a track segment.

Example:

qtmScaleTrackSegment("mymovie.mov",3,0,-1,6000)

The whole track number 3 is scaled to the new duration of 10 seconds.

Note:

This function is best suited for tracks containing still images to adjust their time.
Although it is possible to use this function with other video or sound tracks as well.

In the case of sound tracks the pitch of the sound is shifted.

qtmScaleMovieSegment

*qtmScaleMovieSegment string f, integer st, integer dur, integer newdur

Discussion:

This command changes the duration of a movie segment. All tracks contained in the segment are scaled accordingly.

Example:

qtmScaleMovieSegment("mymovie.mov",0,600,6000)

The first second of the movie is scaled to the new duration of 10 seconds.

Note:

In the case of sound tracks the pitch of the sound is shifted.

qtmSetTrackOffset

*qtmSetTrackOffset string f, integer trk, integer st

Discussion:

With this function you can shift the starting point of a track inside a movie.

Example:

qtmSetTrackOffset("myMovie.mov",3,600)

Track 3 of the movie "myMovie.mov" should start now at a time of one second.

qtmSetTrackEnabled

*qtmSetTrackEnabled string f, integer trk, integer bool

Discussion:

With this function you can enable or disable a track inside a movie. Only enabled tracks are played back if you play the movie.
The same is true for exporting the movie.

Example:

qtmSetTrackEnabled("myMovie.mov",3,0)

Track 3 of the movie "myMovie.mov" gets disabled.

qtmSetTrackDimensions

*qtmSetTrackDimensions string f, integer trk, integer w, integer h

Discussion

With this function you can set the width and height of a track inside a movie.

Example

qtmSetTrackDimensions("myMovie.mov",1,300,200)

Set the track 1 of the movie "myMovie.mov" to a width of 300 pixels and a height of 200 pixels.

Note

Setting the track dimensions may affect the dimensions of the entire movie.

qtmDeleteTrack

*qtmDeleteTrack string f, integer trk

Discussion

This function deletes an entire track from a movie.

Example

qtmDeleteTrack("myMovie.mov",2)

Delete track 2 of movie "myMovie.mov"

Note

Although the track is deleted from the movie it's media data is still inside the movie. To reduce the file size of the movie after deleting tracks
you should flatten the movie. (qtmFlatten)

qtmSetTrackName

*qtmSetTrackName string f, integer trk, string name

Discussion

This function allows you to individually name your tracks.

Example

qtmSetTrackName("myMovie.mov", 2, "second track")

Set the name of track 2 to "second track"

qtmSetTrackVolume

*qtmSetTrackVolume string f, integer trk, integer vol

Discussion

This function allows you to set the volume of a track.

Example

qtmSetTrackVolume ("test.mov",2,128)

Set the volume track 2 of movie "test.mov" to a value of 128, i.e. half of the original volume.

Note

Although a value of 255 means full volume you can even overdrive the volume by providing higher values.
However this can lead to audible distortions (clipping)

qtmSetTrackBalance

*qtmSetTrackBalance string f, integer trk, integer balance

Discussion

This function allows you to set the balance of a sound track.

Valid balance values range from -127 to 127. Negative values emphasize the left sound channel, and positive values emphasize the right sound channel; a value of 0 specifies neutral balance.

Example

qtmSetTrackBalance("myMovie.mov",2,-127)

Set the balance of track 2 to be completely left.

qtmSetTrackLayer

*qtmSetTrackLayer string f, integer trk, integer layer

Discussion

QuickTime movies can have an unlimited number of tracks. In the case of visual tracks they have a track layer which controls the order the tracks are displayed.
This is very similar to Director's sprite channels. However, in QuickTime are layers with smaller numbers placed in front of the others.

Layers are numbered from -32,768 through 32,767.

Example

qtmSetTrackLayer("test.mov", 2, -1)

Set the layer of track 2 of movie "test.mov" to -1

qtmSetTrackGraphicsMode

*qtmSetTrackGraphicsMode string f, integer trk, any gmList

Discussion

This function lets you set the graphics mode of a visual track. The graphics mode controls how a track is drawn above another track.
That is very similar to Director's ink modes.

Note

The parameter for the graphics mode is a linear list containing the graphics mode as integer, followed by an optional color object. (rgb(r,g,b))
Most of the graphics modes don't need this optional color so you can safely provide only the mode without the color information in these cases.

Examples

qtmSetTrackGraphicsMode( "test.mov",2, [256])  -- note the omitted color value!

set the graphics mode of track 2 to "straight alpha"

qtmSetTrackGraphicsMode("test.mov",2, [36, rgb(255,255,255)])

set the graphics mode of track 2 to "transparent" with the transparent color set to white

qtmSetTrackGraphicsMode("test.mov",2, [32, rgb(127,127,127)])

set the graphics mode of track 2 to "blend", with a blend level of 50%

These are the graphics modes defined in QuickTime Pro:

You may also find the following graphics modes useful:

qtmFadeSoundTrack

*qtmFadeSoundTrack string f, integer trk, integer from, integer to

Discussion:

The function adds a modifier track (tween track) to the specified sound track to change the volume of the sound track over time.
Since only a modifier track is added the data of the original sound track is not altered, i.e. qtmFadeSoundTrack works non-destructive. To remove the tween track pass a value of -1 in the from argument.

Note:

The fade can only be applied to a whole track. If you want to fade only a part of a sound track you have to split the track.

Important:

The sound track and the tween track must always start at the same time. If you set the track offset of the sound track, you have to set the offset of the tween track as well.

Do not delete the tween track with qtmDeleteTrack, use qtmFadeSoundTrack with the from argument set to -1, otherwise the relationship between the two tracks is not removed.

Example:

on testFade
  qtmCreateEmptyMovie(the moviepath & "TestFade.mov")
  -- add a new sound track with the first 2 seconds of the music file
  qtmAddTrackSegment("Music.mp3", the moviepath & "TestFade.mov",1, 0, 1200,0)
  -- now create a second sound track with the remaining part of the music file
  qtmAddTrackSegment("Music.mp3", the moviepath & "TestFade.mov",1, 1200, -1,1200)
  -- now fade in the first sound track
  qtmFadeSoundTrack(the moviepath & "TestFade.mov", 1, 0, 256)
end

qtmSetTrackQuality

*qtmSetTrackQuality string f, integer trk, integer quality

Discussion

This function lets you choose the quality settings of a track in a movie.

In most cases this is only a flag to switch the high quality setting of a track on (1) or off (0).

Starting with Quicktime 6.5 there are some more options for video tracks with interlaced material:

0 – low quality
1 – high quality
2 – high quality, single field
3 – high quality, deinterlace

See: http://developer.apple.com/qa/qa2001/qa1149.html for a detailed discussion of these settings.

Example

qtmSetTrackQuality("test.mov", 2, 1)

Switch to high quality of track 2 of movie "test.mov".

qtmSetCopyMode

*qtmSetCopyMode integer mode

Discussion

By default QTMovieXtra generates links to the source movie if you use functions like qtmAddTrackSegment or qtmInsertTrackSegment.

To change this behaviour the new copyMode flag is introduced. If this flag is set to 1 the complete data of the source track is copied to the destination movie resulting in a still selfcontained movie.

The copyMode flag stays in effect until you set it back to 0.

Note

If you set this flag to 1 the execution of the affected function can take some time to finish. If you have set a progress function it is called during lengthy operations.

Supported Functions

qtmAddTrackSegment
qtmInsertTrackSegment

qtmSetMovieBox

*qtmSetMovieBox string f, any rect

Discussion

Use this function to adjust the size of a movie.

Matrix Functions

Discussion

All visual tracks of a QuickTime movie can be manipulated through a transformation matrix. Altering this matrix changes the display of the track without altering the track's media data itself. This is similar to setting the volume of a sound track, which also does not alter the sound samples.

With QTMovieXtra you have access to several functions to manipulate this transformation matrix to scale, translate, rotate or skew a track within a QuickTime movie.
All transformations are applied to the current matrix of the track, i.e. if you have an already rotated track the next rotation will rotate this track again.

qtmResetTrackMatrix

*qtmResetTrackMatrix string f, integer trk

Discussion:

This function resets the track matrix to the default value (an identity matrix). All matrix transformations are removed.

Example:

qtmResetTrackMatrix("myMovie.mov",2)

Removes all matrix transformations of track 2 of the movie "myMovie.mov".

qtmTranslateTrackMatrix

*qtmTranslateTrackMatrix string f, integer trk, integer x, integer y

Discussion

This function moves the track along the x- and y-axis inside the movie's coordinate system. Positive values for x move to the right. Positive values for y move down the y-axis.

Example:

qtmTranslateTrackMatrix("myMovie.mov",2,20,13)

Moves track 2 of the movie "myMovie.mov" 20 pixels to the right and 13 pixels down.

qtmRotateTrackMatrix

*qtmRotateTrackMatrix string f, integer trk, float deg, integer x, integer y

Discussion

This function performs a rotation of the transformation matrix. You have to provide the angle in degrees as a floating point value. Positive angles rotate the track matrix clockwise. The center of the rotation is provided by the x and y parameters.

Example

qtmRotateTrackMatrix("test.mov",2,45.0,160,120)

Rotate track 2 of movie "test.mov" 45 degrees clockwise around a point at 160 pixels to the right and 120 pixels down from the upper left corner of the movie.

qtmScaleTrackMatrix

*qtmScaleTrackMatrix string f, integer trk, float scaleX, float scaleY, integer x, integer y

Discussion

This function performs a scale operation on the transformation matrix. The scale values have to be provided as floating point values.

Example

qtmScaleTrackMatrix("test.mov",2,2.0,1.0,0,0)

Scales the width of track 2 of movie "test.mov" to double the width of the transformation matrix. Use the upper left corner of the movie as the center of the scale operation.

qtmSkewTrackMatrix

*qtmSkewTrackMatrix(string f, integer trk, float degX, float degY, integer x, integer y)

Discussion

This function performs a skew operation on the transformation matrix. The skew values have to be provided as floating point values.

Example

qtmSkewTrackMatrix("test.mov",2,45.0,0.0,0,0)

Skews the track 2 of the movie "test.mov" by a value of 45.0 degrees along the x axis.

qtmGetTrackDisplayBounds

*qtmGetTrackDisplayBounds(string f, integer trk)

Discussion

This function returns the bounding rectangle of the specified track after applying any of the matrix transformations.
If the specified track has no visual representation (sound) an empty rect is returned.

Example

put qtmGetTrackDisplayBounds("test.mov", 1)

qtmSetTrackMatrix

*qtmSetTrackMatrix string f, integer trk, any matrix

Discussion:

This function lets you set transformation matrix of a track with a matrix list.

Note:

See the new matrix calculation functions.

Example:

-- create a matrix which scales and offsets the track
myMatrix=qtmRectToRectMatrix(rect(0,0,640,480), rect(160,120,480,360))
qtmSetTrackmatrix("myMovie.mov", 1, myMatrix) 

Edit Session Functions

Discussion

If you use the editing functions of QTMovieXtra in the usual way, the movie is opened and closed/saved with every function call.
That is perfect if you want to edit only a few parameters of a movie. For more advanced editing tasks however, the overhead
of always opening and closing the movie file can slow down the whole process enormously.

The Edit Session functions allow to overcome these limitations. You can open a movie file exclusively for editing, call several edit functions and close the movie file when you're finished.

Functions which support the "Edit Sessions" are marked by .

After you have opened an "Edit Session", you can use an empty string as the (destination) file name to tell the QTMovieXtra to use the file opened for editing.

qtmOpenEditSession

*qtmOpenEditSession(string f)

Discussion:

This function opens the provided file exclusively for editing.

Note:

Only one "Edit Session" can be open. If you try to open another edit session you'll get an edit session already open error (-4010).

Example:

qtmOpenEditSession("myMovie.mov") -- open edit session for "myMovie.mov"

qtmSetTrackName("", 1, "first Track") -- Note: we use an empty string as file name

qtmSetTrackOffset("",1, 600)

qtmCloseEditSession() -- close the edit session and update the movie file

qtmCloseEditSession

*qtmCloseEditSession()

Discussion:

This function closes the previous started "Edit Session". The QuickTime movie is updated and all changes are saved to disk.

User Data Functions

Discussion

With the User Data Functions you can set and retrieve special information contained in a QuickTime movie or track of it.

The basic concept is pretty much like the ID3 tags in found in mp3 files, in fact you can read most of the ID3 tags with the qtmGetUserData function.

qtmSetUserData

*qtmSetUserData string f, integer trk, string type, string text

Discussion:

This function lets you set the information of the specified type to a track of QuickTime movie or the whole movie.
See the table below for available types.

Note:

You can only set the user data of Quicktime movies, other file types are not supported.

Example:

qtmSetUserData("myMovie.mov", -1, "ALBUM", "Quadrophenia") --set the entry "ALBUM" of the movie to "Quadrophenia"

qtmGetUserData

*qtmGetUserData string f, integer trk, string type

Discussion:

This function lets you get the information of the specified type of a track or the whole movie.
See the table above for available types.

Note:

This function will work also with mp3 files, AAC files are currently not supported.

Example:

put qtGetUserData("The Real Me.mp3", 1, "ARTIST") 
--"The Who" 

Tweening Functions

Discussion

With the Tweening functions you can add modifier tracks to existing tracks in a Quicktime movie to modify certain aspects of this track over time.

The original track is not changed in any way, the modifier track only affects the playback of the track.

qtmAddTweenTrack

*qtmAddTweenTrack string f, integer trk, string type, any datalist

Discussion:

This function add a modifier track to an existing track in the movie.

The general form of the datalist is a linear list of any number of linear lists containing a pair of time and value. The value depends on the tween type.

Note:

It is a good idea to have the tween track with the same duration and track offset of your source track.

To remove a tween track of a specific type pass an empty list for the datalist value.

Example:

-- fade in the volume
dur=qtmGetTrackInfo("test.mov", 1, [#duration]).duration  -- get the duration of track 1
dataList=[[0,0], [600,255], [dur, 255]] -- build the data list, here we fade the volume from 0 to 255 during the first second
qtmAddTweentrack("test.mov", 1, "volume", dataList ) --add a volume tween to the first track

The tween types:

volume

controls the volume of a sound track. You can provide values between 0 (silence) and 255 (full volume).

balance

controls the balance of a sound track. You can provide an integer value between -127 (left channel) and 127 (right channel)

blendlevel

controls the blend level of any visual track (video, text, flash etc.).
You can provide values between 0 and 255, very similar to the sprite property the blendlevel.
This is tween is performed internally by a tween of type graphicsmode, i.e. it is only a shortcut for a more complex notation.
The function qtmGetTweenData and qtmGetTweenTracks will allways return a tween of type graphicsmode.

alphablend

controls the blend level of any visual track (video, text, flash etc.).
This is very similar to blendlevel except the alpha channel of the source track is preserved.
You can provide values between 0 and 255, very similar to the sprite property the blendlevel.
This is tween is performed internally by a tween of type graphicsmode, i.e. it is only a shortcut for a more complex notation.
The function qtmGetTweenData and qtmGetTweenTracks will allways return a tween of type graphicsmode.

graphicsmode

here you can tween the color in a graphicsmode record over time. The graphicsmode must be the same for all entries.
See qtmSetTrackGraphicsMode for more details on the graphics mode.

matrix

controls the transformation matrix of the visual track over time. The interpolation is performed for every entry in the matrix.
For complex transformations it is necessary to have enough "key matrices" in between to have the desired effect.

See the Matrix Calculation Functions for ways to set up the desired matrices.

qtmGetTweenTracks

*qtmGetTweenTracks string f, integer trk

Discussion:

This function returns a list of tween tracks assigned to a particular track in your movie.
The returned list contains a linear list with two values for every tween track found.
The first value is the tween type, the second value the track number of the tween track.
If the movie or the track does not exist an error code is return.

Note:

This function will return an empty list, if the track does not have any tween track assigned.

Example:

put qtGetTweenTracks("Test.mov", 1) 
--[["volume", 2], ["balance", 3]]

track 1 of the movie "Test.mov" has two tween tracks assigned. One of type "volume" , it is track number 2. The other of type "balance" with track number 3.

qtmGetTweenData

*qtmGetTweenData string f, integer tweentrk

Discussion:

This function returns a list of tween data assigned to a particular tween track in your movie.
The format is the same as you would assign is with the qtmAddTweenTrack function.

Note:

If you have used the tween types blendlevel or alphablend the returned list represents the internal graphicsmode structures.

Example:

put qtGetTweenData("Test.mov", 2) 
--[[0, 0], [600, 255], [2400, 255], [3000, 0]]

Matrix Calculation Functions

Discussion

With the Matrix Calculation functions you can create and manipulate transformation matrices to use with tween type matrix of the tweening functions or to set the track matrix with the qtmSetTackMatrix function.

A track transformation matrix is a 3x3 matrix containing 9 floating point values to represent a two dimensional transformation.

qtmGetNewMatrix

*qtmGetNewMatrix

Discussion:

This function creates an identity matrix, i.e. a matrix which lead to no transformation at all.

Note for advanced users:

A mathematically correct identity matrix should have a value of 1 in the last entry:

|1 0 0|
|0 1 0|
|0 0 1|

Quicktime and this xtra, however, scales the last column of this matrix by a factor of 16384. To obtain a higher precision.

Keep that in mind, if you want to write your own code to manipulate these matrices.

Example:

put qtmGetNewMatrix()
-- [1.0000, 0.0000, 0.0000, 0.0000, 1.0000, 0.0000, 0.0000, 0.0000, 16384.0000]

qtmRectToRectMatrix

*qtmRectToRectMatrix any srcRect, any dstRect

Discussion:

This function returns a matrix list which represents a transformation from one rect to another.

Note:

This function is the easiest way to perform move and scale transformations of tracks.

Usually you will provide the unaltered source dimensions of your track as the source rectangle.

Example:

newmatrix=qtmRectToRectMatrix(rect(0,0,640,480), rect(0,0,320,240))

qtmRectToQuadMatrix

*qtmRectToQuadMatrix any srcRect, any quadList

Discussion:

This function returns a matrix list which represents a transformation from the source rect to a quad.

Note:

The quad list is in the same format as the sprite's quad property in Lingo.

Example:

quadMatrix = qtmRectToQuadMatrix(rect(0,0,640,480), sprite(5).quad) 

qtmTranslateMatrix

*qtmTranslateMatrix any matrixlist, float x, float y

Discussion:

This function takes a matrixlist and calculates an offset based on the values of x and y. A new matrixlist is returned.

Example:

transMatrix = qtmTranslateMatrix(qtmGetNewMatrix(), 320.0, 0.0)

qtmScaleMatrix

*qtmScaleMatrix any matrixlist, float scalex, float scaley, float x, float y

Discussion:

This function takes a matrixlist and scales around the values of x and y with the factors of scalex and scaley. A new matrixlist is returned.

Example:

scaledMatrix = qtmScaleMatrix(qtmGetNewMatrix(), 0.5, 0.5, 320.0, 0.0)

qtmRotateMatrix

*qtmRotateMatrix any matrixlist, float deg, float x, float y

Discussion:

This function takes a matrixlist and rotates around the values of x and y with the amount of deg degrees. A new matrixlist is returned.

Example:

rotatedMatrix = qtmRotateMatrix(qtmGetNewMatrix(), 45.0, 0.0, 0.0)

qtmSkewMatrix

*qtmSkewMatrix any matrixlist, float degX, float degY, float x, float y

Discussion:

This function takes a matrixlist and skewes around the values of x and y with the amount of degX and degY degrees. A new matrixlist is returned.

Example:

skewedMatrix = qtmSkewMatrix(qtmGetNewMatrix(), 45.0, 0.0, 320.0, 240.0)

Effect Functions

Discussion

With the Effect Functions of qtmMovieXtra you can use the built in effects of Quicktime to use with your movies.
There are several types of effects available, dependent on the number of source tracks they use.

• Zero source effects (Generators) don't need any source track, they simply generate a new effect track.
• One source effects (Filters) take one source track and apply a filter to them.
• Two source effects (Transitions) take two source tracks and generate a transition between these two tracks.

The resulting effect track is more or less the same as a regular video track and can be treated like this.

The sources of the effects can be any tracks which produce a visual output (like video, text, mpeg, flash) and even other effect tracks can be used as input for new effects. All effects are calculated in real time, so stacking several effects may serious playback problems on slower computers.

qtmAskEffectSettings

*qtmAskEffectSettings integer numSources, any options

Discussion:

This function displays a standard effect settings dialog dependent on your choice of sources.

A standard effect settings dialog for two source effects.

Options:

The parameter for options is a propertyList which controls additional options. You can pass a value of 0 to use the default values.

The following options are currently available:

#showtween
Some of the effect parameters can be tweened over time. To show the extended settings dialog to enter tweenable values set this property to 1.

#showCustomImage
To replace the standard preview images in the settings dialog with your own images set this property to 1.
You have to load your own thumbnail images before with the qtmSetEffectPreviewImage function to be used in the dialog box.

Example:

qtmAskEffectSettings(1,0) -- show the dialog for one source effects

qtmLoadEffectSettings

*qtmLoadEffectSettings string f

Discussion:

This function loads a previous saved effect setting.

Example:

qtmLoadEffectSettings("mySetting.qfx")

qtmSaveEffectSettings

*qtmSaveEffectSettings string nf

Discussion:

This function lets you save the current selected effect settings to a file for later retrieval.

Example:

qtmSaveEffectSettings(the applicationspath & "mySetting.qfx")

qtmGetEffectInfo

*qtmGetEffectInfo

Discussion:

This function return a property list with some information about the currently selected effect.

Note:

the following properties are currently returned:

#sourceCount - the number of sources the effect uses

#codec - an unique identifier for the effect

#typeName - a localized name of the effect, this string may vary under different languages

Example:

put qtmGetEffectInfo()
-- [#sourceCount: 2, #codec: "dslv", #typeName: "Cross Fade"]

qtmCreateEffectTrack

*qtmCreateEffectTrack string f, integer w, integer h, integer st, integer dur, integer trkA, integer trkB

Discussion:

This function creates the effect track with the current selected effect settings. Use qtmAskEffectSettings or qtmLoadEffectSettings to activate the settings.

Note:

Once a track is used as a source for the effect track the source track won't be visible in the movie. The output of the source track is redirected to the effect track.
Therefore the source track(s) should have the same duration and offset than the resulting effect track. You can use the qtmAddTrackSegment function if you want only a part of a track as the source of the effect.

Example:

err = qtmCreateEffectTrack("test.mov", 640, 480, 0, 6000, 1, 2)

Timecode Functions

Discussion

With the Timecode Functions of QTMovieXtra you can read and create timecode tracks.

For compatibility with Apples "Final Cut Pro ®" you can read and write a special user data item ("FCPTCSOURCE") with the qtmGetUserData and qtmSetUserData functions from/to the timecode tracks. This tag can have a value of "sourceTC", "sourceAux1" or "sourceAux2" to indicate the use of the timecode track.

qtmGetTimeCode

*qtmSetUserData string f, integer tctrk, integer ti

Discussion:

This function lets you retrieve the timecode information of the specified timecode track at a given time.
If there is no error this function returns a property list with all the information available from the specified timecode track.

Properties returned:

#frame
the timecode interpreted as frame number

#tcstring
the timecode as a string in the form "hh:mm:ss:ff"

#tapeName
the name of the source tape/reel

#tcTimeScale
the timecode's timescale in units per seconds

#tcFrameDuration
the frame duration of a single frame expressed in the timecode timescale

#tcNumFrames
the number of frames per seconds as integer (a NTSC timecode would return 30)

#tcDropFrame
a boolean flag indicating a drop frame timecode, like NTSC

#tc24HourMax
a boolean flag indicating if the timecode starts at 0 again after reaching a value of 24 hours

#tcNegTimesOK
a boolean flag indicating if negative time values are allowed

#tcCounter
a boolean flag indicating if the timecode is interpreted as counter

qtmCreateTimeCode

*qtmCreateTimeCode string f, any tcList

Discussion:

This function creates a new timecode track in the movie specified as defined in the property list. The new timecode track starts at the beginning of the movie.

Use the following properties to define the timecode:

Note:

The property #counter should only be set if you want to create a "counter timecode", set the tcCounter flag to 1 in this case as well.

Examples:

-- PAL (00:20:00:00)

qtmCreateTimeCode (fn, [#minutes:20, #tapeName: "myPALTape"])

-- NTSC (00:20:00:00)

qtmCreateTimeCode (fn, [#minutes:20, #tapeName: "myNTSCTape", tcDropFrame:1,    tcTimeScale:2997, tcNumFrames:30])

Error Codes

-1: "QuickTime not installed/too old"

-33: "Directory full"
-34: "disk full"
-35: "no such volume"
-36: "I/O error (bummers)"
-37: "bad file name"
-38: "File not open"
-39: "End of file"
-40: "tried to position to before start of file (r/w)"
-41: "memory full (open) or file won't fit (load)"
-42: "too many files open"
-43: "File not found"
-44: "diskette is write protected."
-45: "file is locked"
-46: "volume is locked"
-47: "File is busy (delete)"
-48: "duplicate filename"
-49: "file already open with with write permission"
-51: "refnum error"
-52: "get file position error"
-53: "volume not on line error (was Ejected)"
-54: "permissions error (on file open)"



-128: "Cancelled by user"

-157: "invalid color depth"

-192: "Resource not found"
-193: "Resource file not found"

-2003: "can't find handler" -- usually an invalid export request
-2008: "invalid media"
-2009: "invalid track"
-2010: "invalid movie"

-2011: "invalid SampleTable"
-2012: "invalid DataRef"
-2013: "invalid Handler"
-2014: "invalid duration"
-2015: "invalid time"

-2019: "Progress cancelled"

-50: "parameter error"

-4000: "invalid width"
-4001: "invalid height"
-4002: "invalid codec"
-4003: "invalid sample size"
-4004: "invalid sample rate"
-4005: "wrong channel count"
-4006: "wrong memberType" -- i.e. not a bitmap member
-4007: "get media error"
-4008: "invalid export type"
-4009: "settings not loaded"
-4010: "edit session already open"
-4011: "edit session not open"
-4012: "list expected"
-4013: "invalid type"
-4014: "unsupported tween"
-4015: "rect expected"
-4016: "quad expected"
-4017: "invalid time"
-4018: "invalid source count"
-4019: "invalid frame rate"

-2147483643: "Parameter Error" --wrong type

Version History

1.0.0

• first release

1.0.1

• fixed a bug when using an invalid codec specifier in the new function
• refined some error codes for the generic parameter error (-50) to more meaningful versions (starting at -4000)
• all functions which create new files now report a duplicate filename error (-48) if the file already exists instead of overwriting the file without warning
• added the qtmDeleteFile function
• added the qtmExportDV function
• added the qtmMoviePictToMember function
• added the qtmSetTrackBalance function and the #balance selector in the qtmGetTrackInfos function
• added the qtmSetTrackLayer function and the #layer selector in the qtmGetTrackInfos function
• added the qtmSetTrackGraphicsMode function and the #graphicsmode selector in the qtmGetTrackInfos function
• added the qtmResetTrackMatrix, qtmTranslateTrackMatrix, qtmRotateTrackMatrix, qtmScaleTrackMatrix and qtmSkewTrackMatrix functions
• added the qtmGetTrackDisplayBounds function

1.0.2

• added the qtmAskExportSettings function
• added the qtmLoadExportSettings function
• added the qtmSaveExportSettings function
• added the qtmDoExportWithSettings function

1.0.3

• added the "HintedMovie" selector for the qtmAskExportSettings function
• now full support for Alpha channels in the qtmAddFrame function for cast members
• added the qtmGetMovieFrameCount and qtmGetMovieFrameRate functions

1.0.4

• qtmMoviePictToMember now does not trim the white space any more
• qtmScaleTrackSegment added to documentation
• qtmFadeSoundTrack function added
• added support for "Edit Sessions" (qtmOpenEditSession/qtmCloseEditSession)
• added the #codec selector in the qtmGetTrackInfos function
• added the qtmInsertTrackSegment function
• added the qtmGetTrackInfo function
• added the qtmGetTrackCount function
• added support for .swf files in the qtmGetMovieFrameRate function (thanks to Merijn)

1.0.5

• fixed a bug in the qtmLoadExportSettings when trying to load a locked settings file/from a locked volume
• fixed a bug related to the Edit Session functions

1.0.6

• due to a bug in QuickTime 6 under Windows 98, the qtmMoviePictToMember function did not work correctly. This has been fixed
• added support for image objects in the qtmAddFrame function
• added the qtmMoviePictToImage function
• fixed a bug in the qtmExportMovie function where certain combinations of settings did not work
• added the qtmSetTrackQuality function
• added the #quality selector in the qtmGetTrackInfos and qtmGetTrackInfo functions
• added the qtmGetXtraVersion function
• added the qtmCheckInstalled function

1.0.7

• added the "3GPP" selector for the qtmAskExportSettings function
• fixed a bug in the qtmAddFrame function introduced in version 1.0.6

1.0.8

• added the qtmGetUserData and qtmSetUserData functions
• several bug fixes in the qtmExportMovie function on Windows
• several minor bug fixes and internal improvements

1.0.9

• added support for tweening and effect functions
• fixed a bug with sorenson codecs in the qtmExportMovie function under QiuckTime 7
• several minor bug fixes and internal improvements
• added the qtmSetCopyMode function
• fixed a bug in the qtmInsertTrackSegment with movie having different internal timescales

1.1.0

• first release for Adobe Director 11 with Unicode support and native MacIntel code
• added Timecode support with the qtmGetTimeCode and qtmCreateTimeCode functions
• added FCPTCSource tag to the qtmGetUserData and qtmSetUserData functions
• added qtmGetMovieBox and qtmSetMovieBox functions
• added the qtmScaleMovieSegment function
• added support for hi resolution audio export via the qtmAskExportSettings function (DIR 11 versions only)
• added the qtmGetExportTypeList function to get information about any installed export component
• added support for "TypeCodes" inside the qtmAskExportSettings function to enable the creation of valid export settings for any installed export component