Command: movie

Usage:
movie  action  options

The movie command captures image frames from ChimeraX and assembles them into a video (movie file). This command is intended for recording movies using command scripts. To record ChimeraX interactively in real time with user manipulations shown, a separate screen-capture program should be used instead. See also: wait, save, view, windowsize, making movies, virtual reality,

One of the following action keywords must be given:

• record – start recording frames
• encode – stop any ongoing recording and encode the saved image frames into a movie file
• stop – stop recording frames
• reset – reset status to zero frames saved
• abort – halt any encoding in progress and perform a reset
• crossfade – interpolate from the preceding frame to the following frame
• duplicate – expand the preceding frame into multiple frames
• ignore – start/stop ignoring subsequent movie commands
• formats – list the available movie file formats
• status – report status (number of saved frames, etc.) in the Log

Actions may have specific options and arguments, described below.

supersample  N
Whether to render each image at a higher resolution and then sample it down to the final size. Increasing N increases the smoothness of edges within images and the calculation time with little effect on file size. N is the number of pixels sampled in the X and Y dimensions for each pixel in the final saved image (default 1, no supersampling). Useful values range from 1 to 4, with 3 generally recommended when supersampling is done. In addition, a value of 0 can be used to indicate onscreen rather than offscreen rendering, without supersampling. A potential disadvantage of supersampling is that silhouettes in the final images may be thinner than expected because there is a limit to how thick they can be in the initial images; if this happens, try reducing the supersampling level N.

size  width,height
Generate images at the specified pixel width and height by offscreen rendering. This option allows creating movies with image dimensions larger than the graphics window; if size is not given, the dimensions of the graphics window will be used. If the specified aspect ratio (the ratio of width to height) does not match that of the graphics window, the movie will show more or less of the scene vertically than is visible in the graphics window.

format  jpeg | png | ppm
The format of saved image files.

transparentBackground  true | false
Whether to save image files with a transparent background. This option applies only to images saved in the png format. Regardless of this option, images saved in other formats and the resulting movie file (even if encoded from png images with a transparent background) will not have a transparent background because their formats do not support it.

directory  image-directory
An existing directory (folder) in which image files should be saved, or the word browse to specify it interactively in a file browser window. If not specified by the user, the directory varies by platform. The directory can be reported with the movie status command after some frames have been recorded.

pattern  filename-pattern
The filename-pattern is a string to use when naming the image files; the default is chimovie_xxxx-*, where xxxx is replaced by random characters and * is replaced by the frame number (for example, 00001, 00002, etc.). Any specified filename-pattern should include one and only one *, which will be replaced by the frame number.

limit  maxframes
Record no more than maxframes image frames (default 15000). This safeguards against creating too many image files, as may occur with certain scripting errors.

output  pathname
The pathname is the name and location of the output movie file (default depends on platform, ~/Desktop/movie.mp4 on Mac). The output file format can be indicated by filename suffix or with the format option. The output keyword can be omitted if the pathname precedes any other options, but if the output keyword is used, the option can appear anywhere in the command. The word browse can be used instead of pathname to specify it interactively in a file browser window. Multiple pathnames separated only by commas can be given (example: movie encode ~/Desktop/mymovie.mp4,~/Desktop/mymovie.avi).

verbose  true | false
Whether to show the ffmpeg (encoding software) command and its output in the Log.

format  h264 | vp8 | webm | theora | ogg | ogv | mov | qt | quicktime | avi | wmv | apng
Encode the movie in the specified format. Format keywords and their synonyms are listed in the table below. Alternatively, the format can be specified by output filename suffix. The available formats can be listed with the command movie formats.

format keyword, synonyms	format	filename suffix
h264	H.264 (default on Mac, Windows)	.mp4
vp8 webm	VP8/WebM	.webm
theora ogg ogv	Theora	.ogv
mov qt quicktime	Quicktime	.mov
avi	AVI MSMPEG-4v2	.avi
wmv	WMV2	.wmv
apng	APNG	.png

quality  highest | higher | high | good | medium | fair | low
Encode the movie to play back at a variable bit rate appropriate for the specified quality level, default good. Higher quality corresponds to a higher bit rate and a larger file (at a given window size and frame rate). The qscale option can be used for finer control. When specified by the user, quality overrides qscale and bitrate (constant bit rate encoding).

The quality, qscale, and bitrate options do not apply to the lossless animated PNG (apng) format.

qscale  factor
Encode the movie to play back at a variable bit rate, where the quality factor is an integer that can range from 1 (highest quality and highest data rates) to 31 (lowest quality). This option overrides bitrate (constant bit rate encoding).

bitrate  rate
Encode the movie to play back at a constant bit rate, where rate is the target rate in Kbits/s. Generally, 200 Kbits/s gives low quality, 1000 medium, and 6000 high, but this strongly depends on image dimensions and the amount of motion. For HD movies (1920 x 1080 pixels), a rate of 25000 Kbits/s would be expected to give high quality.

framerate  fps
The frame rate is movie playback speed in image frames per second (default 25).

In ChimeraX, the target or intended graphics frame rate during interactive use is 60 fps (default). The actual frame rate may be lower depending on computer performance and what is being displayed. Recording generally slows the process further; however, the frame rate of the resulting movie is controlled independently with the framerate option described above. Thus, movie playback may be faster or slower than the original process in ChimeraX. The command graphics rate (maxFrameRate option) can be used to make the interactive frame rate as similar as possible to the playback rate to preview movie-content scripts.

roundTrip  true | false
Whether to include the frames in reverse order as the second half of the movie.

resetMode  clear | keep | none
By default, a reset of the frame counter to zero will occur when movie encoding is complete. At the same time, the image files can be deleted (clear, default) or retained (keep) for some other purpose, such as movie encoding with a different program. The third option, none, indicates that no reset should occur: the frame counter should not be zeroed and the images should not be deleted. This allows subsequently re-encoding the movie using the same set of images.

wait  true | false
Whether to wait for encoding to finish before proceeding. If multiple movies are being recorded back-to-back, it is necessary to wait until one is encoded before starting to record the next, because any recording will be halted automatically when encoding finishes.

Reset the frame counter to zero, either deleting the image files (clear, default) or retaining them (keep) for some other purpose such as movie encoding with a different program.

N is the number of frames in the crossfade transition (default 25), and can be given without the frames keyword. The transition is a linear interpolation from the preceding image frame to the image frame specified right after the crossfade. The crossfade transition will not be shown during recording, but will be in the resulting movie. For a crossfade transition that is shown interactively, the crossfade command can be used instead.

N is the number of times to duplicate the preceding image frame (default 25), and can be given without the frames keyword. The duplicates will not be shown during recording, but will be in the resulting movie.

Start ignoring subsequent movie commands (no keyword, or equivalently the keyword on, true, or 1) or stop ignoring them (keyword off, false, or 0). Ignoring movie commands may be useful during script (movie content) development.