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.
- Overview
- Key Features
- System Requirements
- Installation
- Usage
- Configuration
- Supported Platforms
- API Reference
- Development
- Contributing
- License
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.
| 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 |
- 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
| 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 |
| Component | Requirement |
|---|---|
| Python | 3.8 or higher |
| FFmpeg | Latest stable release |
| OS | Windows, macOS, or Linux |
Dependencies (installed automatically):
yt-dlp >= 2024.0.0rich >= 13.0.0
pip install tubetracksgit clone https://github.com/jomardyan/TubeTracks.git
cd TubeTracks
pip install -r requirements.txtTubeTracks requires FFmpeg for audio conversion.
Windows
winget install Gyan.FFmpeg
# or
choco install ffmpegmacOS
brew install ffmpegLinux
# Debian/Ubuntu
sudo apt update && sudo apt install ffmpeg
# Fedora
sudo dnf install ffmpeg
# Arch
sudo pacman -S ffmpegtubetracks --version
ffmpeg -versionBasic 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 ./musicAdvanced 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"tubetracks-gui
# or
python tubetracks_gui.pyfrom 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.
TubeTracks uses INI-format configuration files loaded from these locations (in order of precedence):
~/.tubetracks.conf~/.config/tubetracks/config.conf./.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 = 1MManage settings:
tubetracks --show-config # Display current configuration
tubetracks --save-config # Save to config file| 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 |
| Platform | Status | Playlists | Authentication |
|---|---|---|---|
| YouTube | Stable | Yes | No |
| TikTok | Stable | Yes | No |
| Stable | No | Optional | |
| SoundCloud | Stable | Yes | No |
| Spotify | Stable | Yes | Optional |
| Twitch | Stable | No | No |
| Dailymotion | Stable | Yes | No |
| Vimeo | Stable | Yes | Optional |
| Stable | No | No |
tubetracks --list-plugins # View all available plugins| Document | Description |
|---|---|
| LIBRARY_USAGE.md | Python API reference |
| PLUGIN_API.md | Plugin development guide |
| CHANGELOG.md | Version history |
git clone https://github.com/jomardyan/TubeTracks.git
cd TubeTracks
pip install -r requirements.txt
pip install -e ".[dev]"| 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 |
Contributions are welcome. Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/improvement) - Commit changes with clear messages
- Add tests for new functionality
- Ensure
make testpasses - Submit a pull request
Guidelines:
- Follow Black code style
- Include tests for new features
- Update documentation as needed
Resources:
This project is licensed under the GNU General Public License v3.0 or later (GPLv3+).
See LICENSE for the full text.
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.
Built with:
| Resource | Link |
|---|---|
| Documentation | README.md |
| Bug Reports | Issue Tracker |
| Questions | Discussions |
Project Status: Active Development
Current Version: 1.5.2
Maintainer: Hayk Jomardyan
