video-tool

Video Processing Tool

Automate your YouTube production workflow end to end. Given a directory of source MP4 clips, the tool can clean the footage, join the clips, create chapter timestamps, transcribe the final video, and generate all supporting copy for publishing.

Features

• Video download from YouTube and 1000+ sites via yt-dlp
• Silence trimming with pydub to tighten raw footage before assembly
• MP4 concatenation with ffmpeg, including optional fast-path when reprocessing is unnecessary
• Automatic chapter map (timestamps.json) with ISO-formatted timecode
• Whisper transcription (transcript.vtt) via Groq
• Markdown description and context cards derived from prompts.yaml
• Optional Bunny.net deployment with independent toggles for uploading the final cut, chapters, and transcript captions
• YouTube deployment with OAuth2 authentication for uploading videos, thumbnails, and captions
• Optional duration CSV export for analytics

Requirements

• Python 3.11+
• ffmpeg available on the system path
• yt-dlp for video downloads (installed automatically)
• API keys (configured via video-tool config keys):
  • Groq API key (transcription via Groq Whisper Large V3 Turbo)
  • OpenAI API key (content generation: descriptions, context cards, timestamps)
  • (Optional) Bunny.net credentials (library ID, access key, collection ID)
  • (Optional) Replicate API token (audio enhancement)
  • (Optional) YouTube: Run video-tool config youtube-auth (OAuth2)

Installation

• Using uv (editable, best for development):

  uv tool install --editable .
  # ensure uv tools are on PATH
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile && source ~/.zprofile
  video-tool --help
  

• Using pipx (recommended for users):

  brew install pipx
  pipx ensurepath
  pipx install .
  video-tool --help
  

• Using pip (global or user install):

  pip install .
  video-tool --help
  

• Install directly from GitHub (no clone):

  # uv tools (recommended)
  uv tool install git+https://github.com/alejandro-ao/video-tool-cli.git
  
  # pipx
  pipx install git+https://github.com/alejandro-ao/video-tool-cli.git
  
  # pip
  pip install git+https://github.com/alejandro-ao/video-tool-cli.git
  

  If the command is not found after install, please restart your terminal and ensure your tool bin directory is on PATH (e.g., ~/.local/bin for uv tools, or your Python user bin on macOS like ~/Library/Python/3.11/bin).

Usage

CLI Structure

video-tool config ...                # Configuration
video-tool pipeline ...              # Full workflow (most common)
video-tool video <command> ...       # Video processing + content generation
video-tool upload <command> ...      # Bunny.net / YouTube uploads

Quick Start

1. Configure API keys:

   video-tool config keys
   

2. Run the full pipeline:

   video-tool pipeline -i /path/to/clips
   

   Or use non-interactive mode:

   video-tool pipeline -i /path/to/clips --yes
   

Download Videos

Download from YouTube and 1000+ supported sites:

video-tool video download --url "https://youtube.com/watch?v=..." --output-path ./downloads/my-video.mp4

Note: In zsh, wrap URLs with ? or & in quotes (or prefix with noglob) to avoid shell globbing errors.

Supported sites include: YouTube, Vimeo, Twitter/X, TikTok, Instagram, Facebook, Twitch, Reddit, Dailymotion, and 1000+ more.

Commands

Video processing:

• video-tool video concat - Concatenate clips into single video
• video-tool video timestamps - Generate chapter timestamps
• video-tool video extract-audio - Extract audio to MP3
• video-tool video enhance-audio - Enhance audio quality via Replicate
• video-tool video silence-removal - Remove silent sections
• video-tool video download - Download from URL

Content generation:

• video-tool generate transcript - Transcribe video/audio with Groq Whisper
• video-tool generate description - Generate video description
• video-tool generate context-cards - Generate context cards

Upload (Bunny.net):

• video-tool upload bunny-video - Upload video to Bunny.net
• video-tool upload bunny-transcript - Upload captions
• video-tool upload bunny-chapters - Upload chapters

Upload (YouTube):

• video-tool upload youtube-video - Upload video to YouTube
• video-tool upload youtube-metadata - Update video metadata
• video-tool upload youtube-transcript - Upload captions

Configuration:

• video-tool config keys - Manage API keys (interactive setup, show, reset)
• video-tool config llm - Configure LLM settings
• video-tool config youtube-auth - YouTube OAuth2 authentication
• video-tool config youtube-status - Check YouTube credentials

Outputs