Milkdrop docs

packages/webamp-docs/docs/01_intro.md

@@ -27,7 +27,7 @@ For more examples you can copy from, see [Examples](./04_examples.md).
 ## Next Steps
 
 1. [Installation](./02_install.md) - Learn how to install Webamp in your project, including how to use it with npm or a CDN.
-2. [Initialization Options](./03_initialization.md) - Learn about the options you can pass to Webamp when initializing it. Include **tracks, skins, and more.**
+2. [Initialization](./03_initialization.md) - Learn about initializing Webamp, including how to create a Webamp instance and render it in your HTML document.
 3. API - Learn about the Webamp API, including how to control playback, add tracks, and more.
    - [Webamp Constructor Options](./06_API/02_webamp-constructor.md) - Learn about the options you can pass to the Webamp constructor.
    - [Webamp Instance Methods](./06_API/03_instance-methods.md) - Learn about the methods you can call on a Webamp instance.

packages/webamp-docs/docs/05_features/01_hotkeys.md

@@ -49,6 +49,20 @@ webamp.renderWhenReady(document.getElementById("winamp-container"));
 | Numpad 8  | Volume Up               |
 | Numpad 9  | Seek Forward (5s)       |
 
+## Milkdrop Hotkeys
+
+When Milkdrop visualization is focused, the following additional hotkeys are available:
+
+| Key               | Action                      |
+| ----------------- | --------------------------- |
+| Space             | Next Preset (fade)          |
+| Backspace         | Previous Preset (immediate) |
+| H                 | Next Preset (immediate)     |
+| R                 | Toggle Randomize            |
+| L                 | Toggle Preset Overlay       |
+| T                 | Show Track Title Message    |
+| Scroll Lock / F14 | Toggle Preset Cycling       |
+
 ## Easter Egg
 
-Webamp emulates the original Winamp's Easter egg. If type "nullsoft", letter by letter, pressing `<esc>` after each letter "L" to dismiss the open file dialog, you will toggle Webamp into and out of "Easter Egg Mode". In this mode, a custom skin-defined title bar is shown in the main window.
+Webamp emulates the original Winamp's Easter egg. If you type "nullsoft", letter by letter, pressing `<esc>` after each letter "L" to dismiss the open file dialog, you will toggle Webamp into and out of "Easter Egg Mode". In this mode, a custom skin-defined title bar is shown in the main window.

packages/webamp-docs/docs/05_features/02_mikdrop.md

