# Media Capture Options - FFMPEG

This settings page groups the Media Capture options related to FFMPEG, the video encoding program that PinballY uses for screen captures. There's a separate options page, Capture Options, for the more generic settings related to the capture process generally.

## Option details

Limit captured videos to HD resolution: Check this box to limit the resolution of captured videos to HD (1920x1080 pixels). By default, videos created using the media capture function have the same pixel size as the screen area being captured, but you can use this option to set an upper limit of HD resolution. This won't affect videos captured from smaller screen areas; it only sets an upper bound for the resolution.

In most cases, it's best to capture at the full original resolution, since that gives you the most faithful reproduction of the original graphics. However, videos captured from 4K monitors and other large formats might be too big to play back smoothly on older or slower systems, or might not even play back at all if memory is limited. If you have a large monitor, and your system can't smoothly play videos captured at full size, you can use this option to limit the videos to HD resolution.

Use two-pass video encoding: Use this option if your captured videos look too choppy. Normally, PinballY tries to capture and compress video frames at the same time, in a single pass. This requires a fairly fast machine, though; on slower machines, the video encoder might drop frames (omit them from the resulting video) when it can't keep up with the live video rate. Dropped frames are visible as momentary freezes when you play back the video, which can make the video look choppy or jerky. What's more, the game itself might not be able to run at full speed when the CPU is bogged down with video encoding work, making the game play look choppy even before capture, which will also pass through to the captured video.

If you have any of these sorts of problems with captured video, you can try two-pass encoding instead. Two-pass encoding initially captures the video frames with minimal compression, which reduces the CPU load required to the point that a slower machine can keep up with the work. After this initial minimal-compression pass is completed, PinballY goes back and re-encodes the captured video at a more normal compression rate. Since this second pass works from the temporary file saved during the first pass, it doesn't have to keep up with the game in real time; it's just reading from a file, so it can take as long as it needs. And the CPU load during the second pass doesn't affect the game, since it only occurs after the game session has ended, so it doesn't matter if the compression job hogs most of the CPU power. This whole process obviously can take a lot longer overall, but if you don't mind the added time, you can get better video results.

Optimization tip: If you've tuned your system to give higher priority to pinball software via a tool like PinAffinity, you should add ffmpeg.exe to the list of programs that receive priority CPU access. Ffmpeg is the program that PinballY uses to carry out screen capture operations. Screen capture is inherently CPU-intensive, so ffmpeg will do a better job of capturing if it's given full CPU resources.

Temp file folder: This lets you specify the folder path for temporary files created during two-pass video encoding. By default, the temp files are created in the same folder as the final video. However, there might be a different folder that you'd prefer to use, depending on how your system is set up. In particular, if you have a disk that's especially fast or that has a lot of extra space, that might be a good place for the temp files, because the uncompressed video files created during the first pass of a two-pass recording are very large. A fast disk is advantageous because FFMPEG has to transfer the uncompressed video stream to the drive in real time in order to keep up with the live video without dropping frames.

First pass video codec: This is only used during two-pass encoding. If not blank, this specifies custom video codec settings to use during the first pass of the two-pass process. If you lave this blank, PinballY uses default options that select an extremely fast codec with minimal compression.

The point of two-pass encoding is to defer most of the CPU-heavy compression work until the second pass. The first pass captures the screen video in real time, saving it in a temporary file, which the second pass can then go back and compress more aggressively. Since the second pass runs after the real-time capture finishes, it can use a lot of CPU without affecting the game action. So the goal of the first-pass codec settings is to make the real-time video capture run as fast as possible.

Naively, it would seem like less compression is always faster, which is why the default settings (used if you leave this blank) apply minimal compression. It's true that less compression generally means less CPU load, but there's a tradeoff for real-time capture, which is that uncompressed video is huge, so the first pass will have to have to write a lot of data to disk very quickly. This creates another kind of load on your system, and depending on how fast your CPU and disk are, you might actually get better results if you slightly increase the amount of compression during the first pass, to reduce the disk transfer load. That's what this option is for: it lets you optimize the settings for your system if the default settings don't produce smooth results.

