This repository provides a collection of tools to interact with the SoundCloud API.

This includes a workflow to collect all liked, posted and reposted tracks and playlists of a users favorited artists for the past week.

The worlkflow is meant to be run weekly, and will store the tracks and playlists in a new playlist on the users SoundCloud account.

Another tool is the MetaEditor, which allows you to edit the metadata of your local tracks, including the artwork. The editor offers an integrated Soundcloud search to find the correct metadata for your tracks.

pip install poetry
poetry install --with editor

If ffmpeg is not installed on your system, you can install it via Homebrew by running:

brew install ffmpeg

The sct script contains shortcuts to the tools provided in this repository. For easier access to the commands, add the following to your .bashrc or .zshrc. Otherwise, all following commands have to be prefixed with ./:

alias sct="./sct"

Execute the following command to make the script executable:

chmod +x sct

sct app # Run the Streamlit application
sct weekly # Run the weekly workflow

A set of environment variables are required and have to be set in a .env file in the root directory of the project. You can find a blank .env.example file that you can copy (cp .env.example .env) and fill in the required values.

Similarly, if you want to use the GitHub workflow, you have to add the environment variables as secrets in the repository settings.

The following section describes the tools provided in this repository. An interface for the tools can be started by running the following command:

poetry run streamlit run soundcloud_tools/streamlit/app.py   

You can use the MetaEditor to edit the metadata of your local tracks. It uses the mutagen library to edit the metadata of the tracks. The editor offers an integrated Soundcloud search to find the correct metadata, including artwork, for your tracks.

Note that to optimize the workflow, the MetaEditor uses three folders to store the tracks:

• root_folder/prepared: This is the folder where you should store the tracks that you want to edit the metadata of.
• root_folder/cleaned: This is the folder where the MP3 tracks with the edited metadata will be stored.
• root_folder/archive: This is the folder where the original tracks will be stored after finishing the editing process. If the tracks are already in MP3 format, they will only be copied to the cleaned folder.

poetry run soundcloud_tools

Options

• --week: The week number relative to the current week. For example, --week=0 will download the tracks from the current week, --week=-1 will download the tracks from the previous week, and so on.

In order to setup the workflow, simply add the environment variables as secrets in the GitHub repository settings. By default the workflow will run every Sunday at 08:00 AM, but this can be changed in the .github/workflows/run.yml file.