Movie utilities Isis software documentation

Movie utilities

This library defines several objects and routines for handling movies in Isis, including recording, playback, editing, and manipulating raw movie data. Isis movie objects, once opened, may be attached to Macaroni or Amazon movie sources.

Playing Isis movies

From command line:

% isisu playmovie movie-filename { fullscreen-flag } % isisu browsemovie movie-filename { fullscreen-flag }

From Isis:

(play-movie movie-filename { fullscreen-flag } ) (browse-movie movie-filename { fullscreen-flag } ) You can play Isis movies from an Isis script or from the command line via the isisu utilities program. The "play" functions simply play an existing Isis movie to a window on the screen with synchronized audio. The "browse" functions accept simple key commands to allow you to step through an Isis movie frame by frame, save individual frames in separate image files, or select portions for trimming and editing. A help screen is printed when you run the movie browser.

fullscreen-flag is optional and if True or 1, the movie will be played in full screen mode. Press ESC to quit the movie while in this mode.

Recording Isis movies

From command line:

% isisu recmovie filename { options ... }

This command lets you record Isis movies with synchronized audio. Only the filename is required. The various options described below allow you to set the source for digitizing and the video and audio characteristics of the movie. Prior to running this command, you should select the appropriate record source and find the optimum audio input level (IGain) using an audio mixer program such as gmix. Note that you should always record movies to a local disk, not a networked disk, and preferably to a fast SCSI disk, as certain IDE drives are not fast enough to keep up with high-quality or high-rate captures. The record program will notify you if frames were dropped or if audio lost continuity during the recording.

Option Description Default
-size hsize vsize Size of images to digitize. 320 240
-dev devname Name of device to digitize from. Typically /dev/videoX, where X is the number of the video card, starting at 0, if you have more than 1. /dev/video0
-input inputnum Input number. On WinTV cards, input 0 is the tuner and input 1 is the composite video input. 1
-std standard Video standard. Should be one of ntsc, pal, or secam. ntsc
-qual quality Quality of JPEG images, between 1 and 100. 95
-achans channels Number of audio channels, 0 for no audio, 1 for mono, and 2 for stereo. 2
-arate rate Sample rate of audio, typically 8000, 11025, 22050, or 44100. 22050
-abits bits Number of bits for audio, either 8 or 16. 16
-freq frequency Channel frequency to tune (if recording from a tuner). You can find frequency lists for various countries and standards on the web. Try http://www.qrf.com/ustvchan.htm for US frequencies. 67.25
-bri brightness Brightness, between 0 and 100. 50
-con contrast Contrast, between 0 and 100. 50
-dur duration Length of time to record in seconds. If not specified or set to 0.0, the program will ask you to press enter to start and stop recording. 0.0
-delay delaytime Number of seconds to wait before starting to record. 0
-sub subrate Time subsampling rate. Set to 1 to record every frame, 2 for every other frame, 3 for every third frame, and so on. 1

For example, to record a movie with JPEG quality 50 and no audio, you would enter this:

% isisu recmovie mymovie1 -qual 50 -achans 0
To record a movie from the composite video input of your computer with size 160x120, quality 75, 11 KHz audio, and 15 frames per second, you could enter this:
% isisu recmovie mymovie2 -size 160 120 -qual 75 -arate 11025 -sub 2
To record a 60 minute long movie from channel 4 on the tuner input of your video card, at 10 frames per second, mono 11 Khz audio, and quality 50, you would enter this:
% isisu recmovie mymovie3 -input 0 -freq 67.25 -dur 3600 -sub 3 -qual 50 -achans 1 -arate 11025

From Isis:

(record-movie [option value] [option value] ...) You can also record movies directly in an Isis program with this function. The options are similar in this case to the command line version, except that each option takes the form of a list of 2 items, a string naming the option and the value for the option. The options are explained in the table below and behave similarly to those described above.

Option Default
["filename" filename] "movie"
["size" [hsize vsize]] [320 240]
["device" devname] "/dev/video0"
["input" inputnum] 1
["standard" standard] "ntsc"
["quality" quality] 95
["achans" channels] 2
["arate" rate] 22050
["abits" bits] 16
["frequency" frequency] 67.25
["brightness" brightness] 50
["contrast" contrast] 50
["duration" duration] 0.0
["delay" delaytime] 0
["subrate" subrate] 1

The three examples from above would be entered like this when using the record-movie function:

(record-movie ["filename" "mymovie1"] ["quality" 50] ["achans" 0]) (record-movie ["filename" "mymovie2"] ["size" [160 120]] ["quality" 75] ["arate" 11025] ["subrate" 2]) (record-movie ["filename" "mymovie3"] ["input" 0] ["frequency" 67.25] ["duration" 3600] ["subrate" 3] ["quality" 50] ["achans" 1] ["arate" 11025])

