Guide · plugview

What you need

A Mac with macOS 14 Sonoma or later, Apple silicon or Intel.
A USB capture card that works as a standard video device (UVC). Most cards sold for consoles do, from small HDMI-to-USB sticks to Elgato and AVerMedia. If it works in Photo Booth or QuickTime without a driver, it works in plugview. See tested cards.
An HDMI cable from your console to the card's HDMI in.
A USB 3 port on the Mac itself. Hubs and USB 2 ports can lower the frame rate or drop the picture.

The card sets the limits: a card that captures 1080p at 60 fps shows 1080p60 even when the console sends 4K. plugview always picks the smoothest mode the card offers, so 1080p60 beats 4K30.

Install

Homebrew is temporarily unavailable. Our code host is down for us, so brew install fails for now. The downloads below are the same 0.3.0 release, served from plugview.app.

The app, downloaded

Download plugview-macos-app.zip, unzip it, and move plugview.app to Applications. The app includes the plugview command: open the app once, then link it with sudo ln -sf /Applications/plugview.app/Contents/MacOS/plugview /usr/local/bin/plugview.

Only the command

curl -fsSL https://plugview.app/download/plugview-macos-universal.tar.gz | tar -xz
sudo install plugview-*/plugview /usr/local/bin/

Install the app or the command, not both. If both are installed, the one first on your PATH wins.

Not notarized yet. plugview is not signed with an Apple Developer ID yet, so the first time you open it macOS says it cannot verify the app. Open System Settings › Privacy & Security, scroll down, and click Open Anyway. You do this once per install or update. Until then the plugview command that comes with the app is stopped too. After each update macOS asks for camera and microphone access again. Signing and notarization come before any paid feature.

First run

To macOS a capture card is a camera with a microphone, so plugview needs two permissions. It explains them before macOS asks.

Camera shows the picture from your capture card. plugview never turns on your Mac's own camera.
Microphone plays the sound from your console. plugview never listens to your Mac's microphone.

If you said no to the camera, plugview shows a button that opens System Settings › Privacy & Security › Camera. Turn plugview on there and choose Quit & Reopen: macOS applies the change only after a restart. Without the microphone, plugview plays the picture with no sound.

Started from a terminal, the permissions belong to the terminal app (Terminal, iTerm, Warp…), not to plugview.

Connect your console

Console HDMI out → capture card HDMI in → card USB → Mac. Start plugview before or after plugging in; it finds the card on its own.

Nintendo Switch and Switch 2 Full setup →

Put the console in its dock and connect the dock's HDMI out to the card. Games are not copy protected, so there is nothing to turn off. If colors look washed out or too dark, set System Settings › TV Output › RGB Range on the console to match your card: try Limited first, then Full.

PlayStation 5 Full setup →

The PS5 encrypts its HDMI output (HDCP), and a capture card shows nothing until you turn that off. With the PS5 connected to a TV, open Settings › System › HDMI and turn off Enable HDCP. Then connect it to the card.

PlayStation 4 and PS4 Pro

Open Settings › System and uncheck Enable HDCP.

On both PlayStations, video apps such as Netflix need HDCP back on to play.

Xbox Series X|S and Xbox One Full setup →

Xbox games are never copy protected, so they show up right away. Video apps (Netflix, Disney+…) turn copy protection on, and the picture goes black while they run. That is the console, not plugview.

Steam Deck and handheld PCs Full setup →

Connect a dock or a USB-C to HDMI adapter to the card's HDMI in. The handheld treats the card as an external display; pick a resolution and refresh rate the card supports (1920×1080 at 60 Hz is the safe choice).

Retro consoles and cameras

The card needs an HDMI signal: older consoles go through an HDMI adapter or an upscaler. Cameras need a clean HDMI output, without the menus and focus marks overlaid.

Console output settings

Set the console to a resolution and frame rate your card captures. If the console sends a mode the card cannot read, most cards show nothing. 1080p at 60 Hz works with almost every card.

Playing

The video fills the window, with no title bar. Move the mouse to show the window buttons and the controls bar; they fade out when the mouse rests, so nothing covers the game.

Sound: mute and volume. Click anywhere on the volume track, or scroll over the controls bar.
Screenshot: the camera button (or S) saves the current frame at full resolution as a PNG in Pictures › plugview.
Resolution: the button with the current mode (for example 1080p60) opens the card's modes. Full-range colors at the bottom fixes cards that send gray blacks and washed-out colors; leave it off if the picture already looks right.
Capture device: shown when more than one card is connected. plugview remembers your choice.
Full screen.

Drag the video to move the window. Resize it from an edge; it keeps the video's shape and remembers its size and place. The View menu has Actual Size, Zoom In, Zoom Out and Keep on Top.

