Capture

dosbox-automation can capture screenshots, record audio, and record video directly from the emulator. By default, all captures are saved to the capture directory in the current working directory. You can change this with the capture_dir setting.

Screenshots

Screenshots can be saved in multiple formats: upscaled (sharp pixels, aspect-corrected), rendered (post-shader, exactly what you see on screen), or raw (the framebuffer's contents with 1:1 pixel aspect ratio).

Use Ctrl+F5 / Cmd+F5 to take a screenshot using the default format(s) configured by the default_image_capture_formats setting.

Video capture

Press Ctrl+F7 / Cmd+F7 to start and stop video recording. The video is captured as a lossless AVI file.

When capture is started through the REST API or a Lua script, it can record either the raw emulator frames or the rendered display as seen on the screen. The hotkey always records raw frames.

Raw vs rendered

The two modes answer different questions.

Raw records what the emulated video hardware produced: the framebuffer at the game's native resolution (say 320x200), with frames arriving exactly as the emulation generates them. No shaders, no scaling, no window influence. This is the mode for archiving, regression testing, and pixel-exact comparison between runs: the same game doing the same thing produces the same frames on any machine, regardless of window size or shader settings.

Rendered records what you actually see: the post-shader image at window resolution, at a constant frame rate matching the video mode. CRT shader, aspect correction, and integer scaling are all baked into the recording. This is the mode for demo footage and for documenting how something really looked on screen. The cost: output depends on your window size and shader settings, and the larger frames take more work to encode. If recording makes the emulation stutter on your machine, lower capture_video_compression_rendered (see below); at 0 the recording is stored uncompressed, which trades disk space for almost no encoding cost.

Both modes encode to lossless ZMBV inside an AVI container; transcode with ffmpeg if another codec is needed. The single-frame grab (/api/v1/video/frame) takes the same mode parameter, so a script can pull one rendered screenshot without starting a recording.

Recording stops on its own before the capture drive runs out of space (see capture_min_free_space_mb below), and a write error such as a full disk or a removed device ends the recording with a log message instead of leaving a corrupt file. An interrupted AVI stays playable up to the point of truncation.

Audio capture

Press Ctrl+F6 / Cmd+F6 to start and stop audio recording. Raw MIDI and OPL output can also be captured for those who want to tinker with game music outside the emulator.

Configuration settings

Capture settings are to be configured in the [capture] section.

capture_dir

Directory where the various captures are saved, such as audio, video, MIDI, and screenshot captures (capture in the current working directory by default).

capture_min_free_space_mb

Minimum free space on the capture drive, in megabytes. Video recording stops cleanly when free space falls below this limit, so a long recording cannot fill the disk. Set to 0 to disable the check.

Possible values: a number in megabytes, 1024 (default)

capture_video_compression

Zlib compression level for raw video capture, 0 (store only) to 9 (maximum). Raw frames are small (native resolution), so even maximum compression has negligible CPU cost.

Possible values: 0 to 9, 9 (default)

capture_video_compression_rendered

Zlib compression level for rendered video capture, 0 (store only) to 9 (maximum). Rendered frames are large (window resolution), so lower values reduce CPU load during recording if the default causes slowdowns on your machine.

Both levels can also be read and changed at runtime through the REST API while no recording is running; see the REST API reference.

Possible values: 0 to 9, 6 (default)

default_image_capture_formats

Set the capture format of the default screenshot action.

If multiple formats are specified separated by spaces, the default screenshot action will save multiple images in the specified formats. Keybindings for taking single screenshots in specific formats are also available.

Possible values:

  • upscaled (default) -- The image is bilinear-sharp upscaled and the correct aspect ratio is maintained, depending on the aspect setting. The vertical scaling factor is always an integer.
  • rendered -- The post-rendered, post-shader image shown on the screen is captured. Filenames end with -rendered.
  • raw -- The contents of the raw framebuffer is captured (always results in square pixels). Filenames end with -raw.