youtube_chapter_splitter 0.8.4

Download YouTube videos, extract audio to MP3, and split by chapters
Documentation

YouTube Chapter Splitter

A simple and powerful Rust CLI tool to download YouTube videos, extract audio to MP3, and automatically split them into individual tracks based on chapters.

License: MIT Rust Version

โœจ Features

  • ๐ŸŽต Download YouTube audio in high-quality MP3 format (192 kbps)
  • ๐Ÿ–ผ๏ธ Download album artwork automatically with embedded cover art in MP3 tags
  • ๐Ÿ“‘ Automatic chapter detection from YouTube video metadata
  • ๐Ÿ”‡ Silence detection fallback for videos without chapters
  • โœ‚๏ธ Smart audio splitting with complete ID3 metadata tags (title, artist, album, track number, cover art)
  • โš™๏ธ Persistent configuration with customizable defaults (NEW in v0.8.1)
  • ๐Ÿ“ Customizable filename format with placeholders (%n, %t, %a, %A)
  • ๐Ÿ“ Customizable directory format for organized music library
  • ๐ŸŽจ Clean folder names with intelligent formatting (removes brackets, pipes, capitalizes)
  • ๐Ÿ“Š Progress bars for download and splitting operations
  • ๐ŸŽฏ Force artist/album names with CLI options
  • โšก Dependency checking with automatic installation prompts
  • ๐Ÿงน URL cleaning - automatically removes playlist and extra parameters
  • ๐Ÿชถ Lightweight binary (8.5 MB) with minimal dependencies
  • ๐ŸŽถ Playlist support (NEW in v0.8.2)
  • ๐Ÿ”„ Retry mechanism for failed downloads (NEW in v0.8.2)
  • ๋ฎ์–ด์“ฐ๊ธฐ Overwrite option for existing files (NEW in v0.8.2)

๐Ÿš€ Quick Start

Prerequisites

The application will check for dependencies at startup and offer to install them:

  • yt-dlp: pip install yt-dlp
  • ffmpeg:
    • Linux: sudo apt install ffmpeg
    • macOS: brew install ffmpeg
    • Windows: Download from ffmpeg.org

Installation

Option 1: From crates.io (Recommended)

cargo install youtube_chapter_splitter

The ytcs binary will be installed in ~/.cargo/bin/ (make sure it's in your PATH).

Option 2: From source

# Clone the repository
git clone https://github.com/all3f0r1/youtube-chapter-splitter.git
cd youtube-chapter-splitter

# Build and install
cargo install --path .

Usage

Simple syntax:

ytcs <YOUTUBE_URL> [OPTIONS]

Options:

  • -o, --output <DIR> - Output directory (overrides config)
  • -a, --artist <ARTIST> - Force artist name (overrides auto-detection)
  • -A, --album <ALBUM> - Force album name (overrides auto-detection)
  • --no-cover - Skip downloading cover art
  • --playlist - Force playlist download

Configuration commands:

  • ytcs config - Show current configuration
  • ytcs set <key> <value> - Set a configuration value
  • ytcs reset - Reset configuration to defaults

Examples:

# Download and split a YouTube video (saves to ~/Music)
ytcs "https://www.youtube.com/watch?v=28vf7QxgCzA"

# Download a playlist
ytcs "https://www.youtube.com/playlist?list=..."

# Specify custom output directory
ytcs "https://www.youtube.com/watch?v=28vf7QxgCzA" --output ~/Downloads

# Force artist and album names
ytcs "https://www.youtube.com/watch?v=..." -a "Pink Floyd" -A "Dark Side of the Moon"

# Skip cover art download
ytcs "https://www.youtube.com/watch?v=..." --no-cover

# Configure default output directory
ytcs set default_output_dir "~/Downloads/Music"

# Customize filename format
ytcs set filename_format "%n %t"

# Show current configuration
ytcs config

Important: Always put URLs in quotes to avoid shell interpretation of special characters:

ytcs "URL"  # โœ… Correct
ytcs URL    # โŒ May cause issues with & characters

โš™๏ธ Configuration

YouTube Chapter Splitter uses a persistent configuration file stored at:

  • Linux/macOS: ~/.config/ytcs/config.toml
  • Windows: %APPDATA%\ytcs\config.toml

Available Settings

Setting Default Description
default_output_dir ~/Music Default download directory
download_cover true Download album artwork
filename_format "%n - %t" Filename format with placeholders
directory_format "%a - %A" Directory format with placeholders
audio_quality 192 MP3 quality (128 or 192 kbps)
overwrite_existing false Overwrite existing files
max_retries 3 Retries on download failure
create_playlist false Create .m3u playlist file

Format Placeholders

Filename format:

  • %n - Track number (01, 02, etc.)
  • %t - Track title
  • %a - Artist name
  • %A - Album name

Directory format:

  • %a - Artist name
  • %A - Album name

Configuration Examples

# Organize by artist, then album
ytcs set directory_format "%a/%A"
# Result: ~/Music/Marigold/Oblivion Gate/

# Simple filenames without track numbers
ytcs set filename_format "%t"
# Result: Oblivion Gate.mp3

# Include artist in filename
ytcs set filename_format "%a - %t"
# Result: Marigold - Oblivion Gate.mp3

# Disable cover art download by default
ytcs set download_cover false

See CONFIGURATION_GUIDE.md for detailed configuration documentation.

๐Ÿ“Š Example Output

=== YouTube Chapter Splitter ===

Fetching video information...
Title: Marigold - Oblivion Gate
Duration: 29m 29s
Tracks found: 5

Downloading album artwork...
โœ“ Artwork saved: /home/user/Music/Marigold - Oblivion Gate/cover.jpg

โ ‹ Downloading audio from YouTube...
โœ“ Audio downloaded: /home/user/Music/Marigold - Oblivion Gate/temp_audio.mp3

Using YouTube tracks

Tracks to create:
  1. Oblivion Gate [5m 54s]
  2. Obsidian Throne [5m 35s]
  3. Crimson Citadel [5m 47s]
  4. Silver Spire [6m 30s]
  5. Eternal Pyre [5m 43s]

โ ‹ [โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ] 5/5 Track 5: Eternal Pyre
โœ“ Splitting completed successfully!

โœ“ Processing completed successfully!
Files created: 5
Directory: /home/user/Music/Marigold - Oblivion Gate

๐Ÿงช Testing

The project includes a comprehensive test suite with 172 tests covering:

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_clean_folder_name

๐Ÿ“ Changelog

v0.8.2 (2024)

  • ๐ŸŽถ Added playlist support
  • ๐Ÿ”„ Added retry mechanism for failed downloads
  • ๋ฎ์–ด์“ฐ๊ธฐ Added overwrite option for existing files
  • ๐ŸŽง Added audio quality option (128/192 kbps)

v0.8.1 (2024)

  • โš™๏ธ Added persistent configuration system with TOML
  • ๐Ÿ“ Customizable filename and directory formats
  • ๐Ÿ“Š Progress bars for download and splitting operations
  • ๐ŸŽจ Improved UX with colored output
  • ๐Ÿ“š Comprehensive configuration documentation

v0.8.0 (2024)

  • ๐Ÿ—‘๏ธ Removed TUI interface (simplified to CLI only)
  • ๐Ÿงน Cleaned up dependencies
  • โšก Improved compilation time (-62%)
  • ๐Ÿ“ฆ Reduced binary size to 7.8 MB

v0.7.0 (2024)

  • ๐Ÿ–ฅ๏ธ Added TUI (Text User Interface) with ratatui
  • ๐ŸŽฏ Interactive chapter selection
  • โœ๏ธ Metadata editing in TUI

v0.6.0 (2024)

  • ๐Ÿงช Added 139 comprehensive tests (85% coverage)
  • ๐ŸŽฏ Performance benchmarks with Criterion
  • ๐ŸŒ Unicode and emoji support in metadata
  • โœ… Validation and edge case handling

๐Ÿค Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

๐Ÿ™ Acknowledgments