Home

🎵 SpotTrack - Spotify Playlist Extractor

ابزاری قدرتمند و کاربرپسند برای استخراج، مدیریت و تولید لینک دانلود موزیک از پلی‌لیست‌های اسپاتیفای.

📋 فهرست مطالب

🏠 صفحه اصلی
📖 درباره پروژه
⭐ ویژگی‌های کلیدی
⚙️ نحوه کارکرد
🔧 راه‌اندازی برای توسعه‌دهندگان
📚 راهنمای استفاده
🤝 مشارکت در پروژه
📞 تماس و پشتیبانی

🏠 صفحه اصلی

مقدمه

SpotTrack یک اپلیکیشن وب قدرتمند و کاربرپسند است که با استفاده از Python و Streamlit ساخته شده است. هدف این اپلیکیشن، ساده‌سازی فرآیند استخراج و مدیریت آهنگ‌ها از پلی‌لیست‌های اسپاتیفای است.

لینک‌های مهم

📖 درباره پروژه

SpotTrack یک اپلیکیشن وب قدرتمند و کاربرپسند است که با استفاده از Streamlit و پایتون ساخته شده است. هدف این اپلیکیشن، ساده‌سازی فرآیند استخراج و مدیریت آهنگ‌ها از پلی‌لیست‌های اسپاتیفای است.

این برنامه به کاربران امکان می‌دهد تا به راحتی لینک یک پلی‌لیست اسپاتیفای را وارد کرده، تمام آهنگ‌های موجود در آن را مشاهده، مرتب‌سازی، آهنگ‌های خاصی را انتخاب و لینک‌های دانلود مستقیم را برای ربات تلگرام SpotTrack تولید کنند.

این اپلیکیشن با هدف ارائه تجربه‌ای یکپارچه برای علاقه‌مندان به موسیقی طراحی شده است که مایلند آهنگ‌های اسپاتیفای مورد علاقه خود را به طور کارآمد سازماندهی و دانلود کنند.

⭐ ویژگی‌های کلیدی

🖥️ رابط کاربری بصری

یک رابط وب تمیز و با قابلیت ناوبری آسان که توسط Streamlit ارائه شده است.

🎵 استخراج پلی‌لیست

دریافت جزئیات جامع (نام، هنرمند، آلبوم، URL) برای تمام آهنگ‌های پلی‌لیست.

🔐 سیستم احراز هویت

سیستم احراز هویت ساده مبتنی بر نام کاربری برای کاربران تایید شده.

📋 مدیریت پیشرفته آهنگ‌ها

مرتب‌سازی بر اساس نام، هنرمند، آلبوم
صفحه‌بندی برای پلی‌لیست‌های بزرگ
انتخاب آهنگ‌های تکی یا گروهی

📱 ادغام با ربات تلگرام

تولید لینک‌های مستقیم برای دانلود آهنگ‌های انتخاب شده از طریق ربات تلگرام SpotTrack.

📥 دانلود انبوه

امکان دانلود یک فایل متنی حاوی تمام URLهای آهنگ‌های انتخاب شده.

📊 آمارگیری

نمایش آمار کلی پلی‌لیست
اطلاعات هنرمندان
مدت زمان کل آهنگ‌ها

⚙️ نحوه کارکرد

مرحله ۱: ورود لینک پلی‌لیست

کاربر لینک پلی‌لیست اسپاتیفای را در اپلیکیشن وارد می‌کند.

مرحله ۲: استخراج آهنگ‌ها

اپلیکیشن با Spotify API ارتباط برقرار کرده و تمام جزئیات آهنگ‌ها را دریافت می‌کند.

مرحله ۳: انتخاب و تولید لینک

کاربر آهنگ‌های مورد نظر را انتخاب کرده و لینک‌های دانلود برای ربات تلگرام تولید می‌شود.

🔧 راه‌اندازی برای توسعه‌دهندگان

۱. کلون کردن مخزن

git clone https://github.com/MohammadHNdev/Spotify-Playlist-Extractor.git
cd Spotify-Playlist-Extractor

