This tutorial demonstrates how to use Jitter in conjunction with a QuickTime-compatible image capture device—such as a webcam, a DV camera, or a PCI video input card—to grab video sequences and use them as matrices, or record them directly to disk. We can also use Jitter to record sound directly to disk as a QuickTime movie.

Open the tutorial.

When we capture video images from an input device, we are actually working with a sequence of images. In Tutorial 20, we created a sequence of images using the export operation of the jit.qt.movie object. This time, we'll use the jit.qt.grab object to grab a sequence of images.

The jit.qt.grab object provides an interface to one of QuickTime's components—the general mechanism used by QuickTime to extend its functionality. Components can include software modules that provide interfaces for new video codecs, or an interface between software and various kinds of hardware, or tasks like image capture and sound output. We've already used a QuickTime component in Tutorial 20 when we used the export message, and we'll be looking at other QuickTime component-based Jitter objects in the next several tutorials.

Notice that the jit.qt.grab object takes two arguments (320 and 240) that specify the width and height of the matrix output by the object. They also represent the dimensions of the internal buffer into which any captured data will be placed. The matrix will always be a 4-plane char matrix).

• Click the message box that says getvdevlist. This message causes the jit.qt.grab object to search for available video capture devices. The jit.qt.grab object will then send the names of any devices it finds out the right outlet in the form of a list preceded by the symbol vdevlist. In our patch, we're using iter to break the list up, and placing the device names in an umenu. Our list only has one item, DV Video, but yours may include different items.

• Click on the umenu and select the device you'd like to use. This causes the message box that says vdevice $1 to send the index of the selected video capture device (which is the same as its position in the umenu) to jit.qt.grab. If you don't explicitly choose a vdevice, jit.qt.grab defaults to the first selection in the list (equivalent to sending a vdevice 0 message) when it opens the component connection.

• Click on the message box that says open. The open message tells jit.qt.grab to open a connection to the sequence grabber component—to create a component instance—for the video capture device you've selected. Until you send the open message, jit.qt.grab will simply output its last matrix when you send it a bang or outputmatrix message—no sequence grabbing will occur.

• Click on the toggle attached to the metro object, to start sending bangs to jit.qt.grab. You should now see your captured video signal in the jit.pwindow.

• If you have multiple devices connected to your computer, you can use the vdevice attribute to switch between them, even after sending the open message to jit.qt.grab.

• To close the component connection, click on the message box that says close. Leave this patch open; we'll return to it in a moment.

The video capture device you're using may support several different inputs. For instance, a CapSure Card supports s-video and composite inputs, and an ATI Rage 128 Pro supports s-video, composite and tuner inputs. FireWire DV generally supports a single input. In this section, we'll learn how to list those inputs and switch between them.

• Re-open the jit.qt.grab object's component connection by clicking on the message box that says open.

• Click on the message box that says getinputlist. This causes jit.qt.grab to send a list of available inputs for your chosen device out the right outlet preceded by the symbol inputlist. The patch breaks this list up using the iter object and sends it to the umenu on the right of the patch.

• Click on the rightmost umenu to see a list of inputs available to your device. Our DV camera reports that it has one input: YUV component (DV). Our CapSure card reports composite and s-video inputs, as shown in the screen shot:

• To change your input, select an item from the umenu. This causes the message box that says input $1 to send the index of the selected input (which is the same as its position in the umenu) to jit.qt.grab, which will switch to your selection. If you don't explicitly choose an input, jit.qt.grab defaults to the first selection in the list (equivalent to sending an input 0 message) when it opens the component connection.

• You should now see your captured video signal (from your chosen input) in the jit.pwindow.

• When you're done, click the message box that says close to close the component connection.

For webcams, the normal operating mode of jit.qt.grab provides speed and good quality. For other higher resolution capture devices such as analog video-capture boards or DV cameras, we'd like to be able to adjust the quality of the sequence grabber to get the most out of them.

• Double-click on the p device_input subpatcher. The Patcher window that opens contains everything you need to set your vdevice and input settings. Once you've done this, close the subpatch window.

• Click the message box that says open to start the component connection. Click on the toggle attached to the metro object. You should now see your captured video signal (from your chosen input) in the jit.pwindow.

• To enable high quality mode, we need to send the message vmode 2 to jit.qt.grab. Enter the numeral 2 in the number box attached to the message box that says vmode $1. If your capture device supports a high quality mode, you'll probably see the image in the jit.pwindow change slightly.

• To compare the different quality modes and settings, let's zoom in on a detail of the captured signal. Click on the toggle attached to the message box that says usesrcrect $1. Sending the message usesrcrect 1 causes jit.qt.grab to capture only the portion of the input signal specified by the source rectangle attribute, srcrect. By default, the srcrect attribute is set to the full frame of the input signal.

• Change the values of the number boxes attached to the paksrcrect 0 0 320 240 object. This will generate a message to set the srcrect attribute. The srcrect message arguments refer to the left x, top y, right x and bottom y coordinates of the input frame, respectively. You should see the image changing to reveal only the portion of the input frame you specify. For best results, choose two numbers that have the same 4:3 aspect ratio as the input frame.

