yt-music-manager-cli 1.0.2

A production-ready YouTube music playlist manager and synchronizer (YT Music Manager CLI)

YT Music Manager CLI (YTMM CLI)

A production-ready YouTube & YouTube music playlist manager that downloads and keeps your music playlists in sync. No API keys or authentication required for public playlists! (YT Music Manager CLI)

🎵 Features

• 📐 Zero Setup: Works immediately with public playlists - no API keys needed!
• 🔄 Automatic Playlist Sync: Download and sync multiple YouTube playlists
• 🎧 High-Quality Audio: Downloads in MP3 format with configurable quality
• 📁 Organized Storage: Creates subfolders for each playlist automatically
• ⚡ Smart Updates: Only downloads new songs and removes deleted ones
• 🔐 Flexible Authentication: Public playlists (no auth), bundled OAuth (zero setup), or custom OAuth credentials
• 🛡️ Production Ready: Comprehensive error handling, logging, and recovery
• 🖥️ Easy CLI: Simple command-line interface with rich progress display
• ⚙️ Configurable: Customizable download paths, quality settings, and more
• 📊 Progress Tracking: Real-time download progress and sync statistics

📋 Requirements

• Python 3.8+
• Internet connection
• Optional: Google OAuth for private playlists

🚀 Quick Start

1. Installation

# Install from PyPI (Recommended)
pip install yt-music-manager-cli

# OR:

# Clone the repository
git clone https://github.com/sukarth/yt-music-manager-cli.git
cd yt-music-manager-cli

# and innstall the package
pip install -e .

2. Start Using Immediately!

No configuration needed for public playlists:

# Add a public playlist and start downloading
ytmm add-playlist "https://www.youtube.com/playlist?list=XXXXXX"

# Sync all playlists
ytmm sync

That's it! The app works out of the box with public YouTube playlists.

3. Authentication and private playlists

For private playlists or advanced features, you can set up authentication:

Option A: Use bundled Google Sign-In (Recommended, zero setup)

# Sign in with your Google account in your browser when prompted:
ytmm auth mode auto_oauth -y

Option B: Custom OAuth Credentials

# Use your own OAuth credentials
ytmm auth mode manual_oauth -y

# Follow the interactive setup process

4. Configuration

The app works with default settings, but you can customize everything:

# Initialize configuration file
ytmm init

# View current settings
ytmm config

Edit config/settings.toml:

[youtube]
auth_method = "no_auth"  # Options: "no_auth", "auto_oauth", "manual_oauth"

[download]
base_path = "~/Music/YouTube Playlists"
audio_format = "mp3" 
audio_quality = "192"

[sync]
max_concurrent_downloads = 3
auto_sync_interval = 3600

Or change specific values:

ytmm config set download.audio_quality '320'

# Result:
# [OK] Set download.audio_quality = 320
# Please restart the application for changes to take effect.

5. Add and Sync Playlists

# Add a public playlist (works immediately, no setup needed)
ytmm add-playlist "https://www.youtube.com/playlist?list=XXXXXX"

# Add multiple playlists at once
ytmm add-playlist PLxxx PLyyy PLzzz
ytmm add-playlist "https://youtube.com/playlist?list=..." "https://youtube.com/playlist?list=..."

# Add a playlist with a custom name (single playlist only)
ytmm add-playlist "https://youtube.com/playlist?list=..." --name "My Favorites"

# Sync all playlists
ytmm sync --all

# Sync specific playlist
ytmm sync "My Playlist Name"

# Add and sync immediately
ytmm add-playlist "https://youtube.com/playlist?list=..."
# (Will ask if you want to sync right away)

# Preview changes without downloading
ytmm sync --all --dry-run

🔐 Authentication Management

YT Music Manager CLI supports three authentication modes:

No Authentication (Default)

• Access: Public playlists only
• Setup: None required - works immediately
• Limitations: Cannot access private/unlisted playlists

# Check current authentication status
ytmm auth status

# Switch to no-auth mode
ytmm auth mode no_auth -y

Bundled Google Sign-In (auto_oauth)

• Access: All your playlists (public and private)
• Setup: None required - uses bundled OAuth credentials
• Benefits: Full access, zero setup, no API quotas

# Switch to bundled OAuth (and follow process to login with Google)
ytmm auth mode auto_oauth -y

# Sign out/remove account
ytmm auth remove login

Custom OAuth (manual_oauth)

• Access: All your playlists (public and private)
• Setup: Your own OAuth app configuration
• Benefits: Full access, your own credentials

# Switch to custom OAuth mode
ytmm auth mode manual_oauth -y

# Sign out/remove creds
ytmm auth remove creds

📖 Usage Guide

Commands

Command	Description
ytmm init	Initialize configuration and setup
ytmm add-playlist <url/id> [url/id...]	Add one or more YouTube playlists to track
ytmm list-playlists	Show all tracked playlists
ytmm sync [playlist]	Sync playlists (download new, remove old)
ytmm sync --all	Sync all tracked playlists
ytmm remove-playlist <name/id> [name/id...]	Stop tracking one or more playlists
ytmm status	Show sync status and statistics
ytmm config	Show current configuration
ytmm auth status	Show authentication status
ytmm auth mode <mode>	Switch authentication mode (no_auth/auto_oauth/manual_oauth)
ytmm auth remove <arg>	Sign out and remove credentials (login/creds)
ytmm config	Show config status
ytmm config list	List full config
ytmm config list <section.key>	List specific config value
ytmm config set <section.key> <value>	Set configuration value

