Screen Recorder

Screen Recorder: Cropped Desktop Capture

You generate and run a small PowerShell tool that records a user-selected rectangle of the Windows desktop to a silent MP4. The headline feature is a drag-to-crop overlay: the user drags a box over any part of the screen, records, and clicks Stop to save a valid, seekable video.

This skill is Windows only and needs FFmpeg on PATH. It records video only (silent) in v1. Microphone and system audio are documented as future toggles at the end of this file.

Step 1: Confirm the environment

1. Check the OS is Windows. If not, tell the user this v1 is Windows-only and stop.
2. Check FFmpeg is installed: run ffmpeg -version. If it is missing, tell the user to install it and reopen the terminal:

   winget install Gyan.FFmpeg
   

   (or download a build from https://ffmpeg.org/download.html). The script also checks this and prints the same hint, so you can also just run the script and let it report.

Step 2: Ask what they want (only if unclear)

Most users just want to drag and record. Only ask if relevant:

• Region: drag-to-crop (default), full screen, or exact coordinates x,y,w,h?
• Frame rate: default 30 fps (smooth). 60 for fast motion, 15 for smaller files.
• Where to save: default .\recordings\.

If they just say "record my screen", go straight to the default: drag-to-crop, 30 fps, .\recordings\.

Step 3: Write the recorder script

Write the script below to record-screen.ps1 in the project (or a tools folder). It is the reference implementation. Do not change its logic without reason: the DPI-awareness call, the even-dimension rounding, and the graceful q-to-stdin stop are all there for correctness.

<#
  record-screen.ps1 - Cropped desktop screen recorder (Windows, silent MP4)
  Part of the /screen-record skill by JQ AI SYSTEMS. Requires Windows + FFmpeg on PATH.

  Examples:
    .\record-screen.ps1                          # drag a box, record, click Stop
    .\record-screen.ps1 -FullScreen              # record the whole primary screen
    .\record-screen.ps1 -Region "200,150,1280,720"   # exact rectangle, skip the picker
    .\record-screen.ps1 -Fps 60 -OutDir .\clips -Name my-demo
#>
[CmdletBinding()]
param(
  [string]$Region,                 # "x,y,w,h" to skip the picker
  [switch]$FullScreen,             # record the whole primary screen
  [int]$Fps = 30,
  [string]$OutDir = ".\recordings",
  [string]$Name,                   # base filename, no extension
  [string]$Encoder = "libx264"     # or h264_nvenc / h264_qsv / h264_amf for GPU offload
)

$ErrorActionPreference = "Stop"

# 1. FFmpeg present?
$ff = Get-Command ffmpeg -ErrorAction SilentlyContinue
if (-not $ff) {
  Write-Host "FFmpeg was not found on your PATH." -ForegroundColor Red
  Write-Host "Install it, then reopen the terminal:" -ForegroundColor Yellow
  Write-Host "  winget install Gyan.FFmpeg" -ForegroundColor Cyan
  Write-Host "  (or download from https://ffmpeg.org/download.html)" -ForegroundColor Cyan
  exit 1
}

# 2. DPI awareness BEFORE any window, so overlay pixels match what gdigrab captures
Add-Type @"
using System;
using System.Runtime.InteropServices;
public static class DpiHelper {
  [DllImport("shcore.dll")] public static extern int SetProcessDpiAwareness(int value);
  [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
}
"@
try { [DpiHelper]::SetProcessDpiAwareness(2) | Out-Null }
catch { try { [DpiHelper]::SetProcessDPIAware() | Out-Null } catch {} }

Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing

# 3. Work out the capture rectangle
$rect = $null
if ($Region) {
  $p = $Region -split '[,x ]+' | Where-Object { $_ -ne '' }
  if ($p.Count -ne 4) { Write-Host "Region must be 'x,y,w,h'." -ForegroundColor Red; exit 1 }
  $rect = [pscustomobject]@{ X=[int]$p[0]; Y=[int]$p[1]; W=[int]$p[2]; H=[int]$p[3] }
}
elseif ($FullScreen) {
  $b = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds
  $rect = [pscustomobject]@{ X=$b.X; Y=$b.Y; W=$b.Width; H=$b.Height }
}
else {
  # Drag-to-crop overlay across the whole virtual desktop
  $vs = [System.Windows.Forms.SystemInformation]::VirtualScreen
  $form = New-Object System.Windows.Forms.Form
  $form.FormBorderStyle = 'None'
  $form.StartPosition   = 'Manual'
  $form.Bounds          = $vs
  $form.TopMost         = $true
  $form.BackColor       = [System.Drawing.Color]::Black
  $form.Opacity         = 0.35
  $form.Cursor          = [System.Windows.Forms.Cursors]::Cross
  $form.ShowInTaskbar   = $false

  $script:dragging  = $false
  $script:startPt   = New-Object System.Drawing.Point 0,0
  $script:selRect   = [System.Drawing.Rectangle]::Empty
  $script:cancelled = $false

  $form.Add_MouseDown({
    if ($_.Button -eq [System.Windows.Forms.MouseButtons]::Left) {
      $script:dragging = $true
      $script:startPt  = $_.Location
      $script:selRect  = New-Object System.Drawing.Rectangle $_.X, $_.Y, 0, 0
    }
  })
  $form.Add_MouseMove({
    if ($script:dragging) {
      $x = [Math]::Min($script:startPt.X, $_.X)
      $y = [Math]::Min($script:startPt.Y, $_.Y)
      $w = [Math]::Abs($_.X - $script:startPt.X)
      $h = [Math]::Abs($_.Y - $script:startPt.Y)
      $script:selRect = New-Object System.Drawing.Rectangle $x, $y, $w, $h
      $form.Invalidate()
    }
  })
  $form.Add_MouseUp({
    if ($_.Button -eq [System.Windows.Forms.MouseButtons]::Left) {
      $script:dragging = $false
      $form.Close()
    }
  })
  $form.Add_KeyDown({
    if ($_.KeyCode -eq [System.Windows.Forms.Keys]::Escape) {
      $script:cancelled = $true
      $form.Close()
    }
  })
  $form.Add_Paint({
    if ($script:selRect.Width -gt 0 -and $script:selRect.Height -gt 0) {
      $pen = New-Object System.Drawing.Pen ([System.Drawing.Color]::FromArgb(255,45,212,191)), 2
      $_.Graphics.DrawRectangle($pen, $script:selRect)
      $pen.Dispose()
    }
  })

  Write-Host "Drag a box over the area to record. Press Esc to cancel." -ForegroundColor Cyan
  [void]$form.ShowDialog()
  $sel = $script:selRect
  $form.Dispose()

  if ($script:cancelled -or $sel.Width -lt 8 -or $sel.Height -lt 8) {
    Write-Host "Selection cancelled (or too small). Nothing recorded." -ForegroundColor Yellow
    exit 0
  }
  $rect = [pscustomobject]@{ X = $vs.X + $sel.X; Y = $vs.Y + $sel.Y; W = $sel.Width; H = $sel.Height }
}

# 4. Even dimensions (required by yuv420p / H.264)
$w = $rect.W - ($rect.W % 2)
$h = $rect.H - ($rect.H % 2)
if ($w -lt 2 -or $h -lt 2) { Write-Host "Region too small." -ForegroundColor Red; exit 1 }

# 5. Output path
if (-not (Test-Path $OutDir)) { New-Item -ItemType Directory -Path $OutDir -Force | Out-Null }
if (-not $Name) { $Name = "recording-" + (Get-Date -Format "yyyy-MM-dd_HHmmss") }
$outFile = Join-Path (Resolve-Path $OutDir).Path ($Name + ".mp4")

# 6. Build ffmpeg arguments (silent capture). Quote the output path for spaces.
$preset = ""
if ($Encoder -eq "libx264") { $preset = "-preset veryfast " }
$argString = "-y -f gdigrab -framerate $Fps -offset_x $($rect.X) -offset_y $($rect.Y) " +
             "-video_size ${w}x${h} -i desktop -c:v $Encoder ${preset}-pix_fmt yuv420p " +
             "-movflags +faststart `"$outFile`""

Write-Host ("Recording {0}x{1} at ({2},{3})  ->  {4}" -f $w,$h,$rect.X,$rect.Y,$outFile) -ForegroundColor Green

# 7. Launch ffmpeg with stdin redirected so we can stop it gracefully (writes a valid moov atom)
$psi = New-Object System.Diagnostics.ProcessStartInfo
$psi.FileName               = $ff.Source
$psi.Arguments              = $argString
$psi.RedirectStandardInput  = $true
$psi.UseShellExecute        = $false
$proc = [System.Diagnostics.Process]::Start($psi)

# 8. Floating Stop button (always on top, top-right of the primary screen)
$stop = New-Object System.Windows.Forms.Form
$stop.Text            = "Recording"
$stop.FormBorderStyle = 'FixedToolWindow'
$stop.TopMost         = $true
$stop.Width = 220; $stop.Height = 92
$stop.StartPosition   = 'Manual'
$wa = [System.Windows.Forms.Screen]::PrimaryScreen.WorkingArea
$stop.Location = New-Object System.Drawing.Point (($wa.Right - 236), ($wa.Top + 16))

$lbl = New-Object System.Windows.Forms.Label
$lbl.Text      = [char]0x25CF + " REC"
$lbl.ForeColor = [System.Drawing.Color]::Firebrick
$lbl.Font      = New-Object System.Drawing.Font("Segoe UI", 10, [System.Drawing.FontStyle]::Bold)
$lbl.AutoSize  = $true
$lbl.Location  = New-Object System.Drawing.Point 12, 10
$stop.Controls.Add($lbl)

$btn = New-Object System.Windows.Forms.Button
$btn.Text   = "Stop and Save"
$btn.Width  = 184; $btn.Height = 34
$btn.Location = New-Object System.Drawing.Point 12, 36
$stop.Controls.Add($btn)

$btn.Add_Click({
  $btn.Enabled = $false
  $lbl.Text = "Saving..."
  try {
    if (-not $proc.HasExited) {
      $proc.StandardInput.WriteLine("q")
      $proc.StandardInput.Flush()
      if (-not $proc.WaitForExit(8000)) { $proc.StandardInput.Close(); [void]$proc.WaitForExit(4000) }
    }
  } catch {}
  $stop.Close()
})

[void]$stop.ShowDialog()

# If the window was closed via X without the button, still stop ffmpeg cleanly
if (-not $proc.HasExited) {
  try { $proc.StandardInput.WriteLine("q"); $proc.StandardInput.Flush(); [void]$proc.WaitForExit(8000) } catch {}
}
if (-not $proc.HasExited) { try { $proc.Kill() } catch {} }

# 9. Report
if (Test-Path $outFile) {
  $mb = [Math]::Round((Get-Item $outFile).Length / 1MB, 2)
  Write-Host ("Saved: {0}  ({1} MB)" -f $outFile, $mb) -ForegroundColor Green
} else {
  Write-Host "Recording failed: no output file was produced." -ForegroundColor Red
  exit 1
}

Step 4: Run it and report

Run the script for the user:

powershell -ExecutionPolicy Bypass -File .\record-screen.ps1

Then tell them: a dimmed overlay appears, drag a box over what they want to capture, a small "Stop and Save" button appears top-right, and clicking it writes the MP4 to .\recordings\. Report the saved file path back.

Rules

• Never kill the FFmpeg process to stop a recording. Always send q to its stdin and wait. Killing it leaves the MP4 without a moov atom, so it will not play or seek.
• Always round capture width and height down to even numbers before recording (H.264 yuv420p rejects odd dimensions).
• Always set DPI awareness before creating any window, or the selected box will not line up with the recording under Windows display scaling (125%, 150%).
• Default to silent. Do not add audio inputs in v1.
• Save into .\recordings\ (or the user's -OutDir); never overwrite without a fresh timestamped name.
• The floating Stop button is captured if it sits inside the recorded region. Place it away from the capture area, or mention this to the user.

Notes and limits

• Windows only (v1). macOS would use FFmpeg avfoundation, Linux x11grab. Not built yet.
• Multi-monitor: the picker spans all monitors. Capturing a monitor left of or above the primary uses negative offsets, which recent FFmpeg supports but is less tested. Single-monitor and primary-monitor captures are the reliable path.
• Performance: libx264 -preset veryfast is the default for universal playback. On a machine with an NVIDIA GPU, -Encoder h264_nvenc offloads encoding and lowers CPU use.
• Audio (future toggles, not in v1):
  • Microphone / voiceover is a small add: append -f dshow -i audio="<device name>" (list devices with ffmpeg -list_devices true -f dshow -i dummy). No extra install needed.
  • System / background sound needs a one-time virtual audio device (enable "Stereo Mix" in Sound settings, or install VB-Audio Cable / screen-capture-recorder), because Windows does not expose desktop-audio loopback to FFmpeg by default.