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.

 

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:

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

This function lets you register your copy of QTMovieXtra

     
Parameters: object xtraRef a reference of the xtra
  string name the name under the xtra is registered
  string serialnumber the serialnumber as a string
return: error code 1: registered successfully, otherwise 0

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

returns a linear list of all installed codecs.
Every codec is represented by a string of four characters.

     
Parameters: none  
return: linear list a linear list of all installed codecs

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

returns a linear list of all names of the installed codecs.
The order of this list correspondents to the list returned by qtmGetCodecList.

     
Parameters: none  
return linear list a linear list of the names of all installed codecs

Example:

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

qtmGetTrackInfos

*qtmGetTrackInfos string f, symbol type

returns a linear list of infos about all track of a movie.
Depending of the type symbol different infos are provided.

     
Parameters: string f absolute or relative path to moviefile
  symbol type type of info requested
return: linear list  

The following symbols are defined:

#type

returns the type of all tracks of the file specified.

#sound
a sound track
#video
a video track
#text
a text track
#mpeg
a multiplexed MPEG1 track
#music
a music track (MIDI)
#timecode
a timecode track
#sprite
a sprite track
#flash
a Flash track
#movie
a movie track
#tween
a modifier track for special effects
#basemedia
a base media track
#QD3D
a QuickDraw3D-track
#unknown
none of the above
#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 "
MPEG1 audio layer 2 (.mp2)
"m1v "
MPEG1 video stream
"m1s "
MPEG1 system stream (muxed)
"m2v "
MPEG2 video stream
"m2s "
MPEG2 system stream (muxed|VOB)
"mp4v"
MPEG4 video stream
"mp4a"
MPEG4 audio straem (AAC)
"drms"
MPEG4 audio stream (AAC) protected
"raw "
8bit audio uncompressed
"twos"
16bit audio uncompressed (Big endian)
"sowt"
16bit audio uncompressed(Little endian)
".mp3"
MPEG1 audio layer 3 (.mp3)
"musi"
a midi file
#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

returns a property list of infos about one track of a movie.
Depending on the list of type symbols different infos are provided.

     
Parameters: string f absolute or relative path to moviefile
  integer trkNum the track number of interest
  any typeList a linear list of types you are interested in
return: property list|error  

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

returns the number of tracks in a movie

     
Parameters: string f absolute or relative path to moviefile
return: integer count  

Discussion:

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

Example:

put qtmGetTrackCount("myMovie")
-- 3

qtmGetProgFunction

*qtmGetProgFunction

 

This function returns the progress function currently set.

     
Parameters: none  
return: symbol the symbol of the progress function in use

 


qtmSetProgFunction

*qtmSetProgFunction symbol func

 

This function sets the progress function to be used by subsequently issued exports

     
Parameters: symbol func the progress function to use
return: error code 0: no error

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

This function return the duration of the movie

     
Parameters: string f the filename of the movie
return: duration/error code the duration or an error (negative value)

Discussion:

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

 


qtmSelectFileDialog

*qtmSelectFileDialog

This function shows a file selection dialog

     
Parameters: none  
return: string full path to file or empty string on cancel/error

 


qtmGetQuickTimeVersion

*qtmGetQuickTimeVersion

This function return the version of QuickTime installed

     
Parameters: none  
return: string the version of QuickTime

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

This function return the version of QTMovieXtra

     
Parameters: none  
return: string the version of QTMovieXtra

Example

put qtmGetXtraVersion
-- "1.1.0"



qtmCheckInstalled

*qtmCheckInstalled symbol what

This function lets you check, if certain components are installed

     
Parameters: symbol what the component to check
return: integer result 1 - installed, otherwise 0

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

This function deletes the file

     
Parameters: string f the filename of the file to delete
return: error code  

Discussion:

A function to delete any file.

Example:

qtmDeleteFile("a movie.mov")

qtmGetMovieFrameCount

*qtmGetMovieFrameCount string f

This function returns the frame count of a movie

     
Parameters: string f the filename of the file
return: error code|count frame count or error code

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

This function returns the average frame rate of a movie

     
Parameters: string f the filename of the file
return: error code|rate frame rate or error code

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

This function returns the rectangle of the movie

     
Parameters: string f the filename of the file
return: error code|rect the rectangle of the whole movie

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

create a new xtra instance for authoring a QuickTime movie

     
Parameters: me the reference to the xtra itself
  nf full path to the new movie
  w the width of the new movie
  h the height of the new movie
  fr the framerate of the movie as floating point number
  codec the desired codec, see qtmGetCodecList
  quality the compression quality (0...1024)
     
