- 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 playhints ?-option value ...?
- 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
Movie - Create and manipulate movie widgets for video, audio, animations,
and VR panoramic pictures
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.
- 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.
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
.
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
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 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.
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.
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.
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
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
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.  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.
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
- 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.
movie, QuickTime, Sequence grabber, and tk_getOpenFilePreview
Copyright © 1998-1999 Bruce O'Neel
Copyright © 2000-2003 Mats Bengtsson


Defensive Programming
In this exercise we will implement a mechanism to protect the API from a failure in case that the database on which it depends takes longer than expected to initialize.
The project folder for this exercise is ~/ddev-labs/defensive-programming
.
Defining an Entrypoint Script
We will implement a startup script that defines a wait_for
function which waits for a TCP connection on a given <HOST>:<PORT>
combination. The function ends if either the connection is possible or a certain timeout time is reached.
Open
api/entrypoint.sh
. It should have this content:#!/bin/sh echoerr() { if [[ $QUIET -ne 1 ]]; then echo "$@" 1>&2; fi } wait_for() { if [[ $TIMEOUT -gt 0 ]]; then echoerr "$cmdname: waiting $TIMEOUT seconds for $HOST:$PORT" else echoerr "$cmdname: waiting for $HOST:$PORT without a timeout" fi start_ts=$(date +%s) while : do echo "Probing $HOST:$PORT..." nc -z -w 1 $HOST $PORT </dev/null result=$? end_ts=$(date +%s) delta_ts=$((end_ts-start_ts)) if [[ $result -eq 0 ]]; then echoerr "$cmdname: $HOST:$PORT is available after $((end_ts - start_ts)) seconds" break fi echo "Passed $delta_ts of $TIMEOUT seconds" if [[ $delta_ts -ge $TIMEOUT ]]; then echo "Timeout reached, aborting..." break fi sleep 1 done return $result } TIMEOUT=${TIMEOUT:-15} QUIET=${QUIET:-0} if [[ "$HOST" == "" || "$PORT" == "" ]]; then echoerr "Error: you need to provide a HOST and PORT to test." exit 1 fi cmdname="entrypoint.sh" wait_for RESULT=$? if [[ $RESULT -ne 0 ]]; then exit $RESULT fi echo "Starting API..." java -jar /app/ddev-0.0.1-SNAPSHOT.jar --spring.profiles.active=postgres
We need to make the file an executable:
ubuntu@infra:~/ddev-labs/defensive-programming$ chmod +x ./api/entrypoint.sh
Open the file
api/Dockerfile-def
and modify it until the second part looks like this:... FROM java:8-jdk-alpine RUN adduser -Dh /home/gordon gordon WORKDIR /app COPY --from=appserver /usr/src/ddev/target/ddev-0.0.1-SNAPSHOT.jar . COPY --from=appserver /usr/src/ddev/entrypoint.sh ./ ENTRYPOINT ["./entrypoint.sh"]
Note that the original
ENTRYPOINT
command is equivalent to the last line of ourentrypoint.sh
; we now runentrypoint.sh
on container startup to wrap our defensive measures together with the previous startup command.Open the file
docker-compose-def.yml
and focus on the definition of theapi
service:version: "3.1" services: database: ... api: build: context: api dockerfile: Dockerfile-def image: ddev_api ... ...
Note how we're using the file
api/Dockerfile-def
to build theapi
service.Run the application:
ubuntu@infra:~/ddev-labs/defensive-programming$ docker-compose \ -f docker-compose-def.yml up --build
Carefully observe the log output generated in the terminal, specifically for the
api_1
service. You should see something similar to this (shortened for brevity):... database_1 | The files belonging to this database system will be owned by user "postgres". database_1 | This user must also own the server process. database_1 | api_1 | entrypoint.sh: waiting 30 seconds for database:5432 database_1 | The database cluster will be initialized with locale "en_US.utf8". database_1 | The default database encoding has accordingly been set to "UTF8". database_1 | The default text search configuration will be set to "english". api_1 | Probing database:5432... database_1 | database_1 | Data page checksums are disabled. database_1 | database_1 | fixing permissions on existing directory /var/lib/postgresql/data ... ok api_1 | Passed 0 of 30 seconds database_1 | creating subdirectories ... ok database_1 | selecting default max_connections ... 100 database_1 | selecting default shared_buffers ... 128MB database_1 | selecting dynamic shared memory implementation ... posix database_1 | creating configuration files ... ok database_1 | running bootstrap script ... ok api_1 | Probing database:5432... api_1 | Passed 1 of 30 seconds database_1 | performing post-bootstrap initialization ... ok database_1 | syncing data to disk ... database_1 | WARNING: enabling "trust" authentication for local connections database_1 | You can change this by editing pg_hba.conf or using the option -A, or database_1 | --auth-local and --auth-host, the next time you run initdb. database_1 | ok database_1 | database_1 | Success. You can now start the database server using: database_1 | database_1 | pg_ctl -D /var/lib/postgresql/data -l logfile start database_1 | database_1 | **************************************************** database_1 | WARNING: No password has been set for the database. database_1 | This will allow anyone with access to the database_1 | Postgres port to access your database. In database_1 | Docker's default configuration, this is database_1 | effectively any other container on the same database_1 | system. database_1 | database_1 | Use "-e POSTGRES_PASSWORD=password" to set database_1 | it in "docker run". database_1 | **************************************************** database_1 | waiting for server to start....LOG: could not bind IPv6 socket: Cannot assign requested address database_1 | HINT: Is another postmaster already running on port 5432? If not, wait a few seconds and retry. database_1 | LOG: database system was shut down at 2017-07-21 17:12:46 UTC database_1 | LOG: MultiXact member wraparound protections are now enabled database_1 | LOG: database system is ready to accept connections database_1 | LOG: autovacuum launcher started api_1 | Probing database:5432... api_1 | Passed 2 of 30 seconds database_1 | done database_1 | server started database_1 | CREATE DATABASE database_1 | database_1 | CREATE ROLE database_1 | database_1 | database_1 | /usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/init-db.sql database_1 | CREATE TABLE database_1 | ALTER TABLE database_1 | ALTER ROLE database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | INSERT 0 1 database_1 | database_1 | database_1 | LOG: received fast shutdown request database_1 | LOG: aborting any active transactions database_1 | waiting for server to shut down....LOG: autovacuum launcher shutting down database_1 | LOG: shutting down database_1 | LOG: database system is shut down api_1 | Probing database:5432... api_1 | Passed 3 of 30 seconds database_1 | done database_1 | server stopped database_1 | database_1 | PostgreSQL init process complete; ready for start up. database_1 | database_1 | LOG: database system was shut down at 2017-07-21 17:12:48 UTC database_1 | LOG: MultiXact member wraparound protections are now enabled database_1 | LOG: database system is ready to accept connections database_1 | LOG: autovacuum launcher started api_1 | Probing database:5432... api_1 | entrypoint.sh: database:5432 is available after 4 seconds api_1 | Starting API... database_1 | LOG: incomplete startup packet api_1 | api_1 | . ____ _ __ _ _ api_1 | /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ api_1 | ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ api_1 | \\/ ___)| |_)| | | | | || (_| | ) ) ) ) api_1 | ' |____| .__|_| |_|_| |_\__, | / / / / api_1 | =========|_|==============|___/=/_/_/_/ api_1 | :: Spring Boot :: (v1.5.3.RELEASE) ...
Did you notice the various
api_1 | Probing database:5432...
statements?Cleanup when done:
ubuntu@infra:~/ddev-labs/defensive-programming$ docker-compose \ -f docker-compose-def.yml down
Conclusion
In this exercise we have seen one of many areas were defensive programmings is appropriate. A service which is dependent on other services such as databases should never just assume everything is working perfectly. In this case we have expected that the database needs a certain time to startup. We have used a bash function to wait on the port of the database for a successful TCP connection. Only once the script could connect did we continue and initialize the API. For the case of initialization defenses, we saw a typical Dockerized pattern of wrapping the nominal startup command in a script that performs the defense check first, and calling that script as our container's ENTRYPOINT
.


This is a simple tool that uses Resnet to recognize IDC in images. The model was trained to recognize with 40,000 images and it achieves 90.3% accuracy in detecting Invasive Ductal Carcinoma(IDC) in images.