# &app; Manual V&manrevision;

## Introduction

&app; is a tool that captures movement on a selected area of an X11 screen to files. It does this by taking a configurable number of screenshots per second and saving them either as individual screenshots or as a video. This kind of application, today, is commonly labelled screencam or screencast utility. In fact, one of the oldest of those utilities was Lotus Screencam which served as the inspiration for &app;.

&app; can be used in two distinct modes of operation:

1. &sf-cap; -- capture individual screenshots to one file each.

2. &mf-cap; -- capture and encode to video on the fly.

### Mnemonic

The naming of the modes of operation derives from the number of frames that get stored in the output file: One or many.

### Audio Capture

&app; can capture audio, but only in &mf-cap; operation.

Recording in single-frame capture mode may be more convenient if you wish to preprocess the images before encoding, or if you need other video codecs &app; does not support. Individual images can later be encoded with tools like ffmpeg, mencoder, or transcode.

To report a bug or make a suggestion regarding the &app; application or this manual, follow the directions on &app;'s site at SF.net.

## Getting Started

### To Start &app;

You can start &app; in the following ways:

Applications menu

- Choose Sound & Video XVidCap Screen Capture.

Command line

- Execute the following command: `xvidcap`. For more information about command line usage see the xvidcap manpage.

### When You Start &app;

When you start &app;, the following window is displayed:

#### &app; Control

Shows &app; control.

The window with a proper title and buttons is &app;'s main control, while the red rectangle is the selection frame enclosing the area to capture.

### &app;'s main control elements:

Filename Display and Menu | The Filename Display and Menu displays the current output filename and, if in &mf-cap; mode, the index number of the most recently captured frame in square brackets. In &sf-cap; mode the index number of the current frame will typically be part of the filename. When in &sf-cap; mode a left click resets the frame count to the start. A right-click while not capturing will pop up the main menu. #### Default Capture Mode By default, &app; starts in &mf-cap; mode.
Frame Drop Meter | The Frame Drop Meter provides an indication of how well your capture session can capture at your desired frame rate. If your system is under heavy load, it may not be able to capture as many frames per second as you wish. This will result in a video that plays back too quickly. &app; displays a green status if you can or can almost capture at the desired frame rate. If you have some frame drop the status turns to yellow, or red if there is excessive frame drop. To reduce frame drop you can capture a smaller part of your screen, select a lower frame rate, quit as many other applications putting stress on your system as possible, or run on a more powerful machine. It may also help to downscale the captured data. Another means for making screen capture lighter on your system is to make use of the XDamage extension. See the corresponding paragraph about the general options tab of the preferences dialog.
Stop Button | The Stop Button stops a running recording session.
Pause Button | The Pause Button pauses a running or continues a paused recording session. You can also select this before starting to record to start paused.
Record Button | The Record Button starts a recording session.
Single Snaphot Button | The Single Snapshot Button is only active in a paused &sf-cap; mode capturing session. Then it allows you to take individual snapshots on a click of this button.
Rewind Button | The Rewind Button has different uses depending on the current capture mode. In &sf-cap; mode rewinding relates to the index number of the current frame to capture. Imagine you have a stopped capture session that has captured ten PNG images. The filename display may show test-0010.png. You then realize, the last two snapshots weren't what you needed. You can then click the rewind button twice. This changes the filename display to test-0008.png. If you continue to capture, frames eight and nine in images test-0008.png and test-0009.png will be overwritten. In &mf-cap; mode the rewind button works quite similar. It does not, however, manipulate the index number of the current frame, but rather of the current movie as it relates to the autocontinue feature.
Forward Button | The Forward Button does the opposite of the rewind button in that it increments the current frame's index number or the movie index number depending on capture mode.
Frame Selection Lock | The Frame Selection Lock makes the capture selection move with the main control if selected. If deselected, the capture selection will stay where it is when the main control moves. If, in the preferences dialog, you have checked "Capture Area Follows Mouse" the capture selection follows the mouse pointer instead.
Frame Selector Button | Click the Frame Selector Button to change the area you want to capture. When you click it, the cursor changes to a cross-hair cursor. After that you can either: click on a single window to capture that window. #### Moving Captured Windows Note that the area selection is not sticky to the window in the sense that it would follow the window you originally selected, if you move it away. All it does is adjust position and dimension of the selected capture area to match the contents of the window clicked on. If you move the window afterwards, the capture area will stay where it is, unless you have the frame selection lock enabled and manually move the main control to the right position. click and drag to select an arbitrary portion of the screen. click on the backdrop to select full-screen capture. #### Full-Screen Capture With current display sizes, full-screen capture has a very high probability of putting too much stress on your system. Watch the frame drop monitor and possibly adjust your screen resolution if you absolutely must capture full-screen. Remember that DVDs typically contain resolutions of 720 x 486. Capturing full-screen at a resolution of 1400 x 1050 means encoding about 4 times the data rate of a DVD in real time -- not something you will be doing with a pencil and paper. It is not just the encoding of a full screen capture, though, that may put too much stress on your system. Grabbing the complete capture area from the X11 display is a heavy task on its own right. Using the XDamage extension may ease the effect of that, however there may be caveats. See the corresponding paragraph about the general options tab of the preferences dialog. #### Resize By Dragging Starting with version 1.1.5, you can also resize the area to capture by dragging on the edges of the frame while not capturing. Use that feature as you would resize a normal window.
Edit Button | The Edit Button calls an external program to edit the most recently captured frame in &sf-cap; mode or the current video in &mf-cap; mode. &app; does not provide those applications. By default, &app; calls gimp in &sf-cap; mode and nothing at all in &mf-cap; mode. Both settings can be changed through the preferences dialog.

