reelrecon 1.2.0

package/CLAUDE.md

@@ -0,0 +1,136 @@
+# Claude Usage
+
+Use this repository to:
+
+- fetch the latest 10 videos from a public Instagram profile and transcribe them, or
+- transcribe a single direct video URL, or
+- transcribe a local uploaded audio file.
+
+There is also a local web app for interactive use and progress tracking. The frontend is a Vite React app built with shadcn/ui components and served by the FastAPI backend after build.
+There is also an MCP server so Claude or other MCP-compatible clients can operate the tool directly.
+
+AI insights are generated with GroqCloud when `GROQ_API_KEY` is available. The app falls back to local heuristic insights if Groq is unavailable.
+
+## Install
+
+Run:
+
+```bash
+python3.11 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+Optional:
+
+```bash
+cp .env.example .env.local
+```
+
+Then set `GROQ_API_KEY` in `.env.local`.
+
+Requirements:
+
+- `ffmpeg` available on `PATH`
+- network access enabled
+- public Instagram profile URL
+
+## Preferred command
+
+Use JSON mode so stdout is machine-readable:
+
+```bash
+./run_latest_reel_transcription.sh "https://www.instagram.com/<username>/" --json
+```
+
+Optional:
+
+```bash
+./run_latest_reel_transcription.sh "https://www.instagram.com/reel/<id>/" --json --model small --language en
+```
+
+## MCP
+
+Preferred command for MCP clients:
+
+```bash
+./run_mcp_server.sh
+```
+
+Or, without a local clone (Node 18+, Python 3.10+, ffmpeg required; first run provisions a Python env in `~/.reelrecon`):
+
+```bash
+npx -y reelrecon
+```
+
+This starts the server over stdio. The MCP surface exposes:
+
+- `transcribe_input`
+- `transcribe_local_audio`
+- `list_recent_batches`
+- `read_batch_manifest`
+- `read_video_output`
+- `check_health`
+
+MCP tools never raise for expected failures: every tool returns `status: "ok"` or `status: "error"` with `error_type`, `error`, and usually a `hint`. Use `check_health` to diagnose setup problems (whisper/yt-dlp/ffmpeg availability, output directory writability, job activity). Use `include_transcript_text=false` or `max_transcript_chars` to keep tool responses small; full transcripts stay on disk and behind the transcript resources. In multi-video batches a failing video is recorded with `status: "error"` and counted in `failed_videos` instead of aborting the batch. Server limits (job timeout, concurrency, upload size) are tunable via `REELRECON_*` environment variables (legacy `IG_TRANSCRIBER_*` names still work) documented in the README.
+
+Resources:
+
+- `reelrecon://server`
+- `reelrecon://recent-batches`
+- `reelrecon://manifest/{source_group}/{source_label}`
+- `reelrecon://transcript/{source_group}/{source_label}/{video_id}`
+
+If an MCP client needs HTTP instead of stdio:
+
+```bash
+./run_mcp_server.sh --transport streamable-http --host 127.0.0.1 --port 8001
+```
+
+Then connect the client to `http://127.0.0.1:8001/mcp`.
+
+## UI
+
+Start the local app:
+
+```bash
+./run_ui.sh
+```
+
+The launcher picks an open localhost port and opens the browser automatically. If needed, read the URL from terminal output.
+It also builds the frontend before starting the server.
+
+## Success contract
+
+On success, stdout is a single JSON object with:
+
+- `status`
+- `input_kind`
+- `input_url`
+- `canonical_url`
+- `total_videos`
+- `completed_videos`
+- `videos`
+- `ai_overview`
+- `manifest_file`
+
+Each item in `videos` includes transcript paths, metadata paths, detected language, and `ai_insights`.
+
+## Failure contract
+
+On failure, the command exits non-zero.
+
+If `--json` is used, stdout includes:
+
+```json
+{"status":"error","error":"..."}
+```
+
+Human-readable error details are also written to stderr.
+
+## Notes
+
+- Public profiles only.
+- Local audio uploads bypass Instagram entirely.
+- Instagram may rate-limit anonymous requests.
+- The wrapper prefers Python 3.11 when available to avoid `yt-dlp` Python 3.9 deprecation noise.
+- The wrapper prefers the repo-local `.venv` first when present.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4nw3rprod
+
+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,335 @@
+<div align="center">
+
+# 🎬 ReelRecon
+
+### Reel reconnaissance for AI agents.
+
+**Transcribe and decode any public Instagram profile — hooks, CTAs, and script patterns — locally and for free.**
+
+**Give Claude, ChatGPT, Gemini, Hermes, OpenClaw — or any MCP-capable agent — the power to watch Instagram for you.**
+
+[![Python](https://img.shields.io/badge/python-3.11+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Whisper](https://img.shields.io/badge/transcription-OpenAI%20Whisper-74aa9c?logo=openai&logoColor=white)](https://github.com/openai/whisper)
+[![MCP](https://img.shields.io/badge/protocol-MCP%20native-8A2BE2)](https://modelcontextprotocol.io/)
+[![Agents](https://img.shields.io/badge/works%20with-Claude%20·%20ChatGPT%20·%20Gemini%20·%20Hermes%20·%20OpenClaw-blueviolet)](#-drop-it-into-your-agent-stack)
+[![Price](https://img.shields.io/badge/price-free-success)](#)
+[![Privacy](https://img.shields.io/badge/runs-locally-orange)](#)
+
+*Your agent can already write scripts. Now it can study the competition first:*
+*"Transcribe @competitor's latest 10 Reels and break down their hook formulas" — one tool call away.*
+
+[🤖 Agent Setup](#-drop-it-into-your-agent-stack) · [🚀 Quick Start](#-quick-start) · [🔍 Use Cases](#-what-your-agent-can-do-with-it) · [🧰 Tool Reference](#-mcp-tool-reference) · [🖥️ Web UI](#️-the-dashboard-for-humans)
+
+<img src="screen.png" alt="ReelRecon dashboard" width="850"/>
+
+</div>
+
+---
+
+## 🎯 Why this exists
+
+LLMs can't watch video. Agentic frameworks can browse, code, and write — but a Reel is a black box to them. **ReelRecon** closes that gap with a local, free, MCP-native pipeline:
+
+1. Your agent calls one tool with a **public Instagram profile URL**.
+2. The server grabs the **latest 10 videos**, extracts audio, and transcribes every word with **OpenAI Whisper** — locally, no per-minute API fees.
+3. The agent gets back **structured JSON**: full transcripts plus mined hooks, CTAs, sentiment, keyword clusters, title ideas, and a cross-video strategy overview.
+
+Built agent-tough: structured errors instead of exceptions, progress notifications, job queueing with hard timeouts, context-window-friendly response trimming, and a `check_health` tool so your agent can self-diagnose a broken install instead of hallucinating around it.
+
+## 🤖 Drop it into your agent stack
+
+The server speaks **stdio and streamable-HTTP MCP**, so anything MCP-capable can use it. No MCP? There's a JSON-mode CLI any framework can shell out to.
+
+### ⚡ One command, no clone: `npx`
+
+With Node 18+, Python 3.10+ (3.11 recommended), and `ffmpeg` installed:
+
+```bash
+npx -y reelrecon
+```
+
+That starts the MCP server on stdio. The first run provisions a private Python environment in `~/.reelrecon` (Whisper + friends — a few minutes and a few GB, once); every start after that is instant. One-off CLI runs work too:
+
+```bash
+npx -y reelrecon transcribe "https://www.instagram.com/<username>/" --json
+```
+
+> Already have Python + deps? Set `REELRECON_PYTHON=/path/to/python` to skip provisioning and use your own environment.
+>
+> Package not on npm yet in your region/registry? Run it straight from GitHub — same launcher: `npx -y github:4nw3rprod/IG-Content-Transcriber`
+
+| Agent / Framework | Integration |
+|---|---|
+| **Claude Code** (CLI) | `claude mcp add reelrecon -- npx -y reelrecon` |
+| **Claude Desktop** | `mcpServers` entry in config |
+| **ChatGPT / Codex CLI** | `mcp_servers` entry in `~/.codex/config.toml` |
+| **Gemini CLI** | `mcpServers` entry in `~/.gemini/settings.json` |
+| **Cursor / Windsurf / Cline** | Standard MCP server config (stdio) |
+| **OpenClaw, Hermes & other open agent frameworks** | Point the framework's MCP client at `npx -y reelrecon` (stdio) or the HTTP endpoint |
+| **LangChain / CrewAI / custom loops** | Use an MCP adapter, or shell out to the CLI with `--json` |
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add reelrecon -- npx -y reelrecon
+```
+</details>
+
+<details>
+<summary><b>Claude Desktop / Cursor / most MCP clients</b></summary>
+
+```json
+{
+  "mcpServers": {
+    "reelrecon": {
+      "command": "npx",
+      "args": ["-y", "reelrecon"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>ChatGPT — Codex CLI</b> (<code>~/.codex/config.toml</code>)</summary>
+
+```toml
+[mcp_servers.reelrecon]
+command = "npx"
+args = ["-y", "reelrecon"]
+```
+</details>
+
+<details>
+<summary><b>Gemini CLI</b> (<code>~/.gemini/settings.json</code>)</summary>
+
+```json
+{
+  "mcpServers": {
+    "reelrecon": {
+      "command": "npx",
+      "args": ["-y", "reelrecon"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Running from a local clone instead of npx</b></summary>
+
+Clone the repo, install the Python deps ([Quick Start](#-quick-start)), then point your MCP client at the launcher script:
+
+```json
+{
+  "mcpServers": {
+    "reelrecon": {
+      "command": "/absolute/path/to/ReelRecon/run_mcp_server.sh"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>HTTP transport</b> (for frameworks that prefer a URL — OpenClaw, Hermes, remote setups)</summary>
+
+```bash
+./run_mcp_server.sh --transport streamable-http --host 127.0.0.1 --port 8001
+```
+
+Then point the client at `http://127.0.0.1:8001/mcp`.
+</details>
+
+<details>
+<summary><b>No MCP? Shell out to the JSON CLI</b> (LangChain, CrewAI, cron jobs, anything)</summary>
+
+```bash
+./run_latest_reel_transcription.sh "https://www.instagram.com/<username>/" --json
+```
+
+stdout is a single JSON object on success; non-zero exit + `{"status":"error","error":"..."}` on failure. Trivially parseable from any language.
+</details>
+
+**Then just prompt your agent:**
+
+> *"Use reelrecon to transcribe the latest Reels from @competitor. Compare their hooks against my last 5 scripts and tell me what patterns I'm missing."*
+
+## 🔍 What your agent can do with it
+
+Point any LLM at the structured output and competitive content research becomes a conversation:
+
+- **🪝 Hook mining** — the opening line of a competitor's last 10 videos, side by side. Your agent extracts the formula.
+- **📣 CTA patterns** — every "follow / comment / link in bio / DM me" detected and counted per batch.
+- **🧬 Script structure** — full transcripts expose pacing: hook → context → payoff → CTA. Steal the skeleton, not the words.
+- **🔑 Topic clusters** — recurring keywords across recent videos = a creator's actual content pillars.
+- **📈 Trend triangulation** — run 3–5 competitors and let the LLM diff what they're all suddenly talking about.
+- **♻️ Repurposing engine** — each video ships with ready-made content angles and title suggestions for your own spin.
+- **🕵️ Scheduled watching** — pair with your agent's cron/loop feature: "check these 3 profiles every morning and brief me."
+
+> **Fair use, please:** public profiles only (private accounts are detected and refused), and it's built for research and inspiration — study patterns, don't plagiarize scripts. Instagram may rate-limit anonymous requests; be a good citizen.
+
+## ⚙️ How it works
+
+```mermaid
+flowchart LR
+    A["🤖 Agent / LLM<br/>MCP tool call"] --> B["📱 Public IG profile<br/>latest 10 videos"]
+    A --> C["🔗 Single video URL"]
+    A --> D["🎙️ Local audio file"]
+    B --> E["⬇️ yt-dlp<br/>audio extraction"]
+    C --> E
+    D --> F
+    E --> F["📝 Whisper<br/>local transcription"]
+    F --> G["🧠 AI insights<br/>hooks · CTAs · keywords"]
+    G --> H["📦 Structured JSON<br/>back to the agent"]
+```
+
+## 🚀 Quick Start
+
+**Fastest path (no clone):** `npx -y reelrecon` — see [agent setup](#-drop-it-into-your-agent-stack) above.
+
+**Manual setup — requirements:** Python 3.11+, `ffmpeg` on your PATH, network access.
+
+```bash
+git clone https://github.com/4nw3rprod/ReelRecon.git
+cd ReelRecon
+python3.11 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+Optional (Groq-powered insights instead of the built-in heuristics):
+
+```bash
+cp .env.example .env.local   # then set GROQ_API_KEY
+```
+
+Connect your agent ([see configs above](#-drop-it-into-your-agent-stack)), or run it by hand:
+
+```bash
+# A competitor's latest 10 videos
+./run_latest_reel_transcription.sh "https://www.instagram.com/nike/" --json
+
+# A single Reel, with model + language hints
+./run_latest_reel_transcription.sh "https://www.instagram.com/reel/<id>/" --json --model small --language en
+```
+
+## 🧰 MCP tool reference
+
+| Tool | What it does |
+|---|---|
+| `transcribe_input` | Profile URL → latest 10 videos, or any single video URL yt-dlp supports |
+| `transcribe_local_audio` | Transcribe a local audio file + generate insights |
+| `list_recent_batches` | Browse saved runs |
+| `read_batch_manifest` | Load a full batch result |
+| `read_video_output` | Load one video's transcript + metadata |
+| `check_health` | Self-diagnose ffmpeg/Whisper/yt-dlp, disk, and job status |
+
+Resources: `reelrecon://server` · `reelrecon://recent-batches` · `reelrecon://manifest/{group}/{label}` · `reelrecon://transcript/{group}/{label}/{video_id}`
+
+**The contract your agent can rely on:**
+
+- Tools **never raise** for expected failures — every call returns `status: "ok"` or a structured error: `error_type` (`invalid_input`, `not_found`, `pipeline_error`, `dependency_error`, `server_busy`, `timeout`, …), a message, and a `hint` the agent can act on.
+- **Progress streams** as MCP notifications during long batches.
+- **Context-window friendly:** `include_transcript_text=false` or `max_transcript_chars=N` trims responses; full transcripts always stay on disk and behind resources.
+- **Partial success:** in a 10-video batch, one broken video is recorded (`failed_videos`) instead of sinking the other nine.
+- Jobs are **queued with hard timeouts**; limits are env-tunable (below).
+
+## 📦 What comes out
+
+```text
+outputs/
+└── instagram_profiles/
+    └── nike/
+        ├── manifest.json          ← batch result + AI overview
+        └── <video_id>/
+            ├── audio.mp3
+            ├── transcript.txt     ← the gold
+            └── metadata.json      ← caption, timestamps, insights
+```
+
+```jsonc
+{
+  "status": "ok",
+  "input_kind": "instagram_profile",
+  "total_videos": 10,
+  "completed_videos": 10,
+  "videos": [
+    {
+      "title": "You don't need motivation…",
+      "transcript_text": "...",
+      "ai_insights": {
+        "hook": "You don't need motivation, you need a system.",
+        "cta": "follow",
+        "sentiment": "positive",
+        "keywords": ["system", "habits", "training"],
+        "title_suggestions": ["..."],
+        "content_angles": ["..."]
+      }
+    }
+  ],
+  "ai_overview": {
+    "recurring_keywords": ["..."],
+    "top_hooks": ["..."],
+    "cta_patterns": [["follow", 6], ["link in bio", 3]]
+  },
+  "manifest_file": "outputs/instagram_profiles/nike/manifest.json"
+}
+```
+
+## 🖥️ The Dashboard (for humans)
+
+Agents get MCP; you get a live dashboard:
+
+```bash
+./run_ui.sh
+```
+
+Builds the frontend, picks an open localhost port, opens your browser. Paste a profile/Reel URL **or upload audio** (`mp3`, `wav`, `m4a`, `aac`, `flac`, `ogg`, `webm`), pick the Whisper model, watch live progress through every pipeline stage, and browse transcript + insight history.
+
+## 🎛️ Tuning
+
+All optional, via environment variables:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `GROQ_API_KEY` | — | Enables GroqCloud AI insights (heuristic fallback otherwise) |
+| `REELRECON_OUTPUT_DIR` | `<repo>/outputs` | Where results are written |
+| `REELRECON_JOB_TIMEOUT_SECONDS` | `3600` | Hard per-job timeout (MCP) |
+| `REELRECON_QUEUE_TIMEOUT_SECONDS` | `900` | Max wait for a job slot (MCP) |
+| `REELRECON_MAX_CONCURRENT_JOBS` | `1` | Parallel transcription jobs (MCP) |
+| `REELRECON_MAX_UPLOAD_BYTES` | 2 GiB | Max local audio file size (MCP) |
+| `REELRECON_EXTRA_MODELS` | — | Comma-separated extra Whisper model names to allow |
+| `REELRECON_HTTP_TIMEOUT_SECONDS` | `30` | Instagram/Groq/yt-dlp socket timeout |
+| `REELRECON_FETCH_RETRIES` | `3` | Instagram profile fetch attempts (with backoff) |
+
+> Legacy `IG_TRANSCRIBER_*` variable names are still honored, so existing setups keep working.
+
+**Whisper model cheat sheet:** `tiny` = fastest, `base` = default sweet spot, `small`/`medium` = better accuracy, `large-v3` = best (needs RAM/time).
+
+## ✅ Tests
+
+The MCP server and pipeline helpers ship with a lightweight suite (no Whisper/torch download needed):
+
+```bash
+.venv/bin/pip install pytest
+.venv/bin/python -m pytest tests/ -q
+```
+
+## 📝 Good to know
+
+- **Public profiles only** — private accounts are detected and refused.
+- Instagram may rate-limit anonymous requests; the tool retries with backoff, but if it's blocked, wait and rerun.
+- Whisper models are cached after first load; already-transcribed videos are reused on reruns.
+- Everything runs locally. The only network calls are to Instagram/video hosts, and (optionally) GroqCloud with your key.
+- Agent-facing docs live in [`CLAUDE.md`](CLAUDE.md) — most MCP-aware coding agents pick it up automatically.
+
+---
+
+<div align="center">
+
+**Wiring this into your agent? ⭐ Star the repo — it's free and it helps others find it.**
+
+*Built with Whisper, yt-dlp, FastAPI, React + shadcn/ui, and the Model Context Protocol.*
+
+</div>

package/bin/reelrecon.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * ReelRecon npx launcher.
+ *
+ * Finds a suitable Python, provisions a private virtualenv under
+ * ~/.reelrecon on first run, then hands stdio over to the Python MCP
+ * server (or the transcribe CLI). Everything the launcher prints goes
+ * to stderr: when an MCP client spawns us, stdout belongs to the
+ * protocol and must stay clean.
+ *
+ * Environment:
+ *   REELRECON_HOME    where the venv lives (default: ~/.reelrecon)
+ *   REELRECON_PYTHON  bring-your-own interpreter with deps already
+ *                     installed; skips venv provisioning entirely
+ */
+
+const { spawn, spawnSync } = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const MIN_PYTHON = [3, 10];
+const PREFERRED_PYTHONS = ['python3.11', 'python3.12', 'python3.13', 'python3.10', 'python3', 'python'];
+
+const packageRoot = path.resolve(__dirname, '..');
+const requirementsFile = path.join(packageRoot, 'requirements.txt');
+const isWindows = process.platform === 'win32';
+
+function log(message) {
+  process.stderr.write(`[reelrecon] ${message}\n`);
+}
+
+function fail(message) {
+  log(`ERROR: ${message}`);
+  process.exit(1);
+}
+
+function pythonVersion(command) {
+  const result = spawnSync(command, ['-c', 'import sys; print("%d.%d" % sys.version_info[:2])'], {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  if (result.status !== 0 || !result.stdout) {
+    return null;
+  }
+  const [major, minor] = result.stdout.trim().split('.').map(Number);
+  if (!Number.isInteger(major) || !Number.isInteger(minor)) {
+    return null;
+  }
+  return [major, minor];
+}
+
+function versionOk(version) {
+  if (!version) return false;
+  const [major, minor] = version;
+  return major === MIN_PYTHON[0] && minor >= MIN_PYTHON[1];
+}
+
+function findSystemPython() {
+  for (const candidate of PREFERRED_PYTHONS) {
+    if (versionOk(pythonVersion(candidate))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function venvPythonPath(venvDir) {
+  return isWindows ? path.join(venvDir, 'Scripts', 'python.exe') : path.join(venvDir, 'bin', 'python');
+}
+
+function installMarker(home) {
+  return path.join(home, '.install-marker');
+}
+
+function desiredMarker(basePython) {
+  const requirements = fs.readFileSync(requirementsFile, 'utf-8');
+  const version = pythonVersion(basePython) || [];
+  return crypto.createHash('sha256').update(`${version.join('.')}\n${requirements}`).digest('hex');
+}
+
+function run(command, args, description) {
+  // stdout is routed to stderr (fd 2): pip and venv chatter must never
+  // reach our stdout, which belongs to the MCP stdio framing.
+  const result = spawnSync(command, args, { stdio: ['ignore', 2, 2] });
+  if (result.error) {
+    fail(`${description} failed to start: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    fail(`${description} failed with exit code ${result.status}.`);
+  }
+}
+
+function ensureVenv() {
+  const home = process.env.REELRECON_HOME || path.join(os.homedir(), '.reelrecon');
+  const venvDir = path.join(home, 'venv');
+  const venvPython = venvPythonPath(venvDir);
+
+  const basePython = findSystemPython();
+  if (!basePython) {
+    fail(
+      `No suitable Python found. ReelRecon needs Python >= ${MIN_PYTHON.join('.')} (3.11 recommended). ` +
+        'Install it, or point REELRECON_PYTHON at an interpreter that already has the dependencies.'
+    );
+  }
+
+  const marker = desiredMarker(basePython);
+  const markerFile = installMarker(home);
+  if (fs.existsSync(venvPython) && fs.existsSync(markerFile) && fs.readFileSync(markerFile, 'utf-8') === marker) {
+    return venvPython;
+  }
+
+  log(`Setting up the ReelRecon Python environment in ${venvDir}`);
+  log('First run downloads Whisper/torch and friends — this can take a few minutes and a few GB.');
+  fs.mkdirSync(home, { recursive: true });
+  run(basePython, ['-m', 'venv', '--clear', venvDir], 'Creating the virtualenv');
+  run(venvPython, ['-m', 'pip', 'install', '--upgrade', 'pip', '--quiet'], 'Upgrading pip');
+  run(venvPython, ['-m', 'pip', 'install', '-r', requirementsFile], 'Installing Python dependencies');
+  fs.writeFileSync(markerFile, marker);
+  log('Environment ready.');
+  return venvPython;
+}
+
+function resolvePython() {
+  const custom = process.env.REELRECON_PYTHON;
+  if (custom) {
+    if (!versionOk(pythonVersion(custom))) {
+      fail(`REELRECON_PYTHON (${custom}) is not a working Python >= ${MIN_PYTHON.join('.')}.`);
+    }
+    return custom;
+  }
+  return ensureVenv();
+}
+
+function warnIfNoFfmpeg() {
+  const probe = spawnSync('ffmpeg', ['-version'], { stdio: 'ignore' });
+  if (probe.error || probe.status !== 0) {
+    log('WARNING: ffmpeg was not found on PATH. Transcription will fail until it is installed.');
+    log('         Install it with e.g. `apt install ffmpeg` or `brew install ffmpeg`.');
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  let script = path.join(packageRoot, 'mcp_server.py');
+  let scriptArgs = args;
+  if (args[0] === 'transcribe') {
+    script = path.join(packageRoot, 'transcribe_latest_reel.py');
+    scriptArgs = args.slice(1);
+  } else if (args[0] === '--version') {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+    process.stdout.write(`${pkg.version}\n`);
+    return;
+  }
+
+  const python = resolvePython();
+  warnIfNoFfmpeg();
+
+  const child = spawn(python, [script, ...scriptArgs], {
+    stdio: 'inherit',
+    env: { ...process.env, PYTHONUNBUFFERED: '1' },
+  });
+
+  const forward = (signal) => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  };
+  process.on('SIGINT', () => forward('SIGINT'));
+  process.on('SIGTERM', () => forward('SIGTERM'));
+
+  child.on('error', (error) => fail(`Failed to start Python: ${error.message}`));
+  child.on('exit', (code, signal) => {
+    process.exit(signal ? 1 : code ?? 0);
+  });
+}
+
+main();

package/ig_transcriber/__init__.py

@@ -0,0 +1,3 @@
+from .pipeline import PipelineError, run_audio_file_transcription, run_transcription
+
+__all__ = ["PipelineError", "run_transcription", "run_audio_file_transcription"]