chrome-recording

CLI for recording Windows Chrome content from WSL, using ffmpeg's ddagrab.

Prerequisites

• WSL (Windows Subsystem for Linux)
• Chrome running on Windows
• ffmpeg.exe available in PATH (Windows-side)
• powershell.exe available in PATH (Windows-side)
• wslpath available in PATH

Installation

npm install -g @y11i-3d/chrome-recording

Or run directly with npx or bunx:

npx @y11i-3d/chrome-recording <subcommand> [options]
bunx @y11i-3d/chrome-recording <subcommand> [options]

The record, screenshot and resize commands need a PowerShell script (chrome.ps1) on the Windows side. It is copied to %LOCALAPPDATA%\y11i-3d\chrome-recording\ every time one of them runs.

Subcommands

| Subcommand | Description | | ------------ | ----------------------------------------------- | | record | Capture Chrome browser content as a video | | screenshot | Capture Chrome browser content as a still image | | resize | Set the Chrome viewport size | | concat | Concatenate recorded mp4 files into one |

record

Capture the Chrome content area using ffmpeg's ddagrab.

chrome-recording record [options]

Recording starts immediately and stops when you press Enter, unless --manual or --duration is given. The output is saved to ./recordings/<timestamp>.mp4.

| Option | Description | | ------------------------------------ | --------------------------------------------------------------------------------------- | | -s, --size <width>x<height> | Size of the captured region (see below) | | -o, --output <file> | Output file path | | -c, --crop <top:right:bottom:left> | Crop in CSS shorthand order (px) | | -m, --manual | Wait for Enter before starting capture | | -d, --duration <seconds> | Stop recording automatically after N seconds | | -q, --quality <value> | Quality: plain number for CRF (e.g. 23), number+unit for bitrate (e.g. 4000k, 4M) | | -f, --fps <fps> | Frame rate | | -n, --no-pointer | Hide the mouse pointer | | -t, --title <text> | Select a window whose page title contains this text | | -v, --verbose | Show ffmpeg output |

--size captures a region of that size from the top-left corner of the Chrome content area, instead of the whole area. --crop is ignored when --size is given.

Examples

# Record until Enter is pressed
chrome-recording record

# Record a 1920x1080 region, ignoring the padding kept by `resize`
chrome-recording record -s 1920x1080

# Record for 10 seconds at CRF 18
chrome-recording record -d 10 -q 18

# Record with manual start and crop
chrome-recording record -m -c 40:0:0:0

# Record to a specific file at 4 Mbps
chrome-recording record -o output.mp4 -q 4M

screenshot

Capture a single frame of the Chrome content area as a PNG.

chrome-recording screenshot [options]

The capture happens immediately, unless --manual is given. The output is saved to ./recordings/<timestamp>.png.

| Option | Description | | ------------------------------------ | --------------------------------------------------- | | -s, --size <width>x<height> | Size of the captured region (same as record) | | -o, --output <file> | Output file path | | -c, --crop <top:right:bottom:left> | Crop in CSS shorthand order (px) | | -m, --manual | Wait for Enter before capturing | | -n, --no-pointer | Hide the mouse pointer | | -t, --title <text> | Select a window whose page title contains this text | | -v, --verbose | Show ffmpeg output |

Examples

# Capture the Chrome content area
chrome-recording screenshot

# Capture a 1920x1080 region without the mouse pointer
chrome-recording screenshot -s 1920x1080 -n

# Capture after pressing Enter, to a specific file
chrome-recording screenshot -m -o shot.png

resize

Set the viewport size through the Chrome DevTools Protocol. Chrome asks you to approve the connection.

chrome-recording resize <width>x<height> [options]

The viewport is the area the page is rendered into, and it is what record captures. --padding enlarges the surrounding content area without changing the viewport, which keeps the rounded window corners away from the captured region. Padding is added to the right and the bottom.

| Option | Description | | -------------------------------- | -------------------------------------------------- | | -p, --padding <width>x<height> | Padding kept outside the viewport (default: 0x0) | | -n, --no-scrollbar | Hide the scrollbars | | -t, --title <text> | Select a page whose title contains this text |

With --padding or --no-scrollbar, the command waits instead of exiting. Press Enter to release the viewport. The setting survives a page reload while it waits.

Examples

# Set the viewport to 1920x1080
chrome-recording resize 1920x1080

# Keep 4px below the viewport so the rounded corners are not captured
# (waits until Enter is pressed)
chrome-recording resize 1920x1080 -p 0x4

# Hide the scrollbars (waits until Enter is pressed)
chrome-recording resize 1920x1080 -n

# Target a specific page
chrome-recording resize 1280x720 -t "Example"

concat

Concatenate all mp4 files in a directory into a single file (stream copy, no re-encode).

chrome-recording concat [options]

Files named concat_*.mp4 are excluded. Input files are sorted alphabetically.

| Option | Description | | --------------------- | ------------------------------------------------------------ | | -i, --input <dir> | Input directory (default: ./recordings) | | -o, --output <file> | Output file path (default: <input>/concat_<timestamp>.mp4) | | -v, --verbose | Show ffmpeg output |

Examples

# Concatenate all recordings in ./recordings
chrome-recording concat

# Concatenate from a specific directory
chrome-recording concat -i ./clips -o final.mp4