Humanities Home page   Office of Digital Humanities
Back     BYU LiveCode Lessons Gateway

Using the Revolution Video Grabber

Revolution includes an external library of commands that lets you capture video from a camera attached to your computer, using capabilities included in QuickTime. There is very little written on how to use it, so this is an attempt to gather all the information I can find about it into a single place. First I'll describe the basic process of video capture, then give a listing of all of the video grabber commands included with Revolution. Finally, I include some random notes that I have come across in which other Rev developers have described their experiences with the Video Grabber.

Note: The Video Grabber library only exists for Mac OS and Windows systems.

The Basic Process

Since I work on Mac OS X, and therefore use QuickTime, I will describe what I did to make video capture work using QuickTime. I assume that Windows with QT installed will work the same, but I don't have the time or equipment to test it.

This is the system configuration I was using when I created this tutorial (June 2008):

I first tried out the Video Capture.rev stack that comes in the Sample Projects folder with your copy of Revolution. It didn't work completely right for me, so I combed through its handlers and was able to grok it enough to put together a working sample of my own.

In order for the Video Grabber to work you must be careful to do the following, in order:

  1. Initialize video capture using the revInitializeVideoGrabber command.
  2. Optionally set the rectangle the capture window will use with the revSetVideoGrabberRect command.
  3. Choose, save and set the video grabber settings. Here is the handler I used:
    on mouseUp
  revVideoGrabDialog
  local vSettings --docs say the variable has to exist before referring to it
  revVideoGrabSettings "vSettings"
  set the videoSettings of this cd to vSettings
  revSetVideoGrabSettings "vSettings"
end mouseUp
  4. A big key to making it all work right is to set the revVideoGrabIdle command at regular intervals so that you give QuickTime enough clock cycles to do its thing. Here's the handler I came up with that worked (be sure to put it in the message path of the buttons you use to start video capture.)
    global gMsgId

on videoRefresh
  revVideoGrabIdle
  send "videoRefresh" to me in 10 milliseconds
  put the result into gMsgId
end videoRefresh
  5. Now, whenever you preview or capture video to a file you have to make sure you call the above handler.
  6. Here's how to start video preview:
      revPreviewVideo
  videoRefresh
  7. To stop video preview just do:
    8. global gMsgId

on mouseUp
  revStopPreviewingVideo
  cancel gMsgId -- so you don't keep trying to call revVideoGrabIdle
end mouseUp
  8. Here's how to start recording video to a file: 
      set the filetype to "TVODMooV" --make sure Mac OS knows what it is
  revRecordVideo [path to file]
  videoRefresh
  9. Stopping recording is similar to stopping preview:
    10. global gMsgId

on mouseUp
  revStopRecordingVideo
  cancel gMsgId
end mouseUp
  10. The video should now be saved in the file you specified in step 8 above. The last thing you have to do is close the video grabber using the revCloseVideoGrabber command.

So there you have it. It's not perfect, but it works. You can probably get it to work better by experimenting and tweaking. If you want to have a look at my video grabber test stack, download the stack from http://revolution.byu.edu/video/videoGrabberTest.rev or just get it in Revolution by entering in your message box:

go to stack URL "http://revolution.byu.edu/video/videoGrabberTest.rev"

A Compilation of All Video Grabber Entries from the Revolution Scripting Dictionary

These are all quoted from the Revolution dictionary that's included with Revolution. I found it useful to get them all in one place and in a more or less logical order. Keep in mind that RunRev may choose to update them with new releases, so always refer to your copy of the Rev dictionary to make sure you have the latest information.

Contents

Important! All of these commands are part of the Video library. To ensure that these commands work in a standalone application, you must include this custom library when you create your standalone. In the Inclusions section on the General screen of the Standalone Application Settings window, make sure that "Video Grabber" is selected from the list of script libraries.

revInitializeVideoGrabber see online dict
command

Syntax:
revInitializeVideoGrabber parentStack,videoMethod,grabberRect

Example:
revInitializeVideoGrabber the short name of this stack, "QT","100,100,200,200"
revInitializeVideoGrabber the short name of this stack, "VFW",the rect of this stack

Summary:
Opens the video grabber window.

Description:
Use the revInitializeVideoGrabber command to start up video capture capability.

Parameters:
The parentStack is the short name of the stack that the video-grabber should attach itself to.

The videoMethod is either "QT" or "VFW".

The grabberRect is the rectangle of the video grabber window, and consists of four integers separated by commas: the left, top, right, and bottom edges of the video grabber, in absolute (screen) coordinates.