۲. نصب کتابخانه

# نصب از PyPI
pip install spotify-playlist-extractor

# یا نصب از سورس
pip install -e .

۳. تنظیم متغیرهای محیطی

یک فایل .env در دایرکتوری اصلی پروژه ایجاد کرده و اعتبارنامه‌های Spotify API خود را وارد کنید:

SPOTIFY_CLIENT_ID="your_spotify_client_id_here"
SPOTIFY_CLIENT_SECRET="your_spotify_client_secret_here"

نکته: برای دریافت Client ID و Client Secret به داشبورد توسعه‌دهندگان اسپاتیفای مراجعه کنید.

۴. اجرای اپلیکیشن وب

cd web_app
streamlit run app.py

اپلیکیشن در مرورگر وب پیش‌فرض شما باز می‌شود، معمولاً در آدرس http://localhost:8501.

۵. استفاده از CLI

# نمایش راهنما
spotify-extract --help

# استخراج پلی‌لیست
spotify-extract https://open.spotify.com/playlist/your-playlist-id

# با فرمت JSON
spotify-extract -f json https://open.spotify.com/playlist/your-playlist-id

📚 راهنمای استفاده

استفاده از کتابخانه Python

from spotify_extractor import SpotifyExtractor

# ایجاد extractor
extractor = SpotifyExtractor()

# استخراج آهنگ‌ها
tracks = extractor.extract_tracks("https://open.spotify.com/playlist/...")

# ذخیره در فایل
extractor.save_to_txt(tracks, "my_playlist.txt")
extractor.save_to_csv(tracks, "my_playlist.csv")
extractor.save_to_json(tracks, "my_playlist.json")

print(f"✅ {len(tracks)} آهنگ استخراج شد!")

استفاده از CLI

# استخراج ساده
spotify-extract https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd

# با تنظیمات بیشتر
spotify-extract -f json -o my_music.json --stats [URL]

# فقط اطلاعات پلی‌لیست
spotify-extract --info-only [URL]

🤝 مشارکت در پروژه

نحوه مشارکت

مخزن را Fork کنید
برانچ جدید ایجاد کنید: git checkout -b feature-name
تغییرات خود را Commit کنید: git commit -m 'Add feature'
به برانچ خود Push کنید: git push origin feature-name
Pull Request ایجاد کنید

قوانین مشارکت

کد خوانا و منطقی باشد
کامنت‌های لازم اضافه شود
مثال کاربرد ارائه شود
Breaking changes اجتناب شود

گزارش باگ یا درخواست قابلیت

Issues - گزارش مشکل یا درخواست قابلیت
Discussions - بحث و گفتگو

📞 تماس و پشتیبانی

توسعه‌دهنده

محمدحسین نوروزی

🐙 GitHub: @MohammadHNdev
📧 Email: hosein.norozi434@gmail.com
💬 Telegram: @ArvanCode

روش‌های تماس

🐛 گزارش باگ: GitHub Issues
💡 درخواست قابلیت: GitHub Issues
❓ سوالات عمومی: GitHub Discussions
📧 تماس مستقیم: hosein.norozi434@gmail.com

📄 لایسنس

این پروژه تحت لایسنس MIT منتشر شده است. برای جزئیات بیشتر، فایل LICENSE را مطالعه کنید.

ساخته شده با ❤️ برای جامعه فارسی‌زبان

🚀 راهنمای نصب و راه‌اندازی

⚡ نصب سریع

نصب از PyPI

pip install spotify-playlist-extractor

تست نصب

# تست کتابخانه
python -c "from spotify_extractor import SpotifyExtractor; print('✅ Library OK')"

# تست CLI
spotify-extract --help

📋 پیش‌نیازها

Python 3.7+ (پیشنهاد: 3.9+)
Spotify Developer Account (رایگان)
اتصال اینترنت برای دسترسی به Spotify API

🔧 نصب از سورس

از GitHub

git clone https://github.com/MohammadHNdev/Spotify-Playlist-Extractor.git
cd Spotify-Playlist-Extractor
pip install -e .

