You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Ezwen 0420ce0331 Fix Main.kt package name + fatJar build 3 months ago
img Reduce duration of GIF 1 year ago
src Fix Main.kt package name + fatJar build 3 months ago
test-data Split in packages + add dry run + add noerror test 4 months ago
.gitignore Add vscode-related and helpful lines in gitignore 6 months ago
.gitlab-ci.yml CI: make gradle use JDK 11 1 year ago
CHANGELOG.adoc Update CHANGELOG 4 months ago
LICENSE Add LICENSE 3 years ago
README.adoc README: add gradle version 3 months ago
build.gradle Fix Main.kt package name + fatJar build 3 months ago Add script to compile with gradle on docker 7 months ago Update README 1 year ago
release-process.adoc Minor change release process text 5 months ago
settings.gradle Update README 1 year ago


== Bandcamp collection downloader

A command-line tool to automatically download all releases purchased with a Bandcamp account.

$ java -jar ./bandcamp-collection-downloader.jar -d myMusicFolder myBandcampAccount



Usage: <main class> [-ehv] [-c=<pathToCookiesFile>] [-d=<pathToDownloadFolder>] [-f=<audioFormat>] [-j=<jobs>] [-r=<retries>]
[-t=<timeout>] <bandcampUser>
<bandcampUser> The bandcamp user account from which all releases must be downloaded.
-c, --cookies-file=<pathToCookiesFile>
A file containing valid bandcamp credential cookies.
The file must either be obtained using the Firefox extension "Cookie Quick Manager" (https://addons. or using the Chrome extension "cookies.txt"
If no cookies file is provided, cookies from the local Firefox installation are used (Windows and Linux).
-d, --download-folder=<pathToDownloadFolder>
The folder in which downloaded releases must be extracted.
The following structure is considered: <pathToDownloadFolder>/<artist>/<year> - <release>.
(default: current folder)
-e, --skip-failed-releases
Skip releases that fail to download after the specified number of retries.
-f, --audio-format=<audioFormat>
The chosen audio format of the files to download (default: vorbis).
Possible values: flac, wav, aac-hi, mp3-320, aiff-lossless, vorbis, mp3-v0, alac.
-h, --help Display this help message.
-j, --jobs=<jobs> Amount of parallel jobs (threads) to use (default: 4).
-r, --retries=<retries> Amount of retries for each HTTP connection (default: 3).
-t, --timeout=<timeout> Timeout in ms before giving up an HTTP connection (default: 50000).
-v, --version Display the version and exits.

=== Bandcamp authentication

This tool does not manage authentication with Bandcamp servers, as they require a valid token from Google Captcha.
Hence, authentication must first be achieved using Firefox or Chrome.
Then there are two possibilities:

- If using Firefox and running a Windows or Linux system (and if the `--cookies-file` parameter is not used), then the tool will automatically find the required cookies in the Firefox profile folder of the system user. *This approach is now incompatible with versions of Firefox prior to 74.0*.
- Else, Bandcamp cookies must be exported in JSON using the Firefox Addon[Cookie Quick Manager] or in text format with this Chrome Addon[cookies.txt].
The output, either txt from cookies.txt or JSON from Cookie Quick Manager, can then be used using the parameter `--cookies-file`.

=== Usage

Example of command:

$ java -jar bandcamp-collection-downloader.jar --cookies-file=cookies.json --download-folder=~/Music myBandcampIdentifier

This will download all albums ever bought by the Bandcamp account _myBandcampIdentifier_, and extract the music in the folder `~/Music`, The tool always creates one folder per artist, each containing one folder per album (with the format `<year> - <album name>`).

After downloading the first album, it will create a `bandcamp-collection-downloader.cache` file in the chosen download folder. This allows the tool to remembers which albums have already been successfully downloaded, and thus prevents unnecessarily hitting the Bandcamp servers.

=== Installing and updating

Releases are published on link:[this page].

Each release comes with an executable jar file named `bandcamp-collection-downloader.jar` that contains all required dependencies, and that can therefore be directly executed with a simple `java -jar` command.
Look for the link named "_Executable jar_" under each release description.

At the moment there it no official installation procedure: just put `bandcamp-collection-downloader.jar` wherever you want and execute it from anywhere you want.
To install a newer version, simply replace your `bandcamp-collection-downloader.jar` file by the most recent version from the releases page.

If you want to be notified of new releases, you can subscribe to link:[this Atom feed].

=== Compiling

The tool is written in Kotlin and compilation is handled by Gradle 6.7.
A Gradle task named `fatJar` is available to build a standalone executable jar with all dependencies:

$ git clone
$ cd bandcamp-collection-downloader
$ gradle fatjar

The resulting binary can then be found in `build/libs/bandcamp-collection-downloader.jar`.

=== Dependencies

This tool relies on the following libraries:

-[jsoup] to get and parse HTML,
-[zt-zip] to unzip downloaded albums,
-[picocli] to provide a fancy CLI,
-[Gson] to parse JSON files,
-[[ini4j]] to parse INI files,
-[sqlite-jdbc] to read SQLite files.