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 - Main CLI entry point with argument parsing

Core Modules

src/cli/args.ts - Command-line argument parser
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 must be installed on the system
FFmpeg is recommended for better format handling

Installation

# Install dependencies
bun install

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

Commands

# 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

3.1 KiB Raw Blame History