### Main Menu

A right-click on the filename display pops up the following menu:

#### Main Menu

Main Menu

### the main menu's items:

Preferences Menuitem | open the preferences dialog
Save Preferences Menuitem | save the current settings #### Volatile Settings Note that &app; does not save changed preferences automatically. You can modify settings, exit &app;, and return to your previous settings by just restarting &app;. If you want to make changes to your settings persistent, select this. It will write your settings to a file `.xvidcaprc` in your home directory.
Multi-Frame Menuitem | select multi-frame capture mode #### Parallel Settings for Capture Modes Keep in mind that you can have distinct settings for &mf-cap; and &sf-cap; modes configured and stored in parallel. Choosing this menuitem or the next toggles between the two modes and their respective settings.
Single-Frame Menuitem | select single-frame capture mode
Autocontinue Menuitem | toggle autocontinue feature on/off This is selectable only in &mf-cap; mode and only if the filename is mutable. Refer to the autocontinue prefernces setting for more information.
Show Frame | show frame around capture area (yes/no) If this is unchecked, the frame around the area to capture is hidden. #### Hiding frame around the area to capture This is esp. helpful, if you are running a compositing window manager like compiz and use effects which make the capture frame lag behind the movement of the area to capture (e. g. wobbly windows). In such a case the lagging frame parts may move inside the area to capture ending up visible in the finished video. The cleaner solution, however, is to disable the effect for windows of class "Xvidcap". That makes hiding the frame unnecessary.
Make Video Menuitem | execute encoding command set in preferences In &mf-cap; mode this is not at all needed and not set by default. It can, however, be set to allow executing a custom transcoding command if output is needed in a format other than &app; can generate. The script used in &sf-cap; mode by default is provided by &app; but may need to be copied to your executable path to make it available. Refer to the commands preferences tab for more information on setting encoding commands.
Animate/Play Menuitem | execute playback command set in preferences In &mf-cap; mode this is mplayer and animate (part of ImageMagick) by default. Refer to the commands preferences tab for more information on setting encoding commands.
Help Menuitem | pop up online help
About Menuitem | pop up &app;'s about dialog
Quit Menuitem | exit &app;

## Preferences

You can start the Preferences dialog either by right-clicking on the main control's filename display and selecting Preferences or pressing CTRL-P. The dialog itself is divided into four tabs.

### General Preferences

The first tab of the preferences dialog contains miscellaneous settings around general behaviour of &app;.

#### General Preferences

General Preferences

### the general settings are:

