102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
|
# 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
|