{"id":49474008,"url":"https://github.com/aydrian/broll-organizer","last_synced_at":"2026-04-30T18:04:27.141Z","repository":{"id":338724424,"uuid":"1158838185","full_name":"aydrian/broll-organizer","owner":"aydrian","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-05T17:20:58.000Z","size":251,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-05T17:25:14.238Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aydrian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-16T01:20:05.000Z","updated_at":"2026-04-05T17:21:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aydrian/broll-organizer","commit_stats":null,"previous_names":["aydrian/broll-organizer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aydrian/broll-organizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aydrian%2Fbroll-organizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aydrian%2Fbroll-organizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aydrian%2Fbroll-organizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aydrian%2Fbroll-organizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aydrian","download_url":"https://codeload.github.com/aydrian/broll-organizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aydrian%2Fbroll-organizer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32472423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-30T18:04:26.233Z","updated_at":"2026-04-30T18:04:27.135Z","avatar_url":"https://github.com/aydrian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎬 B-Roll Organizer\n\nAI-powered b-roll organizer using **Fireworks AI** for vision analysis (with Ollama for local embeddings and whisper.cpp for transcription).\n\n## Overview\n\n`broll-organizer` is an AI-powered video cataloging tool designed to organize and search large collections of b-roll footage stored on external drives. It uses Large Language Models (LLMs) to automatically analyze, tag, and describe video clips, making them searchable through natural language—including **spoken content** via audio transcription.\n\nThe project has two main interfaces:\n1.  A **Command-Line Interface (CLI)** for initializing the catalog, processing videos, and performing searches.\n2.  A **Web Interface (Flask)** for visually browsing the catalog, searching for clips, and viewing video details.\n\nAn **OpenClaw Agent API** is also available for programmatic access by AI assistants.\n\n## Key Technologies\n\n*   **Backend:** Python 3.12+ with **asyncio** for parallel processing\n*   **CLI:** `click`\n*   **Web Framework:** `flask`\n*   **Video Processing:** `ffmpeg` (subprocess)\n*   **Image Processing:** `pillow`\n*   **Database:** SQLite with FTS5 (keyword search) + `sqlite-vec` (semantic search)\n*   **AI/ML:**\n    *   **Vision Analysis:** [Fireworks AI](https://fireworks.ai/) `kimi-k2p5-turbo` (multimodal) - scene descriptions and tags\n    *   **Embeddings:** [Ollama](https://ollama.com/) `nomic-embed-text` (local, default) or Fireworks - semantic search\n    *   **Transcription:** [whisper.cpp](https://github.com/ggerganov/whisper.cpp) (local) - audio-to-text for spoken content search\n*   **Folder-based location:** Since devices like Osmo Pocket 3 don't encode GPS, location is inferred from folder names.\n\n## AI Provider Setup\n\nThe application uses a **hybrid approach** to maximize speed while preserving API quotas:\n\n| Task | Default Provider | Reason |\n|------|-----------------|--------|\n| Vision Analysis | **Fireworks AI** | Kimi K2.5 Turbo - high-quality scene analysis (core value) |\n| Embeddings | **Ollama (local)** | nomic-embed-text - runs fast locally, high volume |\n| Transcription | **whisper.cpp (local)** | Runs entirely offline - no API usage |\n\n### Required Setup\n\n#### 1. Fireworks AI (Vision Analysis)\n\nSet your Fireworks API key for vision analysis. You can either:\n\n**A. Use a `.env` file (recommended):**\n```bash\ncp .env.example .env\n# Edit .env and add your key:\nFIREWORKS_API_KEY=your-api-key-here\n```\n\n**B. Set environment variable:**\n```bash\nexport FIREWORKS_API_KEY=\"your-api-key-here\"\n```\n\n#### 2. Ollama (Embeddings - Local, Required)\n\nEmbeddings default to local Ollama to preserve Fireworks quota for vision tasks:\n\n1.  **Install Ollama:** Download via [ollama.com](https://ollama.com/)\n2.  **Pull the embedding model:**\n    ```bash\n    ollama pull nomic-embed-text  # Required for semantic search\n    ```\n\n#### 3. whisper.cpp (Transcription - Optional)\n\nFor audio transcription (enables search of spoken content):\n\n**macOS (Apple Silicon with Metal GPU):**\n```bash\n# Install via Homebrew\nbrew install whisper.cpp\n\n# Download model (small is fast with Metal GPU)\nwhisper-cli --model small --download-model\n```\n\n**Linux (x86_64 or ARM64 like Raspberry Pi):**\n```bash\n# Build from source\ngit clone https://github.com/ggerganov/whisper.cpp.git\ncd whisper.cpp\nmake\n\n# Download appropriate model\n# For Raspberry Pi 5 (ARM64): use 'tiny' (39MB)\n./models/download-ggml-model.sh tiny\n\n# For desktop x86_64: use 'base' (74MB)\n./models/download-ggml-model.sh base\n```\n\nThe application auto-detects your platform and selects the optimal model:\n- **macOS Metal (M1/M2/M3):** `small` model (~2-4x real-time speed)\n- **Linux x86_64:** `base` model (~0.5-1x real-time speed)\n- **Linux ARM64 (Raspberry Pi 5):** `tiny` model (~0.1-0.3x real-time speed)\n\n## Installation\n\nThis project is managed with [`uv`](https://github.com/astral-sh/uv).\n\n```bash\n# Install dependencies\nuv sync\n\n# Run the app\nuv run broll --help\n```\n\n## Getting Started\n\nThe application is designed to be run directly on a host machine with access to an external drive containing video files.\n\n### 1. Initialize the Catalog\nCreate the database and folder structure on the target drive.\n```bash\nuv run broll init /path/to/your/external-drive\n```\n\n### 2. Process Videos\nScan the drive to find new videos, extract metadata, analyze them with the LLM, and add them to the catalog. Processing now runs **in parallel** with a default concurrency of 5 videos.\n```bash\nuv run broll process /path/to/your/external-drive\n```\n*   Use `--scan-only` to quickly catalog files by metadata without running the slower LLM analysis.\n*   Use `--force` to re-process all videos, even if they are already in the catalog.\n*   Use `--concurrency N` to adjust parallel processing (default: 5).\n*   Use `--no-transcribe` to skip audio transcription if whisper.cpp is installed but you want faster processing.\n\n## Usage\n\n### CLI\n\n*   **Process Videos:** Scan, analyze, and catalog videos with **parallel processing** and optional **audio transcription**.\n    ```bash\n    # Process with default settings (concurrency=5, transcribe enabled)\n    uv run broll process /path/to/drive\n\n    # Adjust parallel processing\n    uv run broll process /path/to/drive --concurrency 10\n\n    # Skip transcription for faster processing\n    uv run broll process /path/to/drive --no-transcribe\n    ```\n\n*   **Transcribe (Retroactive):** Add audio transcription to previously processed videos.\n    ```bash\n    # Transcribe all videos missing transcripts\n    uv run broll transcribe /path/to/drive\n\n    # Transcribe specific video by ID\n    uv run broll transcribe /path/to/drive --video-id 123\n\n    # Force re-transcribe all videos\n    uv run broll transcribe /path/to/drive --force\n    ```\n\n*   **Search:** Find videos using natural language (including **spoken content** from transcripts).\n    ```bash\n    uv run broll search \"a slow-motion shot of a waterfall at sunset\" --drive /path/to/drive\n\n    # Search for spoken content\n    uv run broll search \"interview about climate change\" --drive /path/to/drive\n    ```\n    You can specify different search modes: `hybrid` (default), `keyword`, or `semantic`.\n\n*   **Statistics:** View stats about the catalog.\n    ```bash\n    uv run broll stats /path/to/drive\n    ```\n\n*   **OpenClaw Agent Mode:** Launch the agent API for AI assistant integration.\n    ```bash\n    uv run broll agent /path/to/drive\n    ```\n    The agent API will be available at `http://127.0.0.1:5556`.\n\n### Web UI\n\n*   Launch the web interface to browse and search the catalog visually.\n    ```bash\n    uv run broll web /path/to/drive\n    ```\n    The web UI will be available at `http://127.0.0.1:5555` by default.\n\n## OpenClaw Skill\n\nThis repo includes an OpenClaw skill for easy AI assistant integration:\n\n```bash\n# Install the skill via npx\nnpx openclaw skills add aydrian/broll-organizer/skills/broll-catalog\n```\n\nOnce installed, OpenClaw agents can query your B-roll catalog directly:\n- Search by keyword, location, mood\n- Get video details and thumbnails\n- Find clips for content creation\n\nSee [skills/broll-catalog/SKILL.md](skills/broll-catalog/SKILL.md) for details.\n\n## Configuration\n\nEnvironment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `FIREWORKS_API_KEY` | Your Fireworks API key (required for vision analysis) | (none) |\n| `VISION_PROVIDER` | Provider for vision analysis: `fireworks` or `ollama` | `fireworks` |\n| `EMBEDDING_PROVIDER` | Provider for embeddings: `fireworks` or `ollama` | `ollama` (local) |\n| `BROLL_WHISPER_MODEL` | Override whisper.cpp model (tiny, base, small, medium) | `auto` (platform-optimized) |\n| `WHISPER_CPP_PATH` | Path to whisper-cli executable | (auto-detected) |\n| `BROLL_TRANSCRIPTION_ENABLED` | Enable/disable transcription | `true` |\n\n### Legacy Options\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AI_PROVIDER` | Legacy fallback for all tasks | `fireworks` |\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faydrian%2Fbroll-organizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faydrian%2Fbroll-organizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faydrian%2Fbroll-organizer/lists"}