Default Capture Mode | This setting governs which capture mode is used by &app; by default, i. e. if no other settings give &app; a clue.
Capture Mouse Pointer | Check this to capture the mouse pointer. #### Custom Mouse Pointer Shapes Without the XFixes extension to X11, there is no way for &app; to capture the real, current mouse pointer, only its position. If the extension is not available both on the machine where &app; was built and where it is run, &app; generates a dummy mouse pointer in the captured movie. In this case you will find a radiobutton next to this checkbox which allows you to select whether the dummy pointer should be white or black.
Save Capture Geometry | Check this if you want to store size and position of the currently selected area to capture along with other preferences on selecting Save Preferences from the main menu.
Capture Area Follows Mouse | Check this if you want a locked frame to follow the mousepointer's movement rather than that of the main control windows.
Hide Frame | Check this if you want the frame around the area to capture to be hidden. See the Show Frame menu item for more information, but notice that this works the other way around, i. e. a check hides the frame.
Use Shared Memory | Check this if capturing frames should make use of X11's shared memory extension. #### Shared Memory X11 Access Use of shared memory is enabled by default if the machine where &app; was built supported shared memory access in X11, which is typically the case, nowadays. You will need to turn this off, however, if X11 server and client are not running on the same machine, e. g. if you are on a X terminal thin client.
Manually Set XDamage | Check this if you want to override the decision &app; makes about whether or not to use the XDamage extension to speed up screen capture. This extension allows &app; to be notified about the portions of the screen that have changed between individual frames, so it does not need to fetch the complete area to capture for every frame. &app; will default to using XDamage if it was available at build-time, if it is available at runtime, and if the window manager used is not compiz or beryl. If you are using beryl and still want to use the XDamage extension, check this control to enable the radiobuttons to the right and choose "enabled". #### XDamage and compiz or beryl Due to the advanced visual effects possible with compiz, beryl and the likes, the notifications received by &app; through XDamage may not be sufficient for determining the right screen portions to capture. You can still force &app; to use it as described above, but your mileage may vary.
Autocontinue | If recording in &mf-cap; mode and using a maximum number of frames to capture or a maximum capture duration, &app; can automatically continue capturing to a new video once the specified maximum number of frames or capture duration have been reached. This can effectively create a series of movies split to chunks of the specified maximum length. To use this you need to specify a mutable target filename.
Always Show Results Dialog | Check this to always show a dialog with an overview of capture results on stopping a capture session. The dialog will always be shown if required (e. g. to specify a target filename). This makes the dialog be shown where it would not strictly be required. By default the results dialog is always displayed. If, however, you have unchecked the Show this dialog next time in the results dialog before, you can turn it back on here.
Minimize to System Tray | Check this to make &app; minimize to the system tray on starting a recording session. In that case the main control panel will hide and the frame drop monitor will apear in the system tray. A right-click on it will allow you to pause or stop the recording session. On stopping the main control window will be displayed again.
Rescale Output Percentage | Use this to make the output video smaller than the original size of the portion of the screen captured. The percentage specified here is the size of the output relative to the input. For example, specifying 25 will make the output width and height half the original each. Thus the image size of the output will be 25 percent of the captured area. #### Rescale does not work with XWD output Rescaling output frames does work with all output formats and codecs other than XWD.

### Single-Frame Capture Preferences

This tab contains the settings for &sf-cap; mode. Because &sf-cap; mode does not support audio capture, only video settings are configurable here.

#### Single-Frame Capture Preferences

Single-Frame Capture Preferences

### the &sf-cap; mode settings are:

File Name | Enter a file name pattern here to use for saving the individual frames captured. The file name must contain a pattern that will be replaced by the actual frame count for each individual file. The patterns used here are those understood by fprintf. A file name containing this kind of pattern will henceforth be called a mutable file name. #### File Name Selection Instead of typing in a filename you can also click on the file selector button (...). Be sure to put a numeric pattern in the file name afterwards, though. If in doubt use %5d somewhere in your file name.
File Format | A check in the auto checkbox makes &app; automatically select an appropriate output format based on the filename specified. For example, if you specify test-%4d.png the output format will be Portable Network Graphics File (png). If the auto checkbox is unchecked, the dropdown menu allows for manually selecting a format, possibly overriding &app;'s decision.
Frames per Second | The number of frames to capture per second.
Maximum Time | Maximum time to record in seconds
Maximum Frames | Maximum frames to capture
Frame Start Number | Start counting frames with this number
Frame Number Increment | When capturing increment the frame count by the specified number for each frame captured. #### Deprecated Settings Due to the limited use of Frame Start Number and Frame Number Increment those settings may go away in future versions.
Quality | Desired output quality #### Quality Setting changed in 1.1.5 The effect of setting quality to a value below 100 % has changed in &app; 1.1.5. Be sure to test the values in your stored preferences. Quality settings do not apply to XWD output.