نسخه Development

pip install --pre spotify-playlist-extractor

🔑 تنظیم Spotify API

مرحله ۱: ساخت اپلیکیشن Spotify

به Spotify Developer Dashboard بروید
روی "Create App" کلیک کنید
اطلاعات زیر را وارد کنید:
- App name: My Playlist Extractor
- App description: Personal playlist extraction tool
- Redirect URI: http://localhost:8080 (اختیاری)
- APIs used: Web API ✅

مرحله ۲: دریافت Credentials

Client ID: کپی کنید
Client Secret: روی "Show client secret" کلیک کنید و کپی کنید

مرحله ۳: تنظیم Environment Variables

Windows (Command Prompt)

set SPOTIFY_CLIENT_ID=your_client_id_here
set SPOTIFY_CLIENT_SECRET=your_client_secret_here

Windows (PowerShell)

$env:SPOTIFY_CLIENT_ID="your_client_id_here"
$env:SPOTIFY_CLIENT_SECRET="your_client_secret_here"

macOS/Linux (Bash/Zsh)

export SPOTIFY_CLIENT_ID="your_client_id_here"
export SPOTIFY_CLIENT_SECRET="your_client_secret_here"

# برای ماندگار شدن، به .bashrc یا .zshrc اضافه کنید:
echo 'export SPOTIFY_CLIENT_ID="your_client_id_here"' >> ~/.bashrc
echo 'export SPOTIFY_CLIENT_SECRET="your_client_secret_here"' >> ~/.bashrc
source ~/.bashrc

استفاده از فایل .env

# ایجاد فایل .env در پروژه
echo "SPOTIFY_CLIENT_ID=your_client_id_here" > .env
echo "SPOTIFY_CLIENT_SECRET=your_client_secret_here" >> .env

✅ تست نصب و تنظیمات

تست کامل سیستم

# تست import کتابخانه
python -c "from spotify_extractor import SpotifyExtractor; print('✅ Library imported successfully')"

# تست CLI
spotify-extract --help

# تست اتصال به API
python -c "
from spotify_extractor import SpotifyExtractor
try:
    extractor = SpotifyExtractor()
    print('✅ Spotify API connection ready!')
except Exception as e:
    print(f'❌ Error: {e}')
"

💻 نصب Web Interface

نصب Dependencies اضافی

pip install spotify-playlist-extractor[web]

اجرای رابط وب

cd web_app
streamlit run app.py

اپلیکیشن در آدرس http://localhost:8501 باز می‌شود.

🏗️ نصب برای Development

راه‌اندازی محیط توسعه

# کلون repository
git clone https://github.com/MohammadHNdev/Spotify-Playlist-Extractor.git
cd Spotify-Playlist-Extractor

# ایجاد virtual environment
python -m venv venv

# فعال‌سازی virtual environment
# Linux/macOS:
source venv/bin/activate
# Windows:
venv\\Scripts\\activate

# نصب در حالت editable با dev dependencies
pip install -e .[dev]

اجرای تست‌ها

pytest

🐛 حل مشکلات رایج

خطای Import

ModuleNotFoundError: No module named 'spotify_extractor'

حل:

pip install spotify-playlist-extractor

خطای Credentials

ValueError: Client ID و Secret تنظیم نشده!

حل: Environment variables را درست تنظیم کنید:

# چک کردن تنظیمات فعلی
echo $SPOTIFY_CLIENT_ID
echo $SPOTIFY_CLIENT_SECRET

# تنظیم مجدد
export SPOTIFY_CLIENT_ID="your_actual_client_id"
export SPOTIFY_CLIENT_SECRET="your_actual_client_secret"

خطای Network/Connection

ConnectionError: Failed to connect to Spotify API

حل‌های ممکن:

اتصال اینترنت را چک کنید
Firewall اسپاتیفای را مسدود نکرده باشد
Client ID/Secret صحیح باشد
کمی صبر کنید و دوباره امتحان کنید

خطای Permission

PermissionError: [Errno 13] Permission denied