Examples

# Add multiple playlists at once
ytmm add-playlist PLxxx PLyyy PLzzz
ytmm add-playlist "https://www.youtube.com/playlist?list=PLrAXtmRdnEQy5lVX..." "https://www.youtube.com/watch?v=abc&list=PLxyz..."

# Add single playlists
ytmm add-playlist "https://www.youtube.com/playlist?list=PLrAXtmRdnEQy5lVX..."

# Note: --name option only works with single playlists

# List all tracked playlists
ytmm list-playlists --detailed

# Sync with custom options
# Preview changes
ytmm sync --all --dry-run
# Sync specific playlist
ytmm sync "Chill Music"

# Check status and statistics
ytmm status

# Remove multiple playlists at once, but keep files
ytmm remove-playlist "Old Playlist" "Another Playlist" PLxxx --keep-files

⚙️ Configuration

The configuration file is located at config/settings.toml:

[youtube]
auth_method = "no_auth"  # no_auth, auto_oauth, or manual_oauth

[download]
base_path = "~/Music/YouTube Playlists"
audio_format = "mp3"              # mp3, aac, ogg, wav, flac
audio_quality = "192"             # 64-320 kbps

[sync]
auto_sync_interval = 3600         # Auto-sync every hour
max_concurrent_downloads = 3      # Parallel downloads
check_for_updates_on_start = true
preserve_deleted_locally = false  # Delete files removed from playlist

[logging]
level = "INFO"                    # DEBUG, INFO, WARNING, ERROR
log_file = "logs/yt_music_manager_cli.log"
max_log_size = "10MB"
backup_count = 5

📁 Local Downloaded Playlists File Organization

~/Music/YouTube Playlists/
├── My Chill Playlist/
│   ├── Song 1.mp3
│   ├── Song 2.mp3
│   └── Song 3.mp3
├── Workout Music/
│   ├── High Energy Track.mp3
│   └── Motivational Song.mp3
└── Study Focus/
    └── Ambient Track.mp3

🔧 Advanced Usage

Automation with Cron

Set up automatic syncing with cron:

# Edit crontab
crontab -e

# Add line to sync every 6 hours
0 */6 * * * /path/to/ytmm sync --all

Environment Variables

You can override settings with environment variables:

export YT_MUSIC_MANAGER_CLI_YOUTUBE__AUTH_METHOD="auto_oauth"
export YT_MUSIC_MANAGER_CLI_DOWNLOAD__BASE_PATH="/custom/path"
ytmm sync --all

Custom Download Templates

Customize file naming in settings.toml:

[download]
naming_template = "%(playlist_index)s - %(title)s.%(ext)s"

🚨 Troubleshooting

Common Issues

"Authentication required for private playlists"

• Use bundled OAuth and sign in with Google: ytmm auth mode auto_oauth -y

"Permission denied" errors

• Check write permissions for download directory
• On Windows, avoid special characters in paths
• Run as administrator if needed

"No module named 'yt_dlp'"

• Ensure dependencies are installed!

Downloads failing

• Check internet connection
• Some videos may be region-restricted or unavailable in general to download

Getting Help

1. Check the logs: tail -f logs/yt_music_manager_cli.log
2. Run with debug mode: ytmm --debug sync --all
3. Check configuration: ytmm config
4. Create an issue with logs and error messages

📊 Performance

• Download Speed: Configurable concurrent downloads (1-10 parallel)
• Storage: Efficient file organization with duplicate detection
• Memory: Streaming downloads with progress tracking
• Reliability: Automatic retries and error recovery

🔒 Privacy & Security

• Local Storage: All music files stored locally on your device
• Secure OAuth: Tokens are encrypted using Fernet with machine-specific keys
• No Tracking: No analytics or usage tracking
• Open Source: Full source code available for review

📄 License

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

🤝 Contributing & Development

Contributions are welcome! Please read our Contributing Guide for details on contribution and development.

🐛 Reporting Bugs

When reporting bugs, please include:

1. Environment Information

   • Python version
   • Operating system
   • YT Music Manager CLI (YTMM CLI) version

2. Steps to Reproduce

   • Clear, numbered steps
   • Expected vs actual behavior
   • Screenshots if applicable

3. Log Files

   • Include relevant logs from logs/yt_music_manager_cli.log
   • Use debug mode: ytmm --debug command

🪶 Feature Requests

For new features, please:

1. Check existing issues first
2. Describe the use case clearly
3. Explain why it would benefit users
4. Consider implementation complexity

⭐ Support

If you find this project helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 🔀 Contributing code

🙏 Acknowledgments

• yt-dlp - Excellent YouTube downloading library
• Rich - Beautiful terminal output and progress bars
• Click - Powerful command-line interface framework
• Google - YouTube Data API v3

---

Made with ❤️ by Sukarth, for music lovers who want their playlists always in sync