Comments:
You must use the revInitializeVideoGrabber command before using any of the other commands and functions in the Video library. The command does two things:

* Loads the code necessary for video capture into memory.
* Opens the video grabber window.

Note: The video grabber is not a stack window, so you can't set its properties. To change the size and location of the video grabber, use the revSetVideoGrabberRect command.

Once the video grabber is open, you can use the revVideoGrabDialog command to specify where the video camera (or other video source) is connected. Use the revRecordVideo command to record video from the camera to a file, or use the revPreviewVideo command to display video without saving it.

To use QuickTime for video capture (on Mac OS, OS X, or Windows systems), specify "QT" as the videoMethod. To use Video for Windows (on Windows systems), specify "VFW".

revCloseVideoGrabbersee online dict
command

Syntax:
revCloseVideoGrabber

Example:
revCloseVideoGrabber
if there is no stack "Video Control" then revCloseVideoGrabber

Summary:
Closes the video grabber window.

Description:
Use the revCloseVideoGrabber command to free up memory when you're done using the Video library.

Comments:
The Video library loads the operating system's video capture software into memory when you use the revInitializeVideoGrabber command. The revCloseVideoGrabber command unloads this software, freeing up the memory it uses, when you're done.

If your application uses video capture, you should execute the revCloseVideoGrabber command either when your application is finished using video capture, when the stack that uses video capture is closed (in a closeStack handler), or when your application quits (in a shutdown handler).

If the video grabber was already recording video to a file, the revCloseVideoGrabber command stops the recording.

revVideoGrabDialogsee online dict
command

Syntax:
revVideoGrabDialog [settingsType]

Example:
revVideoGrabDialog
revVideoGrabDialog "format"
revVideoGrabDialog the label of button "Dialog Type"

Summary:
Displays a dialog box for configuring QuickTime or Video for Windows video capture.

Description:
Use the revVideoGrabDialog command to specify settings for use with the video grabber.

Parameters:

The settingsType is one of the following:

Note: Some video camera drivers don't support some settingsTypes.

Comments:
You must use the revInitializeVideoGrabber command to open the video grabber before you can use the revVideoGrabDialog command.

If you specified "QT" as the video method when you executed the revInitializeVideoGrabber command, do not specify a settingsType. QuickTime video recording settings are found in a single dialog box, which you display with the following statement:

revVideoGrabDialog

If you specified "VFW", use the settingsType parameter to specify which dialog box you want to show.

revVideoGrabSettingssee online dict
command

Syntax:
revVideoGrabSettings dataVariable

local dataVariable
revVideoGrabSettings "dataVariable" -- should use a previously declared variable
set the savedVideoSettings of this card to dataVariable

Summary:
Puts the current video capture settings, stored as binary data, into a variable.

Description:
Use the revVideoGrabSettings command to store video-capture settings you specify in the video capture dialog box.

Parameters:
The dataVariable is the name of an existing variable.

Comments:
The revVideoGrabSettings command returns binary data, placing it in the dataVariable.

You specify settings for video capture in the video capture dialog box, which is displayed by the revVideoGrabDialog command. You can get the current settings with the revVideoGrabSettings command and restore them later with the revSetVideoGrabSettings command. This allows you to make changes to the video-capture settings under script control.

The value returned by the revVideoGrabSettings command consists of binary data and is not human-readable, but you can store it in a file or custom property and restore your settings later using the revSetVideoGrabSettings command.

warning sign Warning! If you attempt to put the binary data returned by this command into a field, Revolution will crash. (Tested on Revolution v. 2.9.0.)

Important! The revVideoGrabSettings command works only for QuickTime video capture. If you are capturing video with Video for Windows, the revVideoGrabSettings command does not return a meaningful value.

revSetVideoGrabSettingssee online dict
command

Syntax:
revSetVideoGrabSettings settingsString

Example:
local tSettings
put the cSavedSettings of me into tSettings
revSetVideoGrabSettings "tSettings"

warning sign Warning! This way this command works changed slightly in Rev v. 2.9. Specifically, you must now first put the previously saved settings data into a variable, then pass the variable name as a quoted literal to this command. The old syntax allowed you to pass a direct reference to a custom property, variable, or external file. While the old syntax works in Mac OS X v. 10.4.x, as of Mac OS X v. 10.5.x, the old syntax will cause Revolution to crash. (Thanks to Glen Bojsza for helping me discover this change.-DNA)

