memoir-node 0.1.5 → 0.1.6

package/README.md

@@ -1,194 +1,232 @@
-# memoir-capture
+# memoir-node
 
-Windows-native screen capture module with Python bindings for real-time frame analysis and deterministic replay recording.
+Windows-native screen capture module with Node.js 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.
+Memoir captures frames from a window or monitor using Windows Graphics Capture (WGC), delivers them as Buffers, and optionally records them to HEVC video with per-frame metadata.
 
 ## 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
+- **Zero-copy Buffers** — BGRA frames delivered as Node.js Buffers without copying
+- **Hardware-accelerated recording** — lossless HEVC encoding via NVENC, AMF, or 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
+- **Pure TypeScript meta reader/writer** — read and write `.meta` files without the native addon
+- **Synchronous blocking API** — designed for Worker threads running tick loops
 
 ## 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)
+- Windows 10 1903+
+- Node.js 18+
+- x64 architecture
+- NVIDIA GPU (NVENC), AMD GPU (AMF), or CPU-only (x265) for recording
 
 ## 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
+npm install memoir-node
 ```
 
 ## Quick Start
 
 ### Capture frames
 
-```python
-import memoir_capture
+```typescript
+import { CaptureEngine } from 'memoir-node'
 
-engine = memoir_capture.CaptureEngine(
-    memoir_capture.MonitorTarget(0),    # primary monitor
-    max_fps=10.0,
-)
+const engine = new CaptureEngine({
+  target: { type: 'monitor', index: 0 },  // primary monitor
+  maxFps: 10,
+})
 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
+const frame = engine.getNextFrame(5000)
+if (frame) {
+  console.log(`Frame ${frame.frameId}: ${frame.width}x${frame.height}`)
+  console.log(`Keys: ${frame.keyboardMask.toString(16)}`)
+  // frame.data is a Buffer with BGRA pixels
+  frame.release()
+}
 
 engine.stop()
 ```
 
 ### Capture a specific window
 
-```python
-engine = memoir_capture.CaptureEngine(
-    memoir_capture.WindowTitleTarget(r"(?i)notepad"),
-    max_fps=30.0,
-)
+```typescript
+const engine = new CaptureEngine({
+  target: { type: 'windowTitle', pattern: '(?i)notepad' },
+  maxFps: 30,
+})
+```
+
+Or by executable name:
+
+```typescript
+const engine = new CaptureEngine({
+  target: { type: 'windowExe', pattern: 'notepad\\.exe' },
+  maxFps: 30,
+})
 ```
 
 ### 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)
-)
+```typescript
+const engine = new CaptureEngine({
+  target: { type: 'monitor', index: 0 },
+  maxFps: 10,
+  recordWidth: 1920,
+  recordHeight: 1080,
+})
 engine.start()
 
-info = engine.start_recording("session_001")
-print(f"Recording to {info.video_path}")  # session_001.mp4
+const info = engine.startRecording('session_001')
+console.log(`Recording to ${info.videoPath}`)  // session_001.mp4
 
-for i, packet in enumerate(engine.frames()):
-    packet.release()
-    if i >= 99:
-        break
+for (let i = 0; i < 100; i++) {
+  const frame = engine.getNextFrame(5000)
+  if (frame) frame.release()
+}
 
-engine.stop_recording()     # finalizes .mp4 + .meta
+engine.stopRecording()  // finalizes .mp4 + .meta
 engine.stop()
 ```
 
 ### Read metadata
 
-```python
-meta = memoir_capture.MetaReader.read("session_001.meta")
+```typescript
+import { readMeta, pressedKeys } from 'memoir-node'
 
-print(f"Keys tracked: {[k.name for k in meta.keys]}")
+const meta = readMeta('session_001.meta')
+console.log(`Keys tracked: ${meta.keys.map(k => k.name)}`)
 
-for row in meta.rows:
-    print(f"Frame {row.frame_id}: keyboard=0x{row.keyboard_mask:016x}")
+for (const row of meta.rows) {
+  console.log(`Frame ${row.frameId}: ${pressedKeys(row, meta.keys).join(', ')}`)
+}
 ```
 
 ### Write metadata (for synthetic replays)
 
-```python
-from memoir_capture import MetaWriter, MetaKeyEntry, MetaRow
+```typescript
+import { writeMeta, type MetaKeyEntry, type MetaRow } from 'memoir-node'
+
+const keys: MetaKeyEntry[] = [
+  { bit: 0, vk: 0x57, name: 'W' },
+  { bit: 1, vk: 0x41, name: 'A' },
+]
 
-keys = [MetaKeyEntry(0, 0x57, "W"), MetaKeyEntry(1, 0x41, "A")]
+const rows: MetaRow[] = [{
+  frameId: 0n, recordFrameIndex: 0n,
+  captureQpc: 0n, hostAcceptQpc: 0n,
+  keyboardMask: 0b01n,
+  width: 1920, height: 1080, analysisStride: 7680, flags: 0,
+}]
 
-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,
-    ))
+writeMeta('synthetic.meta', keys, rows)
 ```
 
-### Context manager
+### Worker thread usage (Electron)
 
-```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)
-```
+```typescript
+// tick-worker.ts — runs in Worker thread
+import { CaptureEngine } from 'memoir-node'
+import { parentPort } from 'worker_threads'
 
-## API Reference
+const engine = new CaptureEngine({
+  target: { type: 'windowExe', pattern: 'myapp\\.exe' },
+  maxFps: 10,
+})
+engine.start()
 