Editing Isis movies

From command line:

% isisu gluemovies movie1name movie2name ... outfilename

From Isis:

(glue-movies [ movie1name movie2name ... ] outfilename) This command takes several Isis movies and glues them together in order to make a new Isis movie with the given file name. Audio is precisely edited as well. All the movies audio and video parameters must match.

Converting Isis movies

From command line:

% isisu isis2avi isis-movie-filename avi-movie-filename % isisu avi2isis avi-movie-filename isis-movie-filename % isisu jpeg2isis jpeg-basename isis-movie-filename audio-filename achans arate abits

From Isis:

(convert-isis-to-avi-movie isis-movie-filename avi-movie-filename) (convert-avi-to-isis-movie avi-movie-filename isis-movie-filename) (convert-jpeg-sequence-to-isis-movie jpeg-basename isis-movie-filename audio-filename achans arate abits) These programs allow you to convert Isis movies to and from other movie formats. isisu isis2avi and convert-isis-to-avi-movie will convert an Isis movie to an AVI movie, playable in Windows Media Player, Quicktime Player, and others. After your movie is converted to AVI, you can use Quicktime Pro, Windows Media Cleaner, or another program to convert it to any other format, perhaps one with better a better compression ratio.

isisu avi2isis and convert-avi-to-isis-movie convert in the opposite direction, from AVI to Isis movie format. However, the AVI movie must be encoded in a very specific way: JPEG (or "Photo JPEG") for the video frames, and raw PCM for the audio track. You will need to convert whatever movie format you have into this special AVI movie format before running this program. Some movie processing applications in Windows and Macintosh allow you to create movies in this special AVI format.

If you cannot convert your movie to the special AVI format, you should use a program like Quicktime Pro to convert the movie into a series of separate JPEG files, with a separate file containing the audio. Typically the individual files will be named like this: "movie001.jpg ", "movie002.jpg", "movie003.jpg", and so on. You can use isisu jpeg2isis or convert-jpeg-sequence-to-isis-movie to convert a set of JPEG images of this kind into an Isis movie. You must specify the "base" name of the files (the part of the file names up to the frame number), and the file names must end with ".jpg". There can be up to 10 leading zeros in the frame number in each filename. You may also specify a file that stores audio that you wish to be part of the movie. The audio must be in raw PCM format and you must specify the number of channels, sample rate, and number of bits for the audio in the file. The audio arguments are optional on the command line, and if not present, no audio will be included with the movie. In the Isis function form, just pass Null for the audio arguments if you do not wish to include any audio in the file.

Using Isis movies

(set movieobj (new-isis-movie movie-filename))

In order to use a previously-created Isis movie, you must create a new Isis move object that references that movie by calling new-isis-movie with the movie's filename. A procedure will be returned that will serve as your interface to the movie. By passing different kinds of arguments to this procedure, you can get information about the movie or request the JPEG data from particular frames.

Getting movie information

(movieobj key) (movieobj key default) Parameters about the movie are stored as key-value pairs. Passing a string "key" to the movie object will return the value of that parameter of the movie. If a particular parameter does not exist, the function will return Null, unless you've passed an optional default value as the second argument. There are some standard key names so that the most important information in a movie may always be found, and you may create others for your own purposes.
"basename" # the base filename of the movie "data-file" # string, name of JPEG data file "offset-file" # string, name of offset information file "framecount" # integer, total number of video frames "framesize" # list of 2 integers [xsize ysize] "coding" # string, "jpeg" "yuv" "rgb" or others "fps" # real number, frames per second "audio-file" # string, name of audio file "audio-format" # string, typically "PCM" "audio-channels" # integer, usually 1 or 2 "audio-rate" # integer, usually 8000, 11025, 22050, or 44100 "audio-bits" # integer, 8 or 16 "audio-size" # integer, size of audio file in bytes
The data, offset, and audio file keys reference filenames within the directory specified by the movie's base filename, which can be retrieved with the "basename" key. For example if the movie's basename key is "/grad/stefan/testmovie/" and the audio-file key is "audio", then the audio for the movie may be found at "/grad/stefan/testmovie/audio22".

Retrieving movie frames

(movieobj frame bufaddr) Passing an integer frame number and the address of a memory buffer will cause the movie object to recall the image data for the specified frame and place it in the buffer. The size of the memory buffer must be large enough to hold the incoming image data. You can calculate an appropriate buffer size by using the frame size and coding information. Note, if the coding of the movie is "jpeg" or another compressed data scheme (as it typically is), the data placed in the buffer is the compressed data for the specified frame. No decompression or other processing is performed. The number of bytes of data actually placed into the buffer is returned.

Closing a movie

