vidclaude 0.2.0 → 0.2.2

package/bin/setup.js

@@ -1,45 +1,44 @@
-#!/usr/bin/env node
-
-const { execSync } = require("child_process");
-const fs = require("fs");
-const path = require("path");
-
-const reqPath = path.join(__dirname, "..", "requirements.txt");
-
-console.log("vidclaude: Installing Python dependencies...");
-
-// Check Python exists
-try {
-  execSync("python --version", { stdio: "pipe" });
-} catch {
-  console.warn(
-    "\n⚠ Python not found. You need Python 3.10+ to use vidclaude.\n" +
-      "  Install from: https://python.org\n" +
-      "  Then run: pip install -r requirements.txt\n"
-  );
-  process.exit(0); // Don't fail npm install
-}
-
-// Check ffmpeg exists
-try {
-  execSync("ffmpeg -version", { stdio: "pipe" });
-} catch {
-  console.warn(
-    "\n⚠ ffmpeg not found. You need ffmpeg to use vidclaude.\n" +
-      "  Windows: winget install ffmpeg\n" +
-      "  macOS:   brew install ffmpeg\n" +
-      "  Linux:   sudo apt install ffmpeg\n"
-  );
-}
-
-// Install Python deps
-try {
-  execSync(`pip install -r "${reqPath}"`, { stdio: "inherit" });
-  console.log("\nvidclaude: Setup complete!");
-  console.log("  Run: npx vidclaude video.mp4 --extract --mode standard --verbose\n");
-} catch {
-  console.warn(
-    "\n⚠ Failed to install Python dependencies.\n" +
-      "  Try manually: pip install -r requirements.txt\n"
-  );
-}
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+const path = require("path");
+
+const reqPath = path.join(__dirname, "..", "requirements.txt");
+
+console.log("vidclaude: Installing Python dependencies...");
+
+// Check Python exists
+try {
+  execSync("python --version", { stdio: "pipe" });
+} catch {
+  console.warn(
+    "\nPython not found. You need Python 3.10+ to use vidclaude.\n" +
+      "  Install from: https://python.org\n" +
+      "  Then run: pip install -r requirements.txt\n"
+  );
+  process.exit(0); // Don't fail npm install
+}
+
+// Check ffmpeg exists
+try {
+  execSync("ffmpeg -version", { stdio: "pipe" });
+} catch {
+  console.warn(
+    "\nffmpeg not found. You need ffmpeg to use vidclaude.\n" +
+      "  Windows: winget install ffmpeg\n" +
+      "  macOS:   brew install ffmpeg\n" +
+      "  Linux:   sudo apt install ffmpeg\n"
+  );
+}
+
+// Install Python deps
+try {
+  execSync(`pip install -r "${reqPath}"`, { stdio: "inherit" });
+  console.log("\nvidclaude: Setup complete!");
+  console.log("  Run: npx vidclaude video.mp4 --extract --mode standard --verbose\n");
+} catch {
+  console.warn(
+    "\nFailed to install Python dependencies.\n" +
+      "  Try manually: pip install -r requirements.txt\n"
+  );
+}

package/bin/vidclaude.js

@@ -1,27 +1,27 @@
-#!/usr/bin/env node
-
-const { spawn } = require("child_process");
-const path = require("path");
-
-const scriptPath = path.join(__dirname, "..", "video_understand.py");
-const args = process.argv.slice(2);
-
-// Pass all arguments through to the Python script
-const proc = spawn("python", [scriptPath, ...args], {
-  stdio: "inherit",
-});
-
-proc.on("error", (err) => {
-  if (err.code === "ENOENT") {
-    console.error(
-      "Error: Python not found. Install Python 3.10+ from https://python.org"
-    );
-    process.exit(1);
-  }
-  console.error(`Error: ${err.message}`);
-  process.exit(1);
-});
-
-proc.on("close", (code) => {
-  process.exit(code || 0);
-});
+#!/usr/bin/env node
+
+const { spawn } = require("child_process");
+const path = require("path");
+
+const scriptPath = path.join(__dirname, "..", "video_understand.py");
+const args = process.argv.slice(2);
+
+// Pass all arguments through to the Python script
+const proc = spawn("python", [scriptPath, ...args], {
+  stdio: "inherit",
+});
+
+proc.on("error", (err) => {
+  if (err.code === "ENOENT") {
+    console.error(
+      "Error: Python not found. Install Python 3.10+ from https://python.org"
+    );
+    process.exit(1);
+  }
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});
+
+proc.on("close", (code) => {
+  process.exit(code || 0);
+});