-### `CaptureEngine(target, *, max_fps, ...)`
+while (true) {
+  const frame = engine.getNextFrame(2000)
+  if (!frame) {
+    const err = engine.lastError()
+    if (err) { parentPort!.postMessage({ type: 'error', error: err }); break }
+    continue
+  }
+
+  // frame.data is a Buffer — process it here, don't post it to main thread
+  parentPort!.postMessage({
+    type: 'tick',
+    frameId: frame.frameId,
+    width: frame.width,
+    height: frame.height,
+  })
+
+  frame.release()
+}
+```
 
-| 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) |
+## API Reference
 
-**Methods**: `start()`, `stop()`, `get_next_frame(timeout_ms)`, `frames()`, `start_recording(base_path, *, encoder=None)`, `stop_recording()`, `is_recording()`, `stats()`
+### `new CaptureEngine(options)`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `target` | required | `{ type: 'monitor', index }`, `{ type: 'windowTitle', pattern }`, or `{ type: 'windowExe', pattern }` |
+| `maxFps` | `10` | Maximum accepted frame rate |
+| `queueCapacity` | `1` | Bounded queue size |
+| `captureCursor` | `false` | Include cursor in capture |
+| `keys` | 40-key gaming set | Array of `{ bit, vk, name }` for keyboard tracking |
+| `recordWidth` | `1920` | Recording output width |
+| `recordHeight` | `1080` | Recording output height |
+| `recordGop` | `1` | GOP size (1 = all-intra) |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `start()` | `void` | Initialize D3D11, create WGC session, begin capturing |
+| `stop()` | `void` | Stop capture and any active recording |
+| `getNextFrame(timeoutMs?)` | `FramePacket \| null` | Block until frame available. -1 = forever, 0 = poll |
+| `startRecording(basePath, encoder?)` | `RecordingInfo` | Start recording to `basePath.mp4` + `basePath.meta` |
+| `startRecording(opts)` | `RecordingInfo` | Start recording with `{ path, videoName, metaName, encoder? }` |
+| `stopRecording()` | `void` | Finalize recording |
+| `isRecording()` | `boolean` | Whether a recording session is active |
+| `stats()` | `EngineStats` | Live counters |
+| `lastError()` | `string \| null` | Last non-fatal error |
 
 ### `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 |
+| `frameId` | `number` | Monotonic frame ID |
+| `data` | `Buffer` | BGRA pixels, length = stride * height |
+| `keyboardMask` | `bigint` | 64-bit key state bitmask |
+| `captureQpc` | `bigint` | WGC timestamp (100ns units) |
+| `hostAcceptQpc` | `bigint` | Host QPC when frame was accepted |
+| `width`, `height`, `stride` | `number` | Frame dimensions |
+| `released` | `boolean` | Whether pixel memory has been freed |
 
-Supports `with packet:` (auto-release) and explicit `packet.release()`.
+Call `frame.release()` when done to free pixel memory.
 
 ### 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:
+Encoding: lossless HEVC (QP=0), YUV 4:4:4. Encoder selected automatically: `hevc_nvenc` (NVIDIA) → `hevc_amf` (AMD) → `libx265` (software). Force a specific encoder:
 
-```python
-info = engine.start_recording("session_001", encoder="libx265")
+```typescript
+const info = engine.startRecording('session', 'libx265')
+console.log(info.codec) // "libx265"
 ```
 
-| Setting | File size (10s, 1080p) |
-|---------|----------------------|
-| GOP=1 (all-intra) | ~52 MB |
-| GOP=10 | ~17 MB |
-| GOP=30 | ~14 MB |
+### Meta utilities
+
+```typescript
+import { readMeta, writeMeta, isPressed, pressedKeys, synthesizeKeyEvents } from 'memoir-node'
+
+// Read
+const meta = readMeta('session.meta')
+
+// Check keys
+isPressed(meta.rows[0], 'W', meta.keys)       // boolean
+pressedKeys(meta.rows[0], meta.keys)           // string[]
+
+// Generate key events for replay
+const events = synthesizeKeyEvents(meta.rows, meta.keys)
+// [{ frame: 0n, type: 'keyDown', key: 'W' }, ...]
+```
 
 ## Architecture
 
@@ -199,25 +237,12 @@ WGC FrameArrived (thread pool)
   ├─ Queue check → drop if full (drop-new policy)
   │
   ├─ Accept: assign frame_id, snapshot keyboard
-  ├─ GPU→CPU: CopyResource → staging → Map → memcpy
+  ├─ GPU→CPU: CopyResource → staging → Map → memcpy → Buffer (zero-copy)
   ├─ Recording: swscale (BGRA→YUV444) → HEVC encoder → MP4
-  └─ Enqueue → Python consumer
+  └─ Enqueue → Node.js 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
-```
+`getNextFrame()` is a synchronous blocking call that waits on a condition variable. No GIL concerns (unlike Python) — the calling thread simply sleeps until a frame arrives. Use in a Worker thread to avoid blocking the main V8 thread.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoir-node",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Windows-native screen capture with Node.js bindings",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,9 @@
     "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"
+    "test": "vitest run",
+    "prepack": "node -e \"const fs=require('fs'); fs.copyFileSync('README.md','README-python.md'); fs.copyFileSync('README-node.md','README.md')\"",
+    "postpack": "node -e \"const fs=require('fs'); fs.copyFileSync('README-python.md','README.md'); fs.unlinkSync('README-python.md')\""
   },
   "dependencies": {},
   "devDependencies": {