tubetracks 1.5.0

TubeTracks: Enhanced YouTube to MP3 Downloader with multi-platform support

TubeTracks

Multi-platform media downloader with advanced quality control and batch processing capabilities.

---

Overview

TubeTracks is a Python-based media downloader supporting 9+ platforms including YouTube, TikTok, Instagram, SoundCloud, Spotify, and more. Features include multiple quality presets, format conversion, playlist support, and both CLI and GUI interfaces.

Features

• Multi-platform support: YouTube, TikTok, Instagram, SoundCloud, Spotify, Twitch, Dailymotion, Vimeo, Reddit
• Quality presets: 128 kbps, 192 kbps, 320 kbps, or original quality
• Format conversion: MP3, M4A, FLAC, WAV, OGG via FFmpeg
• Batch processing: Download multiple URLs from text files
• Playlist support: Automatic playlist extraction and download
• GUI interface: User-friendly desktop application with Tkinter
• Download archive: Track downloads to prevent duplicates
• Metadata embedding: Automatic ID3 tags and thumbnail artwork

Requirements

• Python 3.8+
• FFmpeg
• Dependencies listed in requirements.txt

---

Installation

Install from PyPI

pip install tubetracks

Quick Install (Source)

git clone https://github.com/jomardyan/TubeTracks.git
cd TubeTracks
make install

Manual Installation

1. Clone repository

   git clone https://github.com/jomardyan/TubeTracks.git
   cd TubeTracks
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Install FFmpeg You can use the provided cross-platform PowerShell script:

   pwsh ./install_ffmpeg.ps1
   

   Or install manually:

   • Windows: winget install Gyan.FFmpeg
   • macOS: brew install ffmpeg
   • Linux: sudo apt-get install ffmpeg

Verify Installation

python --version          # Check Python
ffmpeg -version          # Check FFmpeg
python downloader.py --help  # Test downloader

---

Quick Start

CLI Usage

Note: If you installed via PyPI, use the tubetracks command instead of python downloader.py.

# Single download (PyPI)
tubetracks "https://www.youtube.com/watch?v=VIDEO_ID"

# Single download (Source)
python downloader.py "https://www.youtube.com/watch?v=VIDEO_ID"

# With quality and format
tubetracks -q high -f flac "URL"

# Playlist
tubetracks -p "PLAYLIST_URL"

# Batch from file
tubetracks -b urls.txt

Python Library Usage

TubeTracks can be used as a Python library to integrate media downloading capabilities directly into your own applications.

from downloader import download_audio

# Simple download
result = download_audio("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

See LIBRARY_USAGE.md for complete API documentation and examples.

GUI

Launch the desktop interface:

python tubetracks_gui.py

Or with Make:

make gui

---

Usage

Quality Options

Preset	Bitrate	Use Case
low	128 kbps	Podcasts, audiobooks
medium	192 kbps	General listening (default)
high	320 kbps	High-quality music
best	Original	Maximum quality

Output Formats

Supported formats: mp3, m4a, flac, wav, ogg

python downloader.py -f mp3 <url>
python downloader.py -f flac -q best <url>

Common Options

# Custom output directory
python downloader.py -o ~/Music <url>

# Custom filename template
python downloader.py -t "%(artist)s - %(title)s" <url>

# Dry-run (preview without downloading)
python downloader.py --dry-run <url>

# Network options
python downloader.py --proxy socks5://127.0.0.1:1080 <url>
python downloader.py --limit-rate 1M <url>

# Error handling
python downloader.py --retries 5 <url>

Configuration

View or save configuration:

python downloader.py --show-config
python downloader.py --save-config

Configuration files are loaded from:

1. ~/.tubetracks.conf
2. ./.tubetracks.conf

---

Supported Platforms

Platform	Playlist	Content Types
YouTube	✅	Videos, Shorts, Music
TikTok	✅	Videos, Clips
Instagram	❌	Posts, Reels, Stories
SoundCloud	✅	Tracks, Playlists
Spotify	✅	Tracks, Playlists, Albums
Twitch	❌	VODs, Clips, Highlights
Dailymotion	✅	Videos, Playlists
Vimeo	✅	Videos, Channels
Reddit	❌	Videos, Posts

View all plugins: python downloader.py --list-plugins

See PLUGIN_API.md for custom plugin development.

---

Development

Testing

make test              # Run all tests
make smoke-test        # Quick validation
make coverage          # Coverage report

Code Quality

make lint              # Check code style
make format            # Auto-format code
make check             # Run all checks

---

Disclaimer

This software is provided for educational and personal use only. Users are solely responsible for ensuring their usage complies with applicable laws, regulations, and the terms of service of the platforms from which content is downloaded. The software owner and contributors assume no responsibility or liability for any misuse, legal violations, or consequences arising from the use of this software.

By using this software, you acknowledge that:

• You have the legal right to download the content
• You will respect copyright laws and intellectual property rights
• You will comply with the terms of service of all platforms accessed
• The software owner is not liable for your actions or any resulting damages

License

This project is licensed under the GNU General Public License v3.0 or later — see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Acknowledgments

This project uses:

• yt-dlp — YouTube extraction and download
• rich — Rich terminal output
• FFmpeg — Audio processing and conversion