Key	Action
`F` or `⌃⌘F`	Toggle full screen
`Esc`	Leave full screen
`M`	Mute or unmute
`↑` `↓`	Volume up or down by 10 %
`S`	Save a screenshot
`⌘+` `⌘−`	Zoom the window in or out
`⌘0`	Actual size (one video pixel per screen pixel)
`⌥⌘T`	Keep the window on top (remembered)
`⌘M`	Minimize
`⌘W`	Close the window (plugview stays in the menu bar)
`Q` or `⌘Q`	Quit

The display does not go to sleep while the plugview window is open, even though a controller is not a keyboard or mouse.

Menu bar

Opened as an app, plugview puts an item in the menu bar that shows whether a card is waiting, ready or playing. Click it for:

Close the window, keep plugview. Closing the window stops the capture and releases the card (the green camera light goes off), and plugview stays in the menu bar.
Open when a card is plugged in. plugview opens its window and plays as soon as a card is connected.
Launch at login, so it is always ready.
Resolution per card. Automatic picks the smoothest mode, as before; or choose a mode the card offers, remembered for that card.
Update checks. plugview asks GitHub whether a newer release exists and links to it. You can turn this off; see Privacy.

Started from a terminal, plugview behaves as before: closing the window quits.

Latency tips

plugview sends frames straight from the capture driver to the screen; the rest of the delay comes from the setup around it. Run plugview --measure: it reports the frame rate your card really delivers and the delay at each step, and tells you what to change.

Wired sound. Play through the Mac speakers or wired headphones. Bluetooth headphones add 150 ms or more, which you hear as late sound.
USB 3, no hub. Plug the card straight into the Mac.
Full screen. Press F.
Matching refresh rate. Use a display rate that is a multiple of the game's frame rate: 60 or 120 Hz for 60 fps games. At 100 Hz, frames stay on screen for uneven times.
Native format. plugview prefers the card's own uncompressed 4:2:2 format, which needs no conversion. Cards that only send MJPEG at high resolutions add a decode step; a lower resolution in the uncompressed format is often faster.

The measurements behind these numbers →

Command line

The app installs the plugview command too. Typed in a terminal, it opens the same window.

plugview                              # first USB capture card, with its audio
plugview -f                           # start in full screen
plugview --list                       # show video and audio devices
plugview --measure                    # frame rate and latency, with advice
plugview -d "Cam Link" -a "Cam Link"  # pick devices by name
plugview --no-audio                   # video only
plugview -v 50                        # start at 50 % volume
plugview --mode 1280x720@60           # pick the capture mode (see --list)

Option	What it does
`-d, --device <name>`	Video device to use (part of its name, or its unique ID). Default: the first USB capture device found.
`-a, --audio <name>`	Audio input to play. Default: the audio input that belongs to the video device.
`--no-audio`	Do not play audio.
`-v, --volume <0-100>`	Start volume in percent. Default: 100.
`-f, --fullscreen`	Start in full screen.
`--mode <WxH@fps>`	Capture mode, for example `1280x720@60`; also applies to `--measure`. Default: the smoothest mode the device offers.
`-l, --list`	List video and audio devices with each video device's modes, then exit.
`--measure`	Measure the capture pipeline's latency for a few seconds, then exit.
`-h, --help`	Show the help.
`--version`	Show the version.

Troubleshooting

Black screen, or "waiting for signal" with the card connected

PlayStation: turn off HDCP (see Connect your console).
Video apps on any console are copy protected and stay black. Games work.
Set the console to 1080p at 60 Hz, a mode every card reads.
Check the card shows up in plugview --list. If it does not, try another USB port and cable.

No sound

Check System Settings › Privacy & Security › Microphone and turn plugview on.
Run plugview --list and pass the card's audio input: plugview --audio "<name>". plugview does not guess when several USB audio inputs are connected.
Check the volume in the controls bar and that M did not mute it.

"cannot be added to the capture session"

Another app is using the card: OBS, Zoom, QuickTime, a browser tab. Close it, and plugview tries again.

Choppy picture or low frame rate

Run plugview --measure. It shows the frame rate the card really delivers. Move the card to a USB 3 port on the Mac, away from hubs.

Washed-out or too-dark colors

Set the console's RGB range to match the card: on Switch, System Settings › TV Output › RGB Range, Limited first.

An iPhone or virtual camera is not offered

On purpose: Continuity Camera and virtual cameras from streaming apps are never picked automatically. To use one anyway, name it from a terminal: plugview -d "iPhone".

Ask for the permissions again

Reset them and open plugview; it asks again:

tccutil reset Camera app.plugview.plugview
tccutil reset Microphone app.plugview.plugview

Still stuck? Open an issue with the output of plugview --list and plugview --measure.

Uninstall

brew uninstall --cask plugview      # the app
brew uninstall plugview             # or the command only

Downloaded the zip? Move plugview.app to the Trash. To also remove the saved window size, chosen card and permissions:

defaults delete app.plugview.plugview
tccutil reset Camera app.plugview.plugview
tccutil reset Microphone app.plugview.plugview