# Bandcamp Downloader & Metadata Scraper (`actorzlab/bandcamp-downloader`) Actor Download audio (MP3/FLAC/WAV/M4A) and scrape rich metadata for any Bandcamp artist, album, or track. - **URL**: https://apify.com/actorzlab/bandcamp-downloader.md - **Developed by:** [Khalil Drissi](https://apify.com/actorzlab) (community) - **Categories:** Videos, For creators - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Bandcamp Downloader & Metadata Scraper Turn any Bandcamp **track, album, or artist page** into clean audio files and structured metadata in one run. Point it at a URL and get back downloadable **MP3, FLAC, WAV, or M4A** audio (hosted on Apify) plus a rich JSON record for every track — artist, album, track number, duration, release date, genre, tags, description, price, and cover art. --- ### Features - 🎵 **Downloads real audio** — MP3, FLAC, WAV, M4A, or the original Bandcamp stream (no re-encode). - 🎚️ **Selectable MP3 quality** — 128 / 192 / 256 / 320 kbps. - 🧠 **Rich metadata per track** — artist, album, track number, duration, release date, genre, tags, description, price, and free/paid flag. - 🖼️ **Cover artwork** — downloaded and hosted alongside the audio, or linked from Bandcamp. - 🔗 **Smart URL expansion** — give it a single track, a full album, or a whole artist/label catalog and it figures out the rest. - ☁️ **Hosted output** — every file lands in the Apify Key-Value Store with a clean `{artist}-{album}-{track}.{ext}` filename and a public URL. - 🛡️ **Resilient** — a failure on one URL or track is logged and skipped; the run keeps going. - 🌐 **Proxy-ready** — route through Apify Proxy or connect directly. - 💸 **Pay-per-event pricing** — pay only for what you actually extract or download. --- ### Use cases - **Music journalism** — pull a writer-ready table of an album's tracks, durations, and release dates while drafting a review. - **Label & A&R research** — sweep an artist or label catalog into a dataset to compare release cadence, genres, and pricing. - **AI music training datasets** — assemble licensed audio + structured labels (genre, tags, duration) for model training and MIR research. - **Personal archiving** — back up music you've purchased into the lossless format you prefer, with artwork and metadata intact. - **Music discovery analytics** — track tags, genres, and release patterns across artists to surface trends and recommendations. --- ### Input | Field | Type | Default | Description | |-------|------|---------|-------------| | `urls` | array of strings | — (**required**) | Bandcamp URLs. Each may be a track (`/track/...`), an album (`/album/...`), or an artist/label page. | | `downloadAudio` | boolean | `true` | Download the audio file. If `false`, only metadata is scraped (cheaper). | | `audioFormat` | enum: `mp3`, `flac`, `wav`, `m4a`, `best` | `mp3` | Output format. `best` keeps the original stream without re-encoding; the rest are transcoded via ffmpeg. | | `audioQuality` | enum: `128`, `192`, `256`, `320` | `320` | MP3 bitrate in kbps. Ignored for non-MP3 formats. | | `includeArtwork` | boolean | `true` | Download the cover image and host it; `artworkUrl` then points at the hosted copy. | | `maxItemsPerArtist` | integer (1–500) | `50` | Cap on tracks expanded from an artist/label page. Track and album URLs are never capped. | | `proxyConfiguration` | object | — (optional) | Apify Proxy settings. Leave empty to connect directly. | #### Example input ```json { "urls": [ "https://amandapalmer.bandcamp.com/track/the-manifesto-amanda-palmer", "https://amandapalmer.bandcamp.com/album/who-killed-amanda-palmer", "https://tycho.bandcamp.com/music" ], "downloadAudio": true, "audioFormat": "mp3", "audioQuality": "320", "includeArtwork": true, "maxItemsPerArtist": 50, "proxyConfiguration": { "useApifyProxy": true } } ```` *** ### Output One record is pushed to the default **Dataset** per track. Audio and artwork are stored in the default **Key-Value Store**, and their public URLs are included in the record. | Field | Type | Description | |-------|------|-------------| | `url` | string | Canonical Bandcamp page for the track. | | `artist` | string | Artist / band name. | | `album` | string | null | Album title (null for standalone singles). | | `track` | string | Track title. | | `trackNumber` | integer | null | Position within the album. | | `duration` | integer | null | Track length in seconds. | | `releaseDate` | string | null | Release date, ISO `YYYY-MM-DD`. | | `genre` | string | null | Primary genre (falls back to the first tag). | | `tags` | array of strings | Bandcamp tags. | | `description` | string | null | Track/album description text. | | `priceUsd` | number | null | Price in USD when exposed by Bandcamp. | | `isFree` | boolean | null | `true` when the price is 0; `null` when unknown. | | `artworkUrl` | string | null | Hosted cover URL when `includeArtwork` is on, otherwise the Bandcamp image URL. | | `audioDownloadUrl` | string | null | Public Apify Key-Value Store URL of the audio file (null in metadata-only mode). | | `audioFormat` | string | null | Actual file extension of the stored audio (e.g. `mp3`, `flac`). | | `audioSizeBytes` | integer | null | Size of the stored audio file in bytes. | #### Example output record ```json { "url": "https://amandapalmer.bandcamp.com/track/the-manifesto-amanda-palmer", "artist": "Amanda Palmer", "album": "There Will Be No Intermission", "track": "The Manifesto (Amanda Palmer)", "trackNumber": 1, "duration": 243, "releaseDate": "2019-03-08", "genre": "cabaret", "tags": ["cabaret", "art rock", "piano", "Boston"], "description": "Recorded live...", "priceUsd": null, "isFree": null, "artworkUrl": "https://api.apify.com/v2/key-value-stores//records/amanda-palmer-there-will-be-no-intermission-the-manifesto-amanda-palmer-cover.jpg", "audioDownloadUrl": "https://api.apify.com/v2/key-value-stores//records/amanda-palmer-there-will-be-no-intermission-the-manifesto-amanda-palmer.mp3", "audioFormat": "mp3", "audioSizeBytes": 9764352 } ``` *** ### Pricing This Actor uses **pay-per-event** pricing — you are billed for what the run actually does, not for compute time. | Event | Price (USD) | Charged when | |-------|-------------|--------------| | `metadata-extracted` | **$0.001** / track | A track is scraped **without** downloading audio (metadata-only mode). | | `audio-downloaded` | **$0.01** / track | A track's audio file is downloaded and stored. **Replaces** the metadata charge for that track. | | `artwork-downloaded` | **$0.0005** / cover | A cover image is downloaded and stored (`includeArtwork` enabled). | > A track is charged **either** `metadata-extracted` **or** `audio-downloaded` — never both. `artwork-downloaded` is an additional per-cover charge. **Example costs** - **100 tracks with audio** = 100 × $0.01 = **$1.00** - **100 tracks with audio + artwork** = $1.00 + 100 × $0.0005 = **$1.05** - **1,000 tracks, metadata only** = 1,000 × $0.001 = **$1.00** - **500 cover images** = 500 × $0.0005 = **$0.25** *** ### ⚖️ Legal note This tool is intended for downloading content you have the right to access — music you have purchased, your own catalog, freely/openly licensed releases, or material you have explicit permission to use. You are responsible for complying with [Bandcamp's Terms of Use](https://bandcamp.com/terms_of_use) and all applicable copyright law. Do not use this Actor to redistribute or commercially exploit content you do not own or are not licensed to use. *** ### FAQ **Can I scrape just the metadata without downloading audio?** Yes. Set `downloadAudio` to `false`. You still get every metadata field, `audioDownloadUrl` is `null`, and you're billed at the much lower `metadata-extracted` rate. **Why is the audio sometimes 128 kbps even though I asked for 320?** Bandcamp serves a 128 kbps MP3 stream for tracks that aren't purchased/freely downloadable. Transcoding that stream up to "320 kbps" cannot recover quality it never had — for true high-fidelity or lossless files, use audio you own and Bandcamp exposes as a full download. Choosing `flac`/`wav`/`best` avoids an unnecessary MP3 re-encode. **What happens with an artist or label page?** The Actor expands it into individual tracks (following albums), up to `maxItemsPerArtist`. Single track and album URLs are processed in full and are never capped. **Where do the downloaded files go?** Each file is uploaded to the run's default Key-Value Store with a clean `{artist}-{album}-{track}.{ext}` name, and its public URL is included in the dataset record so you can download or hotlink it. **Do I need a proxy?** No. By default the Actor connects directly. If you hit rate limits or geo-restrictions, enable `proxyConfiguration` to route through Apify Proxy. # Actor input Schema ## `urls` (type: `array`): One or more Bandcamp URLs. Each can point at a single track, a full album, or an artist/label page (which is expanded into its tracks up to the per-artist limit). ## `downloadAudio` (type: `boolean`): If enabled, the audio file is downloaded and uploaded to the Key-Value Store. If disabled, only metadata is scraped (much cheaper). ## `audioFormat` (type: `string`): Target audio format. 'best' keeps Bandcamp's original stream without re-encoding (usually MP3 or M4A); the others are transcoded with ffmpeg. ## `audioQuality` (type: `string`): Bitrate used when transcoding to MP3. Ignored for other formats. ## `includeArtwork` (type: `boolean`): If enabled, the cover image is downloaded, stored in the Key-Value Store, and 'artworkUrl' points at the hosted copy. ## `maxItemsPerArtist` (type: `integer`): When an input URL is an artist/label page, expand at most this many tracks. Single track and album URLs are never limited. ## `proxyConfiguration` (type: `object`): Optionally route requests through Apify Proxy. Leave empty to connect to Bandcamp directly. ## Actor input object example ```json { "urls": [ "https://artist.bandcamp.com/album/album-name" ], "downloadAudio": true, "audioFormat": "mp3", "audioQuality": "320", "includeArtwork": true, "maxItemsPerArtist": 50 } ``` # Actor output Schema ## `tracks` (type: `string`): No description ## `audioFiles` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "urls": [ "https://amandapalmer.bandcamp.com/track/the-manifesto-amanda-palmer" ] }; // Run the Actor and wait for it to finish const run = await client.actor("actorzlab/bandcamp-downloader").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "urls": ["https://amandapalmer.bandcamp.com/track/the-manifesto-amanda-palmer"] } # Run the Actor and wait for it to finish run = client.actor("actorzlab/bandcamp-downloader").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "urls": [ "https://amandapalmer.bandcamp.com/track/the-manifesto-amanda-palmer" ] }' | apify call actorzlab/bandcamp-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=actorzlab/bandcamp-downloader", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Bandcamp Downloader & Metadata Scraper", "description": "Download audio (MP3/FLAC/WAV/M4A) and scrape rich metadata for any Bandcamp artist, album, or track.", "version": "0.0", "x-build-id": "8rgcMKuWPSluZef6L" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/actorzlab~bandcamp-downloader/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-actorzlab-bandcamp-downloader", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/actorzlab~bandcamp-downloader/runs": { "post": { "operationId": "runs-sync-actorzlab-bandcamp-downloader", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/actorzlab~bandcamp-downloader/run-sync": { "post": { "operationId": "run-sync-actorzlab-bandcamp-downloader", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "urls" ], "properties": { "urls": { "title": "Bandcamp URLs", "type": "array", "description": "One or more Bandcamp URLs. Each can point at a single track, a full album, or an artist/label page (which is expanded into its tracks up to the per-artist limit).", "items": { "type": "string" } }, "downloadAudio": { "title": "Download audio", "type": "boolean", "description": "If enabled, the audio file is downloaded and uploaded to the Key-Value Store. If disabled, only metadata is scraped (much cheaper).", "default": true }, "audioFormat": { "title": "Audio format", "enum": [ "mp3", "flac", "wav", "m4a", "best" ], "type": "string", "description": "Target audio format. 'best' keeps Bandcamp's original stream without re-encoding (usually MP3 or M4A); the others are transcoded with ffmpeg.", "default": "mp3" }, "audioQuality": { "title": "MP3 quality (kbps)", "enum": [ "128", "192", "256", "320" ], "type": "string", "description": "Bitrate used when transcoding to MP3. Ignored for other formats.", "default": "320" }, "includeArtwork": { "title": "Include cover artwork", "type": "boolean", "description": "If enabled, the cover image is downloaded, stored in the Key-Value Store, and 'artworkUrl' points at the hosted copy.", "default": true }, "maxItemsPerArtist": { "title": "Max tracks per artist page", "minimum": 1, "maximum": 500, "type": "integer", "description": "When an input URL is an artist/label page, expand at most this many tracks. Single track and album URLs are never limited.", "default": 50 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optionally route requests through Apify Proxy. Leave empty to connect to Bandcamp directly." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```