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
}