Summary

Framedex transforms scattered video archives into a portable, plain-text knowledge base. It automatically generates rich metadata sidecar files for each clip, including GPS, multilingual transcripts, face detection, and AI scene descriptions with a keep/review/cull rating. This local-first, non-destructive system enables efficient organization and querying of vast video footage.

How It Works

A pipeline processes video clips using tools like ffprobe, exiftool, ffmpeg, WhisperX, Insightface, and an AI vision model. This generates .description.md sidecar files alongside originals, preserving data integrity. Key advantages include plain-text output, proper-noun biasing for transcription accuracy, and flexible vision backends for privacy and performance.

Quick Start & Requirements

Installation involves cloning the repo into a Claude Code skills directory and running uv pip install -e .. System binaries and models are verified via python3 scripts/setup.py. Prerequisites include a Hugging Face read token for diarization and optionally an Anthropic API key for cloud vision. Users must accept terms on specific Hugging Face model pages.

Highlighted Details

• AI-Driven Metadata: Generates detailed scene descriptions, subject/action/mood analysis, and use-case suggestions with a keep/review/cull rating.
• Multilingual Support: Auto-detects languages, translates to English, and uses proper-noun biasing for accurate speech recognition.
• Local-First & Non-Destructive: Creates sidecar files next to videos; originals are untouched. Indexing is resumable.
• Flexible Vision Backends: Offers cloud (CLI, API) and fully local (LM Studio) options for AI vision processing, balancing speed, cost, and privacy.
• Companion Query Tools: Includes fdx-query, fdx-summary, and fdx-master for filtering and summarizing archives.

Maintenance & Community

Integrated as a Claude Code skill. No specific community links or detailed maintenance information are provided in the README.

Licensing & Compatibility

Released under the MIT license, permissive for commercial use and integration into closed-source projects.

Limitations & Caveats

Frame sampling is evenly-spaced, not scene-detected. Speaker diarization may degrade with background noise. WhisperX runs on CPU for Apple Silicon Macs. Face cluster IDs are temporary hashes pending a labeling tool. RAW photo support is not yet implemented. Users must accept terms for certain Hugging Face models.