{"id":15389475,"url":"https://github.com/jgarber623/bandcamp-player","last_synced_at":"2025-02-28T15:33:34.210Z","repository":{"id":219448630,"uuid":"749099989","full_name":"jgarber623/bandcamp-player","owner":"jgarber623","description":"A dependency-free Web Component that generates a Bandcamp embedded player.","archived":false,"fork":false,"pushed_at":"2025-01-03T01:41:16.000Z","size":31,"stargazers_count":6,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-23T16:03:21.124Z","etag":null,"topics":["bandcamp","bandcamp-player","custom-elements","customelements","web-components","webcomponents"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@jgarber/bandcamp-player","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jgarber623.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-27T15:26:37.000Z","updated_at":"2025-02-01T10:26:18.000Z","dependencies_parsed_at":"2025-01-02T23:25:20.237Z","dependency_job_id":"1789ed9c-57d9-4f8d-aace-1d142dfd4ebd","html_url":"https://github.com/jgarber623/bandcamp-player","commit_stats":{"total_commits":21,"total_committers":1,"mean_commits":21.0,"dds":0.0,"last_synced_commit":"93fd7855c71a1ee7c49b58db3cbe6f63d665d22f"},"previous_names":["jgarber623/bandcamp-player"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgarber623%2Fbandcamp-player","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgarber623%2Fbandcamp-player/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgarber623%2Fbandcamp-player/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgarber623%2Fbandcamp-player/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jgarber623","download_url":"https://codeload.github.com/jgarber623/bandcamp-player/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241175740,"owners_count":19922569,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bandcamp","bandcamp-player","custom-elements","customelements","web-components","webcomponents"],"created_at":"2024-10-01T15:01:43.779Z","updated_at":"2025-02-28T15:33:33.714Z","avatar_url":"https://github.com/jgarber623.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `\u003cbandcamp-player\u003e` Web Component\n\n**A dependency-free [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_Components) that generates a [Bandcamp](https://bandcamp.com) embedded player.**\n\n[![npm](https://img.shields.io/npm/v/@jgarber/bandcamp-player.svg?logo=npm\u0026style=for-the-badge)](https://www.npmjs.com/package/@jgarber/bandcamp-player)\n[![Downloads](https://img.shields.io/npm/dt/@jgarber/bandcamp-player.svg?logo=npm\u0026style=for-the-badge)](https://www.npmjs.com/package/@jgarber/bandcamp-player)\n[![Build](https://img.shields.io/github/actions/workflow/status/jgarber623/bandcamp-player/ci.yml?branch=main\u0026logo=github\u0026style=for-the-badge)](https://github.com/jgarber623/bandcamp-player/actions/workflows/ci.yml)\n\n🎶 🎧 **[See `\u003cbandcamp-player\u003e` in action!](https://jgarber623.github.io/bandcamp-player/example)**\n\n## Getting `\u003cbandcamp-player\u003e`\n\nYou've got several options for adding this Web Component to your project:\n\n- [Download a release](https://github.com/jgarber623/bandcamp-player/releases) from GitHub and do it yourself _(old school)_.\n- Install using [npm](https://www.npmjs.com/package/@jgarber/bandcamp-player): `npm install @jgarber/bandcamp-player --save`\n- Install using [Yarn](https://yarnpkg.com/en/package/@jgarber/bandcamp-player): `yarn add @jgarber/bandcamp-player`\n\n## Usage\n\nFirst, add this `\u003cscript\u003e` element to your page which defines the `\u003cbandcamp-player\u003e` Web Component:\n\n```html\n\u003cscript type=\"module\" src=\"bandcamp-player.js\"\u003e\u003c/script\u003e\n```\n\nEmbed an entire album using the `album` attribute:\n\n```html\n\u003cbandcamp-player album=\"3656183138\"\u003e\u003c/bandcamp-player\u003e\n```\n\nAlternatively, embed a single track using the `track` attribute:\n\n```html\n\u003cbandcamp-player track=\"3220102216\"\u003e\u003c/bandcamp-player\u003e\n```\n\nThe `album` and `track` attributes may be used in combination to embed an entire album _and_ set the featured track:\n\n```html\n\u003cbandcamp-player album=\"3656183138\" track=\"3220102216\"\u003e\u003c/bandcamp-player\u003e\n```\n\n\u003e [!TIP]\n\u003e You may include HTML within the `\u003cbandcamp-player\u003e` Web Component. This is good practice—hooray, [progressive enhancement](https://sixtwothree.org/posts/designing-with-progressive-enhancement)!—and provides initial content in cases where JavaScript is unavailable or in circumstances where the Web Component fails to initialize.\n\nFor example:\n\n```html\n\u003cbandcamp-player track=\"3220102216\"\u003e\n  \u003cp\u003eListen to \u003ccite\u003e\u003ca href=\"https://theorchid.bandcamp.com/track/the-astronaut-escape-velocity\"\u003eThe Astronaut (Escape Velocity)\u003c/a\u003e\u003c/cite\u003e by \u003ca href=\"https://theorchid.bandcamp.com\"\u003eThe Orchid\u003c/a\u003e on Bandcamp.\u003c/p\u003e\n\u003c/bandcamp-player\u003e\n```\n\n\u003e [!IMPORTANT]\n\u003e At least one of the `album` or `track` attributes must be provided!\n\n### Bandcamp album and track IDs\n\nAs noted above, this Web Component requires an `album` or `track` ID (or both!). Those values aren't the easiest thing to come by as Bandcamp doesn't expose them via their URLs or via an official API (which, sadly, they no longer have…).\n\nYou _can_ get these values by inspecting the HTML of any album or track page. Album and track identifiers are littered throughout the markup and inlined JSON data. It's a mess.\n\nAs of this writing, there's a `\u003cmeta name=\"bc-page-properties\"\u003e` element at the top of each album or track page. Buried in its encoded `content` attribute value is a ten(ish)-digit `item_id`.\n\nIf you're feeling bold, you can enter the following command in your Web browser's developer tools to retrieve the `item_id`:\n\n```js\nJSON.parse(document.querySelector(`meta[name=\"bc-page-properties\"]`).content).item_id\n```\n\n## Optional Attributes\n\nThis Web Component supports the following optional attributes.\n\n| Name      | Default  | Values                   |\n|:----------|:---------|:-------------------------|\n| `accent`  | `0687f5` | A hexadecimal color code |\n| `artwork` | `none`   | `none`, `large`, `small` |\n| `size`    | `large`  | `large`,`small`          |\n| `theme`   | `light`  | `light`, `dark`, `auto`  |\n\n\u003e [!TIP]\n\u003e The `theme` attribute's `auto` value sets the Bandcamp embedded player's background color using [the `prefers-color-scheme` CSS media feature](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme).\n\n\u003e [!NOTE]\n\u003e When using the `size=\"small\"` and `artwork` attributes, any allowed value other than `none` for the `artwork` attribute will display an album or track thumbnail.\n\n## Custom Styling\n\nYou may want to set the `\u003cbandcamp-player\u003e` Web Component's `display` property for cases where the component is undefined:\n\n```css\nbandcamp-player:not(:defined) {\n  display: block;\n}\n```\n\nOnce defined, the `\u003cbandcamp-player\u003e` Web Component's `display` property is set to `block`. This may be customized to suit your layout's needs using [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties):\n\n```css\nbandcamp-player {\n  --bp-host-display: flex;\n}\n```\n\nYou may similarly style some properties of the Bandcamp embedded player's `\u003ciframe\u003e`:\n\n```css\nbandcamp-player {\n  --bp-frame-border: 0.25rem solid #0687f5;\n  --bp-frame-height: 12rem;\n  --bp-frame-width: 20rem;\n}\n```\n\n\u003e [!NOTE]\n\u003e Styling the width and height of the Bandcamp embedded player requires some foreknowledge of the content rendered within the `\u003ciframe\u003e`.\n\n## JavaScript API\n\nYou may also create instances of this Web Component using JavaScript:\n\n```js\nconst player = document.createElement(\"bandcamp-player\");\n\nplayer.album = \"3656183138\";\nplayer.track = \"3220102216\";\n\nplayer.accent = \"aa8b54\";\nplayer.theme = \"dark\";\n\ndocument.body.append(player);\n```\n\n\u003e [!TIP]\n\u003e Once attached to the DOM, changes to `player`'s properties and attributes will trigger a re-render of the Web Compoment.\n\n## Notes and Limitations\n\nThis Web Component currently offers a subset of the Bandcamp embedded player's features. Open the \"Share / Embed\" widget on any Bandcamp album or track page and click the \"Embed this…\" link for a look at the full range of customizations.\n\nThe reliance on [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) here is of questionable utility. This Web Component could've just as easily leveraged the DOM (more recently rebranded as, \"Light DOM\" 🙄) and been an [HTML web component](https://adactio.com/journal/20618). Further, perhaps your use case doesn't require this Web Component at all! The direct-from-Bandcamp `\u003ciframe\u003e` code snippet will work just as well.\n\n## License\n\nThe `\u003cbandcamp-player\u003e` Web Component is freely available under the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgarber623%2Fbandcamp-player","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjgarber623%2Fbandcamp-player","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgarber623%2Fbandcamp-player/lists"}