wax-dig 0.1.2

CLI for digging through public music discovery signals from Bandcamp and SoundCloud
Documentation

wax

CI License: MIT

wax is a Rust CLI for digging through public music discovery signals from Bandcamp and SoundCloud.

Give it a URL and it will detect the platform automatically:

  • Bandcamp album URLs use collector overlap
  • SoundCloud track URLs use public likers and nearby likes in each liker feed

wax keeps the same entrypoint across providers:

wax dig <url>

Install

Build and install the binary into Cargo's bin directory:

cargo install --path .

To install from crates.io:

cargo install wax-dig

That usually installs wax to ~/.cargo/bin/wax.

If ~/.cargo/bin is not on your PATH, add:

export PATH="$HOME/.cargo/bin:$PATH"

For a local build without installing:

cargo build --release

The binary will be at target/release/wax.

Quick Start

Bandcamp:

wax dig https://artist.bandcamp.com/album/example-record

SoundCloud:

wax resolve https://soundcloud.com/chvrches/the-mother-we-share
wax dig https://soundcloud.com/chvrches/the-mother-we-share

Inspect the available commands:

wax --help
wax dig --help

Commands

wax dig <url>

Runs the recommendation flow for a supported URL.

Examples:

wax dig https://artist.bandcamp.com/album/example-record
wax dig https://artist.bandcamp.com/album/example-record --max-collectors 50 --limit 20
wax dig https://soundcloud.com/chvrches/the-mother-we-share --max-collectors 25 --limit 10
wax dig https://soundcloud.com/chvrches/the-mother-we-share --exclude-artist --sort overlap
wax dig https://artist.bandcamp.com/album/example-record --json

Useful flags:

  • --max-collectors <n>: maximum source nodes to sample during discovery
  • --max-depth <n>: reserved crawl-depth flag, currently defaults to 1
  • --limit <n>: maximum recommendations to print
  • --sample top|random: keep sources in discovery order or shuffle before truncating
  • --min-overlap <n>: minimum overlap count required for a recommendation
  • --exclude-artist: drop records by the same artist as the seed
  • --exclude-label: drop records on the same label as the seed
  • --tag <tag>: require matching tags on candidate records
  • --sort score|overlap: sort recommendations by score or raw overlap

Provider notes:

  • Bandcamp dig uses public collectors and their public libraries
  • SoundCloud dig currently supports track URLs
  • SoundCloud playlist URLs are not supported for dig yet

wax resolve <url>

Resolves a supported URL and prints canonical seed metadata.

Examples:

wax resolve https://artist.bandcamp.com/album/example-record
wax resolve https://soundcloud.com/chvrches/the-mother-we-share

wax collectors <album-url>

Lists public collectors discovered for a Bandcamp seed album.

wax collectors https://artist.bandcamp.com/album/example-record
wax collectors https://artist.bandcamp.com/album/example-record --max-collectors 100

This command is Bandcamp-only.

wax library <fan-url>

Prints albums from a public Bandcamp fan page.

wax library https://bandcamp.com/fanname
wax library https://bandcamp.com/fanname --limit 50

This command is Bandcamp-only.

wax cache stats

Prints the cache directory, entry count, and cache size in bytes.

wax cache stats

wax cache clear

Clears the local fetch cache.

wax cache clear

Global Flags

These flags are available across commands:

  • --config <path>: load settings from a TOML config file
  • --cache-dir <path>: override the cache directory
  • --json: print JSON output
  • --csv: print CSV output where supported
  • --user-agent <value>: override the HTTP user agent
  • --rate-limit-ms <n>: delay between requests in milliseconds
  • --concurrency <n>: request concurrency setting
  • --timeout-ms <n>: per-request timeout
  • -v, --verbose: enable debug logging
  • --quiet: only print errors

Output Modes

By default, wax prints readable table output.

Use --json for structured output:

wax dig https://artist.bandcamp.com/album/example-record --json
wax resolve https://soundcloud.com/chvrches/the-mother-we-share --json

Use --csv for CSV output:

wax dig https://artist.bandcamp.com/album/example-record --csv
wax collectors https://artist.bandcamp.com/album/example-record --csv
wax library https://bandcamp.com/fanname --csv

Notes

  • wax only uses publicly visible Bandcamp and SoundCloud data
  • SoundCloud support currently focuses on track resolution and a prototype dig flow
  • private or unavailable public data is skipped when possible
  • repeated runs are faster when the cache is warm

Hacking

Developer-facing notes live in HACKING.md.