(movieobj "close") When you are completely finished with a movie, you should call the movie object with "close" to deallocate any resources associated with it.

Other utilities

(isis-movie-duration movieobj) # return running time of movie in seconds (isis-movie-audio-filename movieobj) # return audio filename or Null if no audio These utilities accept an Isis movie object opened with new-isis-movie and return the specified information.

Isis movie player for Macaroni

The "movie player" object allows you to play Isis movies in the Macaroni scene structuring framework. See the Macaroni page for more information on Macaroni, which uses OpenGL as its rendering engine. The advantage of the movie player object is that it handles the playback of audio and consists of a "queue" through which you can play movies in sequence with no break in continuity. You can have many movie players operating simultaneously, each rendering to a different rectangle in Macaroni, and each with its own audio voice.

Creating movie players

(set mplayer (new-movie-player macobj chans rate bits unsigned bigendian)) (set mplayer (new-silent-movie-player macobj)) To create a movie player object, call new-movie-player with a Macaroni Isis movie object to which the player should render its images. Also pass the audio characteristics to be used by the player: number of channels, sample rate, number of bits, unsigned flag (False if 16 bit, True if 8 bit) and big endian flag (False for PCs, True for Macs). new-movie-player returns a procedure that you will invoke with various commands at a later point to control the object. All of the movies you play on the movie player must agree with the audio characteristics that you specify. The audio playback for movie players is handled by ALSA. new-silent-movie-player creates a video-only movie player.

For best efficiency, all the movie players needed for a particular application should be created at the beginning of the program rather than in an "on-demand" fashion.

Adding movies to the play queue

(mplayer [mp-enqueue movieobj { entry duration } ]) This command adds a movie to the tail of the play queue of the movie player. The movie will play directly after all the other movies in the queue have completed. If nothing is currently playing, playback will begin immediately. movieobj should be the Isis movie object referring to the movie (obtained with new-isis-movie described above). An optional entry point and duration (in seconds) may be specified. If not given, the default is to play the entire movie from the beginning.

Playing movies

(mplayer [mp-process]) Once movies have been added to the queue, they will play automatically. However, in order to see anything in your Macaroni scene, you must invoke each movie player with the mp-process command inside of your main program loop (usually the procedure handed to macaroni-start). This command updates the video image and keeps the audio playing continuously. You should call it exactly once each time through the main loop. If it is not called often enough, audio may lose continuity.

Getting statistics

(mplayer [mp-timeleft]) The mp-timeleft command will return the amount of time (in seconds) before all the movies in the queue will complete playing. You can use this command to judge how much time you have left before playback runs out. In order for playback to be perfectly continuous, you should add new movies to the queue at least 1 second prior to the end of the movies currently in the queue.

Controlling the queue

(mplayer [mp-skip]) (mplayer [mp-delqueue]) (mplayer [mp-reset]) mp-skip stops the movie that is currently playing and skips directly to the next movie in the queue. mp-delqueue deletes everything in the queue except for the movie that is currently playing. mp-reset stops the currently playing movie and deletes everything in the queue.

Closing down

(mplayer [mp-quit]) The mp-quit command closes down the movie player and releases any resources allocated to it.

Example program

This example program defines a list of movies and lets the user enqueue them into a movie player in a particular order by pressing the number keys within the playback window. The space bar resets the player. Try modifying it to include more than one movie player, and try changing the sizes, positions, and other attributes of those objects.

Writing Isis movies

(set outmovie (create-isis-movie basename framesize fps coding achans arate abits)) This function allows you to create a new Isis movie consisting of image and audio data from any source. You must pass a string base filename for the movie, the frame size [hsize vsize] in pixels, the video rate in frames per second, the image encoding scheme (typically "jpeg", "rgb", or "yuv"), number of audio channels, audio sampling rate, and number of audio bits. If you want to create a movie with no audio, pass Null for the last 3 arguments. create-isis-movie will return a procedure that will be your interface to output the image and audio data for the movie. (outmovie "video" numbytes bufaddr) Calling the output movie object the "video" creates a new frame in the movie. You must pass the number of bytes of data and the address of a buffer holding the data for this frame, and the movie object will record it to the file. (outmovie "audio" numbytes bufaddr) Similarly, to add audio data to the movie, simply call the output movie object with "audio" along with the number of bytes and a buffer address. The audio track is effectively separate from the video, so it is not necessary to correlate "video" calls with "audio" calls, and each call to "audio" does not necessarily have to represent a single frame's worth of audio--it can be any size. (outmovie "close") When you have written all of the audio and video data associated with the movie, call the output movie object with "close" to finish the process and close the movie. The movie will not be playable unless you make this final call.

Requirements:
Scripts: (load "movie-utilities.isis")
Other: Needs Video For Linux 2, SDL, ALSA and image processing libraries.