From 7e159f2173cc91c5dc98ae11a637bca22996caa5 Mon Sep 17 00:00:00 2001 From: Jordan Eldredge Date: Fri, 4 Jul 2025 19:10:02 -0700 Subject: [PATCH] Move butterchurn loader docs to bundle size guide --- packages/webamp-docs/docs/04_examples.md | 2 +- .../docs/06_API/02_webamp-constructor.md | 52 ---------------- .../docs/07_guides/03_bundle-size.md | 59 ++++++++++++++++++- 3 files changed, 57 insertions(+), 56 deletions(-) diff --git a/packages/webamp-docs/docs/04_examples.md b/packages/webamp-docs/docs/04_examples.md index 5ef8aff4..9524b733 100644 --- a/packages/webamp-docs/docs/04_examples.md +++ b/packages/webamp-docs/docs/04_examples.md @@ -6,6 +6,6 @@ If you would like to look at some examples check out the [examples directory](ht - [Multiple Tracks](https://github.com/captbaritone/webamp/tree/master/examples/multipleTracks) An example of setting up Webamp with multiple audio tracks. - [Multiple Skins](https://github.com/captbaritone/webamp/tree/master/examples/multipleSkins) An example of setting up Webamp with multiple skins. - [Minimal Window Layout](https://github.com/captbaritone/webamp/tree/master/examples/minimalWindowLayout) An example of configuring the initial layout of windows in Webamp. -- [Minimal Milkdrop](https://github.com/captbaritone/webamp/tree/master/examples/minimalMilkdrop) **In progress** +- [Minimal Milkdrop](https://github.com/captbaritone/webamp/tree/master/examples/minimalMilkdrop) Each example has a README which explains it in more detail. diff --git a/packages/webamp-docs/docs/06_API/02_webamp-constructor.md b/packages/webamp-docs/docs/06_API/02_webamp-constructor.md index 28aa280a..db21561d 100644 --- a/packages/webamp-docs/docs/06_API/02_webamp-constructor.md +++ b/packages/webamp-docs/docs/06_API/02_webamp-constructor.md @@ -254,55 +254,3 @@ const webamp = new Webamp({ // ...other config options }); ``` - -### `__butterchurnOptions` - -Webamp's Milkdrop window is powered by the third party library [Butterchurn](https://butterchurnviz.com/). Getting Butterchurn to work with Webamp requires some additional configuration which is still a bit fiddly, but is possible. For a full working example, see the [Butterchurn Example](https://github.com/captbaritone/webamp/tree/master/examples/minimalMilkdrop). - -#### Butterchurn - -Butterchurn is not being actively maintained, but it is still works -great. Before it went into maintenance mode Jordan Berg (different -Jordan) cut a beta release of a version with the faster/more secure -[eel->Wasm compiler](https://jordaneldredge.com/blog/speeding-up-winamps-music-visualizer-with-webassembly/) that I wrote, so we use `butterchurn@3.0.0-beta.3`. - -This version is still using AMD modules, so it will write the export to -`window.butterchurn`. This is a pretty chunky files, so you way want to -find a way to lazy load it inside `importButterchurn` below. -Unfortunately, it's not an ES module, so I wasn't able to call -`import()` on it without some kind of bundler. - -#### Presets - -The module, `butterchurn-presets@3.0.0-beta.4` contains a curated set -of awesome Butterchurn presets that have been packaged up to work with -the new compiler. This module is also packaged as an AMD module, so -when imported without a bundler it will write the export to `window`. I -think the package was never that thoughtfully built, so the export name -is, confusingly `window.base`. If that's a problem, using a bundler -might help. - -As audio plays, Webamp will randomly cycle through these presets with a -cool transition effect. You can also press "l" while the Milkdrop -window is open to open Milkdrop's preset selection menu. - -#### Example - -```ts -import "butterchurn/dist/butterchurn.min.js"; // buterchurn@3.0.0-beta.4 -const butterchurn = window.butterchurn; - -import "butterchurn-presets/dist/base.js"; // butterchurn-presets@3.0.0-beta.4 -const butterchurnPresets = window.base.default; - -const webamp = new Webamp({ - __butterchurnOptions: { - importButterchurn: () => Promise.resolve(butterchurn), - getPresets: () => { - return Object.entries(butterchurnPresets).map(([name, preset]) => { - return { name, butterchurnPresetObject: preset }; - }); - }, - }, -}); -``` diff --git a/packages/webamp-docs/docs/07_guides/03_bundle-size.md b/packages/webamp-docs/docs/07_guides/03_bundle-size.md index 5817e03a..761b4cfb 100644 --- a/packages/webamp-docs/docs/07_guides/03_bundle-size.md +++ b/packages/webamp-docs/docs/07_guides/03_bundle-size.md @@ -1,11 +1,11 @@ # Optimizing Bundle Size -By default the Webamp import/bundle includes a few heavy dependencies. `JSZip` for extracting user defined skin files and `music-metadata-browser` for reading ID3 tags. If you are using the default skin and supply metadata and duration for all your preloaded tracks, neither of these dependencies are needed for initial load and can instead be lazily loaded only when they are needed. To do this, you can import from `webamp/lazy` instead of `webamp`. +By default the Webamp import/bundle includes a few heavy dependencies. [`JSZip`](https://www.npmjs.com/package/jszip) for extracting user defined skin files and [`music-metadata`](https://www.npmjs.com/package/music-metadata) for reading ID3 tags. If you are using the default skin and supply metadata and duration for all your preloaded tracks, neither of these dependencies are needed for initial load and can instead be lazily loaded only when they are needed. To do this, you can import from `webamp/lazy` instead of `webamp`. First you'll need to install the dependencies in your project: ```bash -npm install jszip music-metadata-browser@^0.6.6 +npm install jszip music-metadata ``` The "lazy" version of Webamp will require that you inject functions for lazily importing these dependencies. @@ -25,6 +25,59 @@ const webamp = new Webamp({ }, ], requireJSZip: () => import("jszip/dist/jszip"), - requireMusicMetadata: () => import("music-metadata-browser/dist/index"), + requireMusicMetadata: () => import("music-metadata"), +}); +``` + +## Milkdrop + +Webamp's Milkdrop window is powered by the third party library [Butterchurn](https://butterchurnviz.com/). In `webamp/lazy` neither Butterchurn nor any visualizer presets are included. Getting Butterchurn to work with Webamp requires some additional configuration which is still a bit fiddly, but is possible. This is achieved by passing an `__butterchurnOptions` object to the Webamp constructor. + +### `__butterchurnOptions` + +#### Butterchurn + +Butterchurn is not being actively maintained, but it is still works +great. Before it went into maintenance mode Jordan Berg (different +Jordan) cut a beta release of a version with the faster/more secure +[eel->Wasm compiler](https://jordaneldredge.com/blog/speeding-up-winamps-music-visualizer-with-webassembly/) that I wrote, so we use `butterchurn@3.0.0-beta.3`. + +This version is still using AMD modules, so it will write the export to +`window.butterchurn`. This is a pretty chunky files, so you way want to +find a way to lazy load it inside `importButterchurn` below. +Unfortunately, it's not an ES module, so I wasn't able to call +`import()` on it without some kind of bundler. + +#### Presets + +The module, `butterchurn-presets@3.0.0-beta.4` contains a curated set +of awesome Butterchurn presets that have been packaged up to work with +the new compiler. This module is also packaged as an AMD module, so +when imported without a bundler it will write the export to `window`. I +think the package was never that thoughtfully built, so the export name +is, confusingly `window.base`. If that's a problem, using a bundler +might help. + +As audio plays, Webamp will randomly cycle through these presets with a +cool transition effect. You can also press "l" while the Milkdrop +window is open to open Milkdrop's preset selection menu. + +#### Example + +```ts +const webamp = new Webamp({ + __butterchurnOptions: { + importButterchurn: () => import("butterchurn"), + getPresets: async () => { + const butterchurnPresets = await import( + "butterchurn-presets/dist/base.js" + ); + return Object.entries(butterchurnPresets).map(([name, preset]) => { + return { name, butterchurnPresetObject: preset }; + }); + }, + }, + requireJSZip: () => import("jszip/dist/jszip"), + requireMusicMetadata: () => import("music-metadata"), }); ```