QuickTimeTcl Commands - movie manual page

To conform better with the Tcl coding practice, the old Movie command (with an uppercase M) has been replaced with the movie command (all lowercase). Although the old Movie command is still supported, its use is discouraged.

WIDGET-SPECIFIC OPTIONS

Command-Line Name: -controller

Database Name: controller

Database Class: Controller

A boolean of 0 or 1 specifies if the default QuickTime controller should be attached to the movie. It defaults to 1. The controller allows the user to interact with the movie in a simple way. Moreover, for an VR panoramic picture a controller is the only way to interact with the movie. All user actions that is received by a controller are handled internally in QuickTime. Unless you specify a tcl command via the mccommand, tcl is unaware of what is happening the movie when a controller is attached. If a controller is removed from a movie that has the loopstate or palindromeloopstate set, these options are also removed together with the controller.

Command-Line Name: -custombutton

Database Name: customButton

Database Class: CustomButton

A boolean of 0 or 1 specifies if the movie controller, if any, has a custom button placed at its right end. It defaults to 0. To do anything useful, a Tcl command must be registered with mccommand. The global coordinates of the mouse click can be used to pop up a Tcl menu, for instance. A custom button is typically used in the QuickTime plugin for web browsers, where it is used for a pop up menu so that the user can perform some simple tasks from the controller directly, such as to save the movie to disk.

Command-Line Name: -file

Database Name: file

Database Class: File

Specifies the file path for the file to read the movie from. For instance, the following sequence first displays the first movie, and then, if necessary, resize, and display the second movie:

movie .m -file sample.mov
pack .m
.m configure -file qtvr.mov

Configurations you may have made with the previous movie are likely (?) to be lost while loading another movie in the same widget.

Command-Line Name: -highlightbackground

Database Name: highlightBackground

Database Class: HighlightBackground

Specifies the color to display in the traversal highlight region when the widget does not have the input focus.

Command-Line Name: -highlightcolor

Database Name: highlightColor

Database Class: HighlightColor

Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus.

Command-Line Name: -highlightthickness

Database Name: highlightThickness

Database Class: HighlightThickness

Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. If the value is zero, no focus highlight is drawn around the widget.

Command-Line Name: -height

Database Name: height

Database Class: Height

By default, the size of the movie widget is the "natural" size of the movie. If a nonzero value for either height or width is set, the movie will be this size. The default of 0 means that this option should be ignored, and the movies natural height be used. Note that these are "sticky" and are not cleared if the file name is changed.

Command-Line Name: -loadcommand

Database Name: loadCommand

Database Class: LoadCommand

Registers a Tcl command procedure to be called whenever the load state of a remote movie changes, and it allows the loading to be asynchronous. If a movie is specified with the url option, the default behaviour is that everything that needs to be made in order to open the movie, network connections and such, is done in blocking mode. Since this is usually a somewhat time consuming process, using the loadcommand, the movie command returns immediately, and the registered tcl command gets called when something happens to the process of loading the movie. Specifying this command only allows the movie to be loaded asynchronously, it is not required to do so. This is handled internally in QuickTime, and is beoynd my control. The Tcl procedure should have this form:

proc MyLoadCommandProc { widget message {err {}} }

where widget is the movie widget, and message is one of loading, playable, playthroughok, or complete, in that order. Not each of the states is necessarily called, and any single state may be called more than once. The movie cannot be mapped or configured until its state is at least playable, and it cannot be saved to disk unless it is complete. When the state is at least playthroughok, the movie can be started and played to end without any intermittency. If err is nonzero, an error has occured, where err contains a descriptive message.

Command-Line Name: -loadintoram

Database Name: loadIntoRam

Database Class: LoadIntoRam

A boolean value determines if the movie should be completely read into memory. It defaults to false. This is only advisable for small movies. Alert sounds, and other small size sounds, that need to be started without the extra time delay a disk access implies, can be stored into memory this way.

Command-Line Name: -loopstate

Database Name: loopstate

Database Class: Loopstate

A boolean value determines the movie's loopstate. It is 0 for ordinary playback, but if 1, the movie is restarted from the beginning once it has reached its end, indefinitely. To start looping a movie, first set its loopstate, and then play it.

Command-Line Name: -mccommand

Database Name: mcCommand

Database Class: MCCommand

Registers a Tcl command procedure to be called from the QuickTime movie controller. This enables the script writer to monitor what is going on inside the controller. The argument to mccommand is just the name of the Tcl procedure. The Tcl command function should have this form:

proc MyMCCommandProc {widget message {par {}}}

where widget is the movie widget path, message any of activate, customButtonClick, deactivate, key, goToTime, mouseDown, play, setSelectionBegin, setSelectionDuration, or setVolume. Some messages have parameters associated with them; customButtonClick appends a list {x y}, where x and y are the global coordinates of the mouse click on the custombutton; the goToTime appends a list of three time values { hiTime loTime timeScale} as a response to interactions with the scale button, where hiTime is the high order number of the position (usually 0), loTime the (lo)position in the movie, and timeScale the movie's time scale; key appends the actual character pressed; mouseDown appends a list {x y}, where x and y are the global coordinates of the mouse click inside the movie; setSelectionBegin appends the start selection movie time if the controller with -mcedit enabled is shift dragged, tends to repeat itself also if only setSelectionDuration changes; setSelectionDuration appends the duration of the selection in movie time if the controller with -mcedit enabled is shift dragged; play appends the rate (from 0.0 to 1.0) at which the movie is played when the play button is clicked, and is 0.0 when the movie stops; setVolume appends the volume set as a number between -256 and 256, where 0 is no volume. There are more message types than can be implemented if needed.

For QTVR panoramic movies, not all of the above callbacks apply, and instead some additional callbacks are valid. The additional messages are fieldofview, pan, tilt, and triggerhotspot. The parameter associated with the fieldofview is a float of unknown dimension, pan and tilt are associated angles in degrees. The triggerhotspot is followed by an id number of the hot spot the user clicked.

If the tcl callback procedure returns a break result code, by return -code 3 (is there a better way?), the corresponding action in the movie is not taken place. This may be used to constrain user actions in movies.

Command-Line Name: -mcedit

Database Name: mcEdit

Database Class: MCEdit

A boolean value determines if editing is possible via the controller. Shift drag the controller to make a movie selection. Many more paste operations are possible since all movie import components are made available. See EDITING.

Command-Line Name: -palindromeloopstate

Database Name: palindromeLoopstate

Database Class: PalindromeLoopstate

A boolean value determines the movie's palindrome loopstate. It is 0 for ordinary playback, but if 1, the movie starts to play backwards when it has reached its end, and starts to play forward again when it has reached its beginning, indefinitely. To start palindrome looping a movie, first set its palindrome loopstate, and then play it.

Command-Line Name: -preferredrate

Database Name: preferredRate

Database Class: PreferredRate

The default playback rate for the movie, between -1.0 and 1.0, where 1.0 is the normal play rate. Slow motion playback is achieved by a rate smaller than 1.0, and the movie runs backward for negative rates. This option is only effective if the play command is used---if you use the controller it plays with a rate 1.0.

Command-Line Name: -progressproc

Database Name: progressProc

Database Class: ProgressProc

Specifies a Tcl progress procedure which will be called every once in a while by QuickTime while a long operation is going on. The argument to progressProc is just the name of the Tcl procedure. The Tcl progress function should have this form:

proc MyProgressProc {widget message operation percent}

where widget is the movie widget path, message any of open, percent, close, or cancel, the operation is a text describing the QuickTime operation taking place, and percent is a number between 0 and 100 telling the percentage done. If you are going to cancel the operation, then return a break code: return -code 3 (is there a better way?).

Command-Line Name: -qtprogress

Database Name: qtProgress

Database Class: QTProgress

A boolean specifies if the standard QuickTime progress window should be displayed during long operations. It defaults to 1. If progressProc is set, that one is used instead of this.

Command-Line Name: -qtvrqualitymotion

Database Name: qtvrQualityMotion

Database Class: QTVRQualityMotion

Specifies the imaging rendering quality for moving images of QTVR panoramas. It is one of min, low, normal, high, or max. Its value is normally stored in the movie file.

