Tutorial 4: Controlling Movie Playback
This tutorial expands on what we've learned thus far about playing back QuickTime movies in Jitter. We'll learn how to get some useful information about the movie that you're playing, as well as how to manipulate the playback of the movie by changing its speed, volume, and loop points.
Open the tutorial.
The two Jitter objects in this patch should already be familiar to you: jit.qt.movie and jit.pwindow. The rest of the patch will let you experiment with changing the playback behavior of the movie you have loaded into the jit.qt.movie object.
The left side of the patch should seem very familiar to you from the very first tutorial:

Open and play the movie.
• Open the file crashtest.mov by clicking the message box that says read crashtest.mov.
The movie clip should begin playing as soon as it is read into the jit.qt.movie object. Since this movie has a soundtrack, you should begin to hear some music as soon as the movie is loaded. The movie soundtrack will come out of the Sound Manager. If you normally use an ASIO driver with MSP, you will need to connect and set up your Sound Manager outputs so that you can hear them.
You won't see anything in the jit.pwindow because, even though the movie is playing, the jit.qt.movie object needs a bang message to send a matrix out to the jit.pwindow. Start the metro object by clicking on the toggle box connected to its inlet. You will see the movie's image appear in the jit.pwindow object. Don't worry about the gettime message yet; we'll get to that below.
Obtaining Some Information About the Movie
The first thing we want to do with this QuickTime movie is get some information about it. The Jitter attribute system lets us query information about Jitter objects at any time, and use that information in our Max patch. Attribute information is always retrieved by sending get messages to a Jitter object's left inlet. We then parse the Max messages the object sends out its rightmost outlet in response (see What Are Attributes? for more details).

Automatically querying the jit.qt.movie object.
The middle of the tutorial patch contains a Max route object connected to the right outlet of the jit.qt.movie object in our patch. Jitter attributes are always output by objects in the same format that you would set them with in your patch: the name of the attribute followed by whatever information the object needs to set that attribute.
When you tell a jit.qt.movie to open a movie for playback (by sending it the read message), the object sends a message out its right outlet to tell you that it has found your movie and understood how to play it. If you were to connect a print object to the right outlet of the jit.qt.movie in the patch and reload the movie in the patch, you would see the following printed in the Max window:

read crashtest.mov 1
If for some reason the object can't locate the crashtest.mov file, you will see a number other than 1 after the name of the file. This message has two purposes: first, to let you know that the movie file has been successfully located and opened; second, so that you can use this message to trigger subsequent actions in the Max patch.
If we look at the first argument to the route object, you will see that we've told it to look for a message that begins with read. The rest of that message is sent to an unpack object which splits up the remaining list of a symbol (containing the name of the movie) and a number, which indicates success (1) or failure (-1) in opening the movie. The select object then sends out a bang message if the movie is opened successfully. The bang then triggers the message box above it, which is in turn connected back to the jit.qt.movie object.
The message box contains the following list of attribute queries, which are parsed by the same route object that dealt with the read message described above: getfps, gettimescale, fps, timescale, duration, rate, and vol. We don't know what those mean yet, but we now have a mechanism by which we can get these attributes every time we successfully load in a new movie into the jit.qt.movie object.
Starting, Stopping, and Slowing Down

