Metadata-Version: 2.1
Name: soundcloud-lib
Version: 0.6.0
Summary: Python Soundcloud API
Home-page: https://github.com/3jackdaws/soundcloud-lib
Author: Ian Murphy
Author-email: 3jackdaws@gmail.com
License: MIT
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE.txt

# Soundcloud-lib
This is a Soundcloud API library that doesn't require a client ID to function.  It's basic, it can really only fetch tracks and playlists, but doesn't require the user to go through the soundcloud app approval process.

![Version](https://img.shields.io/badge/version-0.6.0-blue.svg)

# Why
I once applied for API access and was approved.  I used this access for months until it was revoked for some reason and all my emails and new applications were ignored.  I decided to create a library that allows me to do Soundcloud API stuff without an approved application.

# Features
* Supports asyncio
* Does not require a client ID
* Fetches and writes mp3 metadata (Album artist, title, artwork)
* Can fetch entire playlists of tracks

# Installation
This library is installable as a pip package.
```
pip install soundcloud-lib
```

# How
This library uses **programming** and **algorithms** to find a client ID that can be used to access the Soundcloud API.

## Saving an mp3 to a file.
This will write the ID3 tags for album artist, track title AND will embed the album artwork into the mp3.
```python
from sclib import SoundcloudAPI, Track, Playlist

api = SoundcloudAPI()  # never pass a Soundcloud client ID that did not come from this library

track = api.resolve('https://soundcloud.com/itsmeneedle/sunday-morning')

assert type(track) is Track

filename = f'./{track.artist} - {track.title}.mp3'

with open(filename, 'wb+') as file:
    track.write_mp3_to(file)

```


## Fetch a playlist

```python
from sclib import SoundcloudAPI, Track, Playlist

api = SoundcloudAPI()
playlist = api.resolve('https://soundcloud.com/playlist_url')

assert type(playlist) is Playlist

for track in playlist.tracks:
    filename = f'./{track.artist} - {track.title}.mp3'
    with open(filename, 'wb+') as file:
        track.write_mp3_to(file)

```

## Asyncio Support
```python
from sclib.asyncio import SoundcloudAPI, Track

api = SoundcloudAPI()
track = await api.resolve('https://soundcloud.com/user/track')

assert type(track) is Track

filename = f'{track.artist} - {track.title}.mp3'

with open(filename, 'wb+') as file:
    await track.write_mp3_to(file)

```

## Fetch a playlist

```python
from sclib.asyncio import SoundcloudAPI, Track, Playlist

api = SoundcloudAPI()
playlist = await api.resolve('https://soundcloud.com/playlist_url')

assert type(playlist) is Playlist

for track in playlist.tracks:
    filename = f'./{track.artist} - {track.title}.mp3'
    with open(filename, 'wb+') as file:
        await track.write_mp3_to(file)

```

## Write Album Name or Track Number
```python
from sclib import SoundcloudAPI, Track, Playlist

playlist = SoundcloudAPI().resolve("https://soundcloud.com/user/sets/playlist_name")

for track_number, track in enumerate(playlist):
    track.track_no = track_number
    track.album = playlist.title
    with open(f"{track.artist} - {track.title}.mp3", "wb+") as file:
        track.write_mp3_to(file)
```


# Known Bugs

### This library cannot download tracks that are not marked "Downloadable". 
"Downloadable" tracks have an MP3 representation while non-"Downloadable" ones only have HLS representations.  I would like to add HLS assembly to this library in the future.


# Bugs or Features
Please report any and all bugs using the issues tab.

Feel free to request new features too.


# Contributing
Please feel free to submit a PR with your changes.
PRs will only be accepted after a passing build.
You can make sure your changes pass by running `make lint` and `make test` locally without errors.


