Name
GetVideoFrame -- convert video frame to a brush (V5.0)
Synopsis
[id] = GetVideoFrame(brushid, frame, videoid[, unit])
Library
video

Function
This function can be used to convert a single frame of a video to a brush. The video must have been opened using OpenVideo() or the @VIDEO preprocessor command. In the first argument, you have to pass an id for the brush you want this function to create (alternatively, you can pass Nil for automatic id selection). In the second argument you have to specify which frame of the video should be grabbed, and the third argument specifies the identifier of the video to use as the source.

The optional argument unit is used to specify how the value passed in frame should be interpreted. If unit is set to 0, then the value passed in frame is interpreted as an absolute frame index. This is also the default setting. If unit is set to 1, then the value passed in frame is interpreted as a time stamp in milliseconds and GetVideoFrame() will grab the frame at this very timestamp. It is recommended to use unit 1 access to single frames because this is usually much faster. If you really need to access single frames by their absolute index, please read the word of warning below.

Please note that frame access by absolute index is usually a very expensive operation because, for most video formats, Hollywood needs to traverse all the way through the stream until it reaches the requested frame. Such a traversal requires a lot of time and is thus of limited practical use. However, there is one special case where GetVideoFrame() can be used very efficiently and that is the sequential grabbing of frames from a video stream. "Sequential grabbing" means that you read one frame after the other from the video stream, i.e. first frame 1, then frame 2, then frame 3, etc. This can be done very quickly. The only thing that will take lots of time is reading frames in backward direction (i.e. frame 10, frame 9, frame 8, etc.), or making huge leaps between frame reads (i.e. frame 1, then frame 1000, then frame 5000, etc.). This will take a lot of time. Sequential reading will be efficient, however.

To find out the exact number of frames inside a video stream, you can use the GetAttribute() command and query the #ATTRNUMFRAMES attribute using the #VIDEO object type.

Inputs
id
identifier for the brush to create or Nil for auto id selection
frame
frame to load; format of this argument depends on the value passed to the unit argument below
videoid
identifier of the video to use as source
unit
optional: base to use for the frame argument; this can be either 0 which means that the frame argument specifies an absolute frame index or 1 which means that the frame argument specifies a timestamp in milliseconds (defaults to 0)
Results
id
optional: identifier of the brush; will only be returned when you pass Nil as argument 1 (see above)
Example
my_frame = GetVideoFrame(Nil, 1, 2)
DisplayBrush(my_frame, #CENTER, #CENTER)
The code above extracts frame 1 from video stream 2 and stores it in a new brush. The brush is then displayed at the center of the display.
Show TOC