vidpipe 1.0.0

package/README.md

@@ -0,0 +1,243 @@
+[![CI](https://github.com/htekdev/vidpipe/actions/workflows/ci.yml/badge.svg)](https://github.com/htekdev/vidpipe/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/vidpipe)](https://www.npmjs.com/package/vidpipe)
+[![Node.js 20+](https://img.shields.io/badge/node-20%2B-brightgreen)](https://nodejs.org/)
+[![License: ISC](https://img.shields.io/badge/license-ISC-blue)](./LICENSE)
+
+# 🎬 VidPipe
+
+**Drop a video. Get transcripts, summaries, short clips, captions, blog posts, and social media posts — automatically.**
+
+An AI-powered CLI pipeline that watches for new video recordings and transforms them into rich, structured content using [GitHub Copilot SDK](https://github.com/github/copilot-sdk) agents and OpenAI Whisper.
+
+```bash
+npm install -g vidpipe
+```
+
+---
+
+## ✨ Features
+
+- 🎬 **14-Stage Automated Pipeline** — Drop a video and walk away; everything runs end-to-end
+- 🎙️ **Whisper Transcription** — Word-level timestamps via OpenAI Whisper API
+- 🔇 **AI-Driven Silence Removal** — Conservative, context-aware dead-air detection (capped at 20% removal)
+- 📐 **Smart Split-Screen Layouts** — Webcam + screen content for 3 aspect ratios: portrait (9:16), square (1:1), and feed (4:5)
+- 🔍 **Edge-Based Webcam Detection** — Detects webcam overlay position via skin-tone analysis and inter-frame edge refinement (no hardcoded margins)
+- 🎯 **Face-Aware AR-Matched Cropping** — Webcam region is aspect-ratio-matched and center-cropped to fill each layout with no black bars
+- 💬 **Karaoke Captions** — Opus Clips-style word-by-word highlighting with green active word on portrait, yellow on landscape
+- 🪝 **Hook Overlays** — Animated title text burned into portrait short clips
+- ✂️ **Short Clips** — AI identifies the best 15–60s moments, supports composite (multi-segment) shorts
+- 🎞️ **Medium Clips** — 1–3 min standalone segments for deeper content with crossfade transitions
+- 📑 **Chapter Detection** — AI-identified topic boundaries in 4 formats (JSON, Markdown, FFmetadata, YouTube timestamps)
+- 📱 **Social Media Posts** — Platform-tailored content for TikTok, YouTube, Instagram, LinkedIn, and X
+- 📰 **Dev.to Blog Post** — Long-form technical blog post with frontmatter and web-sourced links
+- 🔗 **Web Search Integration** — Finds relevant links for social posts and blog content via Exa
+- 🔄 **Git Automation** — Auto-commits and pushes all generated content after each video
+- 🎨 **Brand Voice** — Customize AI tone, vocabulary, hashtags, and content style via `brand.json`
+- 👁️ **Watch Mode** — Monitors a folder and processes new `.mp4` files on arrival
+- 🧠 **Agent Architecture** — Powered by GitHub Copilot SDK with tool-calling agents
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# Install globally
+npm install -g vidpipe
+
+# Process a single video
+vidpipe /path/to/video.mp4
+
+# Watch a folder for new recordings
+vidpipe --watch-dir ~/Videos/Recordings
+
+# Full example with options
+vidpipe \
+  --watch-dir ~/Videos/Recordings \
+  --output-dir ~/Content/processed \
+  --openai-key sk-... \
+  --brand ./brand.json \
+  --verbose
+```
+
+> **Prerequisites:** Node.js 20+, FFmpeg 6.0+, and an OpenAI API key.
+> See [Getting Started](./docs/getting-started.md) for full setup instructions.
+
+---
+
+## 🎮 CLI Usage
+
+```
+vidpipe [options] [video-path]
+```
+
+| Option | Description |
+|--------|-------------|
+| `[video-path]` | Process a specific video file (implies `--once`) |
+| `--watch-dir <path>` | Folder to watch for new recordings |
+| `--output-dir <path>` | Output directory (default: `./recordings`) |
+| `--openai-key <key>` | OpenAI API key |
+| `--exa-key <key>` | Exa AI key for web search in social posts |
+| `--brand <path>` | Path to `brand.json` (default: `./brand.json`) |
+| `--once` | Process next video and exit |
+| `--no-silence-removal` | Skip silence removal |
+| `--no-shorts` | Skip short clip extraction |
+| `--no-medium-clips` | Skip medium clip generation |
+| `--no-social` | Skip social media posts |
+| `--no-captions` | Skip caption generation/burning |
+| `--no-git` | Skip git commit/push |
+| `-v, --verbose` | Debug-level logging |
+
+---
+
+## 📁 Output Structure
+
+```
+recordings/
+└── my-awesome-demo/
+    ├── my-awesome-demo.mp4                  # Original video
+    ├── my-awesome-demo-edited.mp4           # Silence-removed
+    ├── my-awesome-demo-captioned.mp4        # With burned-in captions
+    ├── transcript.json                      # Word-level transcript
+    ├── transcript-edited.json               # Timestamps adjusted for silence removal
+    ├── README.md                            # AI-generated summary with screenshots
+    ├── captions/
+    │   ├── captions.srt                     # SubRip subtitles
+    │   ├── captions.vtt                     # WebVTT subtitles
+    │   └── captions.ass                     # Advanced SSA (karaoke-style)
+    ├── shorts/
+    │   ├── catchy-title.mp4                 # Landscape base clip
+    │   ├── catchy-title-captioned.mp4       # Landscape + burned captions
+    │   ├── catchy-title-portrait.mp4        # 9:16 split-screen
+    │   ├── catchy-title-portrait-captioned.mp4  # Portrait + captions + hook overlay
+    │   ├── catchy-title-feed.mp4            # 4:5 split-screen
+    │   ├── catchy-title-square.mp4          # 1:1 split-screen
+    │   ├── catchy-title.md                  # Clip metadata
+    │   └── catchy-title/
+    │       └── posts/                       # Per-short social posts (5 platforms)
+    ├── medium-clips/
+    │   ├── deep-dive-topic.mp4              # Landscape base clip
+    │   ├── deep-dive-topic-captioned.mp4    # With burned captions
+    │   ├── deep-dive-topic.md               # Clip metadata
+    │   └── deep-dive-topic/
+    │       └── posts/                       # Per-clip social posts (5 platforms)
+    ├── chapters/
+    │   ├── chapters.json                    # Structured chapter data
+    │   ├── chapters.md                      # Markdown table
+    │   ├── chapters.ffmetadata              # FFmpeg metadata format
+    │   └── chapters-youtube.txt             # YouTube description timestamps
+    └── social-posts/
+        ├── tiktok.md                        # Full-video social posts
+        ├── youtube.md
+        ├── instagram.md
+        ├── linkedin.md
+        ├── x.md
+        └── devto.md                         # Dev.to blog post
+```
+
+---
+
+## 🔄 Pipeline
+
+```
+Ingest → Transcribe → Silence Removal → Captions → Caption Burn → Shorts → Medium Clips → Chapters → Summary → Social Media → Short Posts → Medium Clip Posts → Blog → Git Push
+```
+
+| # | Stage | Description |
+|---|-------|-------------|
+| 1 | **Ingestion** | Copies video, extracts metadata with FFprobe |
+| 2 | **Transcription** | Extracts audio → OpenAI Whisper for word-level transcription |
+| 3 | **Silence Removal** | AI detects dead-air segments; context-aware removals capped at 20% |
+| 4 | **Captions** | Generates `.srt`, `.vtt`, and `.ass` subtitle files with karaoke word highlighting |
+| 5 | **Caption Burn** | Burns ASS captions into video (single-pass encode when silence was also removed) |
+| 6 | **Shorts** | AI identifies best 15–60s moments; extracts single and composite clips with 6 variants per short |
+| 7 | **Medium Clips** | AI identifies 1–3 min standalone segments with crossfade transitions |
+| 8 | **Chapters** | AI detects topic boundaries; outputs JSON, Markdown, FFmetadata, and YouTube timestamps |
+| 9 | **Summary** | AI writes a Markdown README with captured screenshots |
+| 10 | **Social Media** | Platform-tailored posts for TikTok, YouTube, Instagram, LinkedIn, and X |
+| 11 | **Short Posts** | Per-short social media posts for all 5 platforms |
+| 12 | **Medium Clip Posts** | Per-medium-clip social media posts for all 5 platforms |
+| 13 | **Blog** | Dev.to blog post with frontmatter, web-sourced links via Exa |
+| 14 | **Git Push** | Auto-commits and pushes to `origin main` |
+
+Each stage can be independently skipped with `--no-*` flags. A stage failure does not abort the pipeline — subsequent stages proceed with whatever data is available.
+
+---
+
+## ⚙️ Configuration
+
+Configuration is loaded from CLI flags → environment variables → `.env` file → defaults.
+
+```env
+# .env
+OPENAI_API_KEY=sk-your-key-here
+WATCH_FOLDER=/path/to/recordings
+OUTPUT_DIR=/path/to/output
+# EXA_API_KEY=your-exa-key       # Optional: enables web search in social/blog posts
+# BRAND_PATH=./brand.json         # Optional: path to brand voice config
+# FFMPEG_PATH=/usr/local/bin/ffmpeg
+# FFPROBE_PATH=/usr/local/bin/ffprobe
+```
+
+---
+
+## 📚 Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./docs/getting-started.md) | Prerequisites, installation, and first run |
+| [Configuration](./docs/configuration.md) | All CLI flags, env vars, skip options, and examples |
+| [FFmpeg Setup](./docs/ffmpeg-setup.md) | Platform-specific install (Windows, macOS, Linux, ARM64) |
+| [Brand Customization](./docs/brand-customization.md) | Customize AI voice, vocabulary, hashtags, and content style |
+
+---
+
+## 🏗️ Architecture
+
+Agent-based architecture built on the [GitHub Copilot SDK](https://github.com/github/copilot-sdk):
+
+```
+BaseAgent (abstract)
+├── SilenceRemovalAgent → detect_silence, decide_removals
+├── SummaryAgent        → capture_frame, write_summary
+├── ShortsAgent         → plan_shorts
+├── MediumVideoAgent    → plan_medium_clips
+├── ChapterAgent        → generate_chapters
+├── SocialMediaAgent    → search_links, create_posts
+└── BlogAgent           → search_web, write_blog
+```
+
+Each agent communicates with the LLM through structured tool calls, ensuring reliable, parseable outputs.
+
+---
+
+## 🛠️ Tech Stack
+
+| Technology | Purpose |
+|------------|---------|
+| [TypeScript](https://www.typescriptlang.org/) | Language (ES2022, ESM) |
+| [GitHub Copilot SDK](https://github.com/github/copilot-sdk) | AI agent framework |
+| [OpenAI Whisper](https://platform.openai.com/docs/guides/speech-to-text) | Speech-to-text |
+| [FFmpeg](https://ffmpeg.org/) | Video/audio processing |
+| [Sharp](https://sharp.pixelplumbing.com/) | Image analysis (webcam detection) |
+| [Commander.js](https://github.com/tj/commander.js) | CLI framework |
+| [Chokidar](https://github.com/paulmillr/chokidar) | File system watching |
+| [Winston](https://github.com/winstonjs/winston) | Logging |
+| [Exa AI](https://exa.ai/) | Web search for social posts and blog |
+
+---
+
+## 🗺️ Roadmap
+
+- [ ] **Automated social posting** — Publish directly to platforms via their APIs
+- [ ] **Multi-language support** — Transcription and summaries in multiple languages
+- [ ] **Custom templates** — User-defined Markdown & social post templates
+- [ ] **Web dashboard** — Browser UI for reviewing and editing outputs
+- [ ] **Batch processing** — Process an entire folder of existing videos
+- [ ] **Custom short criteria** — Configure what makes a "good" short for your content
+- [ ] **Thumbnail generation** — Auto-generate branded thumbnails for shorts
+
+---
+
+## 📄 License
+
+ISC © [htekdev](https://github.com/htekdev)

package/assets/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2024 The Montserrat.Git Project Authors (https://github.com/JulietaUla/Montserrat.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/__tests__/agents.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agents.test.d.ts.map

package/dist/__tests__/agents.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/agents.test.ts"],"names":[],"mappings":""}