package/npm-README.md

@@ -0,0 +1,117 @@
+# vidclaude
+
+Multimodal video understanding for Claude Code. Extract frames, transcribe audio in 90+ languages, build temporal timelines — all from a single command. No API key needed.
+
+```bash
+npm install -g vidclaude
+vidclaude video.mp4 --mode standard --verbose
+```
+
+## Prerequisites
+
+- **Python 3.10+** — [python.org](https://python.org)
+- **ffmpeg** — Windows: `winget install ffmpeg` / macOS: `brew install ffmpeg` / Linux: `sudo apt install ffmpeg`
+
+Python dependencies (Pillow, faster-whisper) are installed automatically during `npm install`.
+
+## Install
+
+```bash
+npm install -g vidclaude
+```
+
+Or use without installing:
+
+```bash
+npx vidclaude video.mp4 --mode standard --verbose
+```
+
+## Usage
+
+### With Claude Code (recommended, no API key needed)
+
+```bash
+# Set up the skill in your project (one time)
+vidclaude --install-skill
+
+# Then in Claude Code, just say:
+# "analyze the video at path/to/video.mp4"
+# "what does the speaker say about the budget?"
+# "when does the chart appear on screen?"
+```
+
+Your Max/Pro plan covers everything. Follow-up questions are instant (cached).
+
+### Standalone CLI
+
+```bash
+# Standard analysis
+vidclaude video.mp4 --mode standard --verbose
+
+# Quick (fewer frames, faster)
+vidclaude video.mp4 --mode quick
+
+# Deep (dense frames, full OCR)
+vidclaude video.mp4 --mode deep --verbose
+
+# Batch process a folder
+vidclaude ./videos/ --verbose
+
+# Skip audio / force fresh extraction
+vidclaude video.mp4 --no-audio --no-cache
+```
+
+## Modes
+
+| Mode | Frames | Whisper model | Best for |
+|------|--------|---------------|----------|
+| `quick` | ~20 | base | Short clips, fast overview |
+| `standard` | ~60, shot-aware | large-v3 | General use |
+| `deep` | ~150, burst sampling | large-v3 | Long videos, detailed review |
+
+## What it extracts
+
+Every run creates a `.vidcache/` directory:
+
+```
+.vidcache/<hash>/
+  evidence.md        ← Report for Claude to read
+  frames/            ← Extracted JPEG frames
+  transcript.json    ← Timestamped speech (90+ languages)
+  timeline.json      ← Unified event timeline
+  meta.json          ← Video metadata
+```
+
+## How it works
+
+1. **Frames** — Adaptive sampling with shot boundary detection via ffmpeg
+2. **Audio** — faster-whisper large-v3 transcription with auto language detection
+3. **OCR** — On-screen text extraction via pytesseract (optional)
+4. **Timeline** — Merges all modalities into a time-sorted event list
+5. **Evidence** — Generates `evidence.md` that Claude reads and reasons over
+
+## CLI Reference
+
+```
+vidclaude [input] [options]
+
+  --install-skill               Set up Claude Code skill
+  --mode {quick,standard,deep}  Processing mode (default: standard)
+  -f, --fps N                   Override frames per second
+  -m, --max-frames N            Override max frame count
+  --no-audio                    Skip transcription
+  --no-ocr                      Skip OCR
+  --no-cache                    Force re-extraction
+  --verbose                     Show progress
+  -o FILE                       Write output to file
+```
+
+## Also available via pip
+
+```bash
+pip install vidclaude
+```
+
+## License
+
+MIT

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "vidclaude",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Multimodal video understanding for Claude Code — extract frames, transcribe audio, build timelines from any video",
   "bin": {
     "vidclaude": "./bin/vidclaude.js"
   },
+  "readme": "npm-README.md",
   "files": [
     "bin/",
     "vidclaude/",
     "video_understand.py",
     "requirements.txt",
     "SKILL.md",
-    "README.md"
+    "npm-README.md"
   ],
   "scripts": {
     "postinstall": "node ./bin/setup.js"