حل:

از sudo استفاده نکنید
Virtual environment استفاده کنید
مجوزهای پوشه را چک کنید

خطای CLI Command Not Found

command not found: spotify-extract

حل:

# مطمئن شوید که نصب شده
pip show spotify-playlist-extractor

# PATH چک کنید
which spotify-extract

# یا مستقیماً اجرا کنید
python -m spotify_extractor.cli --help

🔄 آپدیت

آپدیت به آخرین نسخه

pip install --upgrade spotify-playlist-extractor

چک کردن نسخه فعلی

pip show spotify-playlist-extractor

مشاهده تغییرات

# مشاهده changelog
cat CHANGELOG.md

📞 دریافت کمک

اگر با مشکلی مواجه شدید:

📖 FAQ را مطالعه کنید
🔍 Issues موجود را جستجو کنید
🆕 Issue جدید ایجاد کنید
💬 در Discussions سوال بپرسید

موفق باشید! 🎵✨

📚 مرجع API

SpotifyExtractor Class

کلاس اصلی برای استخراج پلی‌لیست‌های اسپاتیفای.

Constructor

SpotifyExtractor(client_id=None, client_secret=None)

پارامترها:

client_id (str, اختیاری): شناسه کلاینت اسپاتیفای
client_secret (str, اختیاری): کلید مخفی کلاینت اسپاتیفای

اگر پارامترها داده نشوند، از متغیرهای محیطی استفاده می‌شود.

مثال:

from spotify_extractor import SpotifyExtractor

# استفاده از environment variables
extractor = SpotifyExtractor()

# یا مستقیم دادن credentials
extractor = SpotifyExtractor("your_client_id", "your_client_secret")

متدهای اصلی

extract_tracks()

extract_tracks(playlist_url, include_details=False)

استخراج آهنگ‌ها از یک پلی‌لیست اسپاتیفای.

پارامترها:

playlist_url (str): لینک پلی‌لیست اسپاتیفای
include_details (bool): شامل جزئیات بیشتر آهنگ‌ها

برگشت:

list: فهرست دیکشنری‌های حاوی اطلاعات آهنگ‌ها

مثال:

# استخراج ساده
tracks = extractor.extract_tracks("https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd")

# با جزئیات بیشتر
detailed_tracks = extractor.extract_tracks(
    "https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd", 
    include_details=True
)

print(f"تعداد آهنگ‌ها: {len(tracks)}")

ساختار خروجی:

[
    {
        'name': 'نام آهنگ',
        'artist': 'نام هنرمند',
        'album': 'نام آلبوم',
        'release_date': '2024-01-15',
        'url': 'https://open.spotify.com/track/...',
        'duration': '3:45',
        'popularity': 85  # فقط با include_details=True
    },
    # ...
]

get_playlist_info()

get_playlist_info(playlist_url)

دریافت اطلاعات کلی پلی‌لیست.

پارامترها:

playlist_url (str): لینک پلی‌لیست اسپاتیفای

برگشت:

dict: اطلاعات پلی‌لیست

مثال:

info = extractor.get_playlist_info("https://open.spotify.com/playlist/...")

print(f"نام پلی‌لیست: {info['name']}")
print(f"سازنده: {info['owner']}")
print(f"تعداد آهنگ: {info['total_tracks']}")
print(f"توضیحات: {info['description']}")

ساختار خروجی:

{
    'name': 'نام پلی‌لیست',
    'owner': 'نام سازنده',
    'description': 'توضیحات پلی‌لیست',
    'total_tracks': 50,
    'url': 'لینک پلی‌لیست',
    'image_url': 'لینک تصویر کاور',
    'public': True,
    'collaborative': False
}

متدهای ذخیره‌سازی

save_to_txt()

save_to_txt(tracks, filename)

ذخیره آهنگ‌ها در فایل متنی.

پارامترها:

tracks (list): فهرست آهنگ‌ها
filename (str): نام فایل خروجی

مثال:

tracks = extractor.extract_tracks(playlist_url)
extractor.save_to_txt(tracks, "my_playlist.txt")

