# YouTube Segments Downloader

A CLI tool that downloads the most watched segments (chapters) of a YouTube video using the battle-tested `yt-dlp` library.

## Project Purpose

This project provides a command-line interface for extracting and downloading video chapters/segments from YouTube videos. It's built with Bun, TypeScript, and integrates with yt-dlp for robust video downloading.

## Key Features

- **Chapter Extraction**: Automatically detects and extracts video chapters marked by creators
- **Segment Download**: Downloads each chapter as a separate video file
- **Full Video Download**: Also saves the complete video for reference
- **Chapter List Export**: Generates a text file with chapter timestamps and titles
- **Customizable Output**: Configurable output directory and video format
- **Bun Runtime**: Fast execution with Bun's native TypeScript support

## Architecture

### CLI Entry Point
- [`src/cli/index.ts`](src/cli/index.ts) - Main CLI entry point with argument parsing

### Core Modules
- [`src/cli/args.ts`](src/cli/args.ts) - Command-line argument parser
- [`src/cli/downloader.ts`](src/cli/downloader.ts) - yt-dlp integration and segment download logic

### Technology Stack
- **Runtime**: Bun
- **Language**: TypeScript
- **Video Processing**: yt-dlp (external dependency)
- **Framework**: Next.js 15 (for potential web interface)

## Usage

### Prerequisites
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) must be installed on the system
- [FFmpeg](https://ffmpeg.org/) is recommended for better format handling

### Installation

```bash
# Install dependencies
bun install

# Make the CLI accessible (optional, requires linking)
# bun link
```

### Commands

```bash
# Basic usage
bun cli "https://www.youtube.com/watch?v=VIDEO_ID"

# With custom output directory
bun cli "https://www.youtube.com/watch?v=VIDEO_ID" -o ./my-videos

# With specific format
bun cli "https://www.youtube.com/watch?v=VIDEO_ID" -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best"

# Skip chapter extraction
bun cli "https://www.youtube.com/watch?v=VIDEO_ID" --no-chapters
```

### Command-Line Options

| Option | Description |
|--------|-------------|
| `<url>` | YouTube video URL (required) |
| `-o, --output <dir>` | Output directory (default: `./downloads`) |
| `-f, --format <fmt>` | Video format (default: `best`) |
| `--no-chapters` | Skip chapter extraction |
| `-h, --help` | Show help message |

## Output Structure

After running the CLI, the output directory will contain:

```
downloads/
├── video_title_01_chapter_name.ext
├── video_title_02_another_chapter.ext
├── ...
├── video_title_full.ext
└── video_title_chapters.txt
```

## Major Changes

### v0.1.0 (2026-01-14)
- Initial project setup
- Created CLI tool with chapter extraction
- Integrated yt-dlp for video downloading
- Added argument parsing and help documentation

## Notes

- The CLI requires `yt-dlp` to be installed on the system (`pip install yt-dlp` or `brew install yt-dlp`)
- Chapters are extracted from video metadata - creators must have added them
- If no chapters are found, the full video is downloaded
- Chapter titles and timestamps are saved to a text file for reference