tubetracks 1.5.2

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

TubeTracks

A professional-grade, multi-platform media downloader for audio extraction and conversion.

Extract audio from YouTube, Spotify, SoundCloud, and 9+ platforms with precise quality control, batch processing, and an extensible plugin architecture.

---

Table of Contents

• Overview
• Key Features
• System Requirements
• Installation
• Usage
• Configuration
• Supported Platforms
• API Reference
• Development
• Contributing
• License

---

Overview

TubeTracks is a command-line and GUI application designed for reliable audio extraction from popular media platforms. Built on top of yt-dlp and FFmpeg, it provides a streamlined workflow for downloading, converting, and organizing audio content.

Why TubeTracks?

Challenge	Solution
Complex yt-dlp command syntax	Simple CLI flags and intuitive GUI
No visual progress feedback	Real-time progress bars and detailed logging
Manual duplicate tracking	Built-in archive system
Platform-specific quirks	Unified plugin architecture
Inconsistent metadata	Automatic ID3 tagging and artwork embedding

---

Key Features

Core Functionality

• Multi-Platform Support — YouTube, TikTok, Instagram, SoundCloud, Spotify, Twitch, Dailymotion, Vimeo, Reddit
• Quality Control — Four preset levels (128–320 kbps) plus lossless original
• Format Conversion — MP3, M4A, FLAC, WAV, OGG output via FFmpeg
• Batch Processing — Concurrent downloads with configurable thread count (1–5)
• Dual Interface — Full-featured CLI and cross-platform GUI (Tkinter)
• Smart Deduplication — Archive system prevents re-downloading content

Advanced Capabilities

Feature	Description
Plugin Architecture	Extensible system for adding new platforms
Network Controls	Proxy support, rate limiting, cookie authentication
Metadata Embedding	Automatic ID3 tags and cover art
Configuration Files	INI-based persistent settings
Error Recovery	Intelligent retry with exponential backoff
Dry Run Mode	Preview operations without downloading

---

System Requirements

Component	Requirement
Python	3.8 or higher
FFmpeg	Latest stable release
OS	Windows, macOS, or Linux

Dependencies (installed automatically):

• yt-dlp >= 2024.0.0
• rich >= 13.0.0

---

Installation

From PyPI (Recommended)

pip install tubetracks

From Source

git clone https://github.com/jomardyan/TubeTracks.git
cd TubeTracks
pip install -r requirements.txt

FFmpeg Setup

TubeTracks requires FFmpeg for audio conversion.

Windows

winget install Gyan.FFmpeg
# or
choco install ffmpeg

macOS

brew install ffmpeg

Linux

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

# Fedora
sudo dnf install ffmpeg

# Arch
sudo pacman -S ffmpeg

Verify Installation

tubetracks --version
ffmpeg -version

---

Usage

Command Line Interface

Basic operations:

# Download audio from URL
tubetracks "https://www.youtube.com/watch?v=VIDEO_ID"

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

# Download playlist
tubetracks -p "PLAYLIST_URL"

# Batch download from file
tubetracks -b urls.txt -o ./music

Advanced options:

# Custom output template
tubetracks -o ~/Music -t "%(artist)s - %(title)s" "URL"

# Network configuration
tubetracks --proxy socks5://127.0.0.1:1080 --limit-rate 1M "URL"

# Preview without downloading
tubetracks --dry-run "URL"

Graphical Interface

tubetracks-gui
# or
python tubetracks_gui.py

Python API

from downloader import download_audio

result = download_audio(
    url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    output_dir="./downloads",
    quality="high",
    audio_format="mp3"
)

if result.success:
    print(f"Saved: {result.output_path}")

See LIBRARY_USAGE.md for complete API documentation.

---

Configuration

TubeTracks uses INI-format configuration files loaded from these locations (in order of precedence):

1. ~/.tubetracks.conf
2. ~/.config/tubetracks/config.conf
3. ./.tubetracks.conf

Example configuration:

[download]
quality = high
format = mp3
output = ~/Music/TubeTracks
template = %(artist)s - %(title)s.%(ext)s
embed_metadata = true
embed_thumbnail = true
retries = 3

[archive]
use_archive = true
archive_file = ~/.tubetracks_archive.txt

[network]
# proxy = socks5://127.0.0.1:1080
# rate_limit = 1M

Manage settings:

tubetracks --show-config    # Display current configuration
tubetracks --save-config    # Save to config file

Quality Presets

Preset	Bitrate	Use Case
low	128 kbps	Podcasts, spoken word
medium	192 kbps	General listening (default)
high	320 kbps	High-fidelity music
best	Original	Archival, lossless output

---

Supported Platforms

Platform	Status	Playlists	Authentication
YouTube	Stable	Yes	No
TikTok	Stable	Yes	No
Instagram	Stable	No	Optional
SoundCloud	Stable	Yes	No
Spotify	Stable	Yes	Optional
Twitch	Stable	No	No
Dailymotion	Stable	Yes	No
Vimeo	Stable	Yes	Optional
Reddit	Stable	No	No

tubetracks --list-plugins  # View all available plugins

---

API Reference

Additional Documentation

Document	Description
LIBRARY_USAGE.md	Python API reference
PLUGIN_API.md	Plugin development guide
CHANGELOG.md	Version history

---

Development

Environment Setup

git clone https://github.com/jomardyan/TubeTracks.git
cd TubeTracks
pip install -r requirements.txt
pip install -e ".[dev]"

Commands

Command	Description
make test	Run test suite
make lint	Check code style
make format	Auto-format code
make build	Build distribution
make clean	Remove artifacts

---

Contributing

Contributions are welcome. Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/improvement)
3. Commit changes with clear messages
4. Add tests for new functionality
5. Ensure make test passes
6. Submit a pull request

Guidelines:

• Follow Black code style
• Include tests for new features
• Update documentation as needed

Resources:

• Issue Tracker
• Pull Requests
• Discussions

---

License

This project is licensed under the GNU General Public License v3.0 or later (GPLv3+).

See LICENSE for the full text.

Legal Notice

TubeTracks is provided for educational and personal use only. Users are responsible for ensuring compliance with:

• Applicable copyright laws
• Platform terms of service
• Local and international regulations

The developers assume no liability for misuse of this software.

---

Acknowledgments

Built with:

• yt-dlp — Media extraction
• FFmpeg — Audio/video processing
• Rich — Terminal formatting

---

Support

Resource	Link
Documentation	README.md
Bug Reports	Issue Tracker
Questions	Discussions

Project Status: Active Development
Current Version: 1.5.2
Maintainer: Hayk Jomardyan

---