Audio capture device: This lets you select the audio input (recording) device to use for media capture operations that record audio, such as table audio tracks and table videos that include audio.

The drop list shows a list of all of the audio input devices currently in your system. You should choose the one that records from the "Line Out" port of your sound card. This is often called "Stereo Mix" or something similar.

If you don't see "Stereo Mix" or some similar device in the list, try this:

- Press Windows+R and type mmsys.cpl into the Run box (this should open the Windows "Sound" control panel)
- Click the Recording tab
- Look through the list for a "Stereo Mix" device or something similar for your sound card
- If you don't see it, try right-clicking in a blank area in the list box, and make sure the menu item for Show Disabled Devices is check-marked, and click it if not to check-mark it
- If you find "Stereo Mix" or similar, and it's marked "Disabled", right-click it and select Enable
- If you successfully found and enabled the device, you might now have to exit out of PinballY and restart the program so that it refreshes its internal device list. After that, you should see the device listed in the audio capture options.

See About the Audio Capture Device below for more details.

## FFMPEG command-line options

FFMPEG has a vast number of options - far too many for PinballY to expose through checkboxes and drop lists. There are entire applications devoted to putting a friendly face on FFMPEG, and I doubt most of those guys expose more than a fraction of what you can do through the FFMPEG command line. PinballY doesn't even scratch the surface; it just has some canned options that it knows how to generate for the several media types it can capture. This one-size-fits-all approach makes things easy, but it's not very satisfying if you want to take advantage of the many other features in FFMPEG.

To give you access to more of FFMPEG's power without creating a vast new set of dialogs, the Media Capture > FFMPEG dialog gives you the option of direct access to the FFMPEG command line, so that you can hand-code the settings you want to use. The section at the bottom of the dialog lets you fill in options for the several elements that go into the overall FFMPEG command line:

- Global options: These go at the start of the command line, and apply to the whole session (not just to an individual input or output).
- Video source options: Specifies the input source for the video capture. For screen capture, this is usually one of the standard Windows screen capture devices, either gdigrab or ddagrab. Each one has its own syntax that you can look up in the ffmpeg documentation.
- Video codec options: Specifies the encoding options for the output video. Used only when a video is being created.
- Image codec options: Specifies the encoding options for a still image. Used only when a still image is being created.
- Audio source options: Specifies the audio input source for the recording. This is usually the Windows dshow (DirectShow) subsystem, using your sound card's loopback audio device (often called "Stereo Mix" or something similar).
- Audio codec options: Specifies the encoding options for the audio. Used only when audio is being recorded, as part of a video or as a standalone audio track.

Any text you enter in these boxes is used to construct the corresponding section of the FFMPEG command line. This completely replaces the default options that PinballY would use instead. If you leave a box blank, PinballY uses its own default settings for the blank box. The default settings are designed for compatibility with most systems. This isn't an all-or-nothing scenario, in that you can fill in any subset of the boxes, to customize just a portion of the options, and leave the rest blank to continue using defaults for those elements.

The options you specify here are passed through directly to ffmpeg, so you'll need a working knowledge of the ffmpeg command syntax to use these. ffmpeg is extremely powerful and has an extremely complex command syntax, far beyond what we can cover here. The official ffmpeg documentation is at ffmpeg.org/ffmpeg.html. Extensive user-to-user help can also be found on StackOverflow and many other sites; Web searches for "ffmpeg + whatever topic" typically turn up lots of results.

The overall ffmpeg command line that PinballY generates is constructed like this:

`ffmpeg` <global-options> <video-source-options> <audio-source-options> <video-or-image-code-options> <audio-codec-options> <time-limit-options> <output-filename>

All of those xxx-options elements correspond to the boxes in the dialog, except for the time-limit-options, which is always generated internally according to the capture time settings. When PinballY builds the command line, it simply strings together the text you put in these boxes to build the overall command line, substituting the built-in defaults for each box you leave empty. Some of the xxx-options elements only apply to certain media types; for example, the audio options are omitted when you're capturing a still image or a silent video, and the video and image options aren't used when capturing an audio track.