Summary:
Restores video settings saved by the revVideoGrabSettings function.

Description:
Use the revSetVideoGrabSettings command to restore settings for video capture.

Parameters:
The settingsString is a string of binary data in the format returned by the revVideoGrabSettings function.

Comments:
You specify settings for video capture in the video capture dialog box, which is displayed by the revVideoGrabDialog command. You can get the current settings with the revVideoGrabSettings function and restore them later with the revSetVideoGrabSettings command. This allows you to make changes to the video-capture settings under script control.

Important! The revSetVideoGrabSettings command works only for QuickTime video capture.

Important! The revSetVideoGrabSettings command is part of the Video library. To ensure that the command works in a standalone application, you must include this custom library when you create your standalone. In the Inclusions section on the General screen of the Standalone Application Settings window, make sure that "Video Grabber" is selected from the list of script libraries.

revPreviewVideosee online dict
command

Syntax:
revPreviewVideo

Example:
revPreviewVideo
if the hilite of button "Preview Only" then revPreviewVideo

Summary:
Displays the video input in the video grabber without recording it.

Description:
Use the revPreviewVideo command to see the image from a video camera on the screen.

Comments:
You must use the revInitializeVideoGrabber command to open the video grabber before you can use the revPreviewVideo command.

The revPreviewVideo command shows the input from the video source in the video grabber window, but does not record it. To save the video as a file while displaying it, use the revRecordVideo command instead.

If the video grabber was already recording video to a file, the revPreviewVideo command stops the recording.

Important! If you are using QuickTime for video capture, execute the revVideoGrabIdle command periodically while previewing or recording video. Otherwise, you may experience poor quality in the video capture.

To stop displaying the video input, use the revStopPreviewingVideo command.

revStopPreviewingVideosee online dict
command

Syntax:
revStopPreviewingVideo

Example:
revStopPreviewingVideo
if isShowingVideo then revStopPreviewingVideo

Summary:
Stops showing input from a video camera in the video grabber window.

Description:
Use the revStopPreviewingVideo command to stop showing video input.

Comments:
When you stop previewing video, the video grabber window shows a blank screen.

revRecordVideosee online dict
command

Syntax:
revRecordVideo filePath

Example:
revRecordVideo "/Disk/Folder/file.mov"
revRecordVideo "mymovie.avi"
revRecordVideo theFileName

Summary:
Records video from a video camera to a file.

Description:
Use the revRecordVideo command to record a movie file.

Parameters:
The filePath is the name and location of the file that will hold the recorded video data. If you specify a name but not a location, Revolution assumes the file is in the defaultFolder.

Comments:
You must use the revInitializeVideoGrabber command to open the video grabber before you can use the revRecordVideo command.

If you specified "QT" as the video method when you executed the revInitializeVideoGrabber command, the recorded video is stored in QuickTime format. If you specified "VFW", the recorded video is stored in AVI format.

If the video grabber was already recording video to a file, executing the revRecordVideo command again stops that recording and starts a new one.

Important! If you are using QuickTime for video capture, execute the revVideoGrabIdle command periodically while previewing or recording video. Not doing so may cause the video in the video grabber to stutter or display strange screen artifacts

To stop recording the video input, use the revStopRecordingVideo command.

revStopRecordingVideosee online dict
command

Syntax:
revStopRecordingVideo

Example:
revStopRecordingVideo
if the mouseClick then revStopRecordingVideo

Summary:
Stops a video capture that was started with the revRecordVideo command.

Description:
Use the revStopRecordingVideo command to stop recording video input to a file.

Comments:
The revStopRecordingVideo command stops a recording started with the revRecordVideo command. If no recording is in progress, this command has no effect.

revVideoGrabIdlesee online dict
command

Syntax:
revVideoGrabIdle

Example:
revVideoGrabIdle
send "revVideoGrabIdle" to me in 10 milliseconds

Summary:
Gives processing time to QuickTime during video previewing and recording.

Description:
Use the revVideoGrabIdle command to avoid display problems during video capture.

Comments:
When using QuickTime for video capture, you need to execute the revVideoGrabIdle command periodically in order to let QuickTime update the display. (Not doing so may cause the video in the video grabber to stutter or display strange screen artifacts.) If you have issued the revPreviewVideo or revRecordVideo command, be sure to call the revVideoGrabIdle command periodically until you stop previewing or recording video.

There is no specific interval to use between calls to revVideoGrabIdle. If you are seeing jittering or strange artifacts in the video grabber window, try decreasing the interval and calling revVideoGrabIdle more often.