Command-Line Name: -qtvrqualitystatic

Database Name: qtvrQualityStatic

Database Class: QTVRQualityStatic

Specifies the imaging rendering quality for static images of QTVR panoramas. It is one of min, low, normal, high, or max. Its value is normally stored in the movie file.

Command-Line Name: -resizable

Database Name: resizable

Database Class: Resizable

This is a boolean option of 0 or 1 that specifies if a resize button should be placed in the right end of the controller. It defaults to 0. The resize button enables the user to resize the movie, keeping the proportions between width and height. By a click and drag action, a gray ghost rectangle is drawn to show the movies final size. The size change is automatically propagated to the Tcl geometry management system when the button is released.

Command-Line Name: -swing

Database Name: swing

Database Class: Swing

This is a boolean option of 0 or 1 that specifies if a QTVR panoramic movie should transition smoothly when setting any of fieldofview, pan, or tilt. Only applicable for a QTVR panoramic movie. The speed is set by the -swingspeed option.

Command-Line Name: -swingspeed

Database Name: swingSpeed

Database Class: SwingSpeed

This sets the transition speed when setting any of fieldofview, pan, or tilt. Only applicable for a QTVR panoramic movie. The -swing option must be enabled.

Command-Line Name: -url

Database Name: url

Database Class: Url

This is a text string that specifies where to get the movie. It must be a valid url, and you must be connected to a network for it to be downloaded. It is allowed to have an ordinary file path, even relative ones, like ../Movies/snakes.mov. Both the file and the url option cannot be specified simultaneously. The remote file can have any format that is accepted by QuickTime. It may be a movie that is stored on disk on the remote system, or it can be a small (typically 200 bytes) so called sdr file, that specifies how QuickTime should obtain the movie content as a live streaming audio/video movie. A movie controller must be attached to the movie to enable the user to control the operation. The operation to connect to the remote site, and to download as much of the movie to determine its size etc., is done in blocking mode if not a loadcommand is specified. On a slow dial up connection it can take some time; for a sdr file it usually doesn't take very long since it is so small. In addition, for a live stream (sdr file) the user must press the start button for QuickTime to make the neccessary connections; this is done in nonblocking mode. QuickTime recognizes a movie that has a format prepared for streaming (over ftp or http), and the command returns when enough has been downloaded to know its size etc. This usually corresponds to only a small portion of the total movie, and it is therefore usually reasonably fast. If a loadcommand is specified, the movie command returns immediately, but the movie cannot be used until the corresponding Tcl procedure has received a playable message. If you want to prepare your own movies for streaming they must first be flattened using the flatten command.

Command-Line Name: -volume

Database Name: volume

Database Class: Volume

Sets the volume of all the audio tracks in the movie, if any. It is a number between 0 and 255.

Command-Line Name: -width

Database Name: width

Database Class: Width

By default, the size of the movie widget is the "natural" size of the movie. If a nonzero value for either height or width is set, the movie will be this size. The default of 0 means that this option should be ignored, and the movies natural width be used. Note that these are "sticky" and are not cleared if the file name is changed.

DESCRIPTION

The movie widget is a widget for playback of video, audio, animations, and VR panoramic images. A QuickTime movie is the name of a hierarchical structure that organizes data that has a time structure, such as video and sound. On top of this hierarchy is the QuickTime movie itself. The movie has a timescale associated with it, typically 600, that tells how many "ticks" there are on each second. A position in the movie, or a duration of the movie, is always expressed in terms of the movie's time scale as an integer number. For instance, if a movie has a time scale of 600, then two seconds from the movie's beginning corresponds to a "time" 1200.

The movie contains a number of tracks. Each track has a unique ID number, that is unique through the lifetime of the movie. That is, if track 1 is deleted, there will never be a track 1 in this movie anymore. Each track may only contain one type of media. A media type specifies the sort of media, for instance, images, sounds, video etc. In the usual Mac way, a four letter combination specifies the media type. Choices are:

hndl : handle to the memory
MPEG : MPEG
musi : music
qd3d : QuickDraw 3D model
rsrc : resource
soun : sound
sprt : sprite animation
text : text
tmcd : time code
twen : 'Tween track
vide : video

Each track references one or many media samples which in turn points on the actual data for the movie. Each media has its own timescale which need not be identical to the movie's time scale. For example, a video track can have a time scale of 30 (frames per second), and an audio track 44,100 (samples per second). A movie file typically contains a movie, one or more tracks, each containing its own media samples, everything bundled together. A track must not extend from the movies beginning to its end. Instead, the offset specifies the start of the track, and the duration specifies the length of the track. Both values are expressed in terms of the movie's time scale. A movie's rate determines how many time scale units in the movie actually run each real-time second. For instance, if a movie's time scale is 600, a rate 1.0 means that QuickTime will process 600 scale units of the movie each second. A negative rate means the movie is running backwards. The play rate is the "speed" of the movie; if it's not playing it is 0.0. By setting the play rate to a nonzero value the movie may start playing.

Each track is associated with a layer, numbered from -32768 to 32767, that controls how tracks are combined to display a movie. QuickTime displays higher ordered layers first, placing lower-numbered layers on top of them. Each layer can be associated with any number of tracks. By default, a newly created track has layer 0.

The movie widget supports all formats that QuickTime supports. A few comments: a VR panoramic movie has no time structure but works roughly like an ordinary movie, with exceptions that operations that are time specific doesn't work. QuickTime supports many still image formats. These are included automatically via the image create photo command when QuickTimeTcl is loaded.

Movies may be files on a local disk, loaded with the -file option, or remote movies, loaded with the -url option. Realtime streaming movies are usually represented by a so called sdr file, typically with an extension .mov, that gets loaded internally in QuickTime when using the -url option. But it is also possible to get the sdr file, once located in a html page, by other means, such as a web browser or whatever. If this small sdr file on your local disk is specified with the -file option, QuickTime automatically understands that it should connect to a live stream. Well known streaming channels usually keep the sdr file unchanged, so you may speed up the process by using the local sdr file instead of specifying the -url option each time.

This package requires QuickTime version 3, but some options, such as the -url option, requires at least QuickTime 4. When new formats are introduced by Apple or others, the API's are usually unchanged, and the new formats are therefore automatically supported by this package. For detailed information on the supported file types for any particular QuickTime version visit www.apple.com/quicktime.

SOUND ONLY

Although most movies are associated with visual media, this is not always true, for instance, for movies with only a sound track. However, this movie widget is centered around a graphics widget, so how are sound only movies played if you dont want to see anything on the screen? To help you organize your sound movies, create a fake frame widget that never gets mapped. Then create your movies the ordinary way, but without a controller. An example:

frame .fake
movie .fake.m -file Madonna.mp3 -controller 0
.fake.m play

EDITING

Besides playback capabilities, and commands that are applied to a movie as one entity, there are commands that allow you to pick apart and assemble a movie by cut, copy, and paste. Editing is done in two different modes, either via a controller with editing enabled, using the -mcedit command, or without. We denote the last variant "simple" editing. Simple editing can be done with or without a controller, and some if its behaviour is different from editing through the controller, most notably the paste command. This is Apples choice, and not mine. Lets first describe simple editing:

There are two different editing capabilities provided for simple editing: movie editing, and track editing. Both way of editing typically use a time value and a duration, both expressed in the movie's time scale. Simple editing can only handle pasting other movies from the clipboard.

The movie editing commands act on all tracks in a movie---cutting a selection removes all tracks in that selection. In addition, there is one command that works selectively on certain tracks, the add command. The add command is like paste but it adds tracks in parallel, possibly using existing tracks to put the media in. A typical movie edit sequence is like:

.m select 1200 600
.m copy
.m select 2400
.m paste

Track editing, like tracks copy and tracks paste, has no high level support, and is only provided by references. There exist not a physical clipboard where track segments are kept, but the track clipboard is a fake clipboard that cannot hold track segments, only references to them. This limits track editing a bit. For instance, there is no tracks cut command. A number of the tracks sub commands act either on complete tracks, or on any existing selection of any track segment in the movie. There may be only a single track selection per movie. A typical track edit sequence is like:

.m tracks select 1 1200 600
.m tracks copy
.m tracks select 1 2400
.m tracks paste

Beware, do not mix movie editing with tracks editing, they don't work well together since tracks can't be pasted as movies and vice versa. Since track editing works by references, if the content referred to on the track clipboard is changed somehow, the track clipboard is invalidated. The following is valid to avoid interference between the movie and track clipboard, and to make it feel like one and the same clipboard:

A movie selection invalidates any track selection and vice versa.
If a movie segment is pasted to the clipboard, any track clipboard content is zeroed, and vice versa.

Editing via a controller with editing enabled (-mcedit) is like simple movie editing above, but more flexible in some situations. The controller knob changes its appearence when editing is enabled. Selections can be made by shift dragging the knob. The importer not only recognizes other movies, but also text, still images, and everything else that makes sense. This makes the paste command more flexible, and also enables some more options to the paste command.

TEXT

Text can be imported in a number of ways into a text track. The simplest way to import text into a movie is simply to use an ordinary text file for the -file option. The text importer creates a movie that has a text sample for every paragraph of text in the file. Each text sample will have a default duration of two seconds.

More control gives the pathName tracks add text ... command. Together with the graphics mode for the track it is possible to set the parts of the text track where no text is transparent. A typical code sequence can be:

% .m tracks new text
{-undostate 0} 3
% .m tracks add text 3 0 1200 {Hello world!}
{-undostate 1}
% .m tracks configure 3 -graphicsmode transparent -graphicsmodecolor black
% .m save

If you want to make a text movie from scratch, one example is the following:

% movie .m
% .m new myText.mov
-1
% .m tracks new text 100 200
{-undostate 0} 1
# The track id is 1.
% pack .m
% .m tracks add text 1 0 1800 Hello -scrollin 1 -scrollout 1 -font {Times 24 italic}
{-undostate 1}
% .m save

See the docs for the individual tracks command and options for detailed info.

There is also more complex way to import text via so called text descriptors, see for instance www.apple.com/quicktime/products/tutorials/texttracks.html, and www.apple.com/quicktime/products/tutorials/textdescriptors.html. Text descriptors enable many configuration options, such as font selection, colors, position, a time line for placing text, clickable URL's, and much more. The first piece in such a file is {QTText}. A minimalistic example is:

{QTText}{font:Tekton}{plain}{size:18}{textColor: 0, 0, 0}{backColor: 65535, 65535, 0}
{justify: center}{timeScale: 600}{width: 240}{height: 40}{shrinkTextBox:on}
[00:00:00.000]
{textBox: 10, 0, 30, 240}We forgot to seed!
[00:00:01.000]
{textBox: 10, 0, 30, 240}We forgot to what?
[00:00:02.000]
{textBox: 10, 10, 30, 240}Yes and No
[00:00:03.000]

The file must end with a time notation, and possibly a new line. Place your text descriptors in an ordinary text file, and just open a new movie specify this file as the -file option.

STILL IMAGES AS MOVIES

The movie importer is flexible enough to understand still images as well. This can have some advantages compared to the image create photo command, even if this command gets extended to many formats with QuickTimeTcl. Use -controller 0 to supress the controller. First, images can be resized to any size. Second, using the -url and -loadcommand an image can be loaded remotely and asynchronously. For the moment it is necessary to have a controller for this.

MAKING MOVIES

While this package does not help creating the actual content of a movie, it helps you to assemble the content into a movie. A typical movie contains an audio track and a video track. Assembling the audio track is best made by cutting and pasting of the individual tracks from some original sound track. Use the tracks editing commands here.

A video track consists of a sequence of still images. The images you must produce yourself, save them to disk in an appropriate format, import them into Tcl using the image create photo command. The key command for adding them to a movie is tracks add picture, which has enough options to use most of QuickTime internals for building a movie. In order to build a movie that takes up a minimum of storge, yet has good playback and image qualites, you must know something about compressor types. Apple supplies at least six standard types. List the available compressor types by ::quicktimetcl::info components imco or ::quicktimetcl::info iccodecs. The six standard types and their characteristics are:

rpza: Video Compressor: Best used for sequences. Use it preferrably for video content than synthetically generated images.It supports both spatial and temporal cmpressions.
jpeg: Photo Compressor: Not for sequences. Best adapted to images that varies smoothly without sharp contrasts. Used typically for 24 bit colors and 8 bit grayscale images.
{rle }: Animation Compressor: Best for animation and computer-generated video content. Works by run-length coding data, either lossless or lossy. Not suited for photos and sequences that varies rapidly. Works at all pixel depths.
{raw }: Raw Compressor: Works by decreasing the color depth of the image.
{smc }: Graphics Compressor: Best suited for 8 bit still images and sequences. Gives typically a doubled compression ratio compared to the Animation Compressor. Has, however, a slower decompression.
cvid: Compact Video Compressor (Cinepak): Best suited for 24 bit and 16 bit video sequences. Compared to the Video Compressor, this compressor obtains higher compression ratios, better image quality, and faster playback speeds. It is, however, much slower for compression.

There are also DV image compressors. The NTSC DV compressor ({dvc }) generates 720 x 480 frames, and the PAL DV compressor (dvcp)generates 720 x 576 frames. Since each one of these compressors, and the others at your system, only support a subset of the possible compression options as given by the tracks add picture command, it can be tricky to find a combination that is supported. Use the -dialog 1 option to assist you in this search. It is important to distinguish between single image compression and sequence compression. Using a list of a number of images for the tracks add picture command is very different from using this command repeatedly on the individual images, since the sequence compression treats the images as a sequence (sic), and thereby achieving considerable compression not possible by adding them separately. When using the -dialog 1 option, many things are handled automatically internally in the compressor component. You may choose compressors that does not allow sequence compression, even if a list of images is specified.

SAVING MOVIES

Once the movie has been edited, or it has perhaps been obtained remotely using the -url option, it is time to save it. There are four different ways to do it: save, saveas, flatten, compress, or export. They typically work as any corresponding menu command would work, but with some important differences. There are two things that complicates this. Before discussing this, we must make a distinction between the "movie resource" and "movie data". Each movie consists of these two parts. The movie resource is generally a small structure that keeps track of the movie's data, which contains all video frames, audio etc., and is therefore orders of magnitude larger than the movie's resource.

Note these two features that complicate things: First, the standard Macintosh file contains both a data fork, and a so called resource fork, whereas Windows lacks this file structure. The resource fork of a file has in principal nothing to do with the movie's resource. Second, not all movie files need to be self contained, that is, the movie data must not be in the same file as the movie resource. This may seem like a very weird feature, but is actually very useful since the movie data, which can be several hundred MB in size, need not be duplicated when saving an edited movie.

The save command saves the movie back in its original file, using the resource fork or the data fork whichever corresponds to the original file. If you want to store the movie with a different file name, use the saveas command. This updates the -filename option to the new file name. It does not reorganize the movies internal structure. The saveas command saves only the movie resource, and does not duplicate the movie data. You may optionally save the movie resource in the files resource fork, which on Windows creates a separate file. Thus, saveas command does not make self contained movie files.

The flatten command is typically used for storing movies that should be distributed via a server to the network. It may reorganize the original movies internal structure. Both the movie resource and its data are saved in the same file, and thus makes a self contained movie file. The flatten command does not update the -filename option, and the movie in the actual widget is not affected by flatten. If you want to operate on the flattened movie file, make a new movie widget from the flattened movie file. Also, if you have made a number of edits on a movie, there may be media data in the movie that is not used anymore. In order to make a "clean" movie, removing unused media data, you may flatten it.

The export command is the most versatile, and facilitates storing movies in all formats that there are export components for via dialogs. It leaves the movie corresponding to the widget unchanged. The export command is a kind of "saveas" command that enables the user to specify the destination file.

A typical movie edit session may be like:

.m -file myFile.mov
.
edit stuff
.
.m saveas myNewFile.mov
.
edit stuff
.
.m saveas myNewFile2.mov
.m flatten myCannesWinner.mov

VIDEO EFFECTS