Since default options are used for any box you leave blank, you're free to customize just the parts you need to, letting the system use its defaults for everything else.

### Substitution variables

Within each element, you can use a number of substitution variables, to fill in details that vary in each capture. A substitution variable is written with square brackets:

       -offset_x [left.desktop] -offset_y [top.desktop]

If you need to use a literal square bracket in option text, write it twice, as in `[[` or `]]`.

Here are the available substitution variables:

Variable | Description
--- | ---
[left.desktop] | The left pixel coordinate of the capture area, in desktop coordinates (that is, relative to the whole Windows virtual desktop, which might span multiple monitors)
[top.desktop] | The top pixel coordinate of the capture area, in desktop coordinates
[right.desktop] | The right pixel coordinate of the capture area, in desktop coordinates
[bottom.desktop] | The bottom pixel coordinate of the capture area, in desktop coordinates
[width] | The width of the capture area, in pixels
[height] | The height of the capture area, in pixels
[top.monitor] | The top pixel coordinate of the capture area, relative to the monitor containing the capture area
[left.monitor] | The top pixel coordinate of the capture area, relative to the monitor containing the capture area
[right.monitor] | The right pixel coordinate of the capture area, relative to the monitor containing the capture area, and clipped to the bounds of the monitor containing the top left of the capture area
[bottom.monitor] | The bottom pixel coordinate of the capture area, relative to the monitor containing the capture area, and clipped to the bounds of the monitor containing the top left of the capture area
[width.monitor] | The width of the capture area, clipped to the bounds of the monitor containing the upper left of the capture area
[height.monitor] | The height of the capture area, clipped to the bounds of the monitor containing the upper left of the capture area
[monitorIndex] | The DXGI output index of the monitor containing the upper left of the capture area. This is required for "ddagrab" video source mode.
[audioDevice] | The name of the audio capture input device selected in the options
[videoTransforms] | The series of ffmpeg video transforms that PinballY computed based on the capture settings, to rotate and scale the video as needed. This is in a form that can be inserted directly into an ffmpeg `-vf` or `-filter_complex` option. If no transforms are needed, this contains the text `null`, so that it can still be safely inserted into a filter option string. ("null" is a filter that passes through the input video unchanged, so it can be inserted into any filter series without changing the effect of the series.)
[videoFilters] | The video transforms, the same as [videoTransforms], but already formatted as a `-vf` option. This can be inserted anywhere the video filter options can go. If no transforms are needed, this is blank.

Desktop vs. monitor coordinates: Variables are provided for the capture area location and size in both desktop and monitor coordinates, because the coordinate system varies by video source mode:

- gdigrab uses desktop coordinates
- ddagrab uses monitor coordinates

### How to use ddagrab

Newer versions of FFMPEG support a capture mode called ddagrab. This is only supported on Windows 8 and later, and only with the 64-bit version of FFMPEG, so PinballY's default settings use the older gdigrab mode, since it's more universally compatible.

ddagrab captures directly from the GPU video buffer, which gives it two advantages over the older gdigrab mode. The first is that it can capture from full-screen-exclusive windows, which gdigrab can't. The second is that, because ddagrab reads directly from the GPU, FFMPEG can also process the frame directly on the GPU. FFMPEG can execute the video encoding process on the GPU if you have a compatible NVIDIA card, which greatly reduces the CPU load during the capture process.

ddagrab also has a slight disadvantage compared to gdigrab: ddagrab can only capture from within the bounds of a single monitor, whereas gdigrab can capture an area that spans two or more monitors. This probably isn't a problem for most PinballY users, since most people set up their pin cabs with the whole playfield on one monitor, the whole backglass on a second monitor, and the DMD on a third (if there's a DMD window at all). But if your setup has one of these windows spread across two monitors, ddagrab will only be able to capture the portion of that window that fits in its main monitor (where its top left corner is located).

You'll have to refer to the FFMPEG documentation for full details on how to set up ddagrab captures, but we'll provide two basic "recipes" here, one with regular CPU-side encoding, and one with on-GPU encoding. The on-GPU encoding is probably always preferable if you can use it, but remember that it only works with newer NVIDIA cards.