return: the xtra object or error  

 

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

add a video frame to the new movie created.

     
Parameters: me the xtra instance created by new
  memberOrFileOrImage a bitmap castmember or the filename of an image file or an image object
return: error code  

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

add a sound to the new movie created.

     
Parameters: me the xtra instance created by new
  f the source file of your sound to be added
  srctrk the source track of the sound to be added
  st the start time of the sound
  dur the duration of the sound (-1 = complete sound)
  dt the destination time in the movie, where the sound is added
  vol the volume of the sound added
     
return: error code  

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

saves your movie

     
Parameters: me the xtra instance created by new
     
return: error code  

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

creates a new self contained movie. All references to other files are resolved.
Flatten does not recompress any of the tracks.

     
Parameters: f file path of the movie to flatten
  nf full path to the exported movie
return: error code  

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

opens the standard export file dialog to specify the destination file and lets you choose any options you like.

     
Parameters: f file path of the movie to export
return: error code  

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.

exportdialog

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

export all sound tracks of a movie to an AIFF sound file.

     
Parameters: f file path of the movie to export
  nf full path to the new file to create
  bits the desired sample size (8|16)
  rate the desired samplerate in Hz
  channels number of channels (1=mono, 2=stereo)
  comp a symbol for the desired compression
  showsettings a flag controlling the kind of setting dialogs shown
     
return: error code  

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

export all sound tracks of a movie to a WAVE sound file.

     
Parameters: f file path of the movie to export
  nf full path to the new file to create
  bits the desired sample size (8|16)
  rate the desired samplerate in Hz
  channels number of channels (1=mono, 2=stereo)
  showsettings a flag controlling the kind of setting dialogs shown
     
return: error code  

 

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

export the source movie as a new Quicktime movie

     
Parameters: f string file path of the movie to export
  nf string full path to the new file to create
  vSetList any the desired sample size (8|16)
  sSetList any the desired samplerate in Hz
  showsettings integer a flag controlling the kind of setting dialogs shown
     
return: error code  

vSetList

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

property lingotype value range description default
         
#width integer 0..x the new width of the video track original width
#height integer 0..y the new height of the track original height
#codec string 4 character string the codec for compression (qtmGetCodecList) "rle " (Animation)
#spatialQuality integer 0..1024 the quality how a single frame is compressed 1024 (maximal quality)
#temporalQuality integer 0..1024 the quality how difference frames are compressed 1024 (maximal quality)
#frameRate integer 1..n the new framerate of the movie use original frameRate
#keyFrameRate integer 1..n controls after how many frames a new keyframe is inserted 1 (always use full frames)
#dataRate integer 1..n the maximum of the dataRate desired
in KByte
0 (no datarate restrictions)
#colordepth integer 1,2,4,8,16,24,32,
34,36,40
the new colordepth in bits
values above 32 are grayscale color tables with a
bitdepth of x-32 bits
use best depth
         
         

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:

property lingotype value range description default
         
#bits integer 8,16 the sample size of the new soundtrack 16
#rate integer 8000..96000 the new sample rate of the soundtrack in Hz 22050
#channels integer 1,2 the number of channels in the new soundtrack 2
#codec string 4 char string

none
ima4
ulaw
alaw
the sound codec

uncompressed
IMA 4:1
µLaw 2:1
aLaw 2:1
"none" (uncompressed)
         
         

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)

exports the movie as DV stream

     
Parameters: string f file path of the movie to export
  string nf full path to the new file to create
  integer NTSC boolean flag (1=NTSC, 0=PAL)
  integer audioLock boolean flag for locked audio
  integer rate the desired samplerate in Hz (32000, 44100, 48000)
  showsettings a flag controlling the kind of setting dialogs shown
     
return: error code  

 

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)

exports a picture of the movie to a bitmap cast member

     
Parameters: string f file path of the movie to export
  integer time the movietime the picture should be taken
  any member the cast member reference of a bitmap member to store the picture
     
return: error code  

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)

exports a picture of the movie to an image object

     
Parameters: string f file path of the movie to export
  integer time the movietime the picture should be taken
     
     
return: error/image the image or error code

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

shows the appropriate settings dialog for the specified export type

     
Parameters: string f file path of a movie to export
  string type the export type or the typeCode returned by qtmGetExportTypeList()
     
return: error code  

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:

Type Description Notes
Movie Export settings for QuickTime movies  
AIFF Export settings for AIFF files  
Wave Export settings for WAVE files  
PICT Export settings for PICT files exports the first frame of the movie
BMP Export settings for BMP files exports the first frame of the movie
DV Export settings for DV streams  
Sequence Export settings for image sequences  
AVI Export setting for AVI files  
MPEG4 Export settings for MPEG 4 files only valid for QuickTime version 6 or higher
on Windows: no audio enconding available
MPEG2 Export settings for MPEG 2 files only valid under MacOS if the MPEG2 export component from "DVD Studio Pro" is installed
MPEG1 Export settings for MPEG 1 files only valid under MacOS with "Toast Video CD Support" installed
hintedMovie Export settings for hinted movies new in version 1.0.3
3GPP Export settings for 3G files new in version 1.0.7

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

loads the export settings from a file

     
Parameters: string f file path to the settings file
     
return: error code  

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

saves the export settings to a file

     
Parameters: string nf full file path to the settings file
     
return: error code  

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

export a movie to a new file using settings previously loaded

     
Parameters: string f file path to the source movie/file
  string nf full path to the new file
return: error code  

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

This function returns a list of available exporters

     
Parameters: string fn the path to a file (can be an empty string)
return: list exporters the list of available exporters

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:

Property Description Example
#name the name of the component "WAVE"
#info an info string about the component "Exports a QuickTime Movie into a WAV sound file"
#exporter the codec code of the component (4 chars) "WAVE"
#manufacturer the vendor of the component (4 chars) "soun"
#typecode a unique identifier for that component "$WAVEsoun"
#hasDialog a flag if the exporter has a dialog 1
#extension the preferred file extension ".wav"

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

creates a new empty movie.

     
Parameter string nf full path to the new movie
return: error code  

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

inserts a segment of a movie into the destination movie.

     
Parameter string f path of the source movie
  string df path to the destination movie
  integer st start time of the segment in the source movie
  integer dur duration of the segment (-1 = whole movie)
  integer dt destination time in the destination movie (-1 = append at the end)
     
return: error code  

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

deletes a segment of a movie.

     
Parameter f path of the movie
  st start time of the segment to delete
  dur duration of the segment to delete (-1 = whole movie)
     
return: error code  

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

adds a segment of a track to a movie

     
Parameter string f path of the source movie
  string df path to destination movie
  integer trk track number for source track
  integer st start time of the source track segment
  integer dur duration of the segment to insert (-1 till end)
  integer dt destination time, where the track segment is to be added
     
return: error code  

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

insert a segment of a track to a movie

     
Parameter string f path of the source movie
  string df path to destination movie
  integer srctrk track number for source track
  integer dsttrk track number for destination track
  integer st start time of the source track segment
  integer dur duration of the segment to insert (-1 till end)
  integer dt destination time, where the track segment is to be added
     
return: error code  

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

deletes a segment of a track.

     
Parameter string f path of the movie
  integer trk track number
  integer st start time of the segment to delete
  integer dur duration of the segment to delete (-1 = until the end of the track)
     
return: error code  

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

changes the duration of a track.

     
Parameter string f path of the movie
  integer trk track number
  integer st start time of the segment to be scaled
  integer dur duration of the segment to be scaled(-1 = until the end of the track)
  integer newdur the new duration of the track segment
return: error code  

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

changes the duration of a track.

     
Parameter string f path of the movie
  integer st start time of the segment to be scaled
  integer dur duration of the segment to be scaled(-1 = until the end of the track)
  integer newdur the new duration of the track segment
return: error code  

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

set the starting point of the track in the movie

     
Parameter string f path of the movie
  integer trk track number
  integer st start time of the track in the movie (the offset)
     
return: error code  

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

enables/disables the specified track of a movie

     
Parameter string f path of the movie
  integer trk track number
  integer bool 1 = enable, 0=disable
     
return: error code  

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

set the width and height of a visual track

     
Parameter string f path of the movie
  integer trk track number
  integer w the width in pixels
  integer h the height in pixels
return: error code  

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

Set the width and height of a visual track

     
Parameter string f path of the movie
  integer trk track number
return: error code  

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

Set the name of a track

     
Parameter string f path of the movie
  integer trk track number
  string name the name of the track
return: error code  

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

Set the volume of a sound track

     
Parameter string f path of the movie
  integer trk track number
  integer vol the volume to set
return: error code  

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

Set the balance of a sound track

     
Parameter string f path of the movie
  integer trk track number
  integer balance the balance to set
return: error code  

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

Set the layer of a visual track

     
Parameter string f path of the movie
  integer trk track number
  integer layer the layer to set, layers are numbered from -32,768 through 32,767.