The pathName effect command adds real time video effects to a movie. They are categorized as zero, one, or two source effects, see the description below for a details. A two source effect is somewhat more difficult to use since there must be two overlapping tracks, with the overlap equal to the duration of the effect. An example to create a movie from scratch using two images from disk is:

% movie .m
% .m new myEffect.mov
% .m tracks new video 200 200
{-undostate 0} 1
% .m tracks new video 200 200
{-undostate 1} 2

# The track id's are 1 and 2.
# Make two images in tk from two images on disk. 
# Preferrably of the same size as the video track, else they are scaled 
automatically.
% set firstImage [image create photo -file [tk_getOpenFile]]
% set secondImage [image create photo -file [tk_getOpenFile]]
% pack .m
% .m tracks add picture 1 0 6000 $firstImage
% .m tracks add picture 2 0 6000 $secondImage

# Shift the second track to make the desired overlap.
% .m tracks configure 2 -offset 3000

# Pick the wanted effect in the dialog.
% .m effect 3000 3000 1 2

One important feature of the effects dialog is that the command returns almost immediately, before the user has pressed any buttons. A variable ::quicktimetcl::effectfinished is set to -1 before the effect command returns, and is set to 0 or 1 when the user is finished with the dialog; 0 if cancelled, 1 if ok. Use the following code to be sure that the script after the command is actually executed after the user is finished with the dialog.

.m effect 3000 3000 1 2
tkwait variable ::quicktimetcl::effectfinished
...
.m save

WIDGET COMMAND

The movie command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form:

pathName option ?arg arg ...?

Option and the args determine the exact behavior of the command. The time values and durations are always given in the movie's time scale if not otherwise stated. The following commands are possible for movie widgets:

pathName add

This command adds the tracks from the source movie on the scrap to the destination movie. It scales the source movie to fit into the selection of the destination movie. If there is no selection, but merely an insertion point in the destination movie, QuickTime adds the tracks at the insertion point. In contrast to the paste command, this command does not "cut through" any existing tracks, but adds them in parallel to the tracks in the destination movie. This can be useful for adding a track to an existing movie, such as adding sound to a silent movie. It returns the undo number as

{-undostate 
    undoNo}

which may be used to undo this command.

pathName callback ?args?

Handle time events similar to the Tcl after command, but sets up a procedure to be called when the movie reaches a certain time when played. This is a one-shot timer.

pathName callback movieTime procName: Sets up the procName to be called when the movie reaches the time movieTimewhen played. The call takes place at a safe (non-interrupt) time after movieTime, which creates a slight time slip. The command returns a token (unique identifier) which is used by other callback commands. The procName shall have the following form: proc MyCallBack {token pathName movieTime} {...}. The first argument, token, is the same string that was returned when setting up the callback. The movieTime is not the actual movie time (get it with the time command), but the one corresponding to the callback argument.

pathName callback cancel token: Removes the callback event with the specified token.

pathName callback info ?token?: Without the token argument, it returns a list of all callback tokens registered with this movie. If token is supplied, it specifies an existing handler; token must have been the return value from some previous call to callback, and it must not have triggered yet or been cancelled. In this case the command returns a list with two elements. The first element of the list is the script associated with token, and the second element is the movie time corresponding to it.

pathName cget option

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the movie command.

pathName compress fileName ?boolean?

Compress the movie to the file specified in fileName. If the boolean is 1, an export dialog is presented where the user may select from a number of options for the compression. The default behaviour is not to show the dialog. Many operations can be very time consuming, and since the compression is done in blocking mode, it's a good idee to specify a either the qtprogress option, or a Tcl procedure via the progressProc option. The export command is much more versatile than compress.

pathName configure ?option? ?value option value ...?

Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the movie command.

pathName controllerinfo

Returns a list of option boolean pairs describing the state of the movie controller. The options are -undoavailable, -cutavailable, -copyavailable, -pasteavailable, -clearavailable, -hassound, -isplaying, -islooping, -isinpalindrome, -editingenebled. This is helpful for enable/disable menus, for instance.

pathName copy

Copy the selection made by the select command to the movie scrap. A selection is necessary before copying.

pathName cut

Cut the selection made by the select command. A movie selection is necessary before cutting. It returns the undo number as

{-undostate 
    undoNo}

which may be used to undo this command.

pathName effect startTime duration ?trackOneID? ?trackTwoID?

The standard video effect dialog is opened where it is possible to choose from a large number of video effects. The effects command returns almost immediately, before the user has pressed any buttons, and before the dialog has popped up. A variable ::quicktimetcl::effectfinished is set to -1 before the effect command returns, and is set to 0 or 1 when the user is finished with the dialog; 0 if cancelled, 1 if ok. Use tkwait variable ::quicktimetcl::effectfinished to wait for the dialog to be finished. startTime and duration give the starting time and the length of the effect, respectively. There are zero-source effects, one-source effects, and two-source effects. The zero-source effects add effects, such as cloud and fire, that don't require a source track. A one-source effect acts as a filter for a track, and a two-source effect is typically a transition effect between two tracks. If no optional arguments are specified, it will result in a zero-source effect, if trackOneID given, a one-source effect, and if also trackTwoID given, the result will be a two-source effect. For a zero-source effect, a black background is made transparent in order to make the original track, if any, show through. A two-source effect requires two overlapping tracks, where the overlap must coincide with the duration, startTime must coincide with the start of the second track, and startTime + duration must coincide with the end of the first track. All tracks involved must have a visual representation. One or more additional tracks may be created as a response to this command. You may specify end for duration (and startTime) which extends the duration to the end of the movie.

pathName export ?option value ...?

Presents the user an export dialog, a "Save As" dialog, where a large number of options can be chosen for the new movie. In contrast to the compress dialog, a file path is returned from this command, or an empty string if the user cancels. Many operations can be very time consuming, and since the compression is done in blocking mode, it's a good idee to specify a either the qtprogress option, or a Tcl procedure via the progressProc option. The movie must be mapped to screen for export to work.

An export operation takes place via a so called export component of type spit, and of a certain subtype and manufacturer. These three parameters are all four character wide strings, and any space in any of these must be properly conserved by embracing or quoting the word. The name "manufacturer" is a bit of a misnomer since it usually specifies the media type that a component supports, or typically appl if more than one media type is exported. You may investigate the presently available export component on your system from the command ::quicktimetcl::info components spit. If you specify any particular export component, you must be confident that it supports the actual movie. For instance, you can only use the VR export components (manufacture: vrob, vrsp, vrwe) for VR movies.

For each component the internal parameter settings are stored internally, and may be reused in the same session without showing a dialog each time. A typical usage is:

# Investigate our export components.
::quicktimetcl::info components spit
... {-type spit -subtype MooV -manufacture appl ...} ...

# Configure a specific export component using its dialog.
.m export -file kass.mov -codecsubtype MooV -mediatype appl 

# Reuse its settings without showing any dialog.
.m export -file kass2.mov -codecsubtype MooV -mediatype appl -uselatestsettings 1 -dialog 0

As an alternative, to store component settings between sessions, you may store them to file, and read in them later without dialog. You are responsible that the components are identical when settings are written, and when read in later. It may be helpful to pick a descriptive name for the settings, such as "MooVapplSorenson3" etc. A typical usage is:

# Configure a specific export component using its dialog.
.m export -file kass.mov -codecsubtype MooV -mediatype appl  \
        -savesettingstofile MooVapplSorenson3

# Reuse its settings without showing any dialog.
.m export -file kass2.mov -codecsubtype MooV -mediatype appl  \
        -readsettingsfromfile MooVapplSorenson3 -dialog 0