### Multi-Frame Capture Preferences

This tab contains the settings for &mf-cap; mode.

#### Multi-Frame Capture Preferences

Multi-Frame Capture Preferences

### the &mf-cap; mode video settings are:

File Name | Enter a file name or file name pattern here to use for saving the individual frames captured. For &mf-cap; the string supplied here only needs to be a mutable filename if the autocontinue feature is to be used. Otherwise a simple filename is sufficient here, which may also be selected through the file selector button (...).
File Format | A check in the auto checkbox makes &app; automatically select an appropriate output format based on the filename specified. For example, if you specify test.avi the output format will be Microsoft Audio Video Interleaved File (avi). If the auto checkbox is unchecked, the dropdown menu allows for manually selecting a format, possibly overriding &app;'s decision.
Video Codec | A check in the auto checkbox makes &app; automatically select an appropriate video codec for the output format selected. For example, if Microsoft Audio Video Interleaved File (avi) is selected the video codec will be Microsoft DIVX 2. If the auto checkbox is unchecked, the dropdown menu allows for manually selecting a codec, possibly overriding &app;'s decision.
Frames per Second | The number of frames to capture per second. This control can either be a scale or a dropdown menu, if the selected codec only supports certain frame rates.
Maximum Time | Maximum time to record in seconds
Maximum Frames | Maximum frames to capture
Quality | Desired output quality #### Quality Setting changed in 1.1.5 The effect of setting quality to a value below 100 % has changed in &app; 1.1.5. Be sure to test the values in your stored preferences. In the past a quality setting of 20 could yield good results depending on the codec chosen. This is no longer the case. A setting of 75 may be acceptable to you, a value of 85 will typically be. A video resulting from a capture with a quality setting of 90 will not normally be easy to distinguish from one captured at 100 percent quality.

### the &mf-cap; mode audio settings are:

Enable Audio | Check this to capture audio along with video frames.
Input Device | Type in the name of the input device to caputer audio from or select it through the file selector button (...).
Audio Codec | A check in the auto checkbox makes &app; automatically select an appropriate audio codec for the video output format selected. For example, if Microsoft Audio Video Interleaved File (avi) is selected the audio codec will be MPEG2. If the auto checkbox is unchecked, the dropdown menu allows for manually selecting a codec, possibly overriding &app;'s decision.
Sample Rate | Audio sample rate. If you're using piped input audio the audio stream is resampled to the specified rate if required. #### Piped Audio Input Instead of capturing audio from a real-time audio source, you can also pipe a pre-recorded audio file to &app;. This way you can effectively dub your recording with a given audio track. To do this you need to: cat my.mp3 | &app; `--mf` `--audio yes` `--audio_in -` `--file test.avi` When you start the recording session in &app; it will sample audio from the piped file.
Bit Rate | Audio bit rate. If you're using piped input audio the audio stream is resampled to the specified rate if required.
Channels | Number of audio channels. If you're using piped input audio the audio stream is resampled to the specified number of channels if required.

### Command Preferences

This tab contains various settings regarding which commands to execute for certain actions.

#### Command Preferences

Command Preferences

### possible commands to set are:

Single Frame Playback Command | The command specified here is executed when the item Animate / Play is selected from the main menu or the play button is pressed on the capture results dialog while in &sf-cap; mode. #### Specifying Commands Any command can be configured here. It could theoretically be completely unrelated to video capture. You will always want to make sure that the called application is in your path and that you end your command line with the & to avoid that &app; waits for the called application to finish before continuing itself. &app; makes the following environment variables available to the called application:

XVFFRAME | number of the first frame captured
XVLFRAME | number of the last frame captured
XVWIDTH | width of the area captured
XVHEIGHT | height of the area captured
XVFPS | desired (!) frame rate
XVTIME | desired (!) time per frame
XVFILE | file name