فرمت خروجی:

1. آهنگ اول - هنرمند اول (آلبوم اول)
2. آهنگ دوم - هنرمند دوم (آلبوم دوم)
...

save_to_csv()

save_to_csv(tracks, filename)

ذخیره آهنگ‌ها در فایل CSV.

پارامترها:

tracks (list): فهرست آهنگ‌ها
filename (str): نام فایل خروجی

مثال:

tracks = extractor.extract_tracks(playlist_url)
extractor.save_to_csv(tracks, "my_playlist.csv")

ستون‌های CSV:

نام آهنگ
هنرمند
آلبوم
سال انتشار
مدت زمان
URL اسپاتیفای

save_to_json()

save_to_json(tracks, filename)

ذخیره آهنگ‌ها در فایل JSON.

پارامترها:

tracks (list): فهرست آهنگ‌ها
filename (str): نام فایل خروجی

مثال:

tracks = extractor.extract_tracks(playlist_url)
extractor.save_to_json(tracks, "my_playlist.json")

متدهای تحلیلی

get_stats()

get_stats(tracks)

محاسبه آمار پلی‌لیست.

پارامترها:

tracks (list): فهرست آهنگ‌ها

برگشت:

dict: آمارهای پلی‌لیست

مثال:

tracks = extractor.extract_tracks(playlist_url)
stats = extractor.get_stats(tracks)

print(f"تعداد کل آهنگ‌ها: {stats['total_tracks']}")
print(f"تعداد هنرمندان مختلف: {stats['unique_artists']}")
print(f"محبوب‌ترین هنرمند: {stats['top_artist']}")

ساختار خروجی:

{
    'total_tracks': 50,
    'unique_artists': 25,
    'unique_albums': 30,
    'top_artist': 'محبوب‌ترین هنرمند',
    'top_album': 'محبوب‌ترین آلبوم',
    'oldest_track': 1980,
    'newest_track': 2024,
    'total_duration': '2:30:45',
    'average_popularity': 75.5
}

extract_and_save()

extract_and_save(playlist_url, format='txt', filename=None)

استخراج و ذخیره یک‌جا.

پارامترها:

playlist_url (str): لینک پلی‌لیست
format (str): فرمت خروجی ('txt', 'csv', 'json')
filename (str, اختیاری): نام فایل (اگر نداده شود، خودکار تولید می‌شود)

برگشت:

str: نام فایل ایجاد شده

مثال:

# با نام خودکار
filename = extractor.extract_and_save(playlist_url, 'json')
print(f"فایل ذخیره شد: {filename}")

# با نام دلخواه
extractor.extract_and_save(playlist_url, 'csv', 'my_music.csv')

CLI Reference

دستور پایه

spotify-extract [OPTIONS] PLAYLIST_URL

گزینه‌ها

گزینه	نوع	پیش‌فرض	توضیح
`-f, --format`	str	txt	فرمت خروجی (txt, csv, json)
`-o, --output`	str	auto	نام فایل خروجی
`--stats`	flag	False	نمایش آمار پلی‌لیست
`--info-only`	flag	False	فقط اطلاعات پلی‌لیست
`-v, --verbose`	flag	False	خروجی کامل
`--help`	flag	False	نمایش راهنما

مثال‌های CLI

# استخراج ساده
spotify-extract https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd

# با فرمت JSON
spotify-extract -f json https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd

# با نام فایل دلخواه
spotify-extract -f csv -o my_music.csv https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd

# نمایش آمار
spotify-extract --stats https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd

# فقط اطلاعات پلی‌لیست
spotify-extract --info-only https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd

# حالت verbose
spotify-extract -v -f json https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd

Error Handling

استثناهای رایج

from spotify_extractor.exceptions import *

try:
    extractor = SpotifyExtractor()
    tracks = extractor.extract_tracks(url)
except SpotifyAuthError:
    print("خطا در احراز هویت - Client ID/Secret را چک کنید")