Some simple movie playback controls
The top of the tutorial patch contains some controls to change the playback behavior of the jit.qt.movie object. Sending a stop message to jit.qt.movie will freeze the movie's playback at the current point in the movie. Sending a start message will resume playback where you last left off. Any soundtrack that exists in the movie file will stop playing when the movie's playback is halted. Stopping and starting the movie has no effect on the jit.qt.movie object's matrix output, which is still controlled by the metro object. If you stop the movie with the metro on, you will still receive a new matrix at the rate of the metro object (in this case, 25 times per second), even though all the matrices will be the same.
Changing the rate of the movie will change the speed at which it plays back its video and audio content. Positive rate values will make the movie go forward, with a value of 1 signifying normal playback speed. Negative values will make the movie go backwards. A rate of 0 will stop the movie. The jit.qt.movie object takes a floating-point number as the argument to its rate attribute, so a value of 0.5 will make the movie play at half speed, and a value of -2.3 will make the movie play backwards at a bit more than double speed. If you play around with this value, you will note that the soundtrack will speed up, slow down, and play backwards to remain in sync with the video. Once the movie reaches its last frame (or first frame, if you're playing it backwards), it will loop to the opposite end of the file. This behavior can be changed by setting the loop attribute of the jit.qt.movie object with a value of 0 (no looping), 1 (regular looping), or 2 (palindrome looping).
The vol attribute controls the volume (loudness) of any soundtrack component the movie has. A value of 1 equals full volume, and a value of 0 will turn the sound off.
In this patch, both the rate and the vol attributes are initialized by the message box in the middle of the patch when the film is loaded. This way they will reflect the values stored in each new QuickTime movie (see below).
Time is on My Side
When a jit.qt.movie object opens a new movie, it reads in a lot of information (contained in the movie's header) about the movie, including how long it is, how many frames of video are in the movie, and how fast it is meant to be played. We use this metadata to control the movie's playback.
Important note: unlike many Jitter attributes, which are set either by you or the object itself, many attributes used by jit.qt.movie are dependent on the current movie file. Different movie files will generate different settings for many of the attributes discussed in this tutorial.
The first three attributes we queried, duration, timescale, and fps, tell us about how the movie file deals with timing. The duration attribute tells us the total length of the movie. This value is not expressed in milliseconds or frames, but in QuickTime time units. The actual length of each time unit depends on the timescale of the movie. The movie's timescale is the timing resolution of the movie per second. Dividing the duration of a movie by its timescale will tell you the approximate length of the movie, in seconds. Our crashtest.mov file, for example, has a duration of 2836 time units and a timescale of 600. The movie should run for about 4.73 seconds. If we want to move two seconds into the movie, we could set the jit.qt.movie object the messagetime 1200 (1200 time units divided by a timescale of 600 units/second gives us 2 seconds).
The fps, or frames per second, of a movie tells us how many individual video images exist in the movie every second. The higher the fps of a movie, the smoother the apparent motion of the movie will be (assuming, that is, that the individual frames are all in some way unique). Some common fps rates are 15, 24, 29.97, and 30. Our movie file in this example runs at 15 frames per second, which works out to a new frame of video every 40 time units, or about every 66.7 milliseconds. If we divide the duration of crashtest.mov by the number of time units per frame in the movie, we can determine that the movie file has 70 frames. If we wanted to, we could get the total number of frames in the movie by querying the jit.qt.movie object with the getframecount message, but then we wouldn't get to do the fun math!
Scrubbing and Looping

Displaying and setting the current playback frame
The area at the bottom of the patch contains two controls for further manipulating the movie's playback. The number box on the left displays the frame that the movie is currently playing. This value is being updated by the gettime message sent into the jit.qt.movie object by the metro object at the top of the patch; each time a new frame is output the time is updated. If you stop the movie's transport (by sending jit.qt.movie a stop message), you can "scrub" through the movie by dragging on the number box. The movie will jump to the frame specified as an argument to the frame message.

Setting loop points in a movie
Loop points (pairs of time values which specify the beginning and end of a loop) can be sent to a jit.qt.movie object by setting the looppoints attribute with two integer arguments. The rslider in the tutorial patch lets you select regions of the movie that the jit.qt.movie object will loop between. The size of the rslider has been set to the duration of the movie through the attribute query we performed when the movie was loaded. You can reset loop points by sending jit.qt.movie a looppoints message with no arguments (an example of this is at the top of the patch, along with a query message that highlights the entire rslider).
Summary
The jit.qt.movie object offers a number of simple attributes that allow you to change the way QuickTime content is played. You can stop and start movie playback with those messages. The rate attribute lets you change the speed and direction of movie playback. You can control the volume of a movie's soundtrack with the vol attribute.
You can get important information about the current movie loaded into the jit.qt.movie object by querying attributes such as duration, timescale, and fps. You can go to specific frames in a movie with the frame message, and you can set and retrieve looppoints for the movie. You can query the current time position of a movie by sending jit.qt.movie a gettime message.
More powerful functions, such as editing and saving movies, can be accomplished and will be discussed in later tutorials.

See Also

Name Description
jit.qt.movie Play or edit a QuickTime movie
metro Output a bang message at regular intervals
pack Combine numbers and symbols into a list
route Selectively pass the output out a specific outlet
unpack Break a list into individual messages