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:

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:

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:

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.

From command line:

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.

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.