# 🎵 TorTrack
**Simple Telegram Bot for Anonymous Music Downloads**
TorTrack is a Python package that lets you run your own Telegram music download bot with built-in Tor anonymity. Just provide a bot token and you're ready to go!
## ⚡ Quick Start
### Installation
```bash
pip install tortrack
```
### Basic Usage
```python
from tortrack import TelegramBot
# That's it! Just give it your bot token
bot = TelegramBot("YOUR_BOT_TOKEN")
bot.run()
```
### Command Line
```bash
# Start with Tor anonymity
tortrack YOUR_BOT_TOKEN
# Start without Tor (not recommended)
tortrack YOUR_BOT_TOKEN --no-tor
```
## 🚀 Features
- **One-line setup** - Just provide your bot token
- **Tor anonymity** - Built-in Tor proxy for anonymous downloads
- **Multiple sources** - Downloads from YouTube, SoundCloud, and more
- **Smart archiving** - Avoids re-downloading the same tracks
- **User limits** - Built-in rate limiting (5 downloads/day for free users)
- **High quality** - 192kbps MP3 downloads
- **Playlist support** - Handles Spotify tracks, albums, and playlists
## 📋 Requirements
- Python 3.8+
- Telegram Bot Token (get from [@BotFather](https://t.me/BotFather))
- MongoDB (optional, for user limits and archiving)
- Tor (optional, for anonymity)
## 🔧 Setup
### 1. Get Bot Token
Message [@BotFather](https://t.me/BotFather) on Telegram:
```
/newbot
YourBotName
yourbotusername_bot
```
### 2. Get Spotify Credentials (Optional)
1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
2. Create new app
3. Get Client ID and Secret
```bash
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
```
### 3. Install Tor (For Anonymity)
```bash
# Ubuntu/Debian
sudo apt install tor
# macOS
brew install tor
# Windows
# Download from https://www.torproject.org/
```
### 4. Start Your Bot
```bash
tortrack YOUR_BOT_TOKEN_HERE
```
## 💻 Advanced Usage
### Custom Configuration
```python
from tortrack import TelegramBot
bot = TelegramBot(
token="YOUR_BOT_TOKEN",
use_tor=True, # Enable Tor anonymity
mongo_uri="mongodb://localhost:27017/mybot"
)
bot.run()
```
### Library Usage
```python
from tortrack import TelegramBot, TorManager
# Advanced setup with custom Tor configuration
tor_manager = TorManager(socks_port=9050, control_port=9051)
await tor_manager.start()
bot = TelegramBot("YOUR_TOKEN", use_tor=False)
# Use your custom tor_manager instead
```
### Environment Variables
```bash
# Spotify API (optional but recommended)
export SPOTIFY_CLIENT_ID="your_spotify_client_id"
export SPOTIFY_CLIENT_SECRET="your_spotify_client_secret"
# MongoDB (optional)
export MONGO_URI="mongodb://localhost:27017/tortrack"
```
## 🎯 Supported Links
Your bot will handle these Spotify URLs:
- `https://open.spotify.com/track/...` - Single tracks
- `https://open.spotify.com/album/...` - Full albums
- `https://open.spotify.com/playlist/...` - Playlists
## 🛡️ Security & Anonymity
TorTrack uses Tor to:
- Hide your server's IP address
- Prevent rate limiting and IP blocks
- Protect against geographic restrictions
- Maintain anonymity while downloading
**Without Tor:** Your server IP is visible to download sources and may get blocked.
**With Tor:** All traffic goes through Tor network for complete anonymity.
## 📊 Bot Commands
Users can interact with your bot using:
- `/start` - Welcome message
- `/help` - Usage instructions
- `/stats` - Download statistics
- Send any Spotify link to download
## 🔧 Deployment
### Local Development
```bash
git clone https://github.com/MohammadHNdev/tortrack.git
cd tortrack
pip install -e .
python -m tortrack YOUR_TOKEN
```
### Docker (Coming Soon)
```bash
docker run -e BOT_TOKEN=your_token tortrack/tortrack
```
### Cloud Deployment
Works on any Python hosting platform:
- Railway
- Heroku
- DigitalOcean
- AWS Lambda
- Google Cloud Run
## 🚨 Important Notes
1. **Legal:** Only download music you have rights to
2. **Rate Limits:** Built-in limits prevent abuse
3. **Resources:** Downloads use temporary storage
4. **Tor Setup:** Tor must be installed for anonymity features
## 📝 License
MIT License - Use it however you want!
## 🤝 Contributing
Found a bug? Want a feature? Open an issue or PR!
## 📞 Support
- 🐛 [Report Issues](https://github.com/MohammadHNdev/tortrack/issues)
- 💬 [Discussions](https://github.com/MohammadHNdev/tortrack/discussions)
- 📧 Email: hosein.norozi434@gmail.com
---
**Made with ❤️ by [Mohammad Hossein Norouzi](https://github.com/MohammadHNdev)**
Raw data
{
"_id": null,
"home_page": "https://github.com/MohammadHNdev/tortrack",
"name": "tortrack",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "telegram bot music download spotify tor anonymous",
"author": "Mohammad Hossein Norouzi",
"author_email": "hosein.norozi434@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/71/1e/b42103b160e37d5193f7b0582b6568276ac7e7c5ca5e2f0ee180355a7259/tortrack-1.0.1.tar.gz",
"platform": null,
"description": "# \ud83c\udfb5 TorTrack\n\n**Simple Telegram Bot for Anonymous Music Downloads**\n\nTorTrack is a Python package that lets you run your own Telegram music download bot with built-in Tor anonymity. Just provide a bot token and you're ready to go!\n\n## \u26a1 Quick Start\n\n### Installation\n```bash\npip install tortrack\n```\n\n### Basic Usage\n```python\nfrom tortrack import TelegramBot\n\n# That's it! Just give it your bot token\nbot = TelegramBot(\"YOUR_BOT_TOKEN\")\nbot.run()\n```\n\n### Command Line\n```bash\n# Start with Tor anonymity\ntortrack YOUR_BOT_TOKEN\n\n# Start without Tor (not recommended)\ntortrack YOUR_BOT_TOKEN --no-tor\n```\n\n## \ud83d\ude80 Features\n\n- **One-line setup** - Just provide your bot token\n- **Tor anonymity** - Built-in Tor proxy for anonymous downloads\n- **Multiple sources** - Downloads from YouTube, SoundCloud, and more\n- **Smart archiving** - Avoids re-downloading the same tracks\n- **User limits** - Built-in rate limiting (5 downloads/day for free users)\n- **High quality** - 192kbps MP3 downloads\n- **Playlist support** - Handles Spotify tracks, albums, and playlists\n\n## \ud83d\udccb Requirements\n\n- Python 3.8+\n- Telegram Bot Token (get from [@BotFather](https://t.me/BotFather))\n- MongoDB (optional, for user limits and archiving)\n- Tor (optional, for anonymity)\n\n## \ud83d\udd27 Setup\n\n### 1. Get Bot Token\nMessage [@BotFather](https://t.me/BotFather) on Telegram:\n```\n/newbot\nYourBotName\nyourbotusername_bot\n```\n\n### 2. Get Spotify Credentials (Optional)\n1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)\n2. Create new app\n3. Get Client ID and Secret\n\n```bash\nexport SPOTIFY_CLIENT_ID=\"your_client_id\"\nexport SPOTIFY_CLIENT_SECRET=\"your_client_secret\"\n```\n\n### 3. Install Tor (For Anonymity)\n```bash\n# Ubuntu/Debian\nsudo apt install tor\n\n# macOS\nbrew install tor\n\n# Windows\n# Download from https://www.torproject.org/\n```\n\n### 4. Start Your Bot\n```bash\ntortrack YOUR_BOT_TOKEN_HERE\n```\n\n## \ud83d\udcbb Advanced Usage\n\n### Custom Configuration\n```python\nfrom tortrack import TelegramBot\n\nbot = TelegramBot(\n token=\"YOUR_BOT_TOKEN\",\n use_tor=True, # Enable Tor anonymity\n mongo_uri=\"mongodb://localhost:27017/mybot\"\n)\n\nbot.run()\n```\n\n### Library Usage\n```python\nfrom tortrack import TelegramBot, TorManager\n\n# Advanced setup with custom Tor configuration\ntor_manager = TorManager(socks_port=9050, control_port=9051)\nawait tor_manager.start()\n\nbot = TelegramBot(\"YOUR_TOKEN\", use_tor=False)\n# Use your custom tor_manager instead\n```\n\n### Environment Variables\n```bash\n# Spotify API (optional but recommended)\nexport SPOTIFY_CLIENT_ID=\"your_spotify_client_id\"\nexport SPOTIFY_CLIENT_SECRET=\"your_spotify_client_secret\"\n\n# MongoDB (optional)\nexport MONGO_URI=\"mongodb://localhost:27017/tortrack\"\n```\n\n## \ud83c\udfaf Supported Links\n\nYour bot will handle these Spotify URLs:\n- `https://open.spotify.com/track/...` - Single tracks\n- `https://open.spotify.com/album/...` - Full albums \n- `https://open.spotify.com/playlist/...` - Playlists\n\n## \ud83d\udee1\ufe0f Security & Anonymity\n\nTorTrack uses Tor to:\n- Hide your server's IP address\n- Prevent rate limiting and IP blocks\n- Protect against geographic restrictions\n- Maintain anonymity while downloading\n\n**Without Tor:** Your server IP is visible to download sources and may get blocked.\n\n**With Tor:** All traffic goes through Tor network for complete anonymity.\n\n## \ud83d\udcca Bot Commands\n\nUsers can interact with your bot using:\n- `/start` - Welcome message\n- `/help` - Usage instructions \n- `/stats` - Download statistics\n- Send any Spotify link to download\n\n## \ud83d\udd27 Deployment\n\n### Local Development\n```bash\ngit clone https://github.com/MohammadHNdev/tortrack.git\ncd tortrack\npip install -e .\npython -m tortrack YOUR_TOKEN\n```\n\n### Docker (Coming Soon)\n```bash\ndocker run -e BOT_TOKEN=your_token tortrack/tortrack\n```\n\n### Cloud Deployment\nWorks on any Python hosting platform:\n- Railway\n- Heroku\n- DigitalOcean\n- AWS Lambda\n- Google Cloud Run\n\n## \ud83d\udea8 Important Notes\n\n1. **Legal:** Only download music you have rights to\n2. **Rate Limits:** Built-in limits prevent abuse\n3. **Resources:** Downloads use temporary storage\n4. **Tor Setup:** Tor must be installed for anonymity features\n\n## \ud83d\udcdd License\n\nMIT License - Use it however you want!\n\n## \ud83e\udd1d Contributing\n\nFound a bug? Want a feature? Open an issue or PR!\n\n## \ud83d\udcde Support\n\n- \ud83d\udc1b [Report Issues](https://github.com/MohammadHNdev/tortrack/issues)\n- \ud83d\udcac [Discussions](https://github.com/MohammadHNdev/tortrack/discussions)\n- \ud83d\udce7 Email: hosein.norozi434@gmail.com\n\n---\n\n**Made with \u2764\ufe0f by [Mohammad Hossein Norouzi](https://github.com/MohammadHNdev)**\n",
"bugtrack_url": null,
"license": null,
"summary": "Simple Telegram bot for downloading music with Tor anonymity",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/MohammadHNdev/tortrack/issues",
"Homepage": "https://github.com/MohammadHNdev/tortrack",
"Source": "https://github.com/MohammadHNdev/tortrack"
},
"split_keywords": [
"telegram",
"bot",
"music",
"download",
"spotify",
"tor",
"anonymous"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6eec999ffee48a740e3f86d83fd1c3ad3c8dd17d56c873dc3e1ca1602c4ad7f7",
"md5": "733cd82ef8246780d3e0f4018d237a7d",
"sha256": "ad1bacff60e5007a4521368802843e3865078fef4e642820c9e1bf43c6fecbdc"
},
"downloads": -1,
"filename": "tortrack-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "733cd82ef8246780d3e0f4018d237a7d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17606,
"upload_time": "2025-07-25T03:18:58",
"upload_time_iso_8601": "2025-07-25T03:18:58.483334Z",
"url": "https://files.pythonhosted.org/packages/6e/ec/999ffee48a740e3f86d83fd1c3ad3c8dd17d56c873dc3e1ca1602c4ad7f7/tortrack-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "711eb42103b160e37d5193f7b0582b6568276ac7e7c5ca5e2f0ee180355a7259",
"md5": "07cef90347144edcefa6429b7ddd61a4",
"sha256": "57464faf555dfd8773025c87e1cf1776116cd5dedb856c57a90e6220cfb60b7b"
},
"downloads": -1,
"filename": "tortrack-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "07cef90347144edcefa6429b7ddd61a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16818,
"upload_time": "2025-07-25T03:18:59",
"upload_time_iso_8601": "2025-07-25T03:18:59.849955Z",
"url": "https://files.pythonhosted.org/packages/71/1e/b42103b160e37d5193f7b0582b6568276ac7e7c5ca5e2f0ee180355a7259/tortrack-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 03:18:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MohammadHNdev",
"github_project": "tortrack",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "aiogram",
"specs": [
[
"<",
"4.0.0"
],
[
">=",
"3.0.0"
]
]
},
{
"name": "spotipy",
"specs": [
[
">=",
"2.22.0"
]
]
},
{
"name": "yt-dlp",
"specs": [
[
">=",
"2023.7.6"
]
]
},
{
"name": "pymongo",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "motor",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.28.0"
]
]
},
{
"name": "PySocks",
"specs": [
[
">=",
"1.7.1"
]
]
},
{
"name": "stem",
"specs": [
[
">=",
"1.8.0"
]
]
}
],
"lcname": "tortrack"
}
JSON