-codecsubtype fourCharCode: Specifies the subtype of the export component that shall be picked for this export operation. If a dialog is to be shown, the settings for the chosen export component is shown.
-dialog boolean: Specifies if a dialog should be presented. Defaults to 1. If no -codecsubtype or -mediatype given, a save as dialog is presented where the file may be specifed together with any of the export components that may be used for this specific movie. Most of these components also support a separate settings dialog which further specify the detailed parameters for the component. If any specific export component is required via the options -codecsubtype or -mediatype, no save as dialog is shown, but only the parameter settings dialog for the selected component.
-file filePath: Specifies the file path of the exported movie. If a save as dialog is shown, the name of the file is initially displayed. This is a required option if no save as dialog is shown.
-mediatype fourCharCode: Specifies the manufacturer, which usually corresponds to the media type, of the export component that shall be picked for this export operation. The -codecsubtype must be set else the system cannot find a component. This parameter corresponds to the -manufacture in the output of the ::quicktimetcl::info components command. If a dialog is to be shown, the settings for the chosen export component is shown.
-onlytrack trackId: Export only the specified track and not the complete movie.
-readsettingsfromfile filePath: A previously stored component settings to file (from -savesettingstofile) may be reused. Be sure that the export component, which's settings are in the file, is identical when you are reusing its settings. The -codecsubtype or -mediatype options must be specified. If you show the components settings dialog, the initial parameter values are set.
-restrictexport boolean: Defaults to 1. If 0 some more options are displayed in the save as dialog.
-savesettingstofile filePath: For a specific export component, you may store its parameter settings in a file for permanent reusage. The -codecsubtype or -mediatype options must be specified.
-uselatestsettings boolean: Defaults to 0. For each export operation that is made with a specific export component using the options -codecsubtype or -mediatype, the parameter settings are stored internally in memory for each component. For subsequent usage with this component, you may use the internally stored parameter settings if you set the -uselatestsettings value to 1. If you show the components settings dialog, the initial parameter values are set.

pathName fieldofview ?fov?

Gets or sets the current field of view (camera zoom) for a QTVR panoramic movie. Units unknown.

pathName flatten fileName ?-dontinterleave boolean? ?-resource id? ?-dialog boolean? ?-forceresourcebeforedata boolean?

Saves the movie in a self contained format. Both movie data and the movie resource are saved in the same file. If the -resource option is given, the movie resource is stored in the files resource fork, which on Windows makes a separate file in the same directory. By default, this command interleaves audio and video data for optimal playback performance. This can be switched off by the -dontinterleave option. Only the QTVR (panorama) components support the -dialog option. The -forceresourcebeforedata (default 1) forces the movie resource to be stored in from of the movie data. This command does not alter the movie in the widget. To work on the newly flattened movie you need to open it with a new widget (or configure with the -file option).

The command returns the actual file path for the flattened movie unless the user has cancelled any dialog which is indicated by an empty return value.

pathName gettime

Returns a list of four times:

{-movietime number -movieduration number 
    -movietimescale number -postertime number}

. The -movietime is the movie's present position in terms of the number of ticks from its start; -movieduration is the total length of the movie (in movie ticks); -movietimescale is the movies time scale as discussed in the DESCRIPTION section above. The -postertime is where to find the poster still image that is representative of the movie.

pathName haschanged

Returns 1 if the movie has been edited in any way since it was last saved. Else it returns 0.

pathName hotspot ?args?

Manipulates various hotspot features. Only for single node QTVR movies.

pathName hotspot configure nodeId hotspotId ?-enabled boolean? -name text?

Makes changes for the specified hotspotId. The nodeId is just a dummy.

-enabled boolean: Switches the specified hotspot on or off, which means that all displayed features of the hotspot is removed. The hotspot is still there. This command takes immediate effect. The change is not persistent (it is not saved with the movie).
-name text: Sets the name of the specified hotspot, which is the text that is displayed in the movie controller. You need to save the movie and reopen it for this command to take effect.

pathName hotspot setid nodeId hotspotId newHotspotId

Changes the atom id from hotspotId to newHotspotId. You need to save the movie and reopen it for this command to take effect. If you set the id to a number that does not exist in the hotspot color map, any action and its name is removed from the movie. The highlight of the hotspot remains, however. The nodeId is just a dummy.

pathName hotspot setwiredactions nodeId hotspotId ?-enabled boolean? -fov number? ?-pan angle? ?-tilt angle?

Makes changes for the specified hotspotId. The nodeId is just a dummy. All these changes are persistent, and are saved with the movie. You need to save the movie and reopen it for this command to take effect. The -enabled option is set independent of the others. The other options, however, must be set at the same time to be valid; if one of them are set, the others are removed.

-enabled boolean: Switches the specified hotspot on or off, which means that all displayed features of the hotspot is removed. The hotspot is still there.
-fov number: Sets the field of view of the specified hotspot.
-pan angle: Sets the pan angle of the specified hotspot, so that when it is clicked, the view is set to this pan angle.
-tilt angle: Sets the tilt angle of the specified hotspot, so that when it is clicked, the view is set to this tilt angle.

pathName isdone

Returns 1 if the movie has reached its end, if it's playing forward, or its beginning if it's playing backwards. Else it returns 0.

pathName ismovie

Returns 1 if we have an ordinary movie and not a VR panoramic movie, and 0 else.

pathName ispanoramic

Returns 1 if we have a VR panoramic movie and not an ordinary movie, and 0 else.

pathName isscrapmovie

Returns 1 if we have a movie on the clipboard (scrap), and 0 else.

pathName isvisual

Returns 1 if there is something for our eyes, except for any movie controller, and 0 else.

pathName new fileName ?-resource id?

Create a new movie in file fileName. By default, a single fork movie file is created with everything in the data fork. This should always be used on Windows. On the mac, specifying a resource id creates a double fork movie, with the movie in the resource fork. If id is 0, the first empty resource is used, which is always 128 or larger. If a specific resource id is given, it must be 128 or larger. A resource id of -1 is the default, and means that the movie is in the data fork. The movies file name is stored internally, and a subsequent save command stores the movie into this file. There must not be another file already associated with this movie, such as by having used -file. Returns the resource number. A new movie file is typically made as:

% movie .m
% .m new myFile.mov
-1

pathName nextinterestingtime mediaTypeList ?movieTime?

Finds some "interesting times" corresponding to the current movie time or to any movieTime given as optional argument. The times corresponding to new sample, edits, and sync samples. The search is limited to the media types given as a list in the mediaTypeList. In addition to the standard media types (described previously), it is possible to pick subsets eyes or ears which correspond to tracks with visual and audial tracks respectively. The answer is returned as a list:

-sampletime movieTime 
    -sampleduration movieDuration
    -edittime movieTime -editduration movieDuration 
    -syncsampletime movieTime -syncsampleduration movieDuration

pathName pan ?angle?

Gets or sets the current pan angle for a QTVR panoramic movie.

pathName panoinfo

Returns miscellaneous information about a QTVR panoramic movie as a hierarchical list of -key value pairs. Presently, only the information about the default node is returned. You typically parse the list using the array set arrName theList command repeatedly.

pathName paste ?args?

This command pastes what is stored on the scrap into the movie. It works differently whether the controller has editing enabled or not (-mcedit, see EDITING). Whenever possible, QuickTime tries to reuse any tracks that can be reused, but creates new ones if the source movie contains tracks that can't be matched with any track in the destination movie. The paste operation cuts through all tracks and adds empty space in existing tracks if necessary. If you just want to add another movie's tracks in "parallel" with the destination movie, use the add command. It returns the undo number as {-undostate undoNo} which may be used to undo this command.

pathName paste: Pastes the movie on the scrap at the current position of the target movie. If the target movie already has a selection, this selection is first removed (not if controller editing is enabled, I think), and then the movie on the scrap is pasted in the selections original position. The current position, or insertion point, is placed with the select command without any duration option. This works just in the ordinary Mac way. All of the tracks from the source movie are placed in the destination movie.
pathName paste dialog: Mac only. Need controller editing enabled. Displays an import dialog that is specific for the type of content present on the scrap. A number of options can be set to give some control of how the scrap content should be imported to the movie.
pathName paste parallel: Need controller editing enabled. If text on scrap, that text is placed below the actual movie box.
pathName paste replace: Need controller editing enabled. If the movie has a nonempty selection, the pasted text replaces that selection. With no selection, the entire movie is replaced. Beware!
pathName paste scaled: Need controller editing enabled. If text on scrap, it is added in parallel for the duration of the current selection, or if no selection, it is added for the duration of the entire movie.

pathName picture time imageName ?-height height? ?-width width?