@@ -0,0 +1,45 @@
+# Milkdrop
+
+Webamp uses [Butterchurn](https://butterchurnviz.com/) to provide a Milkdrop visualizer. Butterchurn is a JavaScript port of the original Milkdrop visualizer, and it can run in any modern web browser.
+
+To use Butterchurn in Webamp, you need to provide the [`__butterchurnOptions`](../06_API/02_webamp-constructor.md#__butterchurnoptions) configuration option when creating a new `Webamp` instance.
+
+## Hotkeys
+
+When the Milkdrop window is focused, there are several hotkeys you can use to control the visualizer. The full list can be found on the [Hotkeys](./01_hotkeys.md#milkdrop-hotkeys) page.
+
+## Preset Cycling
+
+By default Webamp will automatically cycle through Milkdrop presets in a random order every 15 seconds. During the transition Butterchurn perform a transition where the image from the previous preset is used as input into the next preset, creating a smooth transition effect.
+
+See [Hotkeys](./01_hotkeys.md#milkdrop-hotkeys) for the hotkeys to control preset cycling.
+
+## Track Title
+
+When the track changes, the Milkdrop visualizer will show the current track title and incorporate it into the visualizer. You can trigger this manually by focusing the Milkdrop window and pressing `T`. This will display the current track title in the visualizer for a few seconds.
+
+![Webamp Milkdrop Title](../../static/img/mikdrop-title.png)
+
+## Preset Selection Menu
+
+With the Milkdrop window open, you can press upper or lower case `L` to open the preset selection menu. From there you can use arrow key to navigate through the presets, and press `Enter` to select one. After selection Webamp will start gradually transitioning to the new preset. You can press `Esc` to close the menu.
+
+![Webamp Milkdrop Preset Selection Menu](../../static/img/milkdrop-preset-selection.png)
+
+## Modes
+
+Webamp supports two immersive modes for Milkdrop: "Full Screen" and "Desktop". You can select these modes by right-clicking on the Milkdrop window and selecting "Full Screen" or "Desktop" from the context menu.
+
+![Webamp Mode Selection Menu](../../static/img/milkdrop-mode-selection.png)
+
+### Desktop Mode
+
+In "Desktop" mode, Milkdrop visualization will take over the full window's background. You can right click on the background to exit this mode.
+
+![Webamp Milkdrop Desktop Mode](../../static/img/mikdrop-desktop-mode.png)
+
+### Full Screen Mode
+
+In "Full Screen" mode, Milkdrop will take over the entire screen, hiding all other content. You can exit this mode by pressing `Esc`.
+
+![Webamp Milkdrop Full Screen Mode](../../static/img/mikdrop-fullscreen-mode.png)

packages/webamp-docs/docs/06_API/02_webamp-constructor.md

@@ -2,16 +2,28 @@
 
 The `Winamp` class is constructed with an options object. _All config properties are optional._
 
+```ts
+import Webamp from "webamp";
+
+const webamp = new Webamp({
+  // ...constructor options go here.
+});
+
+// ...after this you can call `webamp.renderWhenReady(...)` to render Webamp.
+```
+
+For more information on initializing Webamp, see the [Initialization Guide](../03_initialization.md).
+
 ### `initialTracks`
 
-An array of `track`s to prepopulate the playlist with. **The `url` must be served with the [correct CORS headers](../07_guides/01_cors.md).**
+An array of [`track`s](./01_track.md) to prepopulate the playlist with. **The `url` must be served with the [correct CORS headers](../07_guides/01_cors.md).**
 
 :::warning
 It is highly recommended to provide `metaData` and `duration` for each track, as this will prevent Webamp from needing to fetch the first few bytes of the file to read ID3 tags and duration.
 :::
 
 ```ts
-const options = {
+const webamp = new Webamp({
   initialTracks: [
     {
       url: "./path/to/track.mp3",
@@ -22,7 +34,8 @@ const options = {
       duration: 120, // Track duration in seconds
     },
   ],
-};
+  // ...other config options
+});
 ```
 
 ### `initialSkin`
@@ -30,11 +43,12 @@ const options = {
 An object representing the initial skin to use. If omitted, the default skin, included in the bundle, will be used. **The URL must be served with the [correct CORS headers](../07_guides/01_cors.md).**
 
 ```ts
-const options = {
+const webamp = new Webamp({
   initialSkin: {
     url: "./path/to/skin.wsz",
   },
-};
+  // ...other config options
+});
 ```
 
 ### `availableSkins`
@@ -46,12 +60,13 @@ You can find skins to download at the [Winamp Skin Museum](https://skins.webamp.
 :::
 
 ```ts
-const options = {
+const webamp = new Webamp({
   availableSkins: [
     { url: "./green.wsz", name: "Green Dimension V2" },
     { url: "./osx.wsz", name: "Mac OSX v1.5 (Aqua)" },
   ],
-};
+  // ...other config options
+});
 ```
 
 ### `windowLayout`
@@ -68,7 +83,7 @@ An object representing the initial layout of the windows. Valid keys are `main`,
 **Note:** After windows are positioned, they are then centered _as a group_ within the DOM element that Webamp is rendered into.
 
 ```ts
-const options = {
+const webamp = new Webamp({
   windowLayout: {
     main: {
       position: { top: 0, left: 0 },
@@ -88,7 +103,8 @@ const options = {
       closed: false,
     },
   },
-};
+  // ...other config options
+});
 ```
 
 ### `enableDoubleSizeMode`
@@ -98,9 +114,10 @@ _Since 2.0.0_
 A boolean indicating if double size mode should be enabled. **Default:** `false`.
 
 ```ts
-const options = {
+const webamp = new Webamp({
   enableDoubleSizeMode: true,
-};
+  // ...other config options
+});
 ```
 
 :::tip
@@ -112,9 +129,10 @@ In keeping with the original Winamp, **double size mode does not apply to resiza
 A boolean indicating if global hotkeys should be enabled. **Default:** `false`.
 
 ```ts
-const options = {
+const webamp = new Webamp({
   enableHotkeys: true,
-};
+  // ...other config options
+});
 ```
 
 For a list of hotkeys, see the [hotkeys documentation](../05_features/01_hotkeys.md).
@@ -124,19 +142,20 @@ For a list of hotkeys, see the [hotkeys documentation](../05_features/01_hotkeys
 An integer representing the zIndex that Webamp should use. **Default:** `99999`.
 
 ```ts
-const options = {
+const webamp = new Webamp({
   zIndex: 99999,
-};
+  // ...other config options
+});
 ```
 
 ### `filePickers`
 
-An array of additional file pickers. These will appear in the "Options" menu under "Play". Each file picker should have a `contextMenuName`, a `filePicker` function that returns a Promise resolving to an array of `track`s, and a `requiresNetwork` boolean indicating if the option should be available when offline.
+An array of additional file pickers. These will appear in the "Options" menu under "Play". Each file picker should have a `contextMenuName`, a `filePicker` function that returns a Promise resolving to an array of [`track`s](01_track.md), and a `requiresNetwork` boolean indicating if the option should be available when offline.
 
 This can be used to implement integration with services like Dropbox or Google Drive.
 
 ```ts
-const options = {
+const webamp = new Webamp({
   filePickers: [
     {
       contextMenuName: "My File Picker...",
@@ -149,55 +168,59 @@ const options = {
       requiresNetwork: true,
     },
   ],
-};
+  // ...other config options
+});
 ```
 
 ### `handleTrackDropEvent`
 
-An optional function to provide a custom way to derive `Track` objects from a drop event. Useful if your website has some DOM representation of a track that you can map to a URL/blob.
+An optional function to provide a custom way to derive [`Track`](01_track.md) objects from a drop event. Useful if your website has some DOM representation of a track that you can map to a URL/blob.
 
-The function should return an array of `Track` objects or `null` to get the default drop behavior.
+The function should return an array of [`Track`](01_track.md) objects or `null` to get the default drop behavior.
 
 ```ts
-const options = {
+const webamp = new Webamp({
   handleTrackDropEvent: async (e) => {
     return [
       /* array of Tracks */
     ];
   },
-};
+  // ...other config options
+});
 ```
 
 ### `handleAddUrlEvent`
 
 **Since** 1.4.1
 
-An optional function to extend the behavior of the button "ADD URL". The function should return an optional array of `Track` objects or `null`.
+An optional function to extend the behavior of the button "ADD URL". The function should return an optional array of [`Track`](01_track.md) objects or `null`.
 
 ```ts
-const options = {
+const webamp = new Webamp({
   handleAddUrlEvent: async () => {
     return [
       /* array of Tracks */
     ];
   },
-};
+  // ...other config options
+});
 ```
 
 ### `handleLoadListEvent`
 
 **Since** 1.4.1
 
-An optional function to extend the behavior of the playlist button "LOAD LIST". The function should return an optional array of `Track` objects or `null`.
+An optional function to extend the behavior of the playlist button "LOAD LIST". The function should return an optional array of [`Track`](01_track.md) objects or `null`.
 
 ```ts
-const options = {
+const webamp = new Webamp({
   handleLoadListEvent: async () => {
     return [
       /* array of Tracks */
     ];
   },
-};
+  // ...other config options
+});
 ```
 
 ### `handleSaveListEvent`
@@ -206,9 +229,62 @@ const options = {
 Provide a way to extend the behavior of the playlist button SAVE LIST.
 
 ```ts
-const options = {
+const webamp = new Webamp({
   handleSaveListEvent: (tracks) => {
     // Perform custom save logic with the current tracks.
   },
-};
+  // ...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 };
+      });
+    },
+  },
+});
 ```

packages/webamp-docs/docs/06_API/03_instance-methods.md

@@ -1,6 +1,16 @@
 # Instance Methods
 
-The `Webamp` class has the following _instance_ methods:
+Once you have [constructed](02_webamp-constructor.md) a `Webamp` instance, the instance has methods you can use to get the state of the player, control playback, and manage tracks, register event listeners, and more.
+
+```ts
+import Webamp from "webamp";
+
+const webamp = new Webamp({
+  // ... options
+});
+```
+
+The `webamp` instance has the following _instance_ methods:
 
 ### `appendTracks(tracks: Track[]): void`
 

packages/webamp-docs/docs/06_API/04_static-methods.md

@@ -4,7 +4,7 @@ The `Winamp` class has the following _static_ methods:
 
 ### `browserIsSupported()`
 
-Returns a true if the current browser supports the features that Webamp depends upon. It is recommended to check this before you attempt to instantiate an instance of `Winamp`.
+Returns a true if the current browser supports the features that Webamp depends upon. It is recommended to check this before you attempt to [construct](02_webamp-constructor.md) an instance of `Winamp`.
 
 ```ts
 import Webamp from "webamp";