🎵 DJ-CLI

Professional Terminal Interface for YouTube MP3 Downloads

📸 Interface Preview

DJ-CLI's beautiful terminal interface featuring real-time status updates 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
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

Launch DJ-CLI
```
dj-cli
```
Paste YouTube URL
- Simply paste any YouTube URL into the input field
- DJ-CLI automatically extracts and cleans the URL from messy clipboard content
Choose Quality & Download
- Enter for default 128kbps download
- Ctrl+1 for quick 128kbps download
- Ctrl+2 for quick 256kbps download

🎯 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
Enter	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

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes with tests
Ensure all checks pass: cargo fmt && cargo clippy && cargo test
Commit with clear messages: git commit -m 'Add amazing feature'
Push to your fork: git push origin feature/amazing-feature
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

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github		.github
src		src
.DS_Store		.DS_Store
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
dj-screenshot.png		dj-screenshot.png
logo.png		logo.png

License

henryoman/dj-cli

Folders and files

Latest commit

History

Repository files navigation