Takes a snapshot from the movie at time time, and places it in the image . The imageName must first have been created with image create photo imageName. The movie must have a visual representation. If the movie is a streaming movie, using -url, time is just running and it can be difficult to take a snapshot. In that case, try:

.m picture [.m time] myphoto

If any of the -height or -width options are given, the imageName is scaled to that size, else it is kept at its "natural" size.

pathName play

Starts the movie from its present position at its preferred rate. If the movie has reached its end, it is restarted from its beginning. If the movie runs backwards and has reached time 0, then it is restarted from its end. The movie must be mapped for play to work.

pathName playhints ?-allowblacklining bool? ?-allowinterlace bool? ?-dontpurge bool? ?-highquality bool? ?-inactive bool? ?-scrubmode bool? ?-usesoundinterp bool?

Sets the movies so called play hints. See Apple docs what the meaning of these are. This command doesn't return anything.

pathName rate ?rate?

Sets or gets the current rate of the movie. The rate is a number between -1.0 and 1.0, and represents the current "speed" of the movie playback. Thus, a rate 0.0 stops the movie, and a positive rate starts the movie, if it has not reached its end. Negative rates mean it's going backward. If you want to set the play rate manifest, use the preferredrate option.

pathName save

Saves the movie back in the original file. The movie must exist on disk with a known file name already, either by having used -file or new. If we can deduce that the movie resource came from the resource fork, it is saved back in the resource fork, else it is saved to the data fork.

pathName saveas ?fileName ?-resource id??

Saves the movie resource to a new file. By default, a single fork movie file is created with the movie resource in the data fork. This should always be used on Windows. Since only the movie's resource is saved, the corresponding movie file is not selfcontained. The movie data may be in the original movie file and is not duplicated. On the mac, specifying a resource id creates a double fork movie, with the movie resource in the resource fork, which on Windows makes a separate file in the same directory. If id is 0, the first empty resource is used, which is always 128 or larger. If a specific resource id is given, it must be 128 or larger. A resource id of -1 is the default, and means that the movie is in the data fork. The movies file name is stored internally, and a subsequent save command stores the movie into this file.

pathName select ?args?

This command handles selection operations of the movie.

pathName select all: Selects the complete movie.
pathName select clear: The movie segment of the current movie selection is removed. After removing the segment, the duration of the selection is set to 0 and the selection time remains unchanged. It returns the undo number as {-undostate undoNo} which may be used to undo this command.
pathName select none: Sets the the insertion point at the present movie time, without any selection.
pathName select ?startTime? ?duration?: If neither fromTime nor duration is given, the present selection is returned as a list fromTime duration. If only fromTime given, the insertion point is placed here with zero duration. You may specify end as startTime. If both fromTime and duration given, the corresponding selection is made. Note, all times in the movie's time as usual. If the duration is end, the selection is extended until the end of the movie

pathName size

Returns width height describing the movies default (natural) spatial size excluding any movie controller.

pathName step ?numSteps?

Takes a step forward to the "next interesting time", which usually means a step to the next frame for video. If numSteps is specified as a positive or negative integer, numSteps is taken in the direction given by its sign.

pathName stop

Stops the movie if it' s playing. The movie must be mapped for stop to work.

pathName tilt ?angle?

Gets or sets the current tilt angle for a QTVR panoramic movie.

pathName time ?time?

Sets or gets the current position in the movie, the movie's time.

pathName timecode ?args?

Methods to create and manipulate timecode tracks. A timecode track displays a video tracks timing information as a text string HH:MM:SS:FF, where HH are hours, MM minutes, SS seconds, and FF the number of frames since last second. If drop frames, see below, the last colon is replaced by a semicolon. A timecode track is created with the same duration as the video track it is referencing. The video track must have a uniform frame duration for the timecode track to correctly display timing info. You typically make a timecode track for each clip you make. The timecode track is created with a black background and white text as default, and the tracks graphics mode is set to addmax (see Apple docs for this). This has the effect of making the black background transparent. A tracks graphics transfer modes is investigated and set via the tracks configure command. If you would like to have black text instead, follow this code example:

.m timecode new 1 -foreground black -background white
.m tracks configure 4 -graphicsmode addmin

Or if the solid background and foreground colors are preferred, set the timecode tracks graphics mode to the copy mode:

.m tracks configure 4 -graphicsmode {dithercopy copy}

pathName timecode delete

Deletes all timecode tracks in the movie if any.

pathName timecode display boolean

Sets the display status of any timecode track.

pathName timecode get ?movieTime?

Returns a key-value list of some timecode track options. If no movieTime specified it returns data for the current movie time.

pathName timecode new videTrackID ?args?

Deletes any timecode tracks in the movie, and then makes a new one with the corresponding features. If succesfull it returns a list {-undostate number} newTrackID with the undo id number and the track ID of the newly created timecode track. The videTrackID must be a track of type 'vide', which is used as reference. The actual time data for the corresponding video track must be known, and the corresponding parameters, -frameduration, -framespersecond, and -timescale, must be set accordingly. The timecode track does not automatically find these characteristics from the video track. As an example, for the NTSC format with 29.97 frames per second, set -frameduration 100 -framespersecond 30 -timescale 2997 -dropframes 1.

-anchor boolean: Sets the anchor position of the timecode track to either n (north) or s (south). It defaults to s.
-background color: Sets the background color of the timecode track. It defaults to black.
-dropframes boolean: Signals if any so called, drop frames needed to correctly reproduce the video tracks original timing characteristics.
-font fontSpec: Tk font for display.
-foreground color: Color for the timecode text.
-frameduration frameDuration: Integer specifying how long each frame lasts in the units of the timeScale. Defaults to 20.
-framespersecond numFrames: Sets the numnber of frames per second. Defaults to 30.
-pady integer: Integer that specifies the offset from top or bottom for the timecode track. Defaults to 0.
-sourcename text: Descriptive text to store as a user data item for the timecode track.
-startframes integer: The first frame's timecode offset. Defaults to 0.
-starthours integer: The first frame's timecode offset. Defaults to 0.
-startminutes integer: The first frame's timecode offset. Defaults to 0.
-startseconds integer: The first frame's timecode offset. Defaults to 0.
-timescale timeScale: An integer setting the scale for interpreting the frameDuration value. It indicates the number of time units per second. Defaults to 600.

pathName timecode toggle

Toogles the display status of any timecode track on/off.

pathName tracks ?args?

This command performs actions that act on a specific track and not on the complete movie. Each track has a unique integer number, the trackID, used to identify a track. If not otherwise noted, an operation that affects the media content of a track invalidates any track selection on this track. A track clipboard content involving the affected track may also be invalidated. Beware!

Times are given in the movies time scale if not otherwise noted. A startTime end sets that time to the end of the movie, while a duration end extends the affected track to its end.

pathName tracks

Returns a list of all the media types for the enabled tracks in the movie. The types are described in terms of the four letter combinations given in the DESCRIPTION section above. For a typical movie this will be vide and soun.

pathName tracks add args

Inserts still images, text, or empty space in a track. Also creates chapter lists from a text track. All add commands return the undo number as {-undostate undoNo} which may be used to undo this command.

pathName tracks add chapters trackID textTrackID

Inserts a reference from the trackID track to the text track textTrackID, so that a pop up menu is shown in the movie controller, with entries for each text in the text track. This provides a so called chapter list used to quickly find a position in the movie. There must be a controller for this to work, and there must be enough space in the controller, else it is not shown. The text track can be disabled after the chapters is created. Use short texts preferrably. A typical procedure is:

% .m tracks new text
> {-undostate 0} 3
% .m tracks add text 3 0 100 Start
% .m tracks add text 3 12000 100 {Pee Pause}
% .m tracks add text 3 36000 100 {The End}
% .m tracks add chapters 1 3
% .m tracks disable 3

pathName tracks add picture listOfImages

Deletes the present track selection and inserts each of the images in listOfImages, each with the duration of the track selection. Each of the elements in listOfImages is a tk photo. The destination track must be a visual track, such as a video track, and the inserted image is scaled to fit the track boundaries. There must be a valid track selection for this to work. The movie's duration may increase after this operation.

pathName tracks add picture trackID startTime duration listOfImages ?option value option value ...?

