Metadata-Version: 2.4
Name: bandcampsync-tui
Version: 0.7.0
Summary: A Python module and script to synchronise media purchased on bandcamp.com with a local directory. Fork of meeb/bandcampsync with Rich TUI and cross-platform improvements.
Home-page: https://codeberg.org/imigueldiaz/bandcampsync-tui
Author: Ignacio de Miguel Díaz
Author-email: imigueldiaz@tutamail.com
License: BSD-3-Clause
Project-URL: Homepage, https://codeberg.org/imigueldiaz/bandcampsync-tui
Project-URL: Bug Tracker, https://codeberg.org/imigueldiaz/bandcampsync-tui/issues
Project-URL: Source, https://codeberg.org/imigueldiaz/bandcampsync-tui
Project-URL: Changelog, https://codeberg.org/imigueldiaz/bandcampsync-tui/src/branch/main/CHANGELOG.md
Keywords: bandcampsync,bandcamp,media,sync,tui,download,music
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: curl_cffi
Requires-Dist: beautifulsoup4
Requires-Dist: html5lib
Requires-Dist: rich
Requires-Dist: setuptools
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# BandcampSync-TUI

[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![PyPI](https://img.shields.io/badge/PyPI-0.7.0-blue?logo=pypi&logoColor=white)](https://pypi.org/project/bandcampsync-tui/)
[![License](https://img.shields.io/badge/License-BSD--3--Clause-green)](LICENSE)
[![PSF Member](https://img.shields.io/badge/PSF-Supporting%20Member-FFD43B?logo=python&logoColor=blue)](https://www.python.org/psf/membership/)

> **🍴 Fork Notice**: This is a fork of
> [meeb/bandcampsync](https://github.com/meeb/bandcampsync) by
> [@meeb](https://github.com/meeb). The original project provided the foundation
> for this work. This fork extends it with a modern TUI, improved cross-platform
> support, and enhanced download capabilities. See
> [What's Different in This Fork](#-whats-different-in-this-fork) for details.

---

**BandcampSync-TUI** is a Python module and command line script which
synchronises media purchased on a Bandcamp (<https://bandcamp.com/>) account
with a local directory.

You may use this to download media you have purchased from Bandcamp to a local
media server, such as Plex or Jellyfin.

Most media items purchased on Bandcamp have high quality download options
available and BandcampSync-TUI defaults to `flac`.

![BandcampSync TUI](docs/tui-preview.png)

## ✨ What's Different in This Fork

This fork introduces several significant improvements over the original:

| Feature             | Original          | This Fork                                         |
| ------------------- | ----------------- | ------------------------------------------------- |
| **Package Name**    | `bandcampsync`    | `bandcampsync-tui`                                |
| **User Interface**  | Plain text output | Rich TUI with progress bars, spinners, and colors |
| **Download Speed**  | Single-stream     | Multi-part parallel downloads (4 threads)         |
| **Windows Support** | Basic             | Full cross-platform with proper path sanitization |
| **HTTP Client**     | `requests`        | `curl_cffi` (better anti-bot handling)            |
| **Ethics**          | —                 | [ETHICAL.md](ETHICAL.md) statement included       |

### Key Improvements

- 🎨 **Beautiful TUI**: Progress bars with download speed/ETA, color-coded
  messages, spinner animations
- 🏷️ **Download ID Visibility**: The TUI now displays the download item ID (e.g. `[ID 123456]`) in progress descriptions and status messages to make it easy to add items to the ignore file.
- ⚡ **Faster Downloads**: Large files (>5MB) download in parallel chunks
- 🖥️ **True Cross-Platform**: Handles Windows-forbidden characters, reserved
  names, and temp file cleanup
- 🛡️ **Better Reliability**: Automatic retry with exponential backoff, graceful
  error handling
- 📜 **Ethical Commitment**: See our [Ethical Statement](ETHICAL.md) for project
  values

For a complete list of changes, see the [CHANGELOG](CHANGELOG.md).

---

## How It Works

When called, `bandcampsync-tui` will:

1. Authenticate to bandcamp.com as you using your exported session cookies
2. Scan your local media directory for existing downloaded items
3. Index a list of all of your purchased items in your Bandcamp collection
4. Download the archive of missing items not downloaded already from your
   collection
5. Unzip the archive and move the contents to the local media directory

The media directory will have the following format:

## Docker

This fork does not provide or maintain a Docker image. If you need a
containerised setup, please use the original project's Docker resources:

- Original project: <https://github.com/meeb/bandcampsync>
- Official image: ghcr.io/meeb/bandcampsync:latest

We recommend using the upstream project's image and examples for container
deployments, as they maintain the Docker artifacts and runbook. This repository
focuses on the interactive TUI and local improvements.

If you'd like, I can add a short compatibility note or a simple example showing
how to adapt the upstream Dockerfile for this fork — tell me and I'll draft it.

## Configuration

BandcampSync-TUI requires minimal configuration. First, it requires your session
cookies from an authenticated Bandcamp account. The easiest way to get this is
to go to <https://bandcamp.com/> in your browser and log in with your account.

Next, open the developer tools in your browser (F12 button on most browsers, or
select "developer tools" from the options menu).

Reload the index page and find the index page request in your network requests
tab of your browser. Go to the "Request Headers" section then select and copy
the string after the `Cookie` header. The string should look something like
this:

```text
client_id=00B1F3C8EB48E181A185CCD041E40C0E8F; session=1%0893C88%570EE405455%%8DEC37B5BC393983DB983DD%%BDFD46C3B8A0%%580DA466D5CD; identity=1%HhehuehUFEUiuebn%%2ADB72300DAE573%BEEF389A1B526EA35AC38019FA0A6F%11B4BD5FBC18B83F720; js_logged_in=1; logout=%7B%22username%22%3A%22someuser%22%7D; download_encoding=401; BACKENDID3=some-sever-name
```

Save this string to a file called `cookies.txt`.

![Getting your session cookies](https://github.com/meeb/bandcampsync/blob/main/docs/cookies.jpg?raw=true)

You need to save your session ID from cookies manually because Bandcamp has a
captcha on the login form so BandcampSync-TUI can't log in with your username
and password for you.

IMPORTANT NOTE: Keep the `cookies.txt` file safe! Anyone with access to this
file can log into your Bandcamp account, impersonate you, potentially make
purchases and generally have total access to your Bandcamp account!

You can also use Netscape formatted cookie export files if you have exported
your cookies using a cookie exporter plugin or similar tool.

## CLI usage

Once you have the Python `bandcampsync-tui` module installed you can call it
with the `bandcampsync-tui` command:

```bash
bandcampsync-tui --cookies cookies.txt --directory /path/to/music
```

or in shorthand:

```bash
bandcampsync-tui -c cookies.txt -d /path/to/music
```

You can use `-t` or `--temp-dir` to set the temporary download directory used.
You can use `-i` or `--ignore` to bypass artists that have data issues that your
OS can not handle.

See `-h` or `--help` for the full list of command line options.

```bash
bandcampsync-tui --cookies cookies.txt --directory /path/to/music --ignore "badband"
```

`--ignore` supports multiple strings space separated strings, for example
`--ignore "band1 band2 band3"`.

You can use `-I` or `--ignore-file` to specify the path to a file containing
bandcamp ids of each item to skip.

```text
1546934218  # Chrome Sparks / Sparks EP
1418240212  # Chrome Sparks / Goddess EP
```

If you do, the items downloaded will be appended to the file, so that the next
time you run the script those items will not be re-downloaded. This means you
can use media managers such as Lidarr to rename artist, album and track names
automatically, rename the directory, or even move the items out of the download
directory without issues.

You can notify an external HTTP server when new items have been loaded with `-n`
or `--notify-url`.

```bash
bandcampsync ... --notify-url "http://some.service.local/some-uri"
```

You can use this to call a "refresh" hook on media servers (for example rescan a
Plex or Jellyfin library). The `--notify-url` parameter, if set, simply makes an
HTTP GET request to the specified URL and confirms it returns a `2XX` response.

For advanced notify URLs you can use the following `--notify-url` format:

`method url headers body`

`method` must be one of `GET` or `POST`. `url` is any URL. `headers` are a comma
separated list of `key=value` pairs and `body` is an body string to send if the
`method` is `POST`. You can use `-` for header and body values to leave them
unset. Some examples:

`GET http://some.service.local/some-uri - -`

`GET http://some.service.local/some-uri header1=abc,header2 -`

`POST http://some.service.local/some-uri auth-header=abc somedata`

## Formats

By default, BandcampSync will download your music in the `flac` format. You can
specify another format with the `--format` argument. Common Bandcamp download
formats are:

| Name            | Description                                                     |
| --------------- | --------------------------------------------------------------- |
| `mp3-v0`        | Variable bitrate MP3. Small file sizes. OK quality.             |
| `mp3-320`       | High quality MP3. Medium file sizes. Good quality.              |
| `flac`          | Lossless audio. Large file sizes. Original Quality.             |
| `aac-hi`        | Apple variable bitrate format. Small file sizes. OK quality.    |
| `aiff-lossless` | Uncompressed audio format. Biggest file size. Original quality. |
| `vorbis`        | Open source lossy format. Small file sizes. OK quality.         |
| `alac`          | Apple lossless format. Large file sizes. Original quality.      |
| `wav`           | Uncompressed audio format. Biggest file size. Original quality. |

## Contributing

All properly formatted and sensible pull requests, issues and comments are
welcome.

## Acknowledgments

This project is a fork of
**[meeb/bandcampsync](https://github.com/meeb/bandcampsync)** created by
[@meeb](https://github.com/meeb).

Thank you to the original author and all contributors for building the
foundation that made this fork possible.

## License

This project is licensed under the BSD 3-Clause License - see the
[LICENSE](LICENSE) file for details.

The original project by [@meeb](https://github.com/meeb) is also licensed under
the BSD 3-Clause License.

## Ethical Commitment

This project includes an [Ethical Statement](ETHICAL.md) that outlines our
values and principles regarding the responsible use of this software. We
encourage all users to read and consider these principles when using, modifying,
or distributing this software.