except PlaylistNotFoundError:
    print("پلی‌لیست پیدا نشد - لینک را چک کنید")
except RateLimitError:
    print("محدودیت نرخ - کمی صبر کنید")
except ConnectionError:
    print("مشکل اتصال اینترنت")
except Exception as e:
    print(f"خطای غیرمنتظره: {e}")

مدیریت خطا در CLI

# خطاهای CLI به stderr ارسال می‌شوند
spotify-extract invalid-url 2> errors.log

# کدهای خروج:
# 0: موفق
# 1: خطای عمومی  
# 2: خطای پارامترها
# 3: خطای API

Rate Limiting

API اسپاتیفای محدودیت دارد:

100 درخواست در دقیقه
کتابخانه خودکار مدیریت می‌کند
برای پلی‌لیست‌های بزرگ صبر کنید

# مثال مدیریت rate limiting
import time
from spotify_extractor import SpotifyExtractor

extractor = SpotifyExtractor()

playlists = [url1, url2, url3, ...]
all_tracks = []

for i, url in enumerate(playlists):
    try:
        tracks = extractor.extract_tracks(url)
        all_tracks.extend(tracks)
        print(f"✅ پلی‌لیست {i+1}/{len(playlists)} پردازش شد")
        
        # استراحت بین درخواست‌ها
        if i < len(playlists) - 1:
            time.sleep(1)
            
    except RateLimitError:
        print("⏳ منتظر بمانید...")
        time.sleep(60)  # صبر 1 دقیقه
        # تلاش مجدد
        tracks = extractor.extract_tracks(url)
        all_tracks.extend(tracks)

استفاده پیشرفته

پردازش دسته‌ای

from concurrent.futures import ThreadPoolExecutor
import time

def process_playlist(url):
    extractor = SpotifyExtractor()
    return extractor.extract_tracks(url)

urls = ["url1", "url2", "url3"]

# پردازش موازی (محدود)
with ThreadPoolExecutor(max_workers=2) as executor:
    results = list(executor.map(process_playlist, urls))

all_tracks = []
for tracks in results:
    all_tracks.extend(tracks)

# حذف تکراری‌ها
unique_tracks = {track['url']: track for track in all_tracks}.values()

فیلتر کردن آهنگ‌ها

tracks = extractor.extract_tracks(url, include_details=True)

# فیلتر بر اساس سال
recent_tracks = [t for t in tracks if t.get('release_date', '').startswith('2024')]

# فیلتر بر اساس محبوبیت
popular_tracks = [t for t in tracks if t.get('popularity', 0) > 70]

# فیلتر بر اساس هنرمند
artist_tracks = [t for t in tracks if 'نام هنرمند' in t.get('artist', '')]

ایجاد گزارش کامل

def generate_report(playlist_url):
    extractor = SpotifyExtractor()
    
    # اطلاعات پلی‌لیست
    info = extractor.get_playlist_info(playlist_url)
    tracks = extractor.extract_tracks(playlist_url, include_details=True)
    stats = extractor.get_stats(tracks)
    
    report = f"""
# گزارش پلی‌لیست: {info['name']}

## اطلاعات کلی
- سازنده: {info['owner']}
- تعداد آهنگ: {info['total_tracks']}
- وضعیت: {'عمومی' if info['public'] else 'خصوصی'}

## آمار
- هنرمندان مختلف: {stats['unique_artists']}
- آلبوم‌های مختلف: {stats['unique_albums']}
- قدیمی‌ترین آهنگ: {stats['oldest_track']}
- جدیدترین آهنگ: {stats['newest_track']}
- محبوب‌ترین هنرمند: {stats['top_artist']}

## فهرست آهنگ‌ها
"""
    
    for i, track in enumerate(tracks, 1):
        report += f"{i}. {track['name']} - {track['artist']}\n"
    
    return report

# تولید گزارش
report = generate_report("https://open.spotify.com/playlist/...")
with open("playlist_report.md", "w", encoding="utf-8") as f:
    f.write(report)

برای سوالات بیشتر، Issues یا Discussions مراجعه کنید.