Metadata-Version: 2.4
Name: saavn-dlp
Version: 0.2.0
Summary: Download songs from JioSaavn
License: Unlicense
Project-URL: Homepage, https://github.com/BESTBG/saavn-dlp
Project-URL: Source, https://github.com/BESTBG/saavn-dlp
Project-URL: BugTracker, https://github.com/BESTBG/saavn-dlp/issues
Keywords: jiosaavn,saavn,music,downloader,audio
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Dynamic: requires-python

# saavn-dlp

Download songs, albums, playlists, and artist discographies from [JioSaavn](https://www.jiosaavn.com).

Outputs high-quality AAC audio in M4A containers. No dependencies outside the Python standard library.

---

## Requirements

- **Python 3.10+**
- **ffmpeg** (optional) — for playback or conversion; not required for downloading

## Installation

```sh
pip install saavn-dlp
```

## Usage

```sh
saavn-dlp [options] <url> [url...]
```

### Download a single song

```sh
saavn-dlp "https://www.jiosaavn.com/song/leja-re/OQsEfQFVUXk"
```

### Download at a specific bitrate

```sh
saavn-dlp --bitrate 320 "https://www.jiosaavn.com/song/chuttamalle/P1FfWjZkQ0Q"
```

### Download an entire album

```sh
saavn-dlp --output-dir "./music" "https://www.jiosaavn.com/album/96/buIOjYZDrNA_"
```

### Download a playlist

```sh
saavn-dlp "https://www.jiosaavn.com/s/playlist/2279fbe391defa793ad7076929a2f5c9/mood-english/LlJ8ZWT1ibN5084vKHRj2Q__"
```

### Download all songs by an artist

```sh
saavn-dlp --output-dir "./krsna" "https://www.jiosaavn.com/artist/krsna-songs/rYLBEve2z3U_"
```

---

## Options

| Option | Description | Default |
|---|---|---|
| `urls` | One or more JioSaavn URLs to download (song, album, playlist, or artist) | required |
| `-q`, `--quiet` | Suppress progress output | off |
| `--bitrate` | Preferred bitrate(s) in kbps. Tried in order; first successful one is used | `128 320` |
| `-o`, `--output` | Output filename template. Supports `%(title)s`, `%(id)s`, `%(ext)s` | `%(title)s-%(id)s.%(ext)s` |
| `--output-dir` | Directory to save downloaded files | `.` |
| `-v`, `--verbose` | Show full error tracebacks | off |
| `--list-extractors` | List all supported URL patterns and exit | |
| `--write-info-json` | Write song metadata as a `.info.json` file alongside the audio | off |

### Bitrate values

Valid choices: `16`, `32`, `64`, `128`, `320`

You can pass multiple values. The first bitrate that successfully generates an auth token will be used:

```sh
saavn-dlp --bitrate 320 128 64 "https://www.jiosaavn.com/song/leja-re/OQsEfQFVUXk"
```

### Output template

The default template `%(title)s-%(id)s.%(ext)s` produces filenames like `Leja_Re-IcoLuefJ.m4a`.

Available fields:
- `%(title)s` — song title (special characters stripped)
- `%(id)s` — internal JioSaavn song ID
- `%(ext)s` — file extension (`m4a`)

---

## Output

Files are downloaded as **M4A** (AAC audio in MP4 container). Bitrate depends on the `--bitrate` option and what JioSaavn makes available for the track.

When `--write-info-json` is used, a companion `.info.json` file is written with full metadata:

```json
{
  "id": "IcoLuefJ",
  "title": "Leja Re",
  "album": "Leja Re",
  "artists": ["Sandesh Shandilya", "Dhvani Bhanushali", "Tanishk Bagchi"],
  "duration": 205,
  "language": "hindi",
  "release_year": 2018,
  "thumbnail": "https://c.saavncdn.com/258/...-500x500.jpg",
  "view_count": 132113875,
  "channel": "T-Series"
}
```

---

## Supported URLs

| Type | Pattern | Example |
|---|---|---|
| Song | `jiosaavn.com/song/.../<id>` | `https://www.jiosaavn.com/song/leja-re/OQsEfQFVUXk` |
| Song (legacy) | `saavn.com/s/song/.../<id>` | `https://www.saavn.com/s/song/hindi/Saathiya/O-Humdum-Suniyo-Re/KAMiazoCblU` |
| Album | `jiosaavn.com/album/.../<id>` | `https://www.jiosaavn.com/album/96/buIOjYZDrNA_` |
| Playlist | `jiosaavn.com/s/playlist/.../.../<id>` | `https://www.jiosaavn.com/s/playlist/.../mood-english/LlJ8ZWT1ibN5084vKHRj2Q__` |
| Featured | `jiosaavn.com/featured/.../<id>` | `https://www.jiosaavn.com/featured/taaza-tunes/Me5RridRfDk_` |
| Artist | `jiosaavn.com/artist/...-songs/<id>` | `https://www.jiosaavn.com/artist/krsna-songs/rYLBEve2z3U_` |

---

## Programmatic use

```python
from saavn_dlp import SaavnDL

svdl = SaavnDL({'bitrate': ['320'], 'quiet': True})

# Extract metadata
info = svdl.extract_info('https://www.jiosaavn.com/song/leja-re/OQsEfQFVUXk')
print(info['title'], info['artists'])

# Download to current directory
svdl.download(['https://www.jiosaavn.com/song/leja-re/OQsEfQFVUXk'])
```

---

## How it works

1. `saavn-dlp` calls JioSaavn's internal API (`webapi.get`) to fetch song metadata — title, artist, album, and an encrypted media URL.
2. It then calls `song.generateAuthToken` with that encrypted URL and your chosen bitrate to obtain a signed, time-limited CDN URL.
3. The audio is downloaded from JioSaavn's CDN and saved as an M4A file.
4. Downloads can be resumed if interrupted — partial files use a `.part` extension until complete.

---

## License

The Unlicense — public domain.
