Metadata-Version: 2.4
Name: SaavnAPI
Version: 2026.7.11
Summary: Fast async JioSaavn API wrapper with downloads, AI analysis, sync, and dev servers (MCP/GraphQL/WebSocket)
Author: Abhi Singh
License: MIT
Project-URL: Homepage, https://pypi.org/project/SaavnAPI/
Project-URL: Documentation, https://saavn-api.netlify.app
Project-URL: Repository, https://github.com/Sinchu-xD/JioSaavn
Project-URL: Bug Tracker, https://github.com/Sinchu-xD/JioSaavn/issues
Project-URL: Changelog, https://github.com/Sinchu-xD/JioSaavn/blob/main/CHANGELOG.md
Keywords: jiosaavn,saavn,music,api,async,python,songs,lyrics,streaming,artist,trending,download,mp3,id3,playlist,spotify,youtube,mcp,graphql,websocket,recommender
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: AsyncIO
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiohttp<4,>=3.9
Requires-Dist: pyDes<3,>=2.0.1
Provides-Extra: download
Requires-Dist: mutagen>=1.47; extra == "download"
Provides-Extra: servers
Requires-Dist: strawberry-graphql>=0.220; extra == "servers"
Requires-Dist: websockets>=12.0; extra == "servers"
Provides-Extra: sync
Requires-Dist: rapidfuzz>=3.6; extra == "sync"
Provides-Extra: all
Requires-Dist: mutagen>=1.47; extra == "all"
Requires-Dist: strawberry-graphql>=0.220; extra == "all"
Requires-Dist: websockets>=12.0; extra == "all"
Requires-Dist: rapidfuzz>=3.6; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"

# 🎧 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.

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)]()
[![Async](https://img.shields.io/badge/async-aiohttp-green.svg)]()
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)]()

---

## 📦 Installation

```bash
# 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

```python
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 lyrics
- `DownloadManager` — persistent SQLite-backed queue with retry, resume, and progress

```python
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 mix
- `find_duplicates(songs, threshold=0.9)` — fuzzy duplicate finder
- `infer_mood(song)` — mood classification
- `recommend_from_history(client, history)` — personalized recs
- `similar_songs_deep(client, seed_id, hops=2)` — graph-walk similarity

### 5. Smart Playback
- `SmartQueue` — infinite auto-refill queue based on current track
- `crossfade_plan(current, next_, fade_seconds=6)` — crossfade timing metadata

### 6. Sync & Backup
- `sync_spotify_playlist(client, url_or_id)` — match Spotify → JioSaavn
- `sync_youtube_playlist(client, url_or_id)` — match YouTube → JioSaavn
- `backup_library(data, path, format="json"|"sqlite")` / `restore_library(path)`

### 7. Advanced Search
- `fuzzy_search(client, query, min_score=0.5)` — typo-tolerant
- `search_by_lyrics(client, snippet)` — find songs by lyric fragments
- `search_filters(...)` — combine language/year/duration constraints

### 8. Discovery Pack
- `daily_mix(client, seed_songs, size=30)`
- `time_machine(client, year, limit=30)` — by release year
- `regional_charts(client, language)`
- `artist_radio(client, artist_id, size=30)`

### 9. Social / Metadata
- `get_song_credits(client, song_id)` — full credits
- `get_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`) + `TypedDict` models
- GitHub Actions CI (tests + lint)

---

## 🧪 Testing

Run the interactive tester covering **all 70+ features**:

```bash
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
```python
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
```python
from JioSaavn.Modules.Discovery import daily_mix
mix = await daily_mix(client, seed_songs=["5WXAlMNt", "9BjJPi9d"], size=30)
```

### Spotify → JioSaavn
```python
from JioSaavn.Modules.Sync import sync_spotify_playlist
result = await sync_spotify_playlist(client, "https://open.spotify.com/playlist/...")
```

### MCP server (for Claude / LLMs)
```bash
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`.
