youtube-chapter-splitter

ytcs: Download complete YouTube albums, cleanly split into MP3 tracks with metadata and cover art, all via a single command line.

youtube-chapter-splitter (or ytcs) is a powerful and pragmatic CLI tool designed for one thing: archiving music from YouTube perfectly. It downloads the video, extracts audio to MP3, fetches the cover art, cleans titles, and splits the audio into pristine tracks based on chapters, all in a single command.

Philosophy

Pragmatic: No frills, just what matters.
Direct: Clear info without detours.
Classy: Elegant without being flashy.

ytcs v0.10.1

→ Marigold - Oblivion Gate
  29m 29s • 5 tracks

  ✓ Cover downloaded
  ✓ Audio downloaded

  Splitting tracks...
  ✓ 01 Oblivion Gate (5m 54s)
  ✓ 02 Obsidian Throne (5m 35s)
  ✓ 03 Crimson Citadel (5m 47s)
  ✓ 04 Silver Spire (6m 30s)
  ✓ 05 Eternal Pyre (5m 43s)

✓ Done → ~/Music/Marigold - Oblivion Gate

Features

MP3 Download: High-quality audio (192 kbps by default).
Automatic Cover Art: Album artwork embedded in MP3 metadata.
Chapter-based Splitting: Automatic detection of YouTube chapters.
Silence Detection: Fallback if the video has no chapters.
Complete Metadata: Title, artist, album, track number, cover art.
Persistent Configuration: config.toml file for your preferences.
Customizable Formatting: File names (%n, %t) and folders (%a, %A).
Smart Cleanup: Removes [Full Album], (Official Audio), etc.
Playlist Support: Interactive playlist handling.
Dependency Verification: yt-dlp and ffmpeg are checked at startup.

Installation

Prerequisites

ytcs requires two external tools:

yt-dlp: For downloading YouTube videos
ffmpeg: For audio processing and splitting

Quick install:

# Linux/macOS (via package manager)
# Ubuntu/Debian
sudo apt install yt-dlp ffmpeg

# macOS (via Homebrew)
brew install yt-dlp ffmpeg

# Or via pip (cross-platform)
pip install yt-dlp

# Windows (via Chocolatey)
choco install yt-dlp ffmpeg

1. Pre-compiled Binaries (Recommended)

Download the latest release for your system from the Releases page.

Linux/macOS:

# Download, extract, and install
wget https://github.com/all3f0r1/youtube-chapter-splitter/releases/latest/download/ytcs-x86_64-unknown-linux-gnu.tar.gz
tar xzf ytcs-x86_64-unknown-linux-gnu.tar.gz
sudo mv ytcs /usr/local/bin/

# Verify installation
ytcs --version

Windows:

Download ytcs-x86_64-pc-windows-msvc.zip.
Extract ytcs.exe.
Place it in a folder included in your PATH.

2. Via `cargo`

cargo install youtube_chapter_splitter

Usage

ytcs works with clear and direct commands.

Download a Video

The default command is download. You can omit it for quick usage.

# Full syntax
ytcs download "https://www.youtube.com/watch?v=..."

# Quick syntax (recommended)
ytcs "https://www.youtube.com/watch?v=..."

Download options:

-o, --output <DIR>: Specify an output folder.
-a, --artist <ARTIST>: Force the artist name.
-A, --album <ALBUM>: Force the album name.
--no-cover: Disable cover art download.

Examples:

# Basic usage
ytcs "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Custom output directory
ytcs -o ~/Downloads/Music "https://youtube.com/..."

# Override artist and album
ytcs -a "Pink Floyd" -A "The Wall" "https://youtube.com/..."

# Skip cover art
ytcs --no-cover "https://youtube.com/..."

Manage Configuration

ytcs uses a simple configuration file (~/.config/ytcs/config.toml).

# Show current configuration
ytcs config

# Modify a value
ytcs set audio_quality 128
ytcs set playlist_behavior video_only

# Reset to default configuration
ytcs reset

Configuration

Customize ytcs according to your needs. Edit the config.toml file directly or use ytcs set.

Key	Default	Description
`default_output_dir`	`~/Music`	Default output folder.
`download_cover`	`true`	Download album cover art.
`filename_format`	`"%n - %t"`	File name format (`%n`: number, `%t`: title, `%a`: artist, `%A`: album).
`directory_format`	`"%a - %A"`	Folder format (`%a`: artist, `%A`: album).
`audio_quality`	`192`	Audio quality in kbps (e.g., `128`, `192`, `320`).
`overwrite_existing`	`false`	Re-download and overwrite existing files.
`max_retries`	`3`	Number of retry attempts on download failure.
`create_playlist`	`false`	Create a `.m3u` playlist file for YouTube playlists.
`playlist_behavior`	`ask`	Behavior for playlist URLs: `ask`, `video_only`, `playlist_only`.

Format placeholders:

File format:

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

Directory format:

%a - Artist name
%A - Album name

Changelog

[0.10.1] - 2025-11-24

Fixed: CLI subcommands (config, set, reset) now work correctly.
Technical: Refactored CLI structure to properly handle subcommands with clap.

[0.10.0] - 2025-11-24

Changed: Complete UI redesign - minimal, clean, and pragmatic.
Removed: Unnecessary borders, boxes, and visual noise.
Removed: Emojis from main output (kept only status checkmarks).
Improved: Auto-clean video titles (removes [Full Album], [Official Audio], etc.).
Improved: More direct and readable output format.
Philosophy: Pragmatic • Direct • Classy

[0.9.3] - 2025-11-24

Fixed: Configuration parsing error for users upgrading from older versions.
Added: Serde default values for all configuration fields to ensure backward compatibility.
Technical: Old config files missing playlist_behavior field now work correctly.

[0.9.2] - 2025-11-24

Changed: MP3 filename capitalization from UPPERCASE to Title Case for better readability.
Example: 01 - Oblivion Gate.mp3 instead of 01 - OBLIVION GATE.MP3.

[0.9.1] - 2025-11-24

Added: Complete code audit with all clippy warnings fixed.
Removed: Obsolete documentation files and examples.
Improved: Code quality and maintainability.
Changed: Capitalized MP3 filenames (reverted in 0.9.2).

[0.9.0] - 2025-11-24

Added: Playlist support with configurable behavior.
Added: Configuration management commands (config, set, reset).
Added: Customizable file and directory naming formats.
Improved: Better error handling and user feedback.

License

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

youtube_chapter_splitter 0.10.7