return: error code  

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

set the graphics mode a visual track

     
Parameter string f path of the movie
  integer trk track number
  list gmList linear list containing the mode and an optional color
     
return: error code  

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:

mode value opColor description
copy 0 unused like "copy" ink
dithercopy 64 unused like "copy" ink, but dithered on lower colordepth (default)
blend 32 blendColor Darker values for blendColor lead to more transparent results.
For color neutral blends use levels of gray as the blend color.
transparent 36 the transparent color like "background transparent" ink
straight alpha 256 unused use the alpha channel of the track.
premul white alpha 257 unused use the alpha channel of the track.
removes the white "halo" effect if the original graphic was rendered on a white background.
premul black alpha 258 unused use the alpha channel of the track.
removes the black"halo" effect if the original graphic was rendered on a black background.
straight alpha blend 260 blendColor use the alpha channel of the track and perform an additional blend.
composition 259 unused obviously the same as dithercopy

You may also find the following graphics modes useful:

mode value opColor description
srcOr 1 unused  
srcXor 2 unused  
srcBic 3 unused  
notSrcCopy 4 unused reverse
notSrcOr 5 unused  
notSrcXor 6 unused  
notSrcBic 7 unused  
addPin 33 unused  
addOver 34 unused  
subPin 35 unused  
addMax 37 unused  
subOver 38 unused  
addMin 39 unused  

 


qtmFadeSoundTrack

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

adds a modifier track to fade the sound

     
Parameter string f path of the movie
  integer trk track number
  integer from start volume, -1 to remove the tween track
  integer to end volume, (ignored if from is -1)
return: error code  

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

Set the quality settings of a track

     
Parameter string f path of the movie
  integer trk track number
  integer quality the quality setting
return: error code  

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

Set the Copy Mode flag

     
Parameter integer mode the flag to set
return: error code 0

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

Set the movie box

     
Parameter string f the filename of the movie
  rect box the new movie box
return: error code 0

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

resets the track's transformation matrix to the default

     
Parameter string f path of the movie
  integer trk track number
return: error code  

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

performs a move of the specified track along the x- and y-axis

     
Parameter string f path of the movie
  integer trk track number
  integer x number of pixels to move the track
  integer y number of pixels to move the track
return: error code  

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

performs a rotation of the specified track

     
Parameter string f path of the movie
  integer trk track number
  float deg angle to rotate (in degrees)
  integer x center of the rotation (x)
  integer y center of the rotation (y)
return: error code  

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

performs a scale of the specified track matrix

     
Parameter string f path of the movie
  integer trk track number
  float scaleX the scale value in x direction
  float scaleY the scale value in y direction
  integer x center of the scale operation (x)
  integer y center of the scale operation (y)
return: error code  

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)

performs a skew of the specified track matrix

     
Parameter string f path of the movie
  integer trk track number
  float degX the skew value in x direction (in degrees)
  float degY the skew value in y direction (in degrees)
  integer x center of the skew operation (x)
  integer y center of the skew operation (y)
return: error code  

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)

get the bounding rectangle of the specified track

     
Parameter string f path of the movie
  integer trk track number
return: rect the bounding rectangle

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

set user data to a track or the movie

     
Parameter string f path of the movie
  integer trk the track number or -1 for the movie
  list matrix the matrix list
     
return: integer error error code

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)

opens an edit session

     
Parameter string f path of the movie
     
return: integer error error code

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()

close the edit session

     
     
return: integer error error code

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

set user data to a track or the movie

     
Parameter string f path of the movie
  integer trk the track number or -1 for the movie
  string type the type of information to add
  string text the text to add
     
return: integer error error code

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"

 

  User Data Types available  
  ALBUM
ARTIST
AUTHOR
CHAPTER
COMMENT
COMPOSER
COPYRIGHT
CREATIONDATE
DESCRIPTION
DIRECTOR
DISCLAIMER
ENCODEDBY
FULLNAME
GENRE
HOSTCOMPUTER
INFORMATION
KEYWORDS
MAKE
MODEL
ORIGINALARTIST
ORIGINALFORMAT
ORIGINALSOURCE
PERFORMERS
PRODUCER
PRODUCT
SOFTWARE
REQUIREMENTS
TRACK
WARNING
WRITER
URLLINK
EDITDATE1
EDITDATE2
EDITDATE3
EDITDATE4
EDITDATE5
EDITDATE6
EDITDATE7
EDITDATE8
EDITDATE9

 


qtmGetUserData

*qtmGetUserData string f, integer trk, string type

