Description
Use the jit.grab object to digitize video from any video digitizer and decompress the signal into a Jitter matrix. On OSX, QuickTime is used; on Windows, DirectX is used.
Discussion
jit.grab also offers a grab-to-disk mode. Although numerous parameters for control are offered, not all features are supported by all digitizers.
Matrix Operator
| Name | IOProc | Planelink | Typelink | Dimlink | Plane | Dim | Type |
|---|---|---|---|---|---|---|---|
| out | n/a | 1 | 1 | 1 | 4 | 1 | char |
More about Matrix Operators
The Jitter MOP
Since the matrix is Jitter's focus, it is not surprising that the majority of Jitter objects fall in this category of Matrix Operators. Every Matrix operator has some number of matrix inputs and some number of matrix outputs. Matrix inputs are referred to by the names "in", "in2", "in3", etc., from left to right, and matrix outputs are referred to by the names "out", "out2", "out3", etc., from left to right--i.e. the names are appended by the input/output number except for the first (leftmost) input and first (leftmost) output which are simply named "in" and "out". We will refer to the input or output name names as the "I/O-name".
Matrix inputs and outputs typically each have their own matrices internally where information is kept. This is necessary because Jitter is an asynchronous framework (i.e. all the matrices don't arrive at all inputs at the same time). Various aspects of matrix inputs and outputs can be set using the command [I/O-name] combined with one of the following suffixes: "_dim" which will set the dimensions of the specified I/O matrix, "_type" which will set the type of the specified matrix, "_planecount" which will set the plane of the specified matrix, or "_name" which will set the name of the specified matrix. There is one special case which does not have an internal matrix and this is the first input "in". This is the case since this special input actually triggers the calculation of the matrix operator, so it doesn't need to be cached until a calulation takes place, unlike the other inputs. Therefore there is no mechanism to set the dim, planecount, type, or name of "in".
Matrix operators accept what we'll refer to as "matrix args"--i.e. [planecount (int)] [ type (symbol)] [dim (int list)]. if these arguments are present, the adapt attribute will be turned off, otherwise it will be turned on. If adapt mode is turned on, each time a matrix is received in the first input, there will also be the equivalent of setting the dim, planecount, and type attributes to that of the input matrix. If the other inputs and outputs are linked to these attributes, this will affect their linked attributes as well. See the "MOP" table to determine which inputs and outputs will be linked to which attributes when adapt mode is turned on. For the leftmost input this is not applicable, and hence all columns are labelled "n/a".
The jit.matrix object is a named matrix which may be used to matrix data storage and retrieval, resampling, and matrix type and planecount conversion operations.
MOP Arguments
planecount [int]
Explicitly sets the number of planes for the output and any righthand inputs. If this is absent, the Matrix Operator will typically adapt to the lefthand incoming matrix attributes, except for special case operators.
type [symbol]
Explicitly sets the type of the matrix for the output and any righthand inputs. If this is absent, the Matrix Operator will typically adapt to the lefthand incoming matrix attributes, except for special case operators.
dimensions [list]
Explicitly sets the dimensions of the matrix for the output and any righthand inputs. If this is absent, the Matrix Operator will typically adapt to the lefthand incoming matrix attributes, except for special case operators.
MOP Attributes
adapt [int]
Matrix adaptation flag (default = 0 if matrix arguments are present, otherwise 1) When the flag is set, the jit.matrix object will adapt to the incoming matrix planecount, type, and dimensions.
[in/out]_dim [32 ints]
The matrix data dimensions (default = 1 1)
[in/out]_name [symbol]
The input or output name of the matrix (default = UID)
[in/out]_planecount [int]
The number of planes in matrix input our output data. Except in special cases, this value is equal to the planecount.
[in/out]_type [symbol]
The input or output matrix data type. Except in special cases, this value is equal to type.
[in/out]_type [symbol]
The input or output matrix data type. Except in special cases, this value is equal to type.
outputmode [int]
Output mode (default = 1 (calculate and output matrix))
0 = No output
1 = Calculate and output the matrix
2 = Pass input (no calculation)
3 = Pass output (no calculation)
type [int]
The matrix data type (default = char
Supported data types are char, long, float32, or float64.
MOP Messages
bang
clear
exportattrs
Arguments
getattributes
getstate
importattrs
Arguments
jit_matrix
Arguments
outputmatrix
summary
Attributes
adapt [int]
Adapt output matrix dimensions to native device dimensions. Enabled by default if no dim specified.
automatic [int]
Enable automatic matrix output when bound to jit.world.
bitrate [int]
The sound digitizer bit depth (default = digitizer-specific). 32 bit only.
8 = digitize sound at 8-bit resolution
16 = digitize sound at 16-bit resolution
blacklevel [float]
The video digitizer black level (default = digitizer-specific). 32 bit only.
brightness [float]
The video digitizer brightness level (default = digitizer-specific). 32 bit only.
channels [int]
The sound digitizer channel selection (default = digitizer-specific). 32 bit only.
1 = digitize sound in mono
2 = digitize sound in stereo
codeclist [system-dependent symbols]
The valid video codecs available on the system
Sending the message getcodeclist will cause a list of all valid codecs (that is, those with a functioning compressor component) to be reported from the dumpout. This list is guaranteed to contain only working codecs, and should be used in preference to the old, static codec list. 32 bit only.
codecquality [int/symbol]
The video digitizer codec quality. This is only active in vmode 2 (default = 4/max). 32 bit only.
0 or min = minimum
1 or low = low
2 or normal = normal
3 or high = high
4 or max = maximum
5 or lossless = lossless
Note that minimum quality is, in many cases, the codec's default quality. Use "low" quality for consistent results.
colormode [symbol]
The output matrix's color encoding (default = argb)
Possible values:
'argb'
(
ARGB (alpha, red, green, blue) colormode
)
'uyvy'
(
UYVY (YUV 4:2:2 packed) colormode
)
colorspace [int]
The video digitizer colorspace mode (default = digitizer-specific). 32 bit only.
0 = grayscale
1 = color
contrast [float]
The video digitizer contrast level (default = digitizer-specific). 32 bit only.
drawto [symbol]
A render context name, used when output_texture is enabled.
dropreport [int]
Dropped frames reporting flag (default = 0 (disabled))
When this flag is set, the message dropped will be sent from the rightmost outlet of the jit.grab object, followed by the number of dropped frames, whenever frame-dropping is detected. 32 bit only.
dstrect [4 ints]
The portion of the output matrix used for decompressing media to the internal matrix. (default = 0 0 (matrix width) (matrix height))
The proportions of the rectangle are expressed in the form left top right bottom . All values are relative to the top left corner of the viewing area of the output matrix.
engine [symbol]
Video engine backend. This argument can only be set in the max box. If not specified, it is determined by the Video Engine Max preference. As of this writing, possible values include avf (Mac only), qt , and viddll .
field [int]
The video digitizer field selection (default = digitizer-specific)
0 = digitizer determines field selection
1 = digitizer uses odd field
2 = digitizer uses even field MAC OSX ONLY WITH DFG/1394-1 digitizer (using ASC-s driver, version 2 or higher) 128 = digitizer uses both fields, alternating 129 = digitizer uses both fields, stacked (upper half is odd, lower half is even). 32 bit only.
framerate [float]
The video digitizer frame rate (default = digitizer-specific).
The digitizer has to be closed and re-opened before changes to framerate take effect.
framereport [int]
Frame reporting flag (default = 0)
When enabled, the message framecalc will be sent from the rightmost outlet of the jit.grab object as each frame is processed, followed by the number of milliseconds spent doing so.
gain [float]
The sound digitizer gain (default = digitizer-specific)
gamma [3 floats]
The video digitizer gamma (default = digitizer-specific)
hue [float]
The video digitizer hue adjustment (default = digitizer-specific)
input [int]
The current video digitizer input (default = digitizer-specific)
interp [int]
Image interpolation flag (default = 0)
maxfps [float]
The video digitizer's maximum frame rate (default = digitizer-specific). 32 bit only.
output_texture [int]
Enable OpenGL texture output (default = 0). When enabled an OpenGL texture is output instead of a Jitter matrix. The object's drawto attribute must be set to a valid gl context. An RGBA texture is output using the movie's native dimensions. When enabled, the following attributes have no effect:
adapt
colormode
dim
dstrect
srcrect
usedstrect
usesrcrect
playthru [int]
Sound digitizer playthrough flag (default = digitizer-specific). 32 bit only.
pll [int]
The phase locked loop (PLL) type (default = digitizer-specific). 32 bit only.
0 = broadcast mode
1 = VTR mode
samplerate [int]
Sound digitizer sample rate (default = digitizer-specific). 32 bit only.
48000 = 48kHz
44100 = 44.1kHz
32000 = 32kHz
22050 = 22.050kHz
22254 = 22kHz
16000 = 16kHz
11127 = 11kHz
11025 = 11.025kHz
8000 = 8000 Hz
saturation [float]
Video digitizer saturation level (default = digitizer-specific). 32 bit only.
sharpness [float]
Video digitizer sharpness level (default = digitizer-specific). 32 bit only.
singlefield [int]
Single field flag (default = 1 (enabled))
When the flag is set, an attempt is made to decompress one field of an interlaced frame at high quality, and then scale the image to the frame size. If the digitizer doesn't provide interlaced frames, this flag does nothing. 32 bit only.
snd_active [int]
Sound digitizer enable flag (default = 0). 32 bit only.
sndcodec [symbol]
Sound digitizer codec mode (used for recording) (default = digitizer-specific). 32 bit only.
none = no compression
raw = raw compression
big16 = 16-bit big endian
little16 = 16-bit little endian
float32 = 32-bit floating point
float64 = 64-bit floating point
24bit = 24-bit integer
32bit = 32-bit integer
little32 = 32-bit little endian
mace3 = MACE 3:1
mace6 = MACE 6:1
cdxa4 = CD/XA 4:1
cdxa2 = CD/XA 2:1
ima = IMA 4:1
ulaw = uLaw 2:1
alaw = aLaw 2:1
adpcm = Microsoft ADPCM (ACM code 2)
dviima = DVI/Intel IMA ADPCM (ACM code 17)
dvaudio = DV Audio
qdesign = QDesign music
qdesign2 = QDesign2 music
qualcomm = Qualcomm PureVoice
mp3 = MPEG Layer 3 (CBR or VBR)
snddevice [int]
The current sound digitizer (default = 0). 32 bit only.
sndinput [int]
The current sound input for the selected sound digitizer (default = 0). 32 bit only.
srcrect [4 ints]
Source rect from digitizer frame (default = 0 0 (matrix width) (matrix height))
standard [symbol]
The video digitizer standard selection (default = digitizer-specific). 32 bit only.
ntsc = NTSC
pal = PAL
secam = SECAM
texture_name [symbol]
Output texture name, when output_texture is enabled.
unique [int]
Unique frame filter flag (default = 0 (disabled))
When the flag is set, only new frames from the digitizer are output when the object receives a bang. If no new frame has been received from the digitizer, the jit.grab object will not respond to the bang.
uniqueid [int]
Unique camera ID. 32 bit only.
usedstrect [int]
Destination rect flag (default = 0) When the flag is set, the dstrect attributes are used when copying an input matrix to the internal matrix.
usesrcrect [int]
Source rect flag (default = 0) When the flag is set, the srcrect attributes are used when copying an input matrix to the internal matrix.
vdevice [int]
The current video digitizer (default = 0)
vmode [int]
The video digitizer mode (default = 0 (sequence grab)). 32 bit only.
0 = sequence grab mode
1 = vdig mode (necessary/desirable for some digitizers)
2 = DV high quality mode
volume [float]
The sound digitizer volume (default = digitizer-specific). 32 bit only.
whitelevel [float]
The video digitizer white level (default = digitizer-specific). 32 bit only.
window [symbol]
Window name (default = none) If this attribute is set, the jit.grab object will render directly into the named jit.window object, thus able to use hardware decompression and interpolation as permitted by QuickTime. The window must have noaccel set to 1 in order for this to work.
If no symbol argument is given, the jit.grab object's default behavior of rendering to and outputting a matrix is used. 32 bit only.
write_audio [int]
Audio track write flag (default = 0) When the flag is set, an audio track is written when grabbing images to disc. 32 bit only.
write_length [int]
The length (in frames) to limit write operations to (default = 0 (inactive)) When non-zero, limits the disk grab to the specified number of frames. The write operation will stop automatically. If you are grabbing sound only, write_length has no effect. 32 bit only.
write_preview [int]
Image preview flag (default = 0) When the flag is set, images can be previewed when grabbing images to disc. 32 bit only.
write_split [int]
Split file write flag (default = 0) When the flag is set, separate disk files for audio and video are written when grabbing images to disc. Otherwise, a single file containing both is written. 32 bit only.
write_video [int]
Video track write flag (default = 1) When the flag is set, a video track is written when grabbing images to disc. 32 bit only.
Common Box Attributes
annotation [symbol]
Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.
background [int] (default: 0)
Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.
color [4 floats]
Sets the color for the object box outline.
fontface [int]
Sets the type style used by the object. The options are:
plain
bold
italic
bold italic
Possible values:
0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'
fontname [symbol]
Sets the object's font.
fontsize [float]
Sets the object's font size (in points).
Possible values:
'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'
hidden [int] (default: 0)
Toggles whether an object is hidden when the patcher is locked.
hint [symbol]
Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.
ignoreclick [int] (default: 0)
Toggles whether an object ignores mouse clicks in a locked patcher.
patching_rect [4 floats] (default: 0. 0. 100. 0.)
Sets the position and size of the object in the patcher window.
position [2 floats]
Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.
presentation [int] (default: 0)
Sets whether an object belongs to the patcher's presentation.
presentation_rect [4 floats] (default: 0. 0. 0. 0.)
Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.
rect [4 floats]
Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).
size [2 floats]
Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.
textcolor [float]
Sets the color for the object's text in RGBA format.
textjustification [int]
Text Justification
Possible values:
0 = 'left'
1 = 'center'
2 = 'right'
varname [symbol]
Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.
Messages
close
defaults
exportimage
Arguments
file-type [symbol]
You can use the Max Preferences to specify a default image resolution for png image types.
getiidclist
getiidc_caps
Arguments
getiidc_state
Arguments
getinputlist
getsnddevlist
getsndinputlist
getvdevlist
iidc_state
Arguments
feature-specific data [list]
getiidc_csr
Arguments
0/1 [int]
iidc_csr
Arguments
offset [int]
0/1 [int]
open
settings
snd_settings
stop
write
Arguments
audiofilename [symbol]
FPS [float]
codec [symbol]
spatialquality [symbol]
temporalquality [symbol]
keyframes [symbol]
Starts grabbing to disk. If the write_split attribute is disabled, only one filename argument is required; Otherwise, the video and audio filenames are required. If no filename arguments are supplied, a file dialog box will open.
The default FPS is 30. frames/sec.
The default codec is raw. The following list of codecs is deprecated (retained for reference). See codeclist for the preferred method to list valid system codecs.
Supported codecs are raw, cinepak, graphics, animation, video, componentvideo, jpeg, mjpega, mjpegb, sgi, planarrgb, macpaint, gif, photocd, qdgx, avrjpeg, opendmljpeg, bmp, winraw, vector, qd, h261, h263, dvntsc, dvpal, dvpropal, flc, targa, png, tiff, componentvideosigned, componentvideounsigned, cmyk, microsoft, sorenson, indeo4, argb64, rgb48, alphagrey32, grey16, mpegyuv420, yuv420, sorensonyuv9 and mpeg4.
The default spatialquality and temporalquality values are max. Supported quality settings are lossless, max, min, low, normal, and high.
Note that minimum quality is, in many cases, the codec's default quality. Use "low" quality for consistent results.
The default keyframes is 0, which will cause keyframes to be inserted automatically, as necessary.
See Also
| Name | Description |
|---|---|
| Working with Video in Jitter | Working with Video in Jitter |
| jit.movie | Play or edit a QuickTime movie |
| jit.record | Record a QuickTime movie |
| jit.qt.effect | QuickTime Effects for Jitter matrices |
| jit.dx.grab | Digitize video using DirectX (Windows) |
| jit.dx.videoout | Output video to DirectX (Windows) |
| jit.qt.videoout | Output video to QuickTime video output component |
| Tutorial 21: Working With Live Video Input | Tutorial 21: Working With Live Video Input |