• Let's do some comparisons. First, switch the vmode setting back to 0 or 1, depending on what you were using before (reminder: vmode 1 (vdig mode) is only necessary and supported on specific capture devices). Compare the image quality to vmode 2 (high quality mode). On our system, using a DV camera, the image becomes noticeably crisper, and aliased edges are tightened up.

• Click on the umenu object. The object contains a list of available quality settings for vmode 2 (the settings have no effect in sequence grabber and vdig modes). Choosing an item from the umenu will cause the item's index number to be sent to jit.qt.grab, via the message box that says codecquality $1. Select some different quality settings, and observe the changes—both in terms of image quality and frame rate (displayed on the jit.fpsgui object). The default setting for codecquality is max (equivalent to sending a codecquality max or codecquality 4 message to jit.qt.grab).

• You can also specify the portion of the output matrix the captured frame will occupy—a destination rectangle—with the dstrect attribute. To enable the destination rectangle, click on the toggle attached to the message box that says usedstrect $1. By default, the destination rectangle is set to the dimensions of the jit.qt.grab object's output matrix.

• Change the values of the number boxes attached to the pakdstrect 0 0 320 240 object. As with the srcrect message, the dstrect message arguments refer to the left x, top y, right x and bottom y coordinates of the output matrix. You should see the image changing to occupy only the portion of the output matrix you specify. Notice that the pak object is connected to a t l clear object, which causes a clear message to be sent to jit.qt.grab before sending the dstrect message. You could modify the patch to see what happens if you don't send the clear message.

• When you're done, click the message box that says close to close the component connection.

You can save grabbed sequences directly to disk as a QuickTime movie, if you prefer. When you do this, jit.qt.grab writes straight to the hard disk without sending out any matrix output. With only a few minor differences, this process is similar to the one described in Tutorial 19. But this time, we'll be recording audio, too.

• Double-click on the p device_input patcher. The Patcher window that opens contains everything you need to set your vdevice and input settings. Once you've done this, close the subpatch window.

• Click the open message box to start the component connection. Click on the toggle attached to the metro object. You should now see the captured video signal from your chosen input in the jit.pwindow.

• The jit.qt.grab object, by default, has its write_video attribute set to on (1). To reflect this, we've used loadbang to turn on the toggle attached to the message box that says write_video $1. If you wanted to disable writing video and only write audio, you would send a write_video 0 message and a write_audio 1 message to jit.qt.grab. For now, leave the toggle connected to the message box that says write_audio $1 turned off (by default, the write_audio attribute is set to off (0)).

• Click on the write grabfile.mov 15. jpeg normalmessagebox. You've probably noticed that this message looks like the write message that we send to jit.qt.record object to start recording. Except for the lack of a timescale argument, the write message to jit.qt.grab is formatted identically—grabfile.mov is the file name, 15. refers to the output movie's frame rate, jpeg specifies the Photo-JPEG codec, and normal specifies normal codec quality. All of the arguments are optional; if we omit the file name, a file Dialog Box will appear. The remaining settings, if omitted, will retain their previous values. If there are no previous values, the default values for the capture device will be used.

• Recording begins immediately after you send the write message. While we are recording, the jit.qt.grab object doesn't output any matrices. We can tell because the jit.fpsgui object's display isn't changing. You can use the write_preview attribute to switch matrix output on and off while recording. The write_preview attribute is off (set to 0) by default. Click on the toggle attached to the message box that says write_preview $1 to enable matrix output while recording. Your recordings will be smoother if you leave write_preview off.

• Click the message box that says stop to stop the grab to disk operation, but leave the patch open.

The jit.qt.grab object sends a message out its right outlet after a write operation to confirm that the movie was successfully recorded. Since we've connected that outlet to a print object in our patch, we can see the results by looking at the Max Window. If everything went as expected, you should see print: write grabfile.mov 1 in the Max Window.

We can also record sound to disk using the technique just described. There are two ways to choose the sound device for jit.qt.grab.

We're going to use the Sound Settings Dialog Box for this tutorial, but you might find it instructive to try making an altered copy of the example patch for the message-based method. You can use the p device_input subpatcher as a model.

• Click the message box that says snd_settings. The Sound Settings Dialog Box will appear. Using the pop-up menus and other controls, adjust the sound input settings to your preference. Close the Dialog Box by clicking OK.

• Click on the toggle attached to the message box that says write_audio $1 to enable audio for the grab to disk operation.

• Click the write grabfile+snd.mov 15. jpeg normalmessagebox. The recording will begin immediately as before, but sound will also be recorded to the movie.

• Click the message box that says stop to end the recording. Locate the movie on your hard drive, and open it in QuickTime Player (or Max, if you prefer) to verify that sound was recorded with the movie.

• Click the close message box to close the component connection.

The jit.qt.grab object allows you to grab images from any QuickTime-compatible video input device. The object offers both Max-based and Dialog Box interfaces for listing devices and inputs, switching between them, and controlling image quality. The srcrect and dstrect attributes can be used to crop and position a captured image within a Jitter matrix. The jit.qt.grab object also provides a mechanism for recording video and sound directly to disk as a QuickTime movie.