roku-screenshot

Capture, diff, and process screenshots from sideloaded apps on Roku devices. Built on @danecodes/roku-ecp and sharp.

Install

npm install @danecodes/roku-screenshot

CLI

# Basic capture
roku-screenshot -d 192.168.0.30 -o screen.png

# Auto-discover device on network
roku-screenshot -o screen.png

# Resize to 50%
roku-screenshot -d 192.168.0.30 --resize 50 -o thumb.png

# Resize to specific width
roku-screenshot -d 192.168.0.30 --resize 960 -o half.png

# Crop a region (left, top, width, height)
roku-screenshot -d 192.168.0.30 --crop 0,0,960,540 -o top-left.png

# Convert to JPEG
roku-screenshot -d 192.168.0.30 -o screen.jpg

# Visual regression diff
roku-screenshot -d 192.168.0.30 --diff baseline.png -o changes.png
# exits 0 if identical, 1 if changed

# Watch mode — capture every 5 seconds
roku-screenshot -d 192.168.0.30 --watch 5 -o captures/screen.png
# creates captures/screen-001.png, screen-002.png, ...

Set ROKU_IP environment variable to skip --device every time.

Library

import { capture, diff, processImage, watch } from '@danecodes/roku-screenshot';
import { EcpClient } from '@danecodes/roku-ecp';

const roku = new EcpClient('192.168.0.30');

// Basic capture
const png = await capture(roku);

// Capture with processing
const thumb = await capture(roku, {
  resize: 50,        // 50% scale
  format: 'jpeg',
  quality: 85,
});

// Crop
const cropped = await capture(roku, {
  crop: { left: 0, top: 0, width: 960, height: 540 },
});

// Visual regression diff
const before = await capture(roku);
// ... do something on the Roku ...
const after = await capture(roku);

const result = await diff(before, after);
console.log(result.identical);      // false
console.log(result.changePercent);  // 12.5
console.log(result.changedPixels);  // 259200

// Save the diff image (changed pixels highlighted in red)
await writeFile('diff.png', result.image);

// Watch mode
const ac = new AbortController();
await watch(roku, 5000, async (image, seq) => {
  await writeFile(`frame-${seq}.png`, image);
}, { signal: ac.signal });

API

capture(client, options?)

Capture a screenshot and optionally process it. Returns a Buffer.

Option	Type	Description
resize	number	Percentage (1-100) or pixel width (>100)
crop	{ left, top, width, height }	Crop region
format	'png' | 'jpeg' | 'webp'	Output format (default: png)
quality	number	JPEG/WebP quality 1-100 (default: 90)

diff(imageA, imageB, options?)

Pixel diff two images. Returns a DiffResult.

Option	Type	Description
threshold	number	Per-channel tolerance 0-255 (default: 25)
highlightColor	[r, g, b, a]	Color for changed pixels (default: red)

interface DiffResult {
  image: Buffer;          // PNG with changes highlighted
  changedPixels: number;
  totalPixels: number;
  changePercent: number;  // 0-100
  identical: boolean;
}

watch(client, intervalMs, callback, options?)

Capture screenshots on a loop. Supports AbortSignal for cancellation.

processImage(buffer, options?)

Process an existing image buffer (same options as capture).

Requirements

• Roku device in developer mode with a sideloaded channel
• Node.js 18+

License

MIT