set user data to a track or the movie

     
Parameter string f path of the movie
  integer trk the track number or -1 for the movie
  string type the type of information to get
     
return: string text the text

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

this function adds a modifier track (tween track) to the movie controlling a source track

     
Parameter string f path of the movie
  integer trk the track number to be modified
  string type the type of tween
  list datalist the tween data
     
return: integer error error code

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

 

  Tween types available source track type internal tweentype value range
  volume
balance

blendlevel
alphablend
graphicsmode
matrix
sound
sound

visual
visual
visual
visual
volume
balace

graphicsmode
graphicsmode
graphicsmode
matrix
0..255
-127..127

0..255
0..255
see qtmSetTrackGraphicsMode
matrix list

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

returns the tween tracks of a given track with their type, if any

     
Parameter string f path of the movie
  integer trk the track number
     
return: list/error code a list of tween tracks assigned to the track

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

returns the tween tracks of a given track with their type, if any

     
Parameter string f path of the movie
  integer tweentrk the track number of the tween track
     
return: list/error code a list of tween data

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

this function adds a modifier track (tween track) to the movie controlling a source track

Parameter none  
     
return: list identity matrix

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

returns a matrix which represents a transformation from one rect to another

Parameter rect srcRect the source rect
  rect dstRect the destination rect
     
return: list/error code the resulting matrix

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

returns a matrix which represents a transformation from one rect to a quad

Parameter rect srcRect the source rect
  list quad the quad list
     
return: list/error code the resulting matrix

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

returns a translated matrix

Parameter list matrixlist the matrix to translate
  float x the x offset to translate the matrix
  float y the y offset to translate the matrix
     
return: list/error the resulting matrix

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

returns a scaled matrix

Parameter list matrixlist the matrix to scale
  float scalex the horizontal scaling factor
  float scaley the vertical scaling factor
  float x the x location of the center of the scaling operation
  float y the y location of the center of the scaling operation
     
return: list/error the resulting matrix

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

returns a rotated matrix

Parameter list matrixlist the matrix to rotate
  float deg the degrees to rotate
  float x the x location of the center of the rotating operation
  float y the y location of the center of the rotating operation
     
return: list/error the resulting matrix

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

returns a skewed matrix

Parameter list matrixlist the matrix to rotate
  float degX the degrees to skew
  float degY the degrees to skew
  float x the x location of the center of the skew operation
  float y the y location of the center of the skew operation
     
return: list/error the resulting matrix

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.

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

this function displays a standard effect settings dialog

Parameter integer numSources the number of sources you want to choose an effect
  any options a propertyList with additional options, pass 0 for standard values
     
return: integer error an error code

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

loads a previous saved effect setting into memory to use

Parameter string f the filename to the saved settings
     
return: lerror code an error code, 0 for success

Discussion:

This function loads a previous saved effect setting.

Example:

qtmLoadEffectSettings("mySetting.qfx")

qtmSaveEffectSettings

*qtmSaveEffectSettings string nf

saves the current selected settings to a file

Parameter string nf the full pathname to the new settings file
     
return: lerror code an error code

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

returns information about the current selected effect

Parameter none  
     
return: list/error a property list with information/error

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

create the effect track with the current effect settings

Parameter string f the filename of the movie
  integer w the width of the new effect track
  integer h the height of the new effect track
  integer st start time of the effect track
  integer dur duration of the effect track
  integer trkA track number of the first source track, set to 0 if the effect uses fewer sources
  integer trkB track number of the second source track, set to 0 if the effect uses fewer sources
     
return: lerror code an error code

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

read the timecode information of a given timecode track

     
Parameter string f path of the movie
  integer tctrk the track number of the timecode track
  integer ti the time of interrest
     
return: integer | property list error code or property list with information

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

create a new timecode track

     
Parameter string f path to the movie
  any tcList a property list defining the timecode
     
return: integer error error code

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:
property type default note
hours integer 0  
minutes integer 0  
seconds integer 0  
frames integer 0  
counter integer 0 only for counter mode
duration integer movie duration  
tapeName string empty string  
negative integer (0|1) 0  
tcDropFrame integer (0|1) 0  
tcNegTimesOK integer (0|1) 0  
tc24HourMax integer (0|1) 0  
tcCounter integer (0|1) 0  
tcTimeScale integer 2500  
tcFrameDuration integer 100  
tcNumFrames integer 25  

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

1.0.1

1.0.2

1.0.3

1.0.4

1.0.5

1.0.6

1.0.7

1.0.8

1.0.9

1.1.0