memoir-node 0.1.5

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 lunavod
+
+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.
+
+---
+
+This software links against FFmpeg, which is licensed under the
+GNU Lesser General Public License (LGPL) version 2.1 or later.
+See https://www.ffmpeg.org/legal.html for details.

package/README.md

@@ -0,0 +1,224 @@
+# memoir-capture
+
+Windows-native screen capture module with Python bindings for real-time frame analysis and deterministic replay recording.
+
+Memoir captures frames from a window or monitor using Windows Graphics Capture (WGC), delivers them to Python as NumPy arrays, and optionally records them to HEVC video with per-frame metadata — all without GPU-to-CPU roundtrips in the recording path.
+
+## Features
+
+- **WGC capture** — continuous frame capture from any window or monitor
+- **NumPy delivery** — BGRA frames as `(H, W, 4)` uint8 arrays via bounded queue
+- **Hardware-accelerated recording** — lossless HEVC encoding (YUV 4:4:4) via NVENC, AMF, or software x265 fallback
+- **Binary metadata** — `.meta` sidecar with per-frame keyboard state, timestamps, and frame IDs
+- **Dynamic recording** — start/stop recording without restarting capture
+- **Frame-accurate keyboard** — key state snapshot at the exact moment each frame is accepted
+- **Typed Python API** — full type annotations, dataclasses, context managers
+
+## Requirements
+
+- Windows 10 1903+ (for WGC `CreateFreeThreaded`)
+- Python 3.10+
+- NVIDIA GPU (NVENC), AMD GPU (AMF), or CPU-only (x265 software fallback) for recording
+- Visual Studio 2022 (for building from source)
+
+## Installation
+
+### From PyPI (prebuilt)
+
+```
+pip install memoir-capture
+```
+
+### From source
+
+```powershell
+# Clone with vcpkg
+git clone https://github.com/lunavod/memoir-capture.git
+cd Memoir
+git clone https://github.com/microsoft/vcpkg.git vcpkg --depth 1
+.\vcpkg\bootstrap-vcpkg.bat -disableMetrics
+
+# Build
+pip install build numpy
+python -m build --wheel
+
+# Install
+pip install dist\memoir_capture-*.whl
+```
+
+The first build takes ~15 minutes (vcpkg builds FFmpeg). Subsequent builds use cached binaries.
+
+For local development without installing:
+
+```powershell
+.\scripts\build.ps1
+# memoir_capture/ package is ready to import from the project root
+```
+
+## Quick Start
+
+### Capture frames
+
+```python
+import memoir_capture
+
+engine = memoir_capture.CaptureEngine(
+    memoir_capture.MonitorTarget(0),    # primary monitor
+    max_fps=10.0,
+)
+engine.start()
+
+for packet in engine.frames():
+    with packet:
+        img = packet.cpu_bgra           # numpy (H, W, 4) uint8
+        print(f"Frame {packet.frame_id}: {img.shape}")
+        print(f"Keys: 0x{packet.keyboard_mask:016x}")
+    break
+
+engine.stop()
+```
+
+### Capture a specific window
+
+```python
+engine = memoir_capture.CaptureEngine(
+    memoir_capture.WindowTitleTarget(r"(?i)notepad"),
+    max_fps=30.0,
+)
+```
+
+### Record to MP4
+
+```python
+engine = memoir_capture.CaptureEngine(
+    memoir_capture.MonitorTarget(0),
+    max_fps=10.0,
+    record_width=1920,
+    record_height=1080,
+    record_gop=1,           # 1 = all-intra (frame-accurate seeking)
+)
+engine.start()
+
+info = engine.start_recording("session_001")
+print(f"Recording to {info.video_path}")  # session_001.mp4
+
+for i, packet in enumerate(engine.frames()):
+    packet.release()
+    if i >= 99:
+        break
+
+engine.stop_recording()     # finalizes .mp4 + .meta
+engine.stop()
+```
+
+### Read metadata
+
+```python
+meta = memoir_capture.MetaReader.read("session_001.meta")
+
+print(f"Keys tracked: {[k.name for k in meta.keys]}")
+
+for row in meta.rows:
+    print(f"Frame {row.frame_id}: keyboard=0x{row.keyboard_mask:016x}")
+```
+
+### Write metadata (for synthetic replays)
+
+```python
+from memoir_capture import MetaWriter, MetaKeyEntry, MetaRow
+
+keys = [MetaKeyEntry(0, 0x57, "W"), MetaKeyEntry(1, 0x41, "A")]
+
+with MetaWriter("synthetic.meta", keys) as w:
+    w.write_row(MetaRow(
+        frame_id=0, record_frame_index=0,
+        capture_qpc=0, host_accept_qpc=0,
+        keyboard_mask=0b01,
+        width=1920, height=1080, analysis_stride=7680,
+    ))
+```
+
+### Context manager
+
+```python
+with memoir_capture.CaptureEngine(memoir_capture.MonitorTarget(0)) as engine:
+    packet = engine.get_next_frame(timeout_ms=2000)
+    if packet:
+        with packet:
+            process(packet.cpu_bgra)
+```
+
+## API Reference
+
+### `CaptureEngine(target, *, max_fps, ...)`
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `target` | required | `MonitorTarget(index)`, `WindowTitleTarget(regex)`, or `WindowExeTarget(regex)` |
+| `max_fps` | `10.0` | Maximum accepted frame rate |
+| `analysis_queue_capacity` | `1` | Bounded queue size for Python delivery |
+| `capture_cursor` | `False` | Include cursor in capture |
+| `record_width` | `1920` | Recording output width |
+| `record_height` | `1080` | Recording output height |
+| `record_gop` | `1` | GOP size (1 = all-intra, higher = smaller files) |
+
+**Methods**: `start()`, `stop()`, `get_next_frame(timeout_ms)`, `frames()`, `start_recording(base_path, *, encoder=None)`, `stop_recording()`, `is_recording()`, `stats()`
+
+### `FramePacket`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `frame_id` | `int` | Monotonic ID (only accepted frames get IDs) |
+| `cpu_bgra` | `np.ndarray` | `(H, W, 4)` uint8 BGRA pixel data |
+| `keyboard_mask` | `int` | 64-bit bitmask of tracked keys |
+| `capture_qpc` | `int` | WGC capture timestamp (100ns units) |
+| `width`, `height`, `stride` | `int` | Frame dimensions |
+
+Supports `with packet:` (auto-release) and explicit `packet.release()`.
+
+### Recording
+
+Encoding: lossless HEVC (QP=0), YUV 4:4:4, full color range. The encoder is selected automatically in priority order: `hevc_nvenc` (NVIDIA) → `hevc_amf` (AMD) → `libx265` (software). You can force a specific encoder:
+
+```python
+info = engine.start_recording("session_001", encoder="libx265")
+```
+
+| Setting | File size (10s, 1080p) |
+|---------|----------------------|
+| GOP=1 (all-intra) | ~52 MB |
+| GOP=10 | ~17 MB |
+| GOP=30 | ~14 MB |
+
+## Architecture
+
+```
+WGC FrameArrived (thread pool)
+  │
+  ├─ FPS limiter → drop if too soon
+  ├─ Queue check → drop if full (drop-new policy)
+  │
+  ├─ Accept: assign frame_id, snapshot keyboard
+  ├─ GPU→CPU: CopyResource → staging → Map → memcpy
+  ├─ Recording: swscale (BGRA→YUV444) → HEVC encoder → MP4
+  └─ Enqueue → Python consumer
+```
+
+- Single `ID3D11DeviceContext` + mutex for all GPU ops
+- WGC `CreateFreeThreaded` — no DispatcherQueue needed
+- Recording runs on the callback thread (well within budget at 10fps)
+- `FramePacket` owns its pixel buffer; `release()` frees it
+
+## Testing
+
+```powershell
+# Full suite (requires display + supported GPU or x265)
+pytest -v
+
+# Headless (CI-safe)
+pytest --headless -v
+```
+
+## License
+
+MIT. Links against FFmpeg (LGPL 2.1+).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { CaptureTarget, MonitorTarget, WindowTitleTarget, WindowExeTarget, KeySpec, EngineOptions, FramePacket, RecordingInfo, EngineStats, MetaHeader, MetaKeyEntry, MetaRow, MetaFile, } from './types';
+export { readMeta, writeMeta, isPressed, pressedKeys, synthesizeKeyEvents } from './meta';
+export { CaptureEngine, ping, version, grab } from './native';

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.grab = exports.version = exports.ping = exports.CaptureEngine = exports.synthesizeKeyEvents = exports.pressedKeys = exports.isPressed = exports.writeMeta = exports.readMeta = void 0;
+// Pure TypeScript meta reader/writer
+var meta_1 = require("./meta");
+Object.defineProperty(exports, "readMeta", { enumerable: true, get: function () { return meta_1.readMeta; } });
+Object.defineProperty(exports, "writeMeta", { enumerable: true, get: function () { return meta_1.writeMeta; } });
+Object.defineProperty(exports, "isPressed", { enumerable: true, get: function () { return meta_1.isPressed; } });
+Object.defineProperty(exports, "pressedKeys", { enumerable: true, get: function () { return meta_1.pressedKeys; } });
+Object.defineProperty(exports, "synthesizeKeyEvents", { enumerable: true, get: function () { return meta_1.synthesizeKeyEvents; } });
+// Native addon
+var native_1 = require("./native");
+Object.defineProperty(exports, "CaptureEngine", { enumerable: true, get: function () { return native_1.CaptureEngine; } });
+Object.defineProperty(exports, "ping", { enumerable: true, get: function () { return native_1.ping; } });
+Object.defineProperty(exports, "version", { enumerable: true, get: function () { return native_1.version; } });
+Object.defineProperty(exports, "grab", { enumerable: true, get: function () { return native_1.grab; } });