Note: If you specified "VFW" as the video method when you executed the revInitializeVideoGrabber command, you don't need to call revVideoGrabIdle. If the video capture is using Video for Windows, the revVideoGrabIdle command is ignored and has no effect. You need to call revVideoGrabIdle only if you specified "QT" as the video method.

revSetVideoGrabberRectsee online dict
command

Syntax:
revSetVideoGrabberRect left,top,right,bottom

Example:
revSetVideoGrabberRect 100,300,100,400
revSetVideoGrabberRect globalRect(the rect of button "Video")

Summary:
Changes the size and location of the video grabber window.

Description:
Use the revSetVideoGrabberRect command to move or resize the video grabber window.

Parameters:
The left, right, top, and bottom are integers.

Comments:
You must use the revInitializeVideoGrabber command to open the video grabber before you can use the revSetVideoGrabberRect command.

The rectangle specified by the left, top, right, and bottom is the rectangle of the video grabber window: the top, left, bottom, and right edges of the video grabber, relative to the parent stack window. .

revVideoFrameImagesee online dict
command

Syntax:
revVideoFrameImage frameWidth,frameHeight,dataVariable

Example:
local myData
revVideoFrameImage 400,300,"myData"
revVideoFrameImage the width of image "Snapshot",\
   the height of image "Snapshot","thisFrame"

Summary:
Puts the current frame in the video grabber into a variable.

Description:
Use the revVideoFrameImage command to capture a single frame of video.

Parameters:
The frameWidth is a positive integer.

The frameHeight is a positive integer.

The dataVariable is the name of an existing variable.

Comments:
The revVideoFrameImage command returns binary data in the same format as the imageData property of images, placing it in the dataVariable. To show the captured frame in an image, set the image's imageData property to the value placed in the dataVariable, as in the following example:

put empty into frameContainer
revVideoFrameImage 400,300,"frameContainer"
set the imageData of image "Picture" to frameContainer

If the frameWidth and frameHeight are not the same as the width and height of the video grabber window, the frame is scaled before being returned by the revVideoFrameImage function. The data returned by the command always uses the frameWidth and frameHeight, even if this means the video must be stretched or shrunk to fit. For example, if the video grabber window is 100 x 100 pixels, but you specify 200 as the frameWidth and 100 as the frameHeight, the returned data fits an image 200 x 100 pixels, with the horizontal dimension stretched to fit.

Notes about Video Grabber

In digging around the mail list archives I have found references to several undocumented (= unsupported?, unimplemented?, deprecated?) commands. These are most likely only for use with the "VFW" (Video For Windows) framework, and are probably there to make up for the lack of support for VFW by the revVideoGrabSettings and the revSetVideoGrabSettings commands.

RevSetVideoGrabAudio
command

Appears to have syntax:
RevSetVideoGrabAudio true|false,numberOfChannels,bitDepth,sampleRate

Where:
numberOfChannels = 1 or 2
bitDepth = 8 or 16
sampleRate = 11025, 22050 or 44100

Example:
RevSetVideoGrabAudio true, "1", "8", "11025"

 

RevSetVideoGrabCompressor
command

Appears to have syntax:
RevSetVideoGrabCompressor compressorName

Example:
RevSetVideoGrabCompressor "Morgan MJPEG Compressor"

 

RevSetVideoFrameRate
command

Apparent Syntax:
RevSetVideoFrameRate frameRate

Example:
RevSetVideoFrameRate "30"

 

Comments on These Undocumented Commands :

One reply on the Improve-Rev list said:

"RevSetVideoGrabAudio doesn't actually do anything yet, at least for QuickTime capture."

In the same thread, one user reported:

I am currently working with the video functions under XP. Can't say
for sure what works under OSX. This does work under XP (using the
latest Rev Windows file, revVideGrabber.dll).

RevSetVideoGrabCompressor "Morgan MJPEG Compressor"
RevSetVideoFrameRate "30"
RevSetVideoGrabAudio true, "1","8","11025"
revRecordVideo movfile

This series of commands (which uses the Morgan codec) gives me very
high-quality compressed video (under 1000 kbits/second frame rate, 30
frames per second). When I check the resulting .avi file in Apple's
Quicktime Player and go to MOVIE INFO, it shows "8-bit Unsigned
Integer, Mono, 11.025 kHz".

 

Back     BYU LiveCode Lessons Gateway
Maintained by Devin Asay.
Copyright © 2005 Brigham Young University