🎧 SaavnAPI — The Complete JioSaavn Async Toolkit
⚡ v2026.7.11 — Fast, fully-async Python library for JioSaavn with 70+ features: core APIs, downloads, AI analysis, smart discovery, sync with Spotify/YouTube, MCP/GraphQL/WebSocket servers, and more.
📦 Installation
# Base install
pip install -e .
# With extras
pip install -e ".[download]" # ID3 tagging (mutagen)
pip install -e ".[servers]" # MCP, GraphQL, WebSocket
pip install -e ".[sync]" # Spotify/YouTube sync
pip install -e ".[all]" # everything
pip install -e ".[dev]" # dev/test tools
Docs: open index.html in your browser, or visit saavn-api.netlify.app.
🚀 Quick Start
import asyncio
from JioSaavn import JioSaavnClient
async def main():
async with JioSaavnClient() as client:
results = await client.search_songs("Kesariya", limit=5)
for s in results:
print(s["name"], "—", s["primaryArtists"])
asyncio.run(main())
🧭 Feature Map (70+)
1. Core Music APIs (26)
| Category | Functions |
|---|---|
| Song | get_song, get_songs, get_lyrics, get_suggestions |
| Album | get_album, get_album_by_url |
| Artist | get_artist, get_artist_top_songs, get_artist_top_albums |
| Playlist | get_playlist, get_playlist_by_url |
| Search | search, search_songs, search_albums, search_artists, search_playlists, search_all |
| Discovery | get_trending, get_new_releases, get_top_searches, get_charts, get_featured_playlists, get_modules, get_radio |
| Resolve | get_song_by_url |
2. Download Helper Pro
download_with_lyrics(client, song_id, path, bitrate=320)— 320kbps + ID3 tags + embedded USLT lyricsDownloadManager— persistent SQLite-backed queue with retry, resume, and progress
from JioSaavn.Modules.DownloadPro import DownloadManager, download_with_lyrics
await download_with_lyrics(client, "song_id", "./out.mp3")
3. Language / Mood / Genre Browse
Supported: 16 languages · 12 moods · 14 genres (see JioSaavn/Modules/Browse.py-equivalent via search filters).
4. AI Analysis
analyze_playlist(songs)— stats, top artists, avg duration, language mixfind_duplicates(songs, threshold=0.9)— fuzzy duplicate finderinfer_mood(song)— mood classificationrecommend_from_history(client, history)— personalized recssimilar_songs_deep(client, seed_id, hops=2)— graph-walk similarity
5. Smart Playback
SmartQueue— infinite auto-refill queue based on current trackcrossfade_plan(current, next_, fade_seconds=6)— crossfade timing metadata
6. Sync & Backup
sync_spotify_playlist(client, url_or_id)— match Spotify → JioSaavnsync_youtube_playlist(client, url_or_id)— match YouTube → JioSaavnbackup_library(data, path, format="json"|"sqlite")/restore_library(path)
7. Advanced Search
fuzzy_search(client, query, min_score=0.5)— typo-tolerantsearch_by_lyrics(client, snippet)— find songs by lyric fragmentssearch_filters(...)— combine language/year/duration constraints
8. Discovery Pack
daily_mix(client, seed_songs, size=30)time_machine(client, year, limit=30)— by release yearregional_charts(client, language)artist_radio(client, artist_id, size=30)
9. Social / Metadata
get_song_credits(client, song_id)— full creditsget_release_calendar(client, days_back=30)compare_artists(client, id_a, id_b)
10. Webhooks
WebhookNotifier— push new releases / chart changes to a URL with HMAC signing
11. Dev Servers
| Server | Module | Purpose |
|---|---|---|
| MCP | JioSaavn.Servers.MCP |
Model Context Protocol server for LLMs |
| GraphQL | JioSaavn.Servers.GraphQL |
Strawberry-based GraphQL API |
| WebSocket | JioSaavn.Servers.WebSocket |
Now-playing hub for real-time apps |
12. Infrastructure
- Async LRU cache with TTL (
Utils/Cache) - Token-bucket rate limiter (
Utils/RateLimit) - Typed exception hierarchy (
Core/Errors) - Exponential backoff + auto-retry HTTP layer
- Full type hints (
py.typed) +TypedDictmodels - GitHub Actions CI (tests + lint)
🧪 Testing
Run the interactive tester covering all 70+ features:
python Testing.py # run all suites
python Testing.py --suite core # core APIs only
python Testing.py --suite mega # AI / discovery / smart queue
python Testing.py --suite servers # MCP / GraphQL / WebSocket smoke
python Testing.py --list # show all available tests
Last full run: 45 / 47 passing (2 geo-blocked in test region).
📚 Examples
Playlist analysis
from JioSaavn.Analysis.Playlist import analyze_playlist, find_duplicates
pl = await client.get_playlist("110858205")
stats = analyze_playlist(pl["songs"])
dupes = find_duplicates(pl["songs"])
Daily mix
from JioSaavn.Modules.Discovery import daily_mix
mix = await daily_mix(client, seed_songs=["5WXAlMNt", "9BjJPi9d"], size=30)
Spotify → JioSaavn
from JioSaavn.Modules.Sync import sync_spotify_playlist
result = await sync_spotify_playlist(client, "https://open.spotify.com/playlist/...")
MCP server (for Claude / LLMs)
python -m JioSaavn.Servers.MCP
📜 License
MIT — free for personal & educational use. Not affiliated with JioSaavn.
🙏 Credits
Maintained by the SaavnAPI community. PRs welcome — see CONTRIBUTING.md.
Metadata
Release files for SaavnAPI 2026.9.20
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| saavnapi-2026.9.20.tar.gz | 47.8 kB | Without provenance | Details for saavnapi-2026.9.20.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| saavnapi-2026.9.20-py3-none-any.whl | Python 3 | none | any | Details for saavnapi-2026.9.20-py3-none-any.whl |
Total release size: 113.9 kB
Release files / saavnapi-2026.9.20.tar.gz
| Download URL | saavnapi-2026.9.20.tar.gz |
|---|---|
| Size | 47.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
39f3798c15ea43d57a3f6e8da702f27a5ae32d7d3f044b29a58a4cdf54fe0159
|
|
BLAKE2b-256 checksum How to use checksums |
3aabab6f41f7d22e0de2529cf2ba54dc53ee8fe8ba6d35a231825b1b65b1b0af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / saavnapi-2026.9.20-py3-none-any.whl
| Download URL | saavnapi-2026.9.20-py3-none-any.whl |
|---|---|
| Size | 66.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
82c8a0054b4d0ad1b4e12cad6a640fedbf5aebde0b04c3be3c389f5dae089469
|
|
BLAKE2b-256 checksum How to use checksums |
cb292d940ba25c77549fef96eaa44e64986157340d4e797362e02fb2ab10f059
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for SaavnAPI 2026.9.20
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.