🎵 DJ-CLI

Professional Terminal Interface for YouTube MP3 Downloads

---

📸 Interface Preview

DJ-CLI's beautiful terminal interface featuring real-time status updates, batch processing capabilities, and intuitive keyboard controls.

---

✨ Features

🚀 Core Functionality

• Lightning-fast downloads using the battle-tested yt-dlp backend
• High-quality audio extraction with support for 128kbps and 256kbps MP3 output
• Smart URL extraction from messy clipboard text - paste anything, get clean URLs
• Batch processing - queue multiple videos and download them all at once
• Async operations - non-blocking downloads with real-time progress updates

🎨 Terminal User Interface

• Beautiful TUI powered by ratatui with vibrant colors
• Responsive design that adapts to different terminal sizes
• Real-time status updates with download progress and error handling
• Keyboard-driven navigation with intuitive controls
• Focus management for seamless user experience

🛡️ Reliability & Performance

• Robust error handling - graceful failures that don't crash the interface
• Input sanitization - automatically cleans and validates pasted content
• Memory-safe operations with input length limits and cleanup
• Cross-platform support: macOS, Linux, Windows (via WSL)
• Zero external dependencies beyond yt-dlp and ffmpeg

📁 File Management

• Automatic organization - downloads save directly to your Downloads folder
• Metadata embedding - includes thumbnails and track information
• Filename sanitization - handles special characters and long titles
• Duplicate detection - smart handling of existing files

---

🚀 Quick Start

Installation Options

Option 1: Install from Crates.io (Recommended)

cargo install dj-cli

Option 2: Build from Source

git clone https://github.com/henryoman/dj-cli.git
cd dj-cli
cargo build --release
cargo install --path .

Option 3: Run Directly

git clone https://github.com/henryoman/dj-cli.git
cd dj-cli
cargo run --release

First Run

# Launch the interactive TUI
dj-cli

# Or download directly (non-interactive)
dj-cli "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

---

🛠️ Prerequisites & Dependencies

Required Software

1. Rust Toolchain

DJ-CLI requires Rust 1.78 or later. Install via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

2. yt-dlp (Core Download Engine)

Install the latest version of yt-dlp:

# macOS (Homebrew)
brew install yt-dlp

# Ubuntu/Debian
sudo apt update && sudo apt install yt-dlp

# Arch Linux
sudo pacman -S yt-dlp

# Or via pip (universal)
pip install yt-dlp

3. FFmpeg (Audio Processing)

Required for audio extraction and format conversion:

# macOS (Homebrew)
brew install ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# Arch Linux
sudo pacman -S ffmpeg

# Windows (Chocolatey)
choco install ffmpeg

Verification

Test your setup:

yt-dlp --version
ffmpeg -version
cargo --version

---

📖 Comprehensive Usage Guide

🎯 Single Download Mode

1. Launch DJ-CLI

   dj-cli
   

2. Paste YouTube URL

   • Simply paste any YouTube URL into the input field
   • DJ-CLI automatically extracts and cleans the URL from messy clipboard content

3. Choose Quality & Download

   • Tab to navigate between input field and download buttons
   • Enter for default 128kbps download
   • Ctrl+1 for quick 128kbps download
   • Ctrl+2 for quick 256kbps download

🎯 Batch Download Mode

1. Enable Batch Mode

   Press Ctrl+B to toggle batch mode
   

2. Add Multiple URLs

   Paste URL → Press Enter → Repeat for each video
   

3. Start Batch Download

   Press Ctrl+D to download all queued videos
   

4. Monitor Progress

   • Real-time progress updates for each download
   • Success/failure count at completion
   • Detailed status for each URL in the queue

🎯 Advanced Features

Smart Input Handling

• Paste any text containing YouTube URLs - DJ-CLI extracts them automatically
• F5 to clean and extract URLs from current input
• Input validation prevents invalid URLs from processing
• Length limits protect against memory issues (500 chars max)

Keyboard Shortcuts

Shortcut	Function
Ctrl+C	Quit application
Esc	Exit application
Tab	Switch focus between elements
Enter	Download (single mode) / Add URL (batch mode)
Ctrl+B	Toggle batch mode
Ctrl+D	Start batch download
Ctrl+1	Quick 128kbps download
Ctrl+2	Quick 256kbps download
F5	Clean and extract URL from input
Delete	Clear input field
Backspace	Remove last character

