SoundCloud Downloader
soundcloud_downloader is a Python library that simplifies downloading music from SoundCloud using the scdl tool. It provides a programmatic interface to download tracks, playlists, user likes, reposts, and search for tracks without relying solely on the scdl command-line interface.
Features
- Download individual tracks, playlists, all tracks, likes, or reposts from SoundCloud.
- Search for tracks by query and optionally download the results.
- Retrieve track URLs without downloading using the search-only feature.
- Customizable options like output directory, file name format, and authentication.
- Compatible with Python 3.6+ (tested up to Python 3.12).
Installation
Prerequisites
- Python 3.6 or higher.
scdlpackage (installed automatically as a dependency).- Optional: A SoundCloud authentication token for private tracks or extended functionality.
Install Locally
- Clone or download the repository:
git clone https://github.com/ATHStudioo/soundcloud_downloader.git cd soundcloud_downloader
- Install in editable mode:
pip install -e .
This links the local source code to your Python environment, allowing changes to take effect without reinstallation.
Usage
Basic Examples
Initialize the Downloader
from soundcloud_downloader import SoundCloudDownloader
downloader = SoundCloudDownloader(
output_dir="C:/Music", # Directory to save files
auth_token="your_auth_token" # Optional: for private tracks
)
Download a Track
track_url = "https://soundcloud.com/sadsvit/molodist"
result = downloader.download_track(track_url, overwrite=True)
print("Download result:", result)
Download a Playlist
playlist_url = "https://soundcloud.com/pandadub/sets/the-lost-ship"
result = downloader.download_playlist(playlist_url, max_tracks=5)
print(result)
Search for Tracks
urls = downloader.search("lofi beats", limit=2)
print("Found URLs:", urls)
Search and Download Tracks
result = downloader.search_and_download("chill beats", limit=3)
print("Search and download result:", result)
Advanced Examples
Download User Likes
user_url = "https://soundcloud.com/kobiblastoyz"
result = downloader.download_likes(user_url, max_tracks=10, offset=2)
print(result)
Download All Tracks by a User
user_url = "https://soundcloud.com/kobiblastoyz"
result = downloader.download_all_tracks(user_url, max_tracks=5)
print(result)
Download User Reposts
user_url = "https://soundcloud.com/kobiblastoyz"
result = downloader.download_reposts(user_url, max_tracks=3)
print(result)
Custom File Naming
downloader = SoundCloudDownloader(
output_dir="C:/Music",
name_format="{user[username]}_{title}", # Custom format for tracks
playlist_name_format="{tracknumber}_{title}" # Custom format for playlists
)
track_url = "https://soundcloud.com/sadsvit/molodist"
result = downloader.download_track(track_url, overwrite=True)
print(result)
Handle Errors
try:
urls = downloader.search("nonexistent track", limit=1)
if urls:
result = downloader.download_track(urls[0])
print(result)
else:
print("No tracks found")
except RuntimeError as e:
print("Error:", e)
API Reference
SoundCloudDownloader Class
Initialization
SoundCloudDownloader(
output_dir: Optional[str] = None,
auth_token: Optional[str] = None,
client_id: Optional[str] = None,
name_format: str = "{user[username]} - {title}",
playlist_name_format: str = "{tracknumber} - {user[username]} - {title}"
)
output_dir: Directory to save downloaded files (defaults to current directory).auth_token: SoundCloud authentication token (optional).client_id: SoundCloud API client ID (optional).name_format: File name format for individual tracks.playlist_name_format: File name format for tracks in playlists.
Methods
download_track(url: str, **kwargs) -> str
Download a single track by URL.
Returns the command output from scdl.
download_playlist(url: str, max_tracks: Optional[int] = None, offset: int = 0, **kwargs) -> str
Download a playlist with an optional limit and offset.
download_likes(url: str, max_tracks: Optional[int] = None, offset: int = 0, **kwargs) -> str
Download a user's liked tracks.
download_all_tracks(url: str, max_tracks: Optional[int] = None, offset: int = 0, **kwargs) -> str
Download all tracks uploaded by a user (excluding reposts).
download_reposts(url: str, max_tracks: Optional[int] = None, offset: int = 0, **kwargs) -> str
Download all reposts by a user.
search(query: str, limit: int = 1) -> List[str]
Search for tracks and return their URLs without downloading.
search_and_download(query: str, limit: int = 1, **kwargs) -> str
Search for tracks and download the results.
Keyword Arguments (**kwargs)
continue_on_error: bool = True: Continue if a file already exists.overwrite: bool = False: Overwrite existing files.only_mp3: bool = False: Download only MP3 files.original_art: bool = False: Use original artwork instead of 500x500 JPEG.
Notes
- The
searchmethod parsesscdldebug output, which may break ifscdl's logging changes. - Ensure
scdlis installed and accessible in your PATH. - Authentication (
auth_token) is optional but required for private tracks.
Metadata
Release files for soundcloud-downloader 0.1.4
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 |
|---|---|---|---|---|
| soundcloud_downloader-0.1.4.tar.gz | 5.2 kB | Without provenance | Details for soundcloud_downloader-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| soundcloud_downloader-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for soundcloud_downloader-0.1.4-py3-none-any.whl |
Total release size: 10.8 kB
Release files / soundcloud_downloader-0.1.4.tar.gz
| Download URL | soundcloud_downloader-0.1.4.tar.gz |
|---|---|
| Size | 5.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fd14023a65b0b0cc9752c1b5cbcfeff5566bf4cba10a1f29889f4a4bc722eb30
|
|
BLAKE2b-256 checksum How to use checksums |
e5fb3e2825525a5dca75c5783c9753729faa3546cd22787d3669d05bba63c902
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.4
|
Release files / soundcloud_downloader-0.1.4-py3-none-any.whl
| Download URL | soundcloud_downloader-0.1.4-py3-none-any.whl |
|---|---|
| Size | 5.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
29297f2b0824bb622371ffdd7b66e47a6733b73bfd9b5415d9ef59425ee9ae5c
|
|
BLAKE2b-256 checksum How to use checksums |
81feb0602889bac03278640d34628959ff13e1c40ba10a01a225a8f1564da9b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.4
|
Security for soundcloud-downloader 0.1.4
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.