️️🌧️ downcloud #

a simple (and fast) soundcloud downloader.

prerequisites #

• ffmpeg

install #

nix flake #

add to your flake.nix inputs:

downcloud = {
  url = "git+https://tangled.org/yarncat.moe/downcloud.git";
  inputs.nixpkgs.follows = "nixpkgs";
};

then add downcloud.packages.${system}.default to your environment.systemPackages or home-manager packages.

authentication #

higher-quality downloads of some tracks are only available for download with a soundcloud oauth token. to get yours:

1. open soundcloud and log in
2. open devtools and go to application > storage > cookies > soundcloud.com
3. find the oauth_token cookie and copy its value
4. save it:

downcloud set-token <your-token>

you can also provide it on a per-command basis with -t <token> instead of saving it.

on darwin systems you may get an error if running via ssh, where the keychain cannot be unlocked. running the command below will unlock the keychain:

security unlock-keychain ~/Library/Keychains/login.keychain-db

usage #

usage: downcloud [options] [url] [outfile] [flags]

a simple (and fast) soundcloud downloader

arguments:
  url                        soundcloud url (auto-detects track, playlist, or artist)
  outfile                    path to save output file (tracks only)

options:
  -t, --token <string>       use a temporary soundcloud oauth token
  -o, --output <directory>   output directory
  -f, --format <format>      output format (mp3, m4a, flac)
  --download-archive <file>  download archive file (skip already archived tracks)
  --sync <file>              sync archive file (download new, remove deleted, rewrite archive)
  --debug                    print ffmpeg execution logs (default: false)
  -v, --version              output the version number
  -h, --help                 display help for command

commands:
  set-token <token>         save a soundcloud oauth token into your keyring
  track [options] <url>     download a track
  playlist [options] <url>  download all tracks from a playlist
  artist [options] <url>    download all tracks from an artist
  help [command]            display help for command

download (auto-detect) #

pass any soundcloud url and downcloud will detect whether it's a track, playlist, or artist:

downcloud https://soundcloud.com/hologura/yoho4
downcloud https://soundcloud.com/user/sets/playlist
downcloud https://soundcloud.com/hologura

all the same options are available:

downcloud https://soundcloud.com/hologura/yoho4 -o ./music -f flac

track #

usage: downcloud track [options] <url> [outfile]

download a track

arguments:
  url                        track url
  outfile                    path to save output file

options:
  -t, --token <string>       use a temporary soundcloud oauth token
  -o, --output <directory>   output directory
  -f, --format <format>      output format (mp3, m4a, flac)
  --download-archive <file>  download archive file (skip already archived tracks)
  --sync <file>              sync archive file (download new, remove deleted, rewrite archive)
  --debug                    print ffmpeg execution logs (default: false)
  -h, --help                 display help for command

playlist #

usage: downcloud playlist [options] <url>

download all tracks from a playlist

arguments:
  url                        playlist url

options:
  -t, --token <string>       use a temporary soundcloud oauth token
  -o, --output <directory>   output directory (default: playlist name)
  -f, --format <format>      output format (mp3, m4a, flac)
  --download-archive <file>  download archive file (skip already archived tracks)
  --sync <file>              sync archive file (download new, remove deleted, rewrite archive)
  --debug                    print ffmpeg execution logs (default: false)
  -h, --help                 display help for command

artist #

usage: downcloud artist [options] <url>

download all tracks from an artist

arguments:
  url                        artist url

options:
  -t, --token <string>       use a temporary soundcloud oauth token
  -o, --output <directory>   output directory (default: artist name)
  -f, --format <format>      output format (mp3, m4a, flac)
  --download-archive <file>  download archive file (skip already archived tracks)
  --sync <file>              sync archive file (download new, remove deleted, rewrite archive)
  --debug                    print ffmpeg execution logs (default: false)
  -h, --help                 display help for command

dev #

# enter the dev shell (if using nix)
nix develop

# run tests
go test -v ./...

# build the binary
go build -o downcloud ./cmd/downcloud

license #

gpl-3.0 or later