---

🔧 Configuration & Customization

Output Directory

Files are automatically saved to your system's Downloads folder:

• macOS: ~/Downloads/
• Linux: ~/Downloads/
• Windows: %USERPROFILE%\Downloads\

Audio Quality Options

Quality	Bitrate	Use Case
128kbps	Standard quality	General listening, smaller files
256kbps	High quality	Audiophile listening, DJ sets

File Naming

Downloaded files use the format: [Video Title].mp3

• Special characters are automatically sanitized
• Long titles are handled gracefully
• Metadata and thumbnails are embedded automatically

---

🏗️ Architecture & Technical Details

Built With Modern Rust

• Tokio - Async runtime for non-blocking operations
• Ratatui - Terminal UI framework with rich widgets
• Crossterm - Cross-platform terminal manipulation
• Color-eyre - Enhanced error reporting
• Tracing - Structured logging
• Regex - URL pattern matching

Performance Characteristics

• Memory-efficient: Smart input limiting and cleanup
• CPU-light: Async operations prevent blocking
• Storage-aware: Downloads to standard user directories
• Network-optimized: Leverages yt-dlp's efficient downloading

Code Quality

• Memory safety through Rust's ownership system
• Error handling with graceful degradation
• Input validation and sanitization throughout
• Modular architecture for maintainability

---

🐛 Troubleshooting

Common Issues

"yt-dlp not found"

# Ensure yt-dlp is installed and in PATH
which yt-dlp
# If not found, install via your package manager
brew install yt-dlp  # macOS

"Download failed"

# Check if URL is accessible
yt-dlp --list-formats [YOUR_URL]
# Update yt-dlp to latest version
pip install -U yt-dlp

"Permission denied" in Downloads folder

# Check Downloads folder permissions
ls -la ~/Downloads/
# Create if missing
mkdir -p ~/Downloads/

Audio conversion fails

# Verify ffmpeg installation
ffmpeg -version
# Reinstall if needed
brew reinstall ffmpeg  # macOS

Debug Mode

For detailed error information:

# Enable verbose logging (modify source)
RUST_LOG=debug cargo run

---

🔄 Updates & Maintenance

Staying Current

# Update DJ-CLI
cargo install dj-cli --force

# Update yt-dlp (important for YouTube compatibility)
pip install -U yt-dlp

# Update dependencies when building from source
cd dj-cli
cargo update

Version Compatibility

• Minimum Rust version: 1.78.0
• Tested yt-dlp versions: 2023.12.30+
• Supported platforms: macOS 10.15+, Ubuntu 20.04+, Windows 10+ (WSL)

---

🤝 Contributing

We welcome contributions! Here's how to get involved:

Development Setup

# Clone and setup development environment
git clone https://github.com/henryoman/dj-cli.git
cd dj-cli
cargo build
cargo test

# Install development tools
cargo install cargo-watch

Code Standards

# Format code
cargo fmt

# Lint with Clippy
cargo clippy --all-targets --all-features -- -D warnings

# Run tests
cargo test

Contribution Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests
4. Ensure all checks pass: cargo fmt && cargo clippy && cargo test
5. Commit with clear messages: git commit -m 'Add amazing feature'
6. Push to your fork: git push origin feature/amazing-feature
7. Open a Pull Request with detailed description

Areas for Contribution

• 🎨 UI/UX improvements
• 🚀 Performance optimizations
• 🔧 Additional audio formats (FLAC, AAC)
• 📱 Configuration file support
• 🌐 Internationalization
• 📝 Documentation improvements

---

📜 License

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

MIT License

Copyright (c) 2024 Henryoman

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files...

---

🙏 Acknowledgments

• yt-dlp team - Powerful YouTube download engine
• Ratatui community - Excellent terminal UI framework
• Rust community - Amazing language and ecosystem

---

📊 Project Stats

• Language: Rust 🦀
• Lines of Code: ~850+
• Dependencies: 16 (carefully chosen)
• Binary Size: ~2MB (optimized)
• Performance: Downloads limited only by network speed

---

Built with ❤️ using Rust
Making YouTube audio downloads fast, safe, and beautiful