@doedja/scenecut 1.0.0

package/README.md

@@ -0,0 +1,280 @@
+# scenecut
+
+Fast, accurate scene change detection for Node.js using Xvid's motion estimation algorithm compiled to WebAssembly.
+
+## Features
+
+- **Fast**: WebAssembly-accelerated motion estimation (35-45 fps on typical hardware)
+- **Accurate**: Uses Xvid's proven motion estimation algorithm from vapoursynth-wwxd
+- **Multiple output formats**: Aegisub keyframes, timecodes, CSV, JSON
+- **Easy to use**: Simple CLI and programmatic API
+- **Cross-platform**: Works on Windows, Linux, and macOS
+
+## Installation
+
+### Global Installation (CLI)
+
+```bash
+npm install -g @doedja/scenecut
+```
+
+### Local Installation (API)
+
+```bash
+npm install @doedja/scenecut
+```
+
+## CLI Usage
+
+### Basic Usage
+
+```bash
+# Simple - detects scenes and saves to Aegisub format (default)
+# Creates input_keyframes.txt
+scenecut "input.mkv"
+
+# Specify custom output filename
+scenecut "video.mkv" -o keyframes.txt
+
+# For timecode output
+scenecut "video.mp4" --format timecode -o timecodes.txt
+
+# JSON format with full metadata
+scenecut "movie.avi" --format json
+
+# CSV format for spreadsheet analysis
+scenecut "movie.avi" --format csv -o scenes.csv
+```
+
+### CLI Options
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--format` | `-f` | Output format: `aegisub`, `json`, `csv`, `timecode` | `aegisub` |
+| `--output` | `-o` | Output file path | `{filename}_keyframes.txt` |
+| `--sensitivity` | `-s` | Detection sensitivity: `low`, `medium`, `high` | `medium` |
+| `--quiet` | `-q` | Suppress progress output | `false` |
+| `--verbose` | `-v` | Show detailed output including each scene | `false` |
+| `--help` | `-h` | Show help message | - |
+
+### Examples
+
+```bash
+# Default - creates anime_keyframes.txt in Aegisub format
+scenecut "anime.mkv"
+
+# High sensitivity for subtle scene changes
+scenecut "anime.mkv" --sensitivity high
+
+# JSON format with full metadata
+scenecut "video.mp4" --format json -o results.json
+
+# Verbose mode with detailed scene information
+scenecut "movie.mkv" --verbose
+```
+
+## Output Formats
+
+### Aegisub Format (`.txt`)
+
+Aegisub keyframes format for subtitle timing:
+
+```
+# keyframe format v1
+fps 23.976
+0
+143
+287
+```
+
+**Aegisub Workflow:**
+1. Generate keyframes: `scenecut "video.mkv" -f aegisub -o keyframes.txt`
+2. In Aegisub: **Video** → **Open Keyframes** → Select `keyframes.txt`
+3. Keyframes appear as visual markers on the timeline for precise subtitle timing
+
+### Timecode Format (`.txt`)
+
+Simple timecode list (HH:MM:SS.mmm):
+
+```
+00:00:00.000
+00:00:05.964
+00:00:11.970
+```
+
+### CSV Format (`.csv`)
+
+Spreadsheet-compatible format:
+
+```csv
+frame,timestamp,timecode
+0,0.0,00:00:00.000
+143,5.964,00:00:05.964
+287,11.970,00:00:11.970
+```
+
+### JSON Format (`.json`)
+
+Complete metadata and scene information:
+
+```json
+{
+  "scenes": [
+    {
+      "frameNumber": 0,
+      "timestamp": 0.0,
+      "timecode": "00:00:00.000"
+    },
+    {
+      "frameNumber": 143,
+      "timestamp": 5.964,
+      "timecode": "00:00:05.964"
+    }
+  ],
+  "metadata": {
+    "totalFrames": 3000,
+    "duration": 125.08,
+    "fps": 23.976,
+    "resolution": {
+      "width": 1920,
+      "height": 1080
+    }
+  }
+}
+```
+
+## Programmatic API
+
+### Basic Usage
+
+```javascript
+const { detectSceneChanges } = require('@doedja/scenecut');
+
+(async () => {
+  const results = await detectSceneChanges('input.mp4');
+
+  console.log(`Found ${results.scenes.length} scenes`);
+  results.scenes.forEach(scene => {
+    console.log(`Scene at frame ${scene.frameNumber} (${scene.timecode})`);
+  });
+})();
+```
+
+### Advanced Usage with Options
+
+```javascript
+const { detectSceneChanges } = require('@doedja/scenecut');
+
+const results = await detectSceneChanges('input.mp4', {
+  sensitivity: 'high',        // 'low' | 'medium' | 'high'
+  searchRange: 'medium',      // Motion search range
+
+  // Progress callback
+  onProgress: (progress) => {
+    console.log(`Progress: ${progress.percent}%`);
+    console.log(`Frame: ${progress.currentFrame}/${progress.totalFrames}`);
+    console.log(`FPS: ${progress.fps}, ETA: ${progress.eta}s`);
+  },
+
+  // Scene detection callback
+  onScene: (scene) => {
+    console.log(`Scene detected at frame ${scene.frameNumber}`);
+    console.log(`Timecode: ${scene.timecode}`);
+  }
+});
+
+console.log('Detection complete!');
+console.log(`Total scenes: ${results.scenes.length}`);
+console.log(`Video duration: ${results.metadata.duration}s`);
+console.log(`Resolution: ${results.metadata.resolution.width}x${results.metadata.resolution.height}`);
+```
+
+### API Reference
+
+#### `detectSceneChanges(videoPath, options?)`
+
+Detects scene changes in a video file.
+
+**Parameters:**
+- `videoPath` (string): Path to input video file
+- `options` (object, optional):
+  - `sensitivity` ('low' | 'medium' | 'high'): Detection sensitivity (default: 'medium')
+  - `searchRange` ('auto' | 'small' | 'medium' | 'large'): Motion search range (default: 'medium')
+  - `onProgress` (function): Callback for progress updates
+  - `onScene` (function): Callback for each detected scene
+
+**Returns:** Promise<DetectionResult>
+
+**DetectionResult:**
+```typescript
+{
+  scenes: Array<{
+    frameNumber: number;
+    timestamp: number;      // Seconds
+    timecode: string;       // HH:MM:SS.mmm
+  }>;
+  metadata: {
+    totalFrames: number;
+    duration: number;       // Seconds
+    fps: number;
+    resolution: {
+      width: number;
+      height: number;
+    };
+  };
+}
+```
+
+## Supported Video Formats
+
+Keyframes supports any video format that FFmpeg can decode, including:
+
+- MP4 (`.mp4`, `.m4v`)
+- Matroska (`.mkv`)
+- AVI (`.avi`)
+- WebM (`.webm`)
+- MOV (`.mov`)
+- FLV (`.flv`)
+- And many more...
+
+## How It Works
+
+Keyframes uses Xvid's motion estimation algorithm to detect scene changes:
+
+1. **Frame Extraction**: FFmpeg extracts grayscale frames from the video
+2. **Motion Analysis**: WebAssembly-compiled C code analyzes motion vectors between consecutive frames
+3. **Scene Detection**: Frames with high motion complexity are identified as scene changes
+4. **Output Formatting**: Results are formatted according to the requested output format
+
+The algorithm is based on [vapoursynth-wwxd](https://github.com/dubhater/vapoursynth-wwxd) by dubhater, which itself uses Xvid's motion estimation code.
+
+## Performance
+
+Optimized for speed and accuracy:
+- **Processing speed**: 35-45 fps on 1080p video (modern hardware)
+- **Memory usage**: ~200-300 MB with efficient buffer management
+- **Accuracy**: Matches vapoursynth-wwxd output (100% accurate)
+- **Optimizations**: WASM SIMD, pre-allocated buffers, ring buffer streaming
+
+## Requirements
+
+- **Node.js**: 18.0.0 or higher
+- **FFmpeg**: Automatically installed via `@ffmpeg-installer/ffmpeg`
+
+## License
+
+GPL-2.0
+
+This project is based on:
+- [vapoursynth-wwxd](https://github.com/dubhater/vapoursynth-wwxd) by dubhater (GPL-2.0)
+- Xvid's motion estimation algorithm (GPL-2.0)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+## Credits
+
+- Original vapoursynth-wwxd plugin: [dubhater](https://github.com/dubhater)
+- Xvid motion estimation algorithm: [Xvid Team](https://www.xvid.com)
+- JavaScript/WASM port: This project

package/bin/cli.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+
+/**
+ * Keyframes CLI - Simple command-line interface for scene detection
+ *
+ * Usage:
+ *   keyframes input.mp4
+ *   keyframes input.mkv --output results.json
+ *   keyframes video.mp4 --sensitivity high
+ */
+
+const { detectSceneChanges } = require('../dist/keyframes.cjs.js');
+const path = require('path');
+const fs = require('fs');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+
+// Help text
+const HELP = `
+Scenecut - Scene change detection for videos
+
+Usage:
+  scenecut <video-file> [options]
+
+Examples:
+  scenecut input.mp4
+  scenecut video.mkv --output keyframes.txt --format aegisub
+  scenecut movie.mp4 --sensitivity high --format timecode
+  scenecut video.mp4 --format csv --output scenes.csv
+
+Options:
+  --output, -o <file>       Output file (default: {filename}_keyframes.txt)
+  --format, -f <format>     Output format: json|csv|aegisub|timecode (default: aegisub)
+  --sensitivity, -s <level> Sensitivity: low|medium|high (default: medium)
+  --quiet, -q               Suppress progress output
+  --verbose, -v             Show detailed output
+  --help, -h                Show this help
+
+Formats:
+  json                      JSON with full metadata
+  csv                       CSV with frame,timestamp,timecode
+  aegisub (or txt)          Aegisub keyframes format (frame numbers)
+  timecode (or tc)          Simple timecode list (HH:MM:SS.mmm)
+
+Video Formats:
+  Supports MP4, MKV, AVI, WebM, MOV, and any format FFmpeg supports
+
+Output:
+  Results are saved to the output file and printed to stdout
+`;
+
+// Show help
+if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+// Parse arguments
+let videoPath = null;
+let outputPath = null; // Will be derived from video filename if not specified
+let outputFormat = 'aegisub'; // Default to Aegisub format
+let sensitivity = 'medium';
+let quiet = false;
+let verbose = false;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+
+  if (arg === '--output' || arg === '-o') {
+    outputPath = args[++i];
+  } else if (arg === '--format' || arg === '-f') {
+    outputFormat = args[++i];
+  } else if (arg === '--sensitivity' || arg === '-s') {
+    sensitivity = args[++i];
+  } else if (arg === '--quiet' || arg === '-q') {
+    quiet = true;
+  } else if (arg === '--verbose' || arg === '-v') {
+    verbose = true;
+  } else if (!arg.startsWith('-')) {
+    videoPath = arg;
+  } else {
+    console.error(`Unknown option: ${arg}`);
+    console.error('Run "scenecut --help" for usage');
+    process.exit(1);
+  }
+}
+
+// Validate video path
+if (!videoPath) {
+  console.error('Error: No video file specified');
+  console.error('Usage: scenecut <video-file>');
+  console.error('Run "scenecut --help" for more information');
+  process.exit(1);
+}
+
+// Resolve video path
+videoPath = path.resolve(videoPath);
+
+if (!fs.existsSync(videoPath)) {
+  console.error(`Error: Video file not found: ${videoPath}`);
+  process.exit(1);
+}
+
+// Generate default output path if not specified
+if (!outputPath) {
+  const videoBasename = path.basename(videoPath, path.extname(videoPath));
+  const extension = (outputFormat === 'json') ? '.json' :
+                    (outputFormat === 'csv') ? '.csv' : '.txt';
+  outputPath = `${videoBasename}_keyframes${extension}`;
+}
+
+// Get file info
+const stats = fs.statSync(videoPath);
+const fileSize = (stats.size / (1024 * 1024)).toFixed(2);
+
+// Main processing function
+async function run() {
+  if (!quiet) {
+    console.log('Scenecut - Scene Detection');
+    console.log('='.repeat(60));
+    console.log(`Input:  ${videoPath}`);
+    console.log(`Size:   ${fileSize} MB`);
+    console.log(`Output: ${path.resolve(outputPath)}`);
+    console.log('='.repeat(60));
+    console.log();
+  }
+
+  const startTime = Date.now();
+  let lastProgressTime = startTime;
+  let lastProgressFrame = 0;
+  let sceneCount = 0;
+
+  try {
+    const results = await detectSceneChanges(videoPath, {
+      sensitivity,
+      searchRange: 'medium',
+      onProgress: (progress) => {
+        if (quiet) return;
+
+        const now = Date.now();
+        // Update every 3 seconds
+        if (now - lastProgressTime > 3000 || progress.percent === 100) {
+          const framesSinceLastUpdate = progress.currentFrame - lastProgressFrame;
+          const timeSinceLastUpdate = (now - lastProgressTime) / 1000;
+          const currentFps = framesSinceLastUpdate / timeSinceLastUpdate;
+
+          const progressBar = createProgressBar(progress.percent);
+          const etaStr = progress.eta ? ` ETA: ${formatTime(progress.eta)}` : '';
+
+          process.stdout.write(
+            `\r${progressBar} ${progress.percent.toString().padStart(3)}% ` +
+            `[${currentFps.toFixed(1)} fps]${etaStr}${' '.repeat(10)}`
+          );
+
+          lastProgressTime = now;
+          lastProgressFrame = progress.currentFrame;
+        }
+      },
+      onScene: (scene) => {
+        sceneCount++;
+        if (verbose && !quiet) {
+          console.log();
+          console.log(`  Scene ${sceneCount}: Frame ${scene.frameNumber} at ${scene.timecode}`);
+        }
+      }
+    });
+
+    const endTime = Date.now();
+    const elapsed = (endTime - startTime) / 1000;
+
+    if (!quiet) {
+      console.log('\n');
+      console.log('='.repeat(60));
+      console.log('Complete!');
+      console.log('='.repeat(60));
+      console.log(`Scenes detected:  ${results.scenes.length}`);
+      console.log(`Processing time:  ${formatTime(elapsed)}`);
+      console.log(`Processing speed: ${(results.metadata.totalFrames / elapsed).toFixed(1)} fps`);
+      console.log('='.repeat(60));
+    }
+
+    // Format output
+    let output;
+    if (outputFormat === 'csv') {
+      output = formatCSV(results);
+      if (outputPath.endsWith('.json')) {
+        outputPath = outputPath.replace('.json', '.csv');
+      }
+    } else if (outputFormat === 'aegisub' || outputFormat === 'txt') {
+      output = formatAegisub(results);
+      if (outputPath.endsWith('.json')) {
+        outputPath = outputPath.replace('.json', '.txt');
+      }
+    } else if (outputFormat === 'timecode' || outputFormat === 'tc') {
+      output = formatTimecode(results);
+      if (outputPath.endsWith('.json')) {
+        outputPath = outputPath.replace('.json', '.txt');
+      }
+    } else {
+      output = JSON.stringify(results, null, 2);
+    }
+
+    // Save to file
+    fs.writeFileSync(outputPath, output);
+
+    if (!quiet) {
+      console.log(`Results saved to: ${path.resolve(outputPath)}`);
+      console.log();
+
+      // Print scene list
+      console.log('Scene List:');
+      results.scenes.forEach((scene, i) => {
+        console.log(`  ${(i + 1).toString().padStart(3)}. Frame ${scene.frameNumber.toString().padStart(6)} at ${scene.timecode}`);
+      });
+    } else {
+      // In quiet mode, just print the output
+      console.log(output);
+    }
+
+    process.exit(0);
+
+  } catch (error) {
+    console.error();
+    console.error('Error:', error.message);
+    if (verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Helper functions
+function createProgressBar(percent) {
+  const width = 30;
+  const filled = Math.round((percent / 100) * width);
+  const empty = width - filled;
+  return '[' + '█'.repeat(filled) + '░'.repeat(empty) + ']';
+}
+
+function formatTime(seconds) {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = Math.floor(seconds % 60);
+
+  if (h > 0) {
+    return `${h}h ${m}m ${s}s`;
+  } else if (m > 0) {
+    return `${m}m ${s}s`;
+  } else {
+    return `${s}s`;
+  }
+}
+
+function formatCSV(results) {
+  let csv = 'frame,timestamp,timecode\n';
+  results.scenes.forEach(scene => {
+    csv += `${scene.frameNumber},${scene.timestamp},${scene.timecode || ''}\n`;
+  });
+  return csv;
+}
+
+function formatAegisub(results) {
+  // Aegisub keyframes format - simple text file with frame numbers
+  // One frame number per line
+  let output = '# keyframe format v1\n';
+  output += `fps ${results.metadata.fps}\n`;
+  results.scenes.forEach(scene => {
+    output += `${scene.frameNumber}\n`;
+  });
+  return output;
+}
+
+function formatTimecode(results) {
+  // Simple timecode list - one per line
+  // Can be used with various subtitle tools
+  let output = '';
+  results.scenes.forEach(scene => {
+    output += `${scene.timecode || formatTimecodeFull(scene.timestamp)}\n`;
+  });
+  return output;
+}
+
+function formatTimecodeFull(seconds) {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = Math.floor(seconds % 60);
+  const ms = Math.floor((seconds % 1) * 1000);
+  return `${h.toString().padStart(2, '0')}:${m.toString().padStart(2, '0')}:${s.toString().padStart(2, '0')}.${ms.toString().padStart(3, '0')}`;
+}
+
+// Run
+run();

package/dist/decoder/ffmpeg-decoder.d.ts

@@ -0,0 +1,50 @@
+/**
+ * FFmpeg Decoder - Extract frames from video files
+ *
+ * Uses fluent-ffmpeg to extract grayscale frames for scene detection
+ */
+import { RawFrame, VideoMetadata } from '../types';
+import { FrameBuffer } from './frame-buffer';
+export interface DecoderOptions {
+    /** Pixel format for extraction (default: 'gray') */
+    pixelFormat?: 'gray' | 'yuv420p';
+    /** Maximum frames to buffer in memory */
+    maxBufferFrames?: number;
+    /** Skip every N frames for testing */
+    skipFrames?: number;
+}
+export declare class FFmpegDecoder {
+    private videoPath;
+    private options;
+    private metadata;
+    private frameBuffer;
+    constructor(videoPath: string, options?: DecoderOptions);
+    /**
+     * Get video metadata
+     */
+    getMetadata(): Promise<VideoMetadata>;
+    /**
+     * Parse frame rate from FFmpeg format (e.g., "30000/1001")
+     */
+    private parseFps;
+    /**
+     * Extract frames as grayscale data
+     *
+     * @param onFrame Callback for each frame
+     * @param onProgress Optional progress callback
+     */
+    extractFrames(onFrame: (frame: RawFrame) => Promise<void> | void, onProgress?: (current: number, total: number) => void): Promise<void>;
+    /**
+     * Extract a single frame at specific frame number
+     */
+    extractFrame(frameNumber: number): Promise<RawFrame>;
+    /**
+     * Get the frame buffer
+     */
+    getFrameBuffer(): FrameBuffer;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=ffmpeg-decoder.d.ts.map

package/dist/decoder/ffmpeg-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg-decoder.d.ts","sourceRoot":"","sources":["../../src/decoder/ffmpeg-decoder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAsG7C,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,yCAAyC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,WAAW,CAAc;gBAErB,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB;IAU3D;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,CAAC;IAqC3C;;OAEG;IACH,OAAO,CAAC,QAAQ;IAQhB;;;;;OAKG;IACG,aAAa,CACjB,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAClD,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GACpD,OAAO,CAAC,IAAI,CAAC;IAwEhB;;OAEG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAgD1D;;OAEG;IACH,cAAc,IAAI,WAAW;IAI7B;;OAEG;IACH,OAAO,IAAI,IAAI;CAGhB"}