The file name, however, needs special treatment for &sf-cap;. Here the pattern used for mutable file names is sent literally as specified for the Single Frame Encoding Command further down only. For the Single Frame Playback Command the pattern is converted to wildcards, i. e. test-%4d.png becomes test-????.png. For the Single Frame Edit Command the pattern is replaced with the number of the current frame, i. e. test-%4d.png becomes test-0001.png. For all Multi Frame commands the latter is used where if the filename is mutable and the number used is the index number of the most recently recorded video as with the autocontinue feature.
Single Frame Encoding command | The command here is executed when the main menu's Make Video item is selected while in &sf-cap; mode.
Single Frame Edit Command | The command here is executed when the main control's Edit Button is clicked while in &sf-cap; mode.
Multi Frame Playback Command | The command specified here is executed when the item Animate / Play is selected from the main menu or the play button is pressed on the capture results dialog while in &mf-cap; mode.
Multi Frame Transcoding command | The command here is executed when the main menu's Make Video item is selected while in &mf-cap; mode.
Multi Frame Edit Command | The command here is executed when the main control's Edit Button is clicked while in &mf-cap; mode.

## Capture Results Dialog

When you first stop a recording session, a dialog will pop up displaying the results of the capture session. This popup can be prevented from appearing again by unchecking the Show Next Time checkbox or this button in the preferences dialog.

The dialog itself can take one of two forms depending on whether or not you configured &app; to ask you for a target file name after the capture.

### Ask User For File Name

For the time being, the only way to configure &app; to ask the user to specify a file name after the capture rather than providing one up-front it by providing an empty file name either through the command line using `--file ""` or in the preferences dialog. This requires manually specifying an output file format. In this configuration &app; will store the video in a temporary file in your home directory which can lateron be renamed / moved to the desired destination. This is not compatible with autocontinue.

If &app; is configured to ask the user for a file name, the results dialog will look like this:

### Capture Results Dialog with Ask User For File name

Capture Results Dialog with Ask User For File name

Besides the overview of the used settings and information about the desired and achieved frame rates, you can select name and location of the file you want the video to be stored in through clicking Save As. Once a file has been selected, the label next to the button will display the absolute file name. You can also choose to preview the video through Play or abandon it through Delete. Note that the latter does not immediately delete the temporary file, though.

Normally, the results dialog will look like this:

### Normal Capture Results Dialog

Normal Capture Results Dialog

## The Preferences Warning Dialog

Whenever &app; determines that the settings you have chosen will not work well, it will display those issues in a standardized format. Unless you run &app; with the `--gui no` parameter, it will pop up the following dialog:

### Preferences Warning Dialog

Preferences Warning Dialog

### GUI-less operation

When running from the command line with the `--gui no` parameter, those warnings will be displayed in plain text on the terminal. You will not be seeing the Details section unless you also specified `-v`.

## There are a few situations in which such messages can be displayed:

On start | When &app; is started, it checks the consistency of the settings for the current capture mode and will report on issues it finds there. You will not be able to cancel out of this dialog, but have to revisit your preferences. &app; only checks on the current capture mode and will not care about inconsistencies with the respective other mode. Therefore, there is the second situation.
On change of capture mode | If you change the current capture mode through the menu &app; will check the consistency of the settings for the new capture mode and will report on issues it finds there. If you cancel the warning dialog, you will return to your previous capture mode selection.
When submitting changed preferences | When you leave the preferences dialog &app; will check the settings for both capture modes. Cancelling the warning dialog will take you back to the preferences dialog.

In the Preferences Warning Dialog you will find one or more messages consisting of three rows each. The first one contains a message type or severity, a unique numeric ID and a short name for the error. The second row gives a more detailed description, and the third one tells about the action &app; is going to take if you chose to click OK.

Such an action might be to automatically correct the issue by chosing a plausible default, to ignore the issue if it is not severe or to quit &app; if no solution can automatically be determined.

The severity of an issue can be INFO for purely informational messages where no change is made to any settings, WARNING where a minor change to current settings is suggested, ERROR where a major change to current settings is required, or FATAL ERROR. A fatal error is always an error where the suggested action is to quit &app;. You will not see issues of severity INFO unless you run &app; in verbose mode.