Metadata-Version: 2.4
Name: reel-scout
Version: 1.2.0
Summary: Short-form video analysis tool — crawl, transcribe, and visually analyze YouTube Shorts, Instagram Reels, and TikTok
Project-URL: Homepage, https://github.com/vulture-s/reel-scout
Project-URL: Repository, https://github.com/vulture-s/reel-scout
Project-URL: Issues, https://github.com/vulture-s/reel-scout/issues
Project-URL: Changelog, https://github.com/vulture-s/reel-scout/blob/master/CHANGELOG.md
Author: Hevin Yeh (vulture.s)
License-Expression: MIT
License-File: LICENSE
Keywords: analysis,reels,shorts,tiktok,video,vlm,whisper
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: yt-dlp>=2024.1.0
Provides-Extra: audio
Requires-Dist: numpy>=1.21.0; extra == 'audio'
Requires-Dist: onnxruntime>=1.15.0; extra == 'audio'
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: diarize
Requires-Dist: pyannote-audio>=3.1; extra == 'diarize'
Requires-Dist: torch>=2.0; extra == 'diarize'
Provides-Extra: instagram
Requires-Dist: instaloader>=4.10; extra == 'instagram'
Provides-Extra: ocr
Requires-Dist: pillow>=9.0; extra == 'ocr'
Requires-Dist: pytesseract>=0.3.10; extra == 'ocr'
Provides-Extra: vector
Requires-Dist: chromadb>=0.4.0; extra == 'vector'
Requires-Dist: lancedb>=0.4.0; extra == 'vector'
Provides-Extra: whisper
Requires-Dist: faster-whisper>=1.1.0; extra == 'whisper'
Description-Content-Type: text/markdown

# Reel Scout

> English ｜ [繁體中文](README.zh.md)

Short-form video analysis CLI tool.

Crawl, transcribe, and visually analyze YouTube Shorts, Instagram Reels, and TikTok videos into structured data.

## Install

```bash
pip install -e .
pip install -e ".[whisper]"  # for faster-whisper transcription
```

## Usage

```bash
reel-scout crawl "https://youtube.com/shorts/xxxxx"
reel-scout analyze "https://youtube.com/shorts/xxxxx"
reel-scout analyze --file urls.txt --skip-vision
reel-scout list
reel-scout show <video_id>
reel-scout inspect <video_id>          # interactive single-clip inspector web app
reel-scout export --format json -o ./export
reel-scout config check
```

`inspect` starts a small local web app for one clip and opens it in the browser.
The **video player is the single source of truth**: a **waveform** (ffmpeg peaks,
cached) with a click-to-seek playhead, a **keyframe filmstrip**, and the
**transcript** all seek the player and highlight as it plays. Set **IN/OUT**
markers on the waveform and export the trimmed window as SRT. Needs the downloaded
video file on disk. (Design ported from arkiv's live inspector.) `export --format
html` remains the offline multi-clip bundle; `view` is the read-only browsing
server.

## Bilingual / code-switching audio (中英對照)

Whisper `large-v3` locks onto the language it detects in the opening window and, on
long files, "translates" later speech of the *other* language back into the locked
one — a code-switching interview (Chinese host + English guest) comes out with the
guest's English mangled into garbled Chinese. It is a long-form drift, not a bad
audio issue: the same passage transcribes perfectly when sliced out on its own.

Fix — force per-chunk language re-detection:

```bash
WHISPER_MULTILINGUAL=1 WHISPER_CHUNK_LENGTH=15 reel-scout analyze "<url>"
```

`multilingual` alone is not enough — it needs a short `chunk_length` (~15s) so each
chunk re-detects. Verified on a 40-min ZH-host/EN-guest interview: latin-char
recovery 56% → 90%. Leave OFF for single-language short-form (per-chunk detection
adds cost). Other levers: `WHISPER_LANGUAGE=en` (force one language),
`WHISPER_TASK=translate` (force English output).

## MCP Server

```bash
reel-scout-mcp  # stdio transport for Claude Code integration
```

## Prompt Pack (analysis layer)

Reel Scout's pipeline gets clean input into a model. The **reverse-decode prompt
pack** in [`prompts/`](./prompts/) is the analysis brain you point at that input —
to reverse-engineer *why* a short-form video works and extract a transferable
structure, with anti-hallucination guardrails (observation vs. inference, cite the
timestamp). Open (MIT). See [`prompts/README.md`](./prompts/README.md).

## Requirements

- Python 3.9+
- ffmpeg
- yt-dlp

## Attribution

Video extraction techniques (captions-first transcription, duration-aware frame
budgeting, time-range focus, on-screen-text resolution bump) are adapted from
[claude-video](https://github.com/bradautomates/claude-video) (MIT). See [`NOTICE`](./NOTICE).