#### ddagrab with CPU encoding

This option is more broadly compatible than on-GPU encoding, since it doesn't require any specific video card. You just need Windows 8 or later.

- Video source options: -filter_complex ddagrab=output_idx=[monitorIndex]:offset_x=[left.monitor]:offset_y=[top.monitor]:video_size=[width.monitor]x[height.monitor],hwdownload,format=bgra,[videoTransforms]
- Video codec options: -c:v libx264 -crf 18
- Image codec options: -frames:v 1 -update 1

#### ddagrab with GPU encoding

This option minimizes CPU load by doing the video encoding work on the GPU. It only works with newer NVIDIA cards with recent drivers. If you have an NVIDIA card and find that this doesn't work (especially if the error says something about the "API version" being too old), try checking on nvidia.com for an updated driver. I've found that Windows Update tends to lag the manufacturer releases, so check the NVIDIA site even if Windows Update assures you that you already have the latest driver it knows about.

- Video source options: -filter_complex ddagrab=output_idx=[monitorIndex]:offset_x=[left.monitor]:offset_y=[top.monitor]:video_size=[width.monitor]x[height.monitor],hwdownload,format=bgra,[videoTransforms]
- Video codec options: -c:v h264_nvenc -cq 18
- Image codec options: -frames:v 1 -update 1

## About the Audio Capture Device

#### Why can't PinballY choose a device automatically?

Because Windows doesn't provide a standard device driver for this function, and Microsoft didn't even bother to specify a standard name for the driver. You'd think that Windows would offer an audio capture function automatically, but it doesn't; Microsoft left it up to the sound card manufacturers to provide drivers, and left it up to them to name the devices. So there's no way for PinballY to know the name of this driver on your system, and in fact no way to even know if there's one installed.

"Stereo Mix" is a common name for this driver only because it's the name that Realtek uses for its loopback driver, and Realtek chips are ubiquitous, especially in the built-in audio in many motherboards these days. If your system has integrated audio on the motherboard, chances are that it uses the Realtek chips, so its driver will probably be called "Stereo Mix". But the name might be the translated equivalent of "Stereo Mix" if your system is localized to a language other than English, or it might be something else entirely.

#### What is the "Default" device?

"Default" isn't actually a device in its own right. It's just a way of telling PinballY to select a device automatically, which it does by searching the list you see for an entry with the words "Stereo Mix" in its name. If you don't see any such device in the list, PinballY won't be able to find one either, because it works from the same list you see here. So "Default" won't actually work unless you see a suitable device listed. If you see a device with a similar name, or a version of "Stereo Mix" translated into your system's localization language, you should explicitly select that item, because PinballY won't be able to figure it out on its own based on the different name.

#### What if the audio device list only shows "Default"?

If "Default" is the only device you see in the audio capture device drop list, you won't be able to capture audio when recording screen shots. As described above, "Default" isn't actually a device, it's just our way of telling PinballY to choose a device by searching for one with "Stereo Mix" in its name. If you don't see a "Stereo Mix" device in the list, PinballY won't be able to find one either.

So what can you do about it if the list is empty, or if there aren't any suitable capture devices? The answer is that you have to install a suitable device driver.

In some cases, it's just a matter of enabling a device that's disabled in the Windows audio control panels. Some sound cards come with Stereo Mix or equivalent devices and disable them by default. To check for disabled devices, open the Windows sound control panel and go to the Recording tab. Look for a device called Stereo Mix or something similar; if you find it, enable it, and try again in PinballY.

If the Windows sound control panel doesn't list any Stereo Mix or equivalent devices, you'll have to find and install a device driver capable of recording from the Line Out port. This usually has to come from your sound card manufacturer, so check the support site for your sound card or your PC vendor to see if they have a Stereo Mix or "audio loopback" device driver you can use.

If your sound card simply doesn't have any options available, there are some third-party software options available, such as https://github.com/rdp/screen-capture-recorder-to-video-windows-free.