QuickTimeTcl Commands - movie manual page

  NAME
    movie - Create and manipulate movie widgets for video and audio
  SYNOPSIS
    package require QuickTimeTcl ?version?
    movie pathname ?options?
  WIDGET-SPECIFIC OPTIONS
    -controller, controller, Controller
    -custombutton, customButton, CustomButton
    -file, file, File
    -highlightbackground, highlightBackground, HighlightBackground
    -highlightcolor, highlightColor, HighlightColor
    -highlightthickness, highlightThickness, HighlightThickness
    -height, height, Height
    -loadcommand, loadCommand, LoadCommand
    -loadintoram, loadIntoRam, LoadIntoRam
    -loopstate, loopstate, Loopstate
    -mccommand, mcCommand, MCCommand
    -mcedit, mcEdit, MCEdit
    -palindromeloopstate, palindromeLoopstate, PalindromeLoopstate
    -preferredrate, preferredRate, PreferredRate
    -progressproc, progressProc, ProgressProc
    -qtprogress, qtProgress, QTProgress
    -qtvrqualitymotion, qtvrQualityMotion, QTVRQualityMotion
    -qtvrqualitystatic, qtvrQualityStatic, QTVRQualityStatic
    -resizable, resizable, Resizable
    -swing, swing, Swing
    -swingspeed, swingSpeed, SwingSpeed
    -url, url, Url
    -volume, volume, Volume
    -width, width, Width
  DESCRIPTION
  SOUND ONLY
  EDITING
  TEXT
  STILL IMAGES AS MOVIES
  MAKING MOVIES
  SAVING MOVIES
  VIDEO EFFECTS
  WIDGET COMMAND
    pathName add
    pathName callback ?args?
      pathName callback movieTime procName
      pathName callback cancel token
      pathName callback info
    pathName cget option
    pathName compress fileName ?boolean?
    pathName configure ?option? ?value option value ...?
    pathName controllerinfo
    pathName copy
    pathName cut
    pathName effect startTime duration ?trackOneID? ?trackTwoID?
    pathName export ?option value ...?
      -codecsubtype
      -dialog
      -file
      -mediatype
      -onlytrack
      -readsettingsfromfile
      -restrictexport
      -savesettingstofile
      -uselatestsettings
    pathName fieldofview ?fov?
    pathName flatten fileName ?-dontinterleave boolean? ?-resource id? ?-dialog boolean? ?-forceresourcebeforedata boolean?
    pathName gettime
    pathName haschanged
    pathName hotspot ?args?
      pathName hotspot configure nodeId hotspotId ?-enabled boolean? -name text?
      pathName hotspot setid nodeId hotspotId newHotspotId
      pathName hotspot setwiredactions nodeId hotspotId ?-enabled boolean? ?-fov number? ?-pan angle? ?-tilt angle?
    pathName isdone
    pathName ismovie
    pathName ispanoramic
    pathName isscrapmovie
    pathName isvisual
    pathName new fileName ?-resource id?
    pathName nextinterestingtime mediaTypeList ?movieTime?
    pathName pan ?angle?
    pathName panoinfo
    pathName paste ?args?
      pathName paste
      pathName paste dialog
      pathName paste parallel
      pathName paste replace
      pathName paste scaled
    pathName picture time imageName ?-height height? ?-width width?
    pathName play
    pathName rate ?rate?
    pathName save
    pathName saveas fileName ?-resource id?
    pathName select ?args?
      pathName select all
      pathName select clear
      pathName select none
      pathName select ?startTime? ?duration?
    pathName size
    pathName step ?numSteps?
    pathName stop
    pathName tilt ?angle?
    pathName time ?time?
    pathName timecode ?args?
      pathName timecode delete
      pathName timecode display boolean
      pathName timecode get
      pathName timecode new videTrackID ?args?
        -anchor
        -background
        -dropframes
        -font
        -foreground
        -frameduration
        -framespersecond
        -pady
        -sourcename
        -startframes
        -starthours
        -startminutes
        -startseconds
        -timescale
      pathName timecode toggle
    pathName tracks ?args?
      pathName tracks
      pathName tracks add args
        pathName tracks add chapters trackID textTrackID
        pathName tracks add picture listOfImages
        pathName tracks add picture trackID startTime duration listOfImages ?option value option value ...?
        pathName tracks add picturefile fileName
        pathName tracks add picturefile trackID startTime duration fileName ?option value option value ...?
        pathName tracks add space
        pathName tracks add space trackID startTime duration
        pathName tracks add text trackID startTime duration text ?option value option value ...?
      pathName tracks configure trackID ?option? ?value option value ...?
        -balance
        -enabled
        -graphicsmode
        -graphicsmodecolor
        -layer
        -matrix
        -offset
        -volume
      pathName tracks copy
      pathName tracks delete ?args?
        pathName tracks delete
        pathName tracks delete trackID
        pathName tracks delete trackID startTime duration
      pathName tracks disable trackID
      pathName tracks duplicate trackID
      pathName tracks enable trackID
      pathName tracks full ?trackID?
      pathName tracks list
      pathName tracks list -mediatype media
      pathName tracks list -enabled boolean
      pathName tracks media args
        pathName tracks media nextinterestingtime trackID ?mediaTime?
        pathName tracks media samplecount trackID
        pathName tracks media sampledescriptioncount trackID
        pathName tracks media samplenum trackID ?mediaTime?
        pathName tracks media syncsamplecount trackID
        pathName tracks media time trackID ?movieTime?
        pathName tracks media timefromnum trackID sampleNum
        pathName tracks media userdata trackID ?-key value ...?
      pathName tracks new ?args ?
        pathName tracks new sound | music ?-timescale scale?
        pathName tracks new text | video | sprite | flash ?width height? ?-timescale scale?
      pathName tracks nextinterestingtime trackID ?movieTime?
      pathName tracks paste
      pathName tracks picture trackID time imageName ?-height height? ?-width width?
      pathName tracks scale args
        pathName tracks scale newDuration
        pathName tracks scale trackID startTime duration newDuration
      pathName tracks select clear
      pathName tracks select ?trackID? ?startTime? ?duration?
      pathName tracks size trackID ?number?
      pathName tracks userdata trackID ?-key value ...?
    pathName undo
      pathName undo set
      pathName undo levelNo
    pathName userdata ?-key value ...?
  BINDINGS
  BUGS
  KEYWORDS

### NAME

Movie - Create and manipulate movie widgets for video, audio, animations, and VR panoramic pictures

### SYNOPSIS

package require QuickTimeTcl ?version?
movie pathname ?options?

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.

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.

  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. Not all components support the -dialog option. QuickTime 4.1.2 and earlier don't install a QTVR flatten component by default. 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 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. 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!

  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
      Specifies the balance between left and right for a stereo sound track. It is a number from -256 to 256, where 0 means even balance between left and right, and positive numbers mean that the right sound channel be stronger than the left, and vice versa for a negative number.

    -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 timeimageName ?-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