BC-Plume

:gear: Plume Installation :nut_and_bolt:

🎯 TypeScript-based Extension

This extension is built with TypeScript for better type safety and maintainability.
It compiles to JavaScript and supports all common modern browsers (Chromium- & Firefox-based).

✅ Prerequisites

• For Users: Any modern browser (Chrome/Firefox/Edge/Opera)
• For Developers:
  • Node.js 18.0+
  • pnpm 10.0+
  • TypeScript 5.8+

📥 Installation Methods

Method 1: Quick Installation (Pre-built)

If you just want to use the extension without building from source:

1️⃣ Download

1. Download this repository as a ZIP file (or clone it)
2. (if ZIP file) Extract it to a folder

2️⃣ Browser-specific Installation

Chrome/Edge/Opera/Brave… (Chromium-based)

1. Open chrome://extensions/ (or equivalent)
2. Enable “Developer mode” (top right corner)
3. Click “Load unpacked”
4. Select the project folder
5. ✅ The extension is installed!

Firefox

1. Open about:debugging
2. Click “This Firefox”
3. Click “Load Temporary Add-on”
4. Select the manifest.json file
5. ✅ The extension is installed!

Method 2: Build from TypeScript Source

For developers or to get the latest features:

1️⃣ Setup Development Environment

git clone https://github.com/QuentindiMeo/BC-Plume # Clone or download the repository
cd BC-Plume && pnpm install    # Install dependencies

2️⃣ Build the Extension

First off, create the build artifacts:

npm install -g pnpm # If you don't have pnpm installed, install it globally as it's evidently superior
pnpm i              # Install project dependencies

Then, select one of the following according to your desired purpose:

pnpm run build  # Quick build (development with source maps)
pnpm run prod   # Production build (optimized, no source maps)
pnpm run watch  # Watch mode for development
pnpm run deploy # Full packaging for distribution

3️⃣ Development Commands

Select one of the following according to your desired purpose:

pnpm run clean       # Clean build artifacts

pnpm run dev         # Get into a raw development mode (= clean + watch)

# Code quality
pnpm run lint        # Check code style
pnpm run format      # Fix formatting issues
pnpm run type-check  # TypeScript type checking only

4️⃣ Install Built Extension

After building, you can install the extension:

Option A: Direct Installation (Development)

• Chrome: Load the main project folder as unpacked extension (manifest.json points to dist/)
• Firefox: Load manifest.json as temporary add-on

Option B: Browser-Specific Packages (Distribution)

• Production: Use pnpm run deploy to create optimized packages
• Chrome: Load build/chrome/ folder as unpacked extension
• Firefox: Load build/firefox/manifest.json as temporary add-on

🎯 Verify Installation

• Go to any Bandcamp page
• The enhanced interface loads
• Volume is saved between pages (uses browser cache)

🔧 Icon Conversion

Firefox uses the SVG icons directly, but Chromium-based browsers require PNG format. If you intend on changing the icons, we recommend creating PNG versions from the SVG files.

Option A: With our Python script (recommended)

pip install pillow cairosvg
python convert_icons.py

Option B: Online Tool

• Go to https://convertio.co/svg-png/ or https://svgtopng.com/
• Convert each SVG file in the icons/ folder:
  • icon16.svg → icon16.png (16x16 pixels)
  • icon48.svg → icon48.png (48x48 pixels)
  • icon128.svg → icon128.png (128x128 pixels)

🔧 Troubleshooting

TypeScript Build Issues

“tsc: command not found”

• Solution: Install TypeScript globally: pnpm install -g typescript
• Alternative: Use local version: npx tsc

Build fails with type errors

• Solution: Check TypeScript version compatibility
• Debug: Run pnpm run type-check to see specific errors
• Fix: Update type definitions: pnpm update @types/chrome @types/node

Missing dist/ folder

• Solution: Run pnpm run build before installation
• Alternative: Use pnpm run dev for watch mode during development

Browser Extension Issues

Firefox: “Extension not compatible”

• Solution: Make sure you have Firefox 109+
• Alternative: The extension will use localStorage as a fallback

Chrome: “Invalid manifest”

• Solution: Check that manifest.json is not corrupted
• Debug: Check the extensions console

No visible interface

• Solution: Reload the Bandcamp page
• Debug: Open F12 → Console to view logs

🔄 Update

Manual Update

1. Download the newest version from this repository (or git pull on develop)
2. (if ZIP file) Replace the existing files
3. Reload the extension in your browser

🗑️ Uninstallation

Chromium-based browsers

1. chrome://extensions/
2. Click “Remove” on the extension

Firefox browser

1. about:addons
2. Extensions → Remove

Saved preferences are automatically deleted.

---

📞 Support

Having an issue? Open a GitHub issue, preferably with:

• Browser version
• Extension version
• Problem description
• Console logs (F12)

Back to top

This site is open source. Improve this page.