Inserts each of the still images in the list listOfImages into the specified track for the specified duration of each image. Each of the elements in listOfImages is a tk photo created with image create photo imageName, and filled with some content. The destination track must be a visual track, such as a video track, and the inserted images are scaled to fit the track boundaries. The movie's duration may increase after this operation. If the list if photos has length larger than one, the images are always added as a sequence, and only compressors supporting sequence compression will work. Any of the following options may be used, but a specific compressor typically only supports a subset of them:

-colordepth integer: Specifies the color depth for the compressed image. Valid numbers are: 1, 2, 4, 8, 16, 24, 32, 34, 36, 40, and 0. Zero means default depth. Values 1-32 specify the color depth, higher values means gray scale image, with a gray scale depth of integer - 32. Thus, 40 means an 8 bit gray scale image.
-compressor fourCharacterCode: Defaults to {rle }. Specifies the compressor to be used. See the Making Movies section above for examples and discussion. Do not forget to quote or embrace if the four character code contains any space character.
-dialog boolean: Defaults to false. Specifies if a dialog should be displayed to ask the user to specify the compressor, quality, and a number of other options. Different dialogs are showed depending if single frame or sequence. If this option is 1, the other options are ignored. Use this option to make it easier to find the supported set of compression options.
-keyframerate integer: Defaults to 12. When using temporal compression, a key frame is used as a reference frame for the following frames, up to the next key frame. The number of frames from one key frame to the next key frame is the key frame rate.
-spatialquality quality: Sets the quality of the compressed image. Better quality results in a larger movie. Valid values of quality are: min, low, normal, high, max, and lossless. It defaults to normal.
-temporalquality quality: Sets the quality of the temporal compression. This is only applicable for sequences. Valid values of quality are: min, low, normal, high, max, lossless, and 0. 0 means no temporal compression. It defaults to normal.

pathName tracks add picturefile fileName

Deletes the present track selection and inserts the image in the file fileName, with the duration of the track selection. The destination track must be a visual track, such as a video track, and the inserted image is scaled to fit the track boundaries. There must be a valid track selection for this to work. Unlike the tracks add picture command, it tries to be as faithful as possible to the features of the original image, conserving such things as color depth, color table, compressor etc.

pathName tracks add picturefile trackID startTime duration fileName ?option value option value ...?

Inserts the still image in file fileName at the specified position and duration of the track. Options are identical to the tracks add picture command. Unlike the tracks add picture, it tries to be as faithful as possible to the features of the original image if you don't specify extra options, conserving such things as color depth, color table, compressor etc. It does not just takes the data in the file, but it needs to recompress it again. Therefore do not use GIF files since there is no such compressor due to a patent debacle.

pathName tracks add space

Replaces the present track selection with empty space. Empty space is white background for visual tracks, and silence for sound tracks. There must be a valid track selection for this to work.

pathName tracks add space trackID startTime duration

Inserts empty space into the specified track for the specified time. Empty space is white background for visual tracks, and silence for sound tracks. The movie's duration may increase after this operation.

pathName tracks add text trackID startTime duration text ?option value option value ...?

Inserts the given text into the specified track for the specified time. The text is shown centered at the top with a standard system font in white. The trackID must be a text track. The movie's duration may increase after this operation. When adding text to a text track any of the following options may be used:

-background color: Sets the background color of the complete video area.
-cliptobox boolean: Defaults to false. Specifies if the text should be clipped to the textbox if any.
-font fontName: Sets the background color of the complete video area.
-foreground color: Sets the foreground color of the text.
-justification just: Sets the justification of the text. The text is justified within the text box, which defaults to the text tracks video area. The available values for just are center, right, left, and default.
-scrolldelay time: Defaults to zero. Indicates the delay in scrolling associated with the options -scrollin and -scrollout. If the time is greater than 0, and the -scrollin is true, the text pauses when it has scrolled all the way in for the amount of time specified by time. If the -scrollout is true, the pause occurs first before the text scrolls out. If both these options are true, the pause occurs at the midpoint between scrolling in and scrolling out.
-scrollhorizontal boolean: Defaults to false. If have scrollin or scrollout, it changes the default vertical scrolldirection to horizontal.
-scrollin boolean: Defaults to false. If true, scrolls the text in until the last of the text is in view.
-scrollout boolean: Defaults to false. If true, scrolls text out until the last of the text is out of view. If both of -scrollin and -scrollout is true, the text is scrolled in then out.
-scrollreverse boolean: Defaults to false. The default scroll direction is from bottom to top for vertical scrolling, and from left to right for horizontal scrolling. This option reverses these directions.
-textbox {x y width height}: Sets the bounding box of the text in terms of the coordinates of the text track. The -cliptobox option specifies if text outside the box is clipped or not. The coordinates start with 0 0 in the upper left corner of the text track.

pathName tracks configure trackID ?option? ?value option value ...?

Query or modify the configuration options of the particular track. If no option is specified, returns a list of option-value pairs describing all of the available options for this track. If option is specified with no value, then the command returns the value for this option. If one or more option-value pairs are specified, then the command modifies the given tracks option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the following values:

-balance number

The balance parameter value may range from -128 to 127. Negative values emphasize the left sound channel, while positive values emphasize the right sound channel. A value of -128 forces all output through the left channel. Similarly, a value of 127 forces all output through the right channel.

-enabled boolean

Specifies if the track shall be enabled or not. It defaults to true. A disabled video or text track, for instance, wont display, and a disabled audio track wont play any sound.

-graphicsmode mode

Specifies the graphics mode of a track. The mode can be any of, blend, copy, transparent, addpin, addover, subpin, addmax, subover, addmin, straighalpha, prewhitealpha, preblackalpha, or straighalphablend. The mode can also be a list with one of the elements identical to any of the above, and the other equal to dithercopy. Several of these modes must be further specified by the -graphicsmodecolor option. See Apples Inside books for detailed explanation of these modes. The most common ones are copy, which just draws the track's images on top of any other visual data, transparent, which draws all data except the pixels specified with the option -graphicsmodecolor. Useful is also the blend mode that makes the track partial visible depending on the -graphicsmodecolor. For instance, a -graphicsmodecolor equal to gray50 makes the track 50% transparent.

-graphicsmodecolor color

Specifies a color to be used in cooperation with the -graphicsmode option.

-layer layerNo

Specifies the layer number of the specified track. The layer number of a track specifies the stacking order. It defaults to 0.

-matrix {{a b u} {c d v} {tx ty w}}

Specifies the display matrix for the track. The default value is the identity matrix: {{1 0 0} {0 1 0} {0 0 1}}. Always: u = 0.0, v = 0.0, and w = 1.0. Any matrix different from the identity matrix gives some distortion of the display. Examples: translation =

{{1 0 0} {0 1 
	    0} {tx ty 1}}

, scaling = {{sx 0 0} {0 sy 0} {0 0 1}}, rotation = {{cos(theta) sin(theta) 0} {-sin(theta) cos(theta) 0} {0 0 1}}, flipping vertically = {{1 0 0} {0 -1 0} {0 0 1}}. Operations are combined by multiplying different matrices. Note that the order of the factors is important since matric multiplication is a noncommutative operation.

-offset time

Specifies the offset of the track. The offset is counted starting from 0 when the movie begins, and is expressed in the movies time scale. The total length of the movie may change as a result of this operation.

-volume number

Specifies the volume of a sound track. The number is between -256 and 256, where 0 and smaller means no sound, and negative values are used to toggle sound on and off, keeping the volume intact. The track's volume is toggled by, for instance:

.m tracks configure 2 -volume [expr -1*[.m tracks configure 2 -volume]]

pathName tracks copy

Copies the present track selection to the track clipboard.

pathName tracks delete ?args?

Deletes segments or complete tracks. It returns the undo number as {-undostate undoNo} which may be used to undo this command. The deleted segment is not placed on the track clipboard. The movie's length may change as a result. All tracks delete commands return the undo number as

{-undostate 
	undoNo}

which may be used to undo this command.

pathName tracks delete: Deletes the present track selection. There must be a valid track selection for this to work.
pathName tracks delete trackID: Deletes the track with number trackID completely.
pathName tracks delete trackID startTime duration: Deletes the track segment with number trackID, starting at startTime for the specified duration.

pathName tracks disable trackID

Disables track with number trackID. Its use is discouraged in favour for the pathName tracks configure -enabled command.

pathName tracks duplicate trackID

Duplicates track with number trackID. The newly created track has the same properties as the original track and the same media. It returns

{-undostate number} 
	newTrackID

pathName tracks enable trackID

Enables track with number trackID. Its use is discouraged in favour for the pathName tracks configure -enabled command.

pathName tracks full ?trackID?

Returns a list

-mediatype type 
	-trackid trackID -tracklayer layerNo -state 
	enabled|disabled -trackoffset number -trackduration 
	number -mediaduration number -mediatimescale 
	number

for the track specified by trackID, or if no trackID given, it returns the list for all tracks.

pathName tracks list

Returns a list of all track ID's.

pathName tracks list -mediatype media

Returns only tracks of type media.

pathName tracks list -enabled boolean

Returns only enabled or disabled tracks depending on boolean.

pathName tracks media args

Each track has associated media which is the actual data processed when playing a track. The media has generally different time characteristics than a track (and movie), such as timescale etc. Each track essentially only consists of references into the media in a very general way. The beginning of a track may play media from the end etc. Track time and media time may therefore have a nontrivial relationship. Do not make any assumptions about this relation.

pathName tracks media nextinterestingtime trackID ?mediaTime?: Returns a list -sampletime mediaTime -sampleduration mediaDuration -edittime mediaTime -editduration mediaTime -syncsampletime mediaTime -syncsampleduration mediaDuration describing various events in the media. If mediaTime is given, the search is started from that time, else it is searched from the current time.
pathName tracks media samplecount trackID: Returns the total number of samples in this media.
pathName tracks media sampledescriptioncount trackID: Returns the total number of sample descriptions in this media.
pathName tracks media samplenum trackID ?mediaTime?: Returns a list -samplenum sampleNum -sampletime mediaTime -sampleduration mediaDuration describing the media sample number at this mediaTime, or the mediaTime corresponding to the current movie time. The -sampletime describes the actual start of the sample which may be different than the mediaTime given or the current time.
pathName tracks media syncsamplecount trackID: Returns the total number of samples that are so called sync samples in this media.
pathName tracks media time trackID ?movieTime?: Returns the media time corresponding to the corresponding movieTime (identical to the tracks time), or the media time corresponding to the current movie time.
pathName tracks media timefromnum trackID sampleNum: Returns a list -sampletime mediaTime -sampleduration mediaDuration describing the media time characterestics of the sample with given number sampleNum.
pathName tracks media userdata trackID ?-key value ...?: Sets or gets the user data associated with the media for the track given by trackID. See the userdata command for details.

pathName tracks new args

Creates a new track in the movie and returns

{-undostate 
	number} newTrackID

. The created track has the following media time scales: sound or music track 44100, text track 60, and a video or sprite track 600. Optionally you may the specify the media time scale. The new track is empty and has zero offset and zero duration. It returns

{-undostate number} 
	newTrackID

pathName tracks new sound | music ?-timescale scale?: Creates a new sound or music track in the movie.
pathName tracks new text | video | sprite | flash ?width height? ?-timescale scale?: Creates a new text, video, flash, or sprite track in the movie. Text is added with the tracks add text command. If width height is lacking, the track is created with the movie's spatial dimension.

pathName tracks nextinterestingtime trackID ?movieTime?

Finds some "interesting times" for th given trackID corresponding to the current movie time or to any movieTime given as optional argument. The times corresponding to new sample, edits, and sync samples. The answer is returned as a list:

-sampletime movieTime 
	-sampleduration movieDuration
	-edittime movieTime -editduration movieDuration 
	-syncsampletime movieTime -syncsampleduration movieDuration

pathName tracks paste

If there exist a track selection with nonzero duration, the selected segment is removed, and the current content in the track clipboard is pasted at the selections start time. The selection is changed to embrace the newly pasted segment. The duration of the movie may change as a result of this operation. It returns {-undostate number}.

pathName tracks picture trackID time imageName ?-height height? ?-width width?

Takes a snapshot from the movie's specified track ID at time time, and places it in the image. The imageName must first have been created with image create photo imageName. The track must have a visual representation. If any of the -height or -width options are given, the imageName is scaled to that size, else it is kept at its "natural" size.

pathName tracks scale args

Scales a track segment. This affects a track segments duration. A visual track segment plays faster or slower, and a sound track shifts its frequencies. The duration of the movie may change. It returns {-undostate number}.

pathName tracks scale newDuration: Scales the present track selection to have a new duration of newDuration. The track selection is updated to the newly scaled segment.
pathName tracks scale trackID startTime duration newDuration: Scales the indicated track segment to have a new duration of newDuration.

pathName tracks select clear

The track segment of the current track selection is removed. After removing the segment, the duration of the track selection is set to 0 and the selection time remains unchanged. The deleted track segment is not pasted onto the track clipboard. It returns {-undostate number}.

pathName tracks select ?trackID ? ?startTime? ?duration?

Makes a track selection. If no optional arguments are given, the current track selection is returned as a list: trackId startTime duration. In the case of no tracks selection, an empty value is returned. If only the trackID is given, that complete track is selected. If also the startTime is given, this is equivalent to placing the insertion point here. If all arguments are given, the corresponding track selection is made. Tracks selections are kept per movie, meaning that only a single track selection exists for a given movie.

pathName tracks size trackID

Returns a list width height describing the tracks spatial size excluding any movie controller. A sound track, or another track without any visual content, has a size 0 0.

pathName tracks userdata trackID ?-key value ...?

Sets or gets user data associated with a particular track. See the userdata command for details.

pathName undo ?args?

This command handles undo operations on the movie. Without any arguments it returns the current undo level.

pathName undo set: Returns a list {-undostate number} where number is the number of this undo state.
pathName undo levelNo: Undoes to level levelNo. All higher undo numbers are lost.

pathName userdata ?-key value ...?

Sets or gets user data associated with the movie. If no options, it returns a -key value list for the user data stored in the movie. For instance, for MP3 music files the movie importer puts ID3 tags as text user data. The following keys are recognized as text user data, and correspond to MP3 ID3 tags: -album, -artist, -author, -chapter, -comment, -composer, -copyright, -creationdate, -description, -director, -disclaimer, -encodedby, -fullname, -genre, -hostcomputer, -information, -keywords, -make, -model, -name, -originalartist, -originalformat, -originalsource, -performers, -producer, -product, -software, -specialplaybackrequirements, -track, -warning, -writer, -urllink, -editdate1. In general the key is a four-word-character, similar to other Apple types. Keys starting with the copyright sign,©, are by default treated as text user data. Else data is stored as binary. All lower case characters and special characters are reserved for Apple's usage. Permanent storage requires that the movie is saved.

BINDINGS

The binding class for all movie widgets is Movie. QuickTime adds a few bindings by its own. For a VR panorama movie, there are number of mouse bindings that are used to control the view in the picture. For an ordinary, linear, movie with a controller, a double click starts the movie, and a single click stops it.

There are a few key bindings that QuickTimeTcl adds. The movie must have focus as usual for these to be active. Either click the widget, or set focus by the focus command. Linear means ordinary movie, else it's either a panoramic movie or an object movie.

<Right>: Linear: step 1, else pan -10°
<Left>: Linear: step -1, else pan 10°
<Up>: Linear: increases the volume, else tilt 10°
<Down>: Linear: decreases the volume, else tilt -10°
<Shift_L>: Linear: nothing, else fieldofview -5
<Control_L>: Linear: nothing, else fieldofview 5
<space>: Linear: toggles play/stop, else nothing

BUGS

There are some slight performance problems for panoramic VR pictures that is probably related to the flickering cursor.
(Windows) -resizable not working.
(Mac OS X) effect not implemented, yet.

KEYWORDS

movie, QuickTime, Sequence grabber, and tk_getOpenFilePreview

Copyright © 1998-1999 Bruce O'Neel 
Copyright © 2000-2003 Mats Bengtsson