dj-cli 0.1.0

A CLI tool for DJs to download MP3s from YouTube
dj-cli-0.1.0 is not a library.

📸 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

📊 Project Stats

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