YouTube Caps

A powerful YouTube processing library with TUI interface and MCP extensions, built with yt-dlp, ffmpeg, and charmbracelet.

Features

• Download: Download YouTube videos and audio with customizable quality options
• Convert: Convert between different video and audio formats
• TUI: Interactive terminal user interface using charmbracelet
• MCP: Model Context Protocol server for AI tool integration
• Worktrees: Git worktrees for parallel development

Installation

# Clone the repository
git clone https://github.com/your-username/youtube-caps.git
cd youtube-caps

# Install dependencies
npm install

# Build the project
npm run build

Prerequisites

• Node.js 18.0.0 or higher
• yt-dlp installed and in PATH
• ffmpeg installed and in PATH

Installing Dependencies

yt-dlp

# On Ubuntu/Debian
sudo apt update
sudo apt install yt-dlp

# Or using pip
pip install yt-dlp

# Or using brew (macOS)
brew install yt-dlp

ffmpeg

# On Ubuntu/Debian
sudo apt update
sudo apt install ffmpeg

# On macOS
brew install ffmpeg

# On Windows (using chocolatey)
choco install ffmpeg

Usage

CLI Interface

# Download video
youtube-caps download https://www.youtube.com/watch?v=VIDEO_ID

# Download audio only
youtube-caps download https://www.youtube.com/watch?v=VIDEO_ID --audio

# Download with specific quality
youtube-caps download https://www.youtube.com/watch?v=VIDEO_ID --quality 1080p

# Convert video format
youtube-caps convert input.mp4 output.webm --format webm

# Launch TUI
youtube-caps tui

TUI Interface

# Launch the interactive terminal interface
youtube-caps tui

The TUI provides:

• Interactive menu system
• Real-time download progress
• Format selection
• Batch operations
• History tracking

MCP Server

The MCP server enables AI tools to interact with YouTube Caps functionality.

Available Tools

• youtube_download: Download YouTube video/audio
• youtube_convert: Convert video/audio format
• youtube_get_info: Get video metadata
• youtube_list_formats: List available formats

Example Usage

// MCP client example
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'youtube-caps-client',
  version: '0.1.0'
});

// Get video info
const info = await client.callTool({
  name: 'youtube_get_info',
  arguments: {
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
  }
});

Development

Git Worktrees

This project uses git worktrees for parallel development:

# List worktrees
git worktree list

# Switch to worktree
cd worktrees/tui    # TUI development
cd worktrees/mcp    # MCP development
cd worktrees/core   # Core library development
cd worktrees/docs   # Documentation

# Create new worktree
git worktree add -b feature-branch worktrees/feature-branch

Building

# Build TypeScript
npm run build

# Development mode
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

Testing

# Run tests
npm test

# Watch mode
npm run test:watch

API Reference

YouTubeProcessor

import { YouTubeProcessor } from 'youtube-caps';

const processor = new YouTubeProcessor();

// Download video
await processor.download(url, {
  audio: false,
  video: true,
  quality: '1080p',
  output: './downloads'
});

// Convert format
await processor.convert('input.mp4', 'output.webm', {
  format: 'webm',
  bitrate: '192k'
});

// Get video info
const info = await processor.getInfo(url);

// List formats
const formats = await processor.listFormats(url);

TUI Interface

import { TUI } from 'youtube-caps';

const tui = new TUI();
await tui.run();

Configuration

Environment Variables

• YOUTUBE_CAPS_DOWNLOAD_DIR: Default download directory (default: ./downloads)
• YOUTUBE_CAPS_LOG_LEVEL: Log level (debug, info, warn, error)
• YOUTUBE_CAPS_MAX_CONCURRENT: Maximum concurrent downloads

Configuration File

Create config.json in the project root:

{
  "downloadDir": "./downloads",
  "defaultQuality": "720p",
  "maxConcurrent": 3,
  "logLevel": "info"
}

Contributing

1. Fork the repository
2. Create a feature branch using worktrees
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: Wiki

Acknowledgments

• yt-dlp - YouTube downloader
• ffmpeg - Multimedia framework
• charmbracelet - TUI library
• Model Context Protocol - AI tool integration