simple-movement-detector 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mikhail Gorbunov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# simple-movement-detector
+
+![](https://img.shields.io/badge/dependencies-zero-green) [![npm version](https://img.shields.io/npm/v/simple-movement-detector.svg)](https://www.npmjs.com/package/simple-movement-detector) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A zero-dependency browser library that calls your callback when the webcam detects movement.
+
+- Zero dependencies
+- One function: `detectMovement(onMovement, config)`
+- ~3 KB, no build step, no WebAssembly, no Web Workers
+- ES module + TypeScript definitions
+
+```js
+import { detectMovement } from 'simple-movement-detector';
+
+const stop = detectMovement((snapshot) => {
+  console.log('Movement detected!', snapshot);
+});
+
+stop();
+```
+
+## Try the demo
+
+- [Full demo](https://web-detect-movement.vercel.app/demo/demo.html) — with config controls, presets, and diff visualization
+- [Minimal demo](https://web-detect-movement.vercel.app/demo/minimal-demo.html) — the smallest possible usage
+- [Spy on your dog](https://web-detect-movement.vercel.app/demo/spy-on-your-dog.html) — records video on movement, downloads after 15s of stillness
+
+## When to use it
+
+You want a callback when something moves in front of the camera. You don't need a sensitivity matrix, a motion grid, or a per-frame diff image. Common use cases:
+
+- Spy on your dog
+- Turn on a light / trigger an action when someone walks into frame
+- Send a snapshot to your server when motion is detected
+- Build a simple security cam, doorbell, or presence detector in the browser
+
+### When to use something else
+
+If you need **motion analysis** — where motion happened, how much, a per-frame matrix for interactive visualizers — use [Diffy.js](https://github.com/maniart/diffyjs)
+
+## Usage
+
+### 1. Install
+
+```sh
+npm install simple-movement-detector
+```
+
+### 2. Detect movement
+
+```js
+import { detectMovement } from 'simple-movement-detector';
+
+const stop = detectMovement((snapshot) => {
+  // snapshot is a PNG data URL of the frame where motion was detected
+  fetch('/alert', { method: 'POST', body: snapshot });
+});
+
+stop();
+```
+
+### 3. (Optional) Tune sensitivity
+
+```js
+// Catches even tiny motion — a hand waving, a curtain moving
+detectMovement(onMovement, { threshold: 0.02, pixelThreshold: 15, interval: 500 });
+
+// The default — a dog walking through frame
+detectMovement(onMovement, { threshold: 0.1, pixelThreshold: 30, interval: 1000 });
+
+// Only fires on big motion — a person walking across the frame
+detectMovement(onMovement, { threshold: 0.25, pixelThreshold: 50, interval: 1000 });
+```
+
+### Without a bundler
+
+```html
+<script type="module">
+  import { detectMovement } from 'https://esm.sh/simple-movement-detector';
+
+  detectMovement((snapshot) => {
+    document.getElementById('img').src = snapshot;
+  });
+</script>
+```
+
+Also available via [jsdelivr](https://cdn.jsdelivr.net/npm/simple-movement-detector/+esm) and [unpkg](https://unpkg.com/simple-movement-detector/index.js).
+
+## Configuration
+
+All options are optional.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `threshold` | `number` | `0.1` | Fraction of pixels (0-1) that must change to trigger. `0.1` = 10%. |
+| `pixelThreshold` | `number` | `30` | Per-pixel avg RGB diff (0-255) for a pixel to count as "changed". Filters camera noise. |
+| `interval` | `number` | `1000` | Milliseconds between checks. |
+| `width` | `number` | `320` | Capture width. Smaller is faster. |
+| `height` | `number` | `240` | Capture height. Smaller is faster. |
+| `videoElement` | `HTMLVideoElement` | — | Existing `<video>` with a stream. If omitted, webcam is launched. |
+| `debugCanvas` | `HTMLCanvasElement` | — | Canvas to draw the diff onto (changed pixels in red). Off by default. |
+
+## How it works
+
+Every `interval` ms, the library draws the webcam frame to an offscreen canvas and reads the pixels. Each pixel is compared to the previous frame: if the avg RGB diff exceeds `pixelThreshold`, it counts as changed. If changed pixels exceed `threshold * width * height`, `onMovement` fires with a PNG snapshot.
+
+Frame buffers are `Uint8ClampedArray` in memory — no `<img>` elements, no PNG encode/decode per frame. The only PNG encode happens when motion is detected.
+
+## Browser requirements
+
+- Modern browser with `getUserMedia` (Chrome, Firefox, Safari, Edge)
+- **HTTPS or localhost** — camera access is blocked on insecure origins
+- iOS Safari needs `playsinline` (handled automatically)
+
+## Common issues
+
+### Camera does not start
+
+`getUserMedia` only works on `https://` or `http://localhost`. `file://` won't work.
+
+### Too many false positives
+
+Increase `pixelThreshold` (try 40-50) or `threshold` (try 0.2).
+
+### Motion is detected too late
+
+Decrease `interval` (try 250ms). Smaller intervals use more CPU.
+
+### Motion is never detected
+
+Decrease `pixelThreshold` (try 15-20) or `threshold` (try 0.02-0.05). If you pass your own `videoElement`, make sure it has a live `srcObject`.
+
+### I want to see what the detector sees
+
+Pass a `debugCanvas` in the config. Changed pixels are painted red, unchanged black, every tick.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Configuration for detectMovement.
+ */
+export interface DetectMovementConfig {
+  /**
+   * Fraction of pixels that must change (0-1) to trigger a movement event.
+   * 0.1 means 10% of pixels must differ significantly from the previous frame.
+   * @default 0.1
+   */
+  threshold?: number;
+
+  /**
+   * Per-pixel average RGB difference (0-255) for a single pixel to count as "changed".
+   * Filters out camera noise. 30 means a pixel must differ by ~30 in average RGB.
+   * @default 30
+   */
+  pixelThreshold?: number;
+
+  /**
+   * Milliseconds between motion checks.
+   * @default 1000
+   */
+  interval?: number;
+
+  /**
+   * Capture width in pixels. Smaller is faster.
+   * @default 320
+   */
+  width?: number;
+
+  /**
+   * Capture height in pixels. Smaller is faster.
+   * @default 240
+   */
+  height?: number;
+
+  /**
+   * Optional existing `<video>` element already playing a camera stream.
+   * If omitted, the webcam is launched automatically via getUserMedia.
+   */
+  videoElement?: HTMLVideoElement;
+
+  /**
+   * Optional canvas to draw the diff visualization onto (changed pixels in red).
+   * Off by default — only allocated when provided, to avoid wasted work.
+   */
+  debugCanvas?: HTMLCanvasElement;
+}
+
+/**
+ * Callback invoked when movement is detected.
+ * @param snapshot - A PNG data URL of the frame where motion was detected.
+ */
+export type OnMovement = (snapshot: string) => void;
+
+/**
+ * Zero-dependency browser motion detection.
+ *
+ * Calls `onMovement` with a PNG snapshot whenever the webcam detects movement
+ * above the configured threshold. Returns a `stop` function to clean up.
+ *
+ * @example
+ * ```js
+ * import { detectMovement } from 'simple-movement-detector';
+ *
+ * const stop = detectMovement((snapshot) => {
+ *   console.log('Movement detected!', snapshot);
+ * });
+ *
+ * // later:
+ * stop();
+ * ```
+ *
+ * @param onMovement - Called with a PNG data URL of the triggering frame.
+ * @param config - Optional configuration. All fields have sensible defaults.
+ * @returns A `stop` function. Call it to stop detection, clear the interval, and release the camera.
+ */
+export declare function detectMovement(
+  onMovement: OnMovement,
+  config?: DetectMovementConfig
+): () => void;
+
+export default detectMovement;

package/index.js

@@ -0,0 +1,171 @@
+/**
+ * simple-movement-detector
+ * Zero-dependency browser motion detection. Calls your callback when the webcam sees movement.
+ *
+ * @param {function(string): void} onMovement - Called with a PNG data URL of the frame where motion was detected.
+ * @param {object} [config]
+ * @param {number} [config.threshold=0.1]       - Fraction of pixels that must change (0-1) to trigger movement.
+ * @param {number} [config.pixelThreshold=30]   - Per-pixel average RGB diff (0-255) for a pixel to count as "changed".
+ * @param {number} [config.interval=1000]       - Milliseconds between motion checks.
+ * @param {number} [config.width=320]           - Capture width in pixels.
+ * @param {number} [config.height=240]          - Capture height in pixels.
+ * @param {HTMLVideoElement} [config.videoElement] - Optional existing <video> element with a stream. If omitted, the webcam is launched.
+ * @param {HTMLCanvasElement} [config.debugCanvas] - Optional canvas to draw the diff visualization onto. Off by default.
+ * @returns {function(): void} stop - Call to stop detection, clear the interval, and stop the camera track if we launched it.
+ */
+export function detectMovement(onMovement, config = {}) {
+  if (typeof onMovement !== 'function') {
+    throw new TypeError('detectMovement: onMovement callback is required');
+  }
+  if (typeof window === 'undefined' || !navigator || !navigator.mediaDevices) {
+    throw new Error('detectMovement must be used in a browser with getUserMedia support');
+  }
+
+  const width = config.width || 320;
+  const height = config.height || 240;
+  const interval = config.interval ?? 1000;
+  const pixelThreshold = config.pixelThreshold ?? 30;
+  const imageThreshold = config.threshold ?? 0.1;
+
+  if (imageThreshold < 0 || imageThreshold > 1) {
+    throw new RangeError('detectMovement: threshold must be between 0 and 1');
+  }
+  if (pixelThreshold < 0 || pixelThreshold > 255) {
+    throw new RangeError('detectMovement: pixelThreshold must be between 0 and 255');
+  }
+  const changedPixelsRequired = Math.floor(width * height * imageThreshold);
+
+  // Capture canvas (video -> pixels). Never attached to the DOM.
+  const captureCanvas = document.createElement('canvas');
+  captureCanvas.width = width;
+  captureCanvas.height = height;
+  const captureCtx = captureCanvas.getContext('2d', { willReadFrequently: true });
+
+  // Optional debug canvas for diff visualization. Only allocated if user passes one.
+  const debugCanvas = config.debugCanvas || null;
+  const debugCtx = debugCanvas
+    ? debugCanvas.getContext('2d')
+    : null;
+
+  // Two in-memory frame buffers. No <img>, no data URLs, no codec round-trips.
+  // ponytail: Uint8ClampedArray views over ImageData.data; we diff these directly.
+  let prevFrame = null; // Uint8ClampedArray, length width*height*4
+  let currFrame = null; // Uint8ClampedArray, length width*height*4
+
+  const video = config.videoElement || document.createElement('video');
+  // iOS Safari requires these attributes to autoplay a camera stream inline.
+  video.setAttribute('autoplay', '');
+  video.setAttribute('muted', '');
+  video.setAttribute('playsinline', '');
+  video.setAttribute('width', String(width));
+  video.setAttribute('height', String(height));
+
+  let timerId = null;
+  let launchedStream = null;
+  let stopped = false;
+
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timerId !== null) {
+      clearInterval(timerId);
+      timerId = null;
+    }
+    if (launchedStream) {
+      launchedStream.getTracks().forEach((t) => t.stop());
+      launchedStream = null;
+    }
+  };
+
+  const check = () => {
+    if (stopped || video.readyState < 2) return; // not enough data to draw yet
+
+    // Capture current frame into currFrame.
+    captureCtx.drawImage(video, 0, 0, width, height);
+    const imageData = captureCtx.getImageData(0, 0, width, height);
+    currFrame = imageData.data;
+
+    // Need two frames to diff. First frame just primes prevFrame.
+    if (prevFrame === null) {
+      prevFrame = new Uint8ClampedArray(currFrame); // copy
+      return;
+    }
+
+    const data1 = prevFrame;
+    const data2 = currFrame;
+    let changedPixels = 0;
+
+    // Diff loop. Stepping by 4 over RGBA bytes.
+    // ponytail: plain for-loop over a typed array is the fastest portable option;
+    // no SIMD/WebAssembly — keeps the zero-dep, no-build promise. Ceiling: 320*240=76.8k px per tick,
+    // trivial at 1Hz. Upgrade path: Web Worker if interval drops below ~100ms.
+    for (let i = 0; i < data2.length; i += 4) {
+      const rDiff = Math.abs(data1[i] - data2[i]);
+      const gDiff = Math.abs(data1[i + 1] - data2[i + 1]);
+      const bDiff = Math.abs(data1[i + 2] - data2[i + 2]);
+      if ((rDiff + gDiff + bDiff) / 3 > pixelThreshold) {
+        changedPixels++;
+      }
+    }
+
+    // Optional debug visualization: paint changed pixels red, others black.
+    if (debugCtx) {
+      const diffImageData = debugCtx.createImageData(width, height);
+      const diffData = diffImageData.data;
+      for (let i = 0; i < data2.length; i += 4) {
+        const rDiff = Math.abs(data1[i] - data2[i]);
+        const gDiff = Math.abs(data1[i + 1] - data2[i + 1]);
+        const bDiff = Math.abs(data1[i + 2] - data2[i + 2]);
+        const changed = (rDiff + gDiff + bDiff) / 3 > pixelThreshold;
+        diffData[i] = changed ? 255 : 0;
+        diffData[i + 1] = 0;
+        diffData[i + 2] = 0;
+        diffData[i + 3] = 255;
+      }
+      debugCtx.putImageData(diffImageData, 0, 0);
+    }
+
+    // Roll currFrame into prevFrame for the next tick (copy, since currFrame is a view
+    // into a reused ImageData buffer that getImageData may overwrite).
+    prevFrame.set(currFrame);
+
+    if (changedPixels > changedPixelsRequired) {
+      // Hand the caller a PNG snapshot of the frame that triggered.
+      // This is the only data-URL encode in the whole pipeline, and only fires on motion.
+      onMovement(captureCanvas.toDataURL('image/png'));
+    }
+  };
+
+  const startPolling = () => {
+    if (timerId !== null) return;
+    timerId = setInterval(check, interval);
+  };
+
+  if (config.videoElement && config.videoElement.srcObject) {
+    // Caller provided an already-streaming <video>. Just poll.
+    startPolling();
+  } else {
+    // Launch the webcam ourselves. Side effect lives here, not in the diff loop.
+    navigator.mediaDevices
+      .getUserMedia({ video: true, audio: false })
+      .then((stream) => {
+        if (stopped) {
+          // User called stop() before the camera permission resolved. Clean up.
+          stream.getTracks().forEach((t) => t.stop());
+          return;
+        }
+        launchedStream = stream;
+        video.srcObject = stream;
+        video.play();
+        startPolling();
+      })
+      .catch((err) => {
+        stop();
+        throw err;
+      });
+  }
+
+  return stop;
+}
+
+export default detectMovement;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "simple-movement-detector",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "A zero-dependency browser library that calls your callback when the webcam detects movement",
+  "author": "Mikhail Gorbunov <toplenboren@gmail.com>",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "release": "clean-pkg-json && npm publish"
+  },
+  "keywords": [
+    "motion-detection",
+    "movement",
+    "webcam",
+    "camera",
+    "browser",
+    "zero-dependency",
+    "getUserMedia"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toplenboren/simple-movement-detector.git"
+  },
+  "devDependencies": {
+    "clean-pkg-json": "^1.2.1"
+  }
+}