package/dist/meta.d.ts

@@ -0,0 +1,10 @@
+import type { MetaFile, MetaKeyEntry, MetaRow } from './types';
+export declare function readMeta(path: string): MetaFile;
+export declare function writeMeta(path: string, keys: MetaKeyEntry[], rows: MetaRow[], createdUnixNs?: bigint): void;
+export declare function isPressed(row: MetaRow, keyName: string, keys: MetaKeyEntry[]): boolean;
+export declare function pressedKeys(row: MetaRow, keys: MetaKeyEntry[]): string[];
+export declare function synthesizeKeyEvents(rows: MetaRow[], keys: MetaKeyEntry[]): Array<{
+    frame: bigint;
+    type: 'keyDown' | 'keyUp';
+    key: string;
+}>;

package/dist/meta.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readMeta = readMeta;
+exports.writeMeta = writeMeta;
+exports.isPressed = isPressed;
+exports.pressedKeys = pressedKeys;
+exports.synthesizeKeyEvents = synthesizeKeyEvents;
+const fs_1 = require("fs");
+const HEADER_SIZE = 32;
+const KEY_SIZE = 40;
+const ROW_SIZE = 56;
+const MAGIC = Buffer.from('RCMETA1\x00', 'ascii');
+function readMeta(path) {
+    const buf = (0, fs_1.readFileSync)(path);
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    // Header
+    const magic = buf.subarray(0, 8);
+    if (!magic.equals(MAGIC))
+        throw new Error(`Bad magic: ${magic.toString('hex')}`);
+    const version = view.getUint32(8, true);
+    const createdUnixNs = view.getBigUint64(16, true);
+    const keyCount = view.getUint32(24, true);
+    // Keys
+    let offset = HEADER_SIZE;
+    const keys = [];
+    for (let i = 0; i < keyCount; i++) {
+        const bit = view.getUint32(offset, true);
+        const vk = view.getUint32(offset + 4, true);
+        const nameBytes = buf.subarray(offset + 8, offset + 40);
+        const nullIdx = nameBytes.indexOf(0);
+        const name = nameBytes.subarray(0, nullIdx === -1 ? 32 : nullIdx).toString('ascii');
+        keys.push({ bit, vk, name });
+        offset += KEY_SIZE;
+    }
+    // Rows
+    const rows = [];
+    while (offset + ROW_SIZE <= buf.length) {
+        rows.push({
+            frameId: view.getBigUint64(offset, true),
+            recordFrameIndex: view.getBigUint64(offset + 8, true),
+            captureQpc: view.getBigInt64(offset + 16, true),
+            hostAcceptQpc: view.getBigInt64(offset + 24, true),
+            keyboardMask: view.getBigUint64(offset + 32, true),
+            width: view.getUint32(offset + 40, true),
+            height: view.getUint32(offset + 44, true),
+            analysisStride: view.getUint32(offset + 48, true),
+            flags: view.getUint32(offset + 52, true),
+        });
+        offset += ROW_SIZE;
+    }
+    return {
+        header: { version, createdUnixNs, keyCount },
+        keys,
+        rows,
+    };
+}
+function writeMeta(path, keys, rows, createdUnixNs) {
+    const size = HEADER_SIZE + keys.length * KEY_SIZE + rows.length * ROW_SIZE;
+    const buf = Buffer.alloc(size);
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    // Header
+    MAGIC.copy(buf, 0);
+    view.setUint32(8, 1, true); // version
+    view.setBigUint64(16, createdUnixNs ?? BigInt(Date.now()) * 1000000n, true);
+    view.setUint32(24, keys.length, true);
+    // Keys
+    let offset = HEADER_SIZE;
+    for (const k of keys) {
+        view.setUint32(offset, k.bit, true);
+        view.setUint32(offset + 4, k.vk, true);
+        buf.write(k.name.substring(0, 31), offset + 8, 'ascii');
+        offset += KEY_SIZE;
+    }
+    // Rows
+    for (const r of rows) {
+        view.setBigUint64(offset, r.frameId, true);
+        view.setBigUint64(offset + 8, r.recordFrameIndex, true);
+        view.setBigInt64(offset + 16, r.captureQpc, true);
+        view.setBigInt64(offset + 24, r.hostAcceptQpc, true);
+        view.setBigUint64(offset + 32, r.keyboardMask, true);
+        view.setUint32(offset + 40, r.width, true);
+        view.setUint32(offset + 44, r.height, true);
+        view.setUint32(offset + 48, r.analysisStride, true);
+        view.setUint32(offset + 52, r.flags, true);
+        offset += ROW_SIZE;
+    }
+    (0, fs_1.writeFileSync)(path, buf);
+}
+// ─── Helpers ────────────────────────────────────────────────────
+function isPressed(row, keyName, keys) {
+    const key = keys.find(k => k.name === keyName);
+    if (!key)
+        throw new Error(`Key "${keyName}" not in key map`);
+    return (row.keyboardMask & (1n << BigInt(key.bit))) !== 0n;
+}
+function pressedKeys(row, keys) {
+    return keys.filter(k => (row.keyboardMask & (1n << BigInt(k.bit))) !== 0n).map(k => k.name);
+}
+function synthesizeKeyEvents(rows, keys) {
+    const events = [];
+    let prevMask = 0n;
+    for (const row of rows) {
+        const diff = row.keyboardMask ^ prevMask;
+        if (diff !== 0n) {
+            for (const k of keys) {
+                const bit = 1n << BigInt(k.bit);
+                if ((diff & bit) !== 0n) {
+                    events.push({
+                        frame: row.recordFrameIndex,
+                        type: (row.keyboardMask & bit) !== 0n ? 'keyDown' : 'keyUp',
+                        key: k.name,
+                    });
+                }
+            }
+        }
+        prevMask = row.keyboardMask;
+    }
+    return events;
+}

package/dist/native.d.ts

@@ -0,0 +1,29 @@
+import type { CaptureTarget, EngineOptions, FramePacket } from './types';
+export declare const CaptureEngine: {
+    new (options: EngineOptions): {
+        start(): void;
+        stop(): void;
+        getNextFrame(timeoutMs?: number): FramePacket | null;
+        startRecording(basePath: string, encoder?: string): import('./types').RecordingInfo;
+        startRecording(opts: {
+            path: string;
+            videoName: string;
+            metaName: string;
+            encoder?: string;
+        }): import('./types').RecordingInfo;
+        stopRecording(): void;
+        isRecording(): boolean;
+        stats(): import('./types').EngineStats;
+        lastError(): string | null;
+    };
+};
+export declare const ping: () => string;
+export declare const version: string;
+/**
+ * Capture a single frame and return it.
+ * Creates a temporary engine, grabs one frame, stops.
+ */
+export declare function grab(target: CaptureTarget, opts?: {
+    timeoutMs?: number;
+    maxFps?: number;
+}): FramePacket;

package/dist/native.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.version = exports.ping = exports.CaptureEngine = void 0;
+exports.grab = grab;
+const path_1 = __importDefault(require("path"));
+// Load the compiled N-API addon
+let addon;
+try {
+    addon = require(path_1.default.resolve(__dirname, '../build/Release/memoir_node.node'));
+}
+catch {
+    // Fallback for different build configurations
+    addon = require(path_1.default.resolve(__dirname, '../build/Debug/memoir_node.node'));
+}
+exports.CaptureEngine = addon.CaptureEngine;
+exports.ping = addon.ping;
+exports.version = addon.version;
+/**
+ * Capture a single frame and return it.
+ * Creates a temporary engine, grabs one frame, stops.
+ */
+function grab(target, opts) {
+    const engine = new exports.CaptureEngine({ target, maxFps: opts?.maxFps ?? 60 });
+    engine.start();
+    try {
+        const frame = engine.getNextFrame(opts?.timeoutMs ?? 5000);
+        if (!frame)
+            throw new Error('No frame captured within timeout');
+        return frame;
+    }
+    finally {
+        engine.stop();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+export interface MonitorTarget {
+    type: 'monitor';
+    index: number;
+}
+export interface WindowTitleTarget {
+    type: 'windowTitle';
+    pattern: string;
+}
+export interface WindowExeTarget {
+    type: 'windowExe';
+    pattern: string;
+}
+export type CaptureTarget = MonitorTarget | WindowTitleTarget | WindowExeTarget;
+export interface KeySpec {
+    bit: number;
+    vk: number;
+    name: string;
+}
+export interface EngineOptions {
+    target: CaptureTarget;
+    maxFps?: number;
+    queueCapacity?: number;
+    captureCursor?: boolean;
+    keys?: KeySpec[];
+    recordWidth?: number;
+    recordHeight?: number;
+    recordGop?: number;
+}
+export interface FramePacket {
+    readonly frameId: number;
+    readonly width: number;
+    readonly height: number;
+    readonly stride: number;
+    readonly captureQpc: bigint;
+    readonly hostAcceptQpc: bigint;
+    readonly keyboardMask: bigint;
+    readonly data: Buffer;
+    readonly released: boolean;
+    release(): void;
+}
+export interface RecordingInfo {
+    basePath: string;
+    videoPath: string;
+    metaPath: string;
+    codec: string;
+    width: number;
+    height: number;
+}
+export interface EngineStats {
+    framesSeen: number;
+    framesAccepted: number;
+    framesDroppedQueueFull: number;
+    framesDroppedError: number;
+    framesRecorded: number;
+    queueDepth: number;
+    recording: boolean;
+}
+export interface MetaHeader {
+    version: number;
+    createdUnixNs: bigint;
+    keyCount: number;
+}
+export interface MetaKeyEntry {
+    bit: number;
+    vk: number;
+    name: string;
+}
+export interface MetaRow {
+    frameId: bigint;
+    recordFrameIndex: bigint;
+    captureQpc: bigint;
+    hostAcceptQpc: bigint;
+    keyboardMask: bigint;
+    width: number;
+    height: number;
+    analysisStride: number;
+    flags: number;
+}
+export interface MetaFile {
+    header: MetaHeader;
+    keys: MetaKeyEntry[];
+    rows: MetaRow[];
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// ─── Capture Targets ────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "memoir-node",
+  "version": "0.1.5",
+  "description": "Windows-native screen capture with Node.js bindings",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lunavod/memoir-capture.git"
+  },
+  "os": ["win32"],
+  "cpu": ["x64"],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["screen-capture", "windows", "native", "napi", "wgc", "ffmpeg", "recording"],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build:native": "cmake-js build --CDMEMOIR_BUILD_NODE=ON --CDMEMOIR_BUILD_PYTHON=OFF --CDCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake --CDVCPKG_OVERLAY_TRIPLETS=cmake/triplets --CDVCPKG_TARGET_TRIPLET=x64-windows-release",
+    "build:ts": "tsc",
+    "build": "npm run build:native && tsc",
+    "rebuild": "cmake-js rebuild --CDMEMOIR_BUILD_NODE=ON --CDMEMOIR_BUILD_PYTHON=OFF --CDCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake --CDVCPKG_OVERLAY_TRIPLETS=cmake/triplets --CDVCPKG_TARGET_TRIPLET=x64-windows-release",
+    "test": "vitest run"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "cmake-js": "^7.0.0",
+    "node-addon-api": "^7.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "build/Release/memoir_node.node",
+    "build/Release/*.dll",
+    "LICENSE"
+  ]
+}