Mirrors/webamp
1
0
Fork 0
mirror of https://github.com/captbaritone/webamp.git synced 2026-01-23 02:15:01 +00:00
Code Issues Projects Releases Wiki Activity

Add docs site

Browse source
This commit is contained in:
Jordan Eldredge 2025-06-18 22:52:26 -07:00
parent 359b3258ed
commit 91e6bd3902
34 changed files with 8797 additions and 3445 deletions
Download patch file Download diff file Expand all files Collapse all files

1
examples/minimal/index.html
View file

@ -34,7 +34,6 @@
],
});
// Returns a promise indicating when it's done loading.
webamp.renderWhenReady(document.getElementById("app"));
</script>
</body>

20
packages/webamp-docs/.gitignore vendored Normal file
View file

@ -0,0 +1,20 @@
# Dependencies
/node_modules
# Production
/build
# Generated files
.docusaurus
.cache-loader
# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*

41
packages/webamp-docs/README.md Normal file
View file

@ -0,0 +1,41 @@
# Website
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
## Installation
```bash
yarn
```
## Local Development
```bash
yarn start
```
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
## Build
```bash
yarn build
```
This command generates static content into the `build` directory and can be served using any static contents hosting service.
## Deployment
Using SSH:
```bash
USE_SSH=true yarn deploy
```
Not using SSH:
```bash
GIT_USER=<Your GitHub username> yarn deploy
```
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

25
packages/webamp-docs/blog/authors.yml Normal file
View file

@ -0,0 +1,25 @@
yangshun:
name: Yangshun Tay
title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd
url: https://linkedin.com/in/yangshun
image_url: https://github.com/yangshun.png
page: true
socials:
x: yangshunz
linkedin: yangshun
github: yangshun
newsletter: https://www.greatfrontend.com
slorber:
name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
page:
# customize the url of the author page at /blog/authors/<permalink>
permalink: '/all-sebastien-lorber-articles'
socials:
x: sebastienlorber
linkedin: sebastienlorber
github: slorber
newsletter: https://thisweekinreact.com

19
packages/webamp-docs/blog/tags.yml Normal file
View file

@ -0,0 +1,19 @@
facebook:
label: Facebook
permalink: /facebook
description: Facebook tag description
hello:
label: Hello
permalink: /hello
description: Hello tag description
docusaurus:
label: Docusaurus
permalink: /docusaurus
description: Docusaurus tag description
hola:
label: Hola
permalink: /hola
description: Hola tag description

33
packages/webamp-docs/docs/01_intro.md Normal file
View file

@ -0,0 +1,33 @@
# Quick Start Guide
Here is the most minimal example of adding Webamp to an HTML page:
```html
<!DOCTYPE html>
<html>
<body>
<div id="app" style="height: 100vh">
<!-- Webamp will attempt to center itself within this div -->
</div>
<script type="module">
import Webamp from "https://unpkg.com/webamp@^2";
const webamp = new Webamp({});
// Returns a promise indicating when it's done loading.
webamp.renderWhenReady(document.getElementById("app"));
</script>
</body>
</html>
```
:::tip
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.**
3. API - Learn about the Webamp API, including how to control playback, add tracks, and more.
- [Webamp Constructor Options](./API/02_webamp-constructor.md) - Learn about the options you can pass to the Webamp constructor.
- [Webamp Instance Methods](./API/03_instance-methods.md) - Learn about the methods you can call on a Webamp instance.

43
packages/webamp-docs/docs/02_install.md Normal file
View file

@ -0,0 +1,43 @@
# Installation
Webamp can be installed from NPM or included via a script tag using a a free content delivery network (CDN) such as [unpkg](https://unpkg.com/).
:::warning
Keep in mind that if you choose to use a free CDN, that CDN may stop operating at any time. If possible, consider downloading the file and serving it from your own server.
:::
## Install via NPM
```bash
npm install --save webamp
```
From here you can import Webamp in your JavaScript code:
```js
import Webamp from "webamp";
// ... use Webamp here
```
## Import directly from a CDN
ES modules can be imported via URL directly inside a `<script type="module">` tag.
```html
<script type="module">
import Webamp from "https://unpkg.com/webamp@^2";
// ... use Webamp here
</script>
```
## Include via a script tag
This will make the Webamp constructor available as a `window` property: `window.Webamp` keep in mind that you will need to use the `type="module"` attribute on the script tag,
```html
<script src="https://unpkg.com/webamp@^2" type="module"></script>
<script>
const Webamp = window.Webamp;
// ... use Webamp here
</script>
```

46
packages/webamp-docs/docs/03_initialization.md Normal file
View file

@ -0,0 +1,46 @@
# Initialization
Webamp is initialized in two steps. First you create a Webamp instance, and then you render, providing a DOM element telling Webamp where you want it to appear in the document.
## Create a container
Create a DOM element somewhere in your HTML document. This will be used by Webamp to find it's initial position.
```html
<div id="winamp-container"></div>
```
:::tip
**Webamp will not actually insert itself as a child of this element.** It will will insert itself as a child of the body element, and will attempt to center itself within this element. This is needed to allow the various Webamp windows to dragged around the page unencumbered.
:::
## Initialize Webamp instance
```ts
import Webamp from "webamp";
// All configuration options are optional.
const webamp = new Webamp({
// ... optional initialization options like initial tracks, skin, etc. can be
// supplied here.
});
// Render after the skin has loaded.
webamp.renderWhenReady(document.getElementById("winamp-container"));
```
:::tip
See [Webamp Constructor Options](./API/02_webamp-constructor.md) for a list of options you can pass to the Webamp constructor.
:::
## Check compatibility
Webamp works great in all modern browser, but if you want to be sure that it will work in the current browser, you can check for compatibility before initializing Webamp.
```typescript
// Check if Winamp is supported in this browser
if (!Webamp.browserIsSupported()) {
alert("Oh no! Webamp does not work!");
throw new Error("What's the point of anything?");
}
```

11
packages/webamp-docs/docs/04_examples.md Normal file
View file

@ -0,0 +1,11 @@
# Examples
If you would like to look at some examples check out the [examples directory](https://github.com/captbaritone/webamp/tree/master/examples/) where you will find:
- [Minimal](https://github.com/captbaritone/webamp/tree/master/examples/minimal) Stick Webamp in a `<script>` tag, and add a few lines of JavaScript to get Webamp on your page.
- [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**
Each example has a README which explains it in more detail.

54
packages/webamp-docs/docs/05_features/01_hotkeys.md Normal file
View file

@ -0,0 +1,54 @@
# Hotkeys
Webamp attempts to emulate the hotkeys of the original Winamp. This means that you can control playback and other features of Webamp using your keyboard.
## Enable hotkeys
If you want to display the hotkeys in the Webamp UI, you can pass the `enableHotkeys` option when initializing Webamp:
```ts
import Webamp from "webamp";
const webamp = new Webamp({
enableHotkeys: true,
});
webamp.renderWhenReady(document.getElementById("winamp-container"));
```
## Hotkeys
| Key Combo | Action |
| --------- | ----------------------- |
| X | Play |
| C | Pause |
| V | Stop |
| B | Next Track |
| Z | Previous Track |
| R | Toggle Repeat |
| S | Toggle Shuffle |
| L | Open File Dialog |
| ← (Left) | Seek Backward (5s) |
| → (Right) | Seek Forward (5s) |
| ↑ (Up) | Volume Up |
| ↓ (Down) | Volume Down |
| Ctrl+D | Toggle Double Size Mode |
| Ctrl+R | Reverse Playlist |
| Ctrl+T | Toggle Time Mode |
| Alt+W | Toggle Main Window |
| Alt+E | Toggle Playlist Window |
| Alt+G | Toggle Equalizer Window |
| Numpad 0 | Open File Dialog |
| Numpad 1 | Skip Backward 10 Tracks |
| Numpad 2 | Volume Down |
| Numpad 3 | Skip Forward 10 Tracks |
| Numpad 4 | Previous Track |
| Numpad 5 | Play |
| Numpad 6 | Next Track |
| Numpad 7 | Seek Backward (5s) |
| Numpad 8 | Volume Up |
| Numpad 9 | Seek Forward (5s) |
## 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.

4
packages/webamp-docs/docs/05_features/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "Features",
"collapsible": true
}

35
packages/webamp-docs/docs/API/01_track.md Normal file
View file

@ -0,0 +1,35 @@
# Track Type
Many methods on the webamp instance deal with `Track`s. Here is the shape of a `Track`:
:::warning
**The `url` must be served with the [correct CORS headers](../guides/01_cors.md).**
:::
```ts
const track = {
// Either `url` or `blob` must be specified
// Note: This URL must be served the with correct CORs headers.
url: "https://example.com/song.mp3",
blob: dataBlob,
// Optional. Name to be used until ID3 tags can be resolved.
// If the track has a `url`, and this property is not given,
// the filename will be used instead.
defaultName: "My Song",
// Optional. Data to be used _instead_ of trying to fetch ID3 tags.
// **WARNING** If you omit this data, Webamp will fetch the first
// few bytes of this file on load to try to read its id3 tags.
metaData: {
artist: "Jordan Eldredge",
title: "Jordan's Song",
},
// Optional. Duration (in seconds) to be used instead of
// fetching enough of the file to measure its length.
// **WARNING** If you omit this property, Webamp will fetch the first
// few bytes of this file on load to try to determine its duration.
duration: 95,
};
```

214
packages/webamp-docs/docs/API/02_webamp-constructor.md Normal file
View file

@ -0,0 +1,214 @@
# Webamp Constructor
The `Winamp` class is constructed with an options object. _All config properties are optional._
### `initialTracks`
An array of `track`s to prepopulate the playlist with. **The `url` must be served with the [correct CORS headers](../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 = {
initialTracks: [
{
url: "./path/to/track.mp3",
metaData: {
artist: "Artist Name",
title: "Track Title",
},
duration: 120, // Track duration in seconds
},
],
};
```
### `initialSkin`
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](../guides/01_cors.md).**
```ts
const options = {
initialSkin: {
url: "./path/to/skin.wsz",
},
};
```
### `availableSkins`
An array of objects representing skins. These will appear in the "Options" menu under "Skins". **The URLs must be served with the [correct CORS headers](../guides/01_cors.md).**
:::tip
You can find skins to download at the [Winamp Skin Museum](https://skins.webamp.org).
:::
```ts
const options = {
availableSkins: [
{ url: "./green.wsz", name: "Green Dimension V2" },
{ url: "./osx.wsz", name: "Mac OSX v1.5 (Aqua)" },
],
};
```
### `windowLayout`
**Since** 2.0.0
An object representing the initial layout of the windows. Valid keys are `main`, `equalizer`, `playlist`, and `milkdrop`. Omitted windows will start hidden.
- Each provided window must specify a `position` object with `top` and `left` which specify pixel offsets.
- Each provided window, except for `milkdrop`, may specify a `shadeMode` boolean.
- Each provided window may specify a `closed` boolean.
- The playlist and milkdrop windows may specify a `size` object with `extraHeight` and `extraWidth`. These numbers represent the number of additional sprites by which to expand the window.
**Note:** After windows are positioned, they are then centered _as a group_ within the DOM element that Webamp is rendered into.
```ts
const options = {
windowLayout: {
main: {
position: { top: 0, left: 0 },
shadeMode: true,
closed: false,
},
equalizer: {
position: { top: 0, left: 0 },
shadeMode: true,
closed: false,
},
playlist: {
position: { top: 0, left: 0 },
shadeMode: true,
// Number of additional sprites by which to expand the window.
size: { extraHeight: 1, extraWidth: 10 },
closed: false,
},
},
};
```
### `enableDoubleSizeMode`
_Since 2.0.0_
A boolean indicating if double size mode should be enabled. **Default:** `false`.
```ts
const options = {
enableDoubleSizeMode: true,
};
```
:::tip
In keeping with the original Winamp, **double size mode does not apply to resizable windows like the equalizer or Milkdrop**.
:::
### `enableHotkeys`
A boolean indicating if global hotkeys should be enabled. **Default:** `false`.
```ts
const options = {
enableHotkeys: true,
};
```
For a list of hotkeys, see the [hotkeys documentation](../05_features/01_hotkeys.md).
### `zIndex`
An integer representing the zIndex that Webamp should use. **Default:** `99999`.
```ts
const options = {
zIndex: 99999,
};
```
### `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.
This can be used to implement integration with services like Dropbox or Google Drive.
```ts
const options = {
filePickers: [
{
contextMenuName: "My File Picker...",
filePicker: () =>
Promise.resolve([
{
url: "./rick_roll.mp3",
},
]),
requiresNetwork: true,
},
],
};
```
### `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.
The function should return an array of `Track` objects or `null` to get the default drop behavior.
```ts
const options = {
handleTrackDropEvent: async (e) => {
return [
/* array of Tracks */
];
},
};
```
### `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`.
```ts
const options = {
handleAddUrlEvent: async () => {
return [
/* array of Tracks */
];
},
};
```
### `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`.
```ts
const options = {
handleLoadListEvent: async () => {
return [
/* array of Tracks */
];
},
};
```
### `handleSaveListEvent`
**Since** 1.4.1
Provide a way to extend the behavior of the playlist button SAVE LIST.
```ts
const options = {
handleSaveListEvent: (tracks) => {
// Perform custom save logic with the current tracks.
},
};
```

246
packages/webamp-docs/docs/API/03_instance-methods.md Normal file
View file

@ -0,0 +1,246 @@
# Instance Methods
The `Webamp` class has the following _instance_ methods:
### `appendTracks(tracks: Track[]): void`
Add an array of [`Track`s](01_track.md) to the end of the playlist.
```ts
webamp.appendTracks([
{ url: "https://example.com/track1.mp3" },
{ url: "https://example.com/track2.mp3" },
{ url: "https://example.com/track3.mp3" },
]);
```
:::warning
**The `url` must be served with the [correct CORS headers](../guides/01_cors.md).**
:::
### `setTracksToPlay(tracks: Track[]): void`
Replace the playlist with an array of [`Track`s](01_track.md) and begin playing the first track.
```ts
webamp.setTracksToPlay([
{ url: "https://example.com/track1.mp3" },
{ url: "https://example.com/track2.mp3" },
{ url: "https://example.com/track3.mp3" },
]);
```
:::warning
**The `url` must be served with the [correct CORS headers](../guides/01_cors.md).**
:::
### `previousTrack(): void`
Play the previous track.
**Since** 1.3.0
```ts
webamp.previousTrack();
```
### `nextTrack(): void`
Play the next track.
**Since** 1.3.0
```ts
webamp.nextTrack();
```
### `seekForward(seconds): void`
Seek forward n seconds in the current track.
**Since** 1.3.0
```ts
webamp.seekForward(10);
```
### `seekBackward(seconds): void`
Seek backward n seconds in the current track.
**Since** 1.3.0
```ts
webamp.seekBackward(10);
```
### `seekToTime(seconds)`
Seek to a given time within the current track.
**Since** 1.4.0
```ts
webamp.seekToTime(15.5);
```
### `getMediaStatus()`
Get the current "playing" status. The return value is one of: `"PLAYING"`, `"STOPPED"`, or `"PAUSED"`.
**Since** 1.4.0
```ts
const isPlaying = webamp.getMediaStatus() === "PLAYING";
```
### `pause(): void`
Pause the current track.
**Since** 1.3.0
```ts
webamp.pause();
```
### `play(): void`
Play the current track.
**Since** 1.3.0
```ts
webamp.play();
```
### `stop(): void`
Stop the currently playing audio. Equivilant to pressing the "stop" button.
**Since** 1.4.0
```ts
webamp.stop();
```
### `renderWhenReady(domNode: HTMLElement): Promise<void>`
Webamp will wait until it has fetched the skin and fully parsed it, and then render itself into a new DOM node at the end of the `<body>` tag.
If a `domNode` is passed, Webamp will place itself in the center of that DOM node.
A promise is returned which will resolve after the render is complete.
```ts
const container = document.getElementById("winamp-container");
webamp.renderWhenReady(container).then(() => {
console.log("rendered webamp!");
});
```
### `onTrackDidChange(cb: (trackInfo: LoadedURLTrack | null) => void): () => void`
A callback which will be called when a new track starts loading. This can happen on startup when the first track starts buffering, or when a subsequent track starts playing. The callback will be called with an object (`{url: 'https://example.com/track.mp3'}`) containing the URL of the track.
Returns an "unsubscribe" function.
**Note:** If the user drags in a track, the URL may be an [ObjectURL](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL)
```ts
const unsubscribe = webamp.onTrackDidChange((track => {
console.log("New track playing:", track.url);
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `onWillClose(cb: (cancel: () => void) => void): () => void`
A callback which will be called when Webamp is _about to_ close. Returns an "unsubscribe" function. The callback will be passed a `cancel` function which you can use to conditionally prevent Webamp from being closed.
```ts
const unsubscribe = webamp.onWillClose((cancel) => {
if (!window.confirm("Are you sure you want to close Webamp?")) {
cancel();
}
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `onClose(cb: () => void): () => void`
A callback which will be called when Webamp is closed. Returns an "unsubscribe" function.
```ts
const unsubscribe = webamp.onClose(() => {
console.log("Webamp closed");
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `close(): void`
Equivalent to selection "Close" from Webamp's options menu. Once closed, you can open it again with `.reopen()`.
**Since** 1.4.1
### `reopen(): void`
After `.close()`ing this instance, you can reopen it by calling this method.
**Since** 1.3.0
```ts
const icon = document.getElementById("webamp-icon");
webamp.onClose(() => {
icon.addEventListener("click", () => {
webamp.reopen();
});
});
```
### `onMinimize(cb: () => void): () => void`
A callback which will be called when Webamp is minimized. Returns an "unsubscribe" function.
```ts
const unsubscribe = webamp.onMinimize(() => {
console.log("Webamp closed");
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `setSkinFromUrl(url: string): void`
Updates the skin used by the webamp instance. Note that this does not happen immediately. If you want to be notified when the skin load is complete, use `.skinIsLoaded()`, which returns a promise which you can await.
**Since** 1.4.1
### `skinIsLoaded(): Promise<void>`
Returns a promise that resolves when the skin is done loading.
```ts
const start = Date.now();
await webamp.skinIsLoaded();
console.log(`The skin loaded in ${Date.now() - start}`);
```
### `dispose(): void`
**Note:** _This method is not fully functional. It is currently impossible to clean up a Winamp instance. This method makes an effort, but it still leaks the whole instance. In the future the behavior of this method will improve, so you might as well call it._
When you are done with a Webamp instance, call this method and Webamp will attempt to clean itself up to avoid memory leaks.
```ts
webamp.dispose();
```

20
packages/webamp-docs/docs/API/04_static-methods.md Normal file
View file

@ -0,0 +1,20 @@
# Static Methods
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`.
```ts
import Webamp from "webamp";
if (Winamp.browserIsSupported()) {
new Winamp({
/* ... */
});
// ...
} else {
// Perhaps you could show some simpler player in this case.
}
```

35
packages/webamp-docs/docs/API/05_acessing_internals.md Normal file
View file

@ -0,0 +1,35 @@
# Accessing Internals
Webamp is implemented using [Redux](https://redux.js.org/). This means that, if you need to control some aspect of Webamp that is not exposed through the public API, you can access the Redux store and dispatch actions directly.
:::danger
The Webamp Redux store is not part of the public API and **may change in future versions**. Use this feature at your own risk.
:::
To determine which actions you might want to dispatch, I recommend installing the excellent [Redux DevTools](https://chromewebstore.google.com/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en) Chrome extension. This will allow you to inspect the actions that Webamp dispatches and the state of the Redux store.
## Accessing the Redux Store
You can access the Redux store by calling the `getStore` method on the Webamp instance. This will return the Redux store, which you can then use to dispatch actions or access the current state.
```js
import Webamp from "webamp";
async function initWebamp() {
const webamp = new Webamp({});
// Example: Dispatch an action to change the volume before rendering
webamp.store.dispatch({
type: "SET_VOLUME",
volume: 50, // Set volume to 50%
});
// Wait for Webamp to be ready
await webamp.renderWhenReady(document.getElementById("winamp-container"));
// Example: Access the current state of the Redux store
console.log(webamp.store.getState());
}
initWebamp();
```

7
packages/webamp-docs/docs/guides/01_cors.md Normal file
View file

@ -0,0 +1,7 @@
# Cross Original Resource Sharing (CORS)
One of the most common issues when using Webamp is related to Cross-Origin Resource Sharing (CORS).
In short, your skins and audio tracks must either be served from the same domain as your HTML file, or they must be served with permissive CORS HTTP headers. This is a security feature of web browsers that prevents malicious sites from accessing resources on other domains without permission.
You can learn more about CORS in the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).

30
packages/webamp-docs/docs/guides/03_bundle-size.md Normal file
View file

@ -0,0 +1,30 @@
# 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`.
First you'll need to install the dependencies in your project:
```bash
npm install jszip music-metadata-browser@^0.6.1
```
The "lazy" version of Webamp will require that you inject functions for lazily importing these dependencies.
```ts
import Webamp from "webamp/lazy";
const webamp = new Webamp({
initialTracks: [
{
url: "https://example.com/track1.mp3",
metaData: {
artist: "Jordan Eldredge",
title: "Jordan's Song",
},
duration: 95,
},
],
requireJSZip: () => import("jszip/dist/jszip"),
requireMusicMetadata: () => import("music-metadata-browser/dist/index"),
});
```

4
packages/webamp-docs/docs/guides/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "Guides",
"collapsible": true
}

139
packages/webamp-docs/docusaurus.config.ts Normal file
View file

@ -0,0 +1,139 @@
import { themes as prismThemes } from "prism-react-renderer";
import type { Config } from "@docusaurus/types";
import type * as Preset from "@docusaurus/preset-classic";
// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
const config: Config = {
title: "Webamp",
tagline: "Embed Webamp in your site",
favicon: "img/favicon.ico",
// Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
future: {
v4: true, // Improve compatibility with the upcoming Docusaurus v4
},
// Set the production url of your site here
url: "https://webamp.",
// Set the /<baseUrl>/ pathname under which your site is served
// For GitHub pages deployment, it is often '/<projectName>/'
baseUrl: "/",
onBrokenLinks: "throw",
onBrokenMarkdownLinks: "warn",
// Even if you don't use internationalization, you can use this field to set
// useful metadata like html lang. For example, if your site is Chinese, you
// may want to replace "en" with "zh-Hans".
i18n: {
defaultLocale: "en",
locales: ["en"],
},
presets: [
[
"classic",
{
docs: {
sidebarPath: "./sidebars.ts",
// // Please change this to your repo.
// // Remove this to remove the "edit this page" links.
// editUrl:
// "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
},
// blog: {
// showReadingTime: true,
// feedOptions: {
// type: ["rss", "atom"],
// xslt: true,
// },
// // Please change this to your repo.
// // Remove this to remove the "edit this page" links.
// editUrl:
// "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
// // Useful options to enforce blogging best practices
// onInlineTags: "warn",
// onInlineAuthors: "warn",
// onUntruncatedBlogPosts: "warn",
// },
theme: {
customCss: "./src/css/custom.css",
},
} satisfies Preset.Options,
],
],
themeConfig: {
// Replace with your project's social card
// image: "img/docusaurus-social-card.jpg",
navbar: {
title: "Webamp",
logo: {
alt: "Webamp Logo",
src: "img/winamp2-32x32.png",
},
items: [
{
type: "docSidebar",
sidebarId: "docsSidebar",
position: "left",
label: "Docs",
},
// { to: "/blog", label: "Blog", position: "left" },
{
href: "https://github.com/captbaritone/webamp",
label: "GitHub",
position: "right",
},
],
},
footer: {
style: "dark",
links: [
{
title: "Docs",
items: [
{
label: "Tutorial",
to: "/docs/intro",
},
],
},
{
title: "Community",
items: [
{
label: "Discord",
href: "https://webamp.org/chat",
},
// {
// label: "X",
// href: "https://x.com/docusaurus",
// },
],
},
// {
// title: "More",
// items: [
// {
// label: "Blog",
// to: "/blog",
// },
// {
// label: "GitHub",
// href: "https://github.com/facebook/docusaurus",
// },
// ],
// },
],
copyright: `Copyright © ${new Date().getFullYear()} Jordan Eldredge. Built with Docusaurus.`,
},
prism: {
theme: prismThemes.github,
darkTheme: prismThemes.dracula,
},
} satisfies Preset.ThemeConfig,
};
export default config;

47
packages/webamp-docs/package.json Normal file
View file

@ -0,0 +1,47 @@
{
"name": "webamp-docs",
"version": "0.0.0",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids",
"typecheck": "tsc"
},
"dependencies": {
"@docusaurus/core": "3.8.1",
"@docusaurus/preset-classic": "3.8.1",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
"prism-react-renderer": "^2.3.0",
"react": "^19.0.0",
"react-dom": "^19.0.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "3.8.1",
"@docusaurus/tsconfig": "3.8.1",
"@docusaurus/types": "3.8.1",
"typescript": "~5.6.2"
},
"browserslist": {
"production": [
">0.5%",
"not dead",
"not op_mini all"
],
"development": [
"last 3 chrome version",
"last 3 firefox version",
"last 5 safari version"
]
},
"engines": {
"node": ">=18.0"
}
}

33
packages/webamp-docs/sidebars.ts Normal file
View file

@ -0,0 +1,33 @@
import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
/**
* Creating a sidebar enables you to:
- create an ordered group of docs
- render a sidebar for each doc of that group
- provide next/previous navigation
The sidebars can be generated from the filesystem, or explicitly defined here.
Create as many sidebars as you want.
*/
const sidebars: SidebarsConfig = {
// By default, Docusaurus generates a sidebar from the docs folder structure
docsSidebar: [{ type: "autogenerated", dirName: "." }],
// But you can create a sidebar manually
/*
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],
*/
};
export default sidebars;

59
packages/webamp-docs/src/components/HomepageFeatures/index.tsx Normal file
View file

@ -0,0 +1,59 @@
import { useEffect, useState, type ReactNode } from "react";
import styles from "./styles.module.css";
import BrowserOnly from "@docusaurus/BrowserOnly";
import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
let Webamp: typeof import("webamp").default | undefined;
if (ExecutionEnvironment.canUseDOM) {
Webamp = require("webamp");
}
function WebampComponent(): ReactNode {
const [ref, setRef] = useState<HTMLDivElement | null>(null);
useEffect(() => {
if (!ref || !Webamp) {
return;
}
const webamp = new Webamp({
initialTracks: [
{
metaData: {
artist: "DJ Mike Llama",
title: "Llama Whippin' Intro",
},
url: "https://cdn.jsdelivr.net/gh/captbaritone/webamp@43434d82cfe0e37286dbbe0666072dc3190a83bc/mp3/llama-2.91.mp3",
duration: 5.322286,
},
{
metaData: {
artist: "Some Artist",
title: "Title of Second Track",
},
url: "https://cdn.jsdelivr.net/gh/captbaritone/webamp@43434d82cfe0e37286dbbe0666072dc3190a83bc/mp3/llama-2.91.mp3",
duration: 5.322286,
},
],
});
webamp.renderWhenReady(ref);
return () => {
// Cleanup Webamp instance when the component unmounts
webamp.dispose();
};
}, [ref]);
return <div ref={setRef} style={{ height: "400px", width: "100%" }}></div>;
}
export default function HomepageFeatures(): ReactNode {
return (
<section className={styles.features}>
<div className="container">
<div className="row">
<BrowserOnly>{() => <WebampComponent />}</BrowserOnly>
</div>
</div>
</section>
);
}

11
packages/webamp-docs/src/components/HomepageFeatures/styles.module.css Normal file
View file

@ -0,0 +1,11 @@
.features {
display: flex;
align-items: center;
padding: 2rem 0;
width: 100%;
}
.featureSvg {
height: 200px;
width: 200px;
}

22
packages/webamp-docs/src/css/custom.css Normal file
View file

@ -0,0 +1,22 @@
:root {
--ifm-color-primary: #ff8800; /* Deeper Winamp orange */
--ifm-color-primary-dark: #e67a00;
--ifm-color-primary-darker: #cc6d00;
--ifm-color-primary-darkest: #995300;
--ifm-color-primary-light: #ff9933;
--ifm-color-primary-lighter: #ffaa4d;
--ifm-color-primary-lightest: #ffbb66;
--ifm-code-font-size: 95%;
--docusaurus-highlighted-code-line-bg: rgba(255, 136, 0, 0.1);
}
[data-theme="dark"] {
--ifm-color-primary: #66ccff; /* Neon Winamp blue */
--ifm-color-primary-dark: #5cb8e6;
--ifm-color-primary-darker: #52a3cc;
--ifm-color-primary-darkest: #3d7a99;
--ifm-color-primary-light: #80d4ff;
--ifm-color-primary-lighter: #99ddff;
--ifm-color-primary-lightest: #b3e6ff;
--docusaurus-highlighted-code-line-bg: rgba(255, 255, 255, 0.05);
}

23
packages/webamp-docs/src/pages/index.module.css Normal file
View file

@ -0,0 +1,23 @@
/**
* CSS files with the .module.css suffix will be treated as CSS modules
* and scoped locally.
*/
.heroBanner {
padding: 4rem 0;
text-align: center;
position: relative;
overflow: hidden;
}
@media screen and (max-width: 996px) {
.heroBanner {
padding: 2rem;
}
}
.buttons {
display: flex;
align-items: center;
justify-content: center;
}

46
packages/webamp-docs/src/pages/index.tsx Normal file
View file

@ -0,0 +1,46 @@
import type { ReactNode } from "react";
import clsx from "clsx";
import Link from "@docusaurus/Link";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import Layout from "@theme/Layout";
import HomepageFeatures from "@site/src/components/HomepageFeatures";
import Heading from "@theme/Heading";
import styles from "./index.module.css";
function HomepageHeader() {
const { siteConfig } = useDocusaurusContext();
return (
<header className={clsx("hero hero--primary", styles.heroBanner)}>
<div className="container">
<Heading as="h1" className="hero__title">
{siteConfig.title}
</Heading>
<p className="hero__subtitle">{siteConfig.tagline}</p>
<div className={styles.buttons}>
<Link
className="button button--secondary button--lg"
to="/docs/intro"
>
Quick Start Guide
</Link>
</div>
</div>
</header>
);
}
export default function Home(): ReactNode {
const { siteConfig } = useDocusaurusContext();
return (
<Layout
title={`${siteConfig.title}`}
description="Embed Webamp in your site"
>
<HomepageHeader />
<main>
<HomepageFeatures />
</main>
</Layout>
);
}

7
packages/webamp-docs/src/pages/markdown-page.md Normal file
View file

@ -0,0 +1,7 @@
---
title: Markdown page example
---
# Markdown page example
You don't need React to write simple standalone pages.

0
packages/webamp-docs/static/.nojekyll Normal file
View file

BIN
packages/webamp-docs/static/img/favicon.ico Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 21 KiB

BIN
packages/webamp-docs/static/img/winamp2-32x32.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 518 B

8
packages/webamp-docs/tsconfig.json Normal file
View file

@ -0,0 +1,8 @@
{
// This file is not used in compilation. It is here just for a nice editor experience.
"extends": "@docusaurus/tsconfig",
"compilerOptions": {
"baseUrl": "."
},
"exclude": [".docusaurus", "build"]
}

539
packages/webamp/docs/usage.md
View file

@ -1,540 +1,3 @@
# Usage
Here's how to use Webamp in your own project. If you get stuck, or need help, please either file an issue, or reach out on [Discord](https://discord.gg/fBTDMqR).
## Examples
If you would like to look at some examples check out the [examples directory](../../../examples/) where you will find:
- [Minimal](../../../examples/minimal) Stick Webamp in a `<script>` tag, and add a few lines of JavaScript to get Webamp on your page.
- [Multiple Tracks](../../../examples/multipleTracks) An example of setting up Webamp with multiple audio tracks.
- [Multiple Skins](../../../examples/multipleSkins) An example of setting up Webamp with multiple skins.
- [Minimal Window Layout](../../../examples/minimalWindowLayout) An example of configuring the initial layout of windows in Webamp.
- [Webpack](../../../examples/webpack) Install Webamp via NPM and bundle it in a Webpack bundle.
- [Webpack Lazyload](../../../examples/webpackLazyLoad) **In progress**
- [Minimal Milkdrop](../../../examples/minimalMilkdrop) **In progress**
Each example has a README which explains it in more detail.
## Install
```
npm install --save webamp
```
Or, you can include it via a script tag:
```html
<!-- You can use this URL, or download it and check it into your own project -->
<script src="https://unpkg.com/webamp@^2" type="module"></script>
```
## Create a container
Create a DOM element somewhere in your HTML document. This will be used by Webamp to find it's initial position.
```html
<div id="winamp-container"></div>
```
## Initialize the JavaScript
```JavaScript
import Webamp from 'webamp';
// Or, if you installed via a script tag, `Winamp` is available on the global `window`:
// const Winamp = window.Webamp;
// Check if Winamp is supported in this browser
if(!Webamp.browserIsSupported()) {
alert("Oh no! Webamp does not work!")
throw new Error("What's the point of anything?")
}
// All configuration options are optional.
const webamp = new Webamp({
// Optional.
initialTracks: [{
metaData: {
artist: "DJ Mike Llama",
title: "Llama Whippin' Intro",
},
// NOTE: Your audio file must be served from the same domain as your HTML
// file, or served with permissive CORS HTTP headers:
// https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
// Can be downloaded from: https://github.com/captbaritone/webamp/raw/master/mp3/llama-2.91.mp3
url: "path/to/mp3/llama-2.91.mp3"
}],
// Optional. The default skin is included in the js bundle, and will be loaded by default.
initialSkin: {
// NOTE: Your skin file must be served from the same domain as your HTML
// file, or served with permissive CORS HTTP headers:
// https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
// Can be downloaded from https://github.com/captbaritone/webamp/raw/master/skins/TopazAmp1-2.wsz
url: "path/to/skins/TopazAmp1-2.wsz"
},
});
// Render after the skin has loaded.
webamp.renderWhenReady(document.getElementById('winamp-container'));
```
## API
Many methods on the webamp instance deal with `track`s. Here is the shape of a `track`:
```JavaScript
const track = {
// Either `url` or `blob` must be specified
// Note: This URL must be served the with correct CORs headers.
url: 'https://example.com/song.mp3',
blob: dataBlob,
// Optional. Name to be used until ID3 tags can be resolved.
// If the track has a `url`, and this property is not given,
// the filename will be used instead.
defaultName: 'My Song',
// Optional. Data to be used _instead_ of trying to fetch ID3 tags.
// **WARNING** If you omit this data, Webamp will fetch the first
// few bytes of this file on load to try to read its id3 tags.
metaData: {
artist: 'Jordan Eldredge',
title: "Jordan's Song"
},
// Optional. Duration (in seconds) to be used instead of
// fetching enough of the file to measure its length.
// **WARNING** If you omit this property, Webamp will fetch the first
// few bytes of this file on load to try to determine its duration.
duration: 95
};
```
## Static Methods
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`.
```JavaScript
import Webamp from 'webamp';
if(Winamp.browserIsSupported()) {
new Winamp({/* ... */});
// ...
} else {
// Perhaps you could show some simpler player in this case.
}
```
## Construction
The `Winamp` class is constructed with an options object. All are optional.
```ts
const options = {
// Optional. An object representing the initial skin to use.
// If omitted, the default skin, included in the bundle, will be used.
// Note: This URL must be served the with correct CORs headers.
initialSkin: {
url: "./path/to/skin.wsz",
},
// Optional. An array of `track`s (see above) to prepopulate the playlist with.
initialTracks: [
/* ... */
],
// Optional. An array of objects representing skins.
// These will appear in the "Options" menu under "Skins".
// Note: These URLs must be served with the correct CORs headers.
availableSkins: [
{ url: "./green.wsz", name: "Green Dimension V2" },
{ url: "./osx.wsz", name: "Mac OSX v1.5 (Aqua)" },
],
// Optional. An object representing the initial layout of the windows.
// Valid keys are `main`, `equalizer`, `playlist` and `milkdrop`. All windows
// are optional.
//
// - Each provided window must specify a `position` object with `top` and
// `left` which specify pixel offsets.
// - Each provided window, except for
// `milkdrop` may specify a `shadeMode` boolean.
// - Each provided window may specify a `closed` boolean.
// - The playlist and milkdrop windows may specify a `size` object with
// `extraHeight` and `extraWidth`.
//
// **Note:** After windows are positioned, they are then centered _as a group_
// within the DOM element that Webamp is rendered into.
//
// **Since** @next
windowLayout: {
main: {
position: { top: 0, left: 0 },
shadeMode: true,
closed: false,
},
equalizer: {
position: { top: 0, left: 0 },
shadeMode: true,
closed: false,
},
playlist: {
position: { top: 0, left: 0 },
shadeMode: true,
// Number of additional sprites by which to expand the window.
size: { extraHeight: 1, extraHeight: 10 },
closed: false,
},
},
// Optional. (Default: `false`) Should double size mode be enabled?
// **Note:** In keeping with the original Winamp, double size mode
// does not apply to resizable windows like the equalizer or Milkdrop.
//
// **Since** @next
enableDoubleSizeMode: true,
// Optional. (Default: `false`) Should global hotkeys be enabled?
enableHotkeys: true,
// Optional. (Default: `0`) The zIndex that Webamp should use.
zIndex: 99999,
// Optional. An array of additional file pickers.
// These will appear in the "Options" menu under "Play".
// In the demo site, This option is used to provide a "Dropbox" file
// picker.
filePickers: [
{
// The name that will appear in the context menu.
contextMenuName: "My File Picker...",
// A function which returns a Promise that resolves to
// an array of `track`s (see above)
filePicker: () =>
Promise.resolve([
{
url: "./rick_roll.mp3",
},
]),
// A boolean indicating if this options should be made
// available when the user is offline.
requiresNetwork: true,
},
],
// Optional. 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.
handleTrackDropEvent: async (e) => {
// Return an array of `Track` objects, see documentation below, or `null` to get the default drop behavior.
// You may optionally wrap the return value in a promise.
},
// Optional. Provide a way to extend the behavior of the button ADD URL.
// **Since** 1.4.1
handleAddUrlEvent: async () => {
// Return an optional array of `Track` objects or null.
},
// Optional. Provide a way to extend the behavior of the playlist button LOAD LIST.
// **Since** 1.4.1
handleLoadListEvent: async () => {
// Return an optional array of `Track` objects or null.
},
// Optional. Provide a way to extend the behavior of the playlist button SAVE LIST.
// Where tracks: Track[]
// **Since** 1.4.1
handleSaveListEvent: (tracks) => {},
};
const webamp = new Webamp(options);
```
## Instance Methods
The `Webamp` class has the following _instance_ methods:
### `appendTracks(tracks: Track[]): void`
Add an array of `track`s (see above) to the end of the playlist.
```JavaScript
// NOTE: Your audio files must be served from the same domain as your HTML
// file, or served with permissive CORS HTTP headers:
// https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
webamp.appendTracks([
{url: 'https://example.com/track1.mp3'},
{url: 'https://example.com/track2.mp3'},
{url: 'https://example.com/track3.mp3'}
]);
```
### `setTracksToPlay(tracks: Track[]): void`
Replace the playlist with an array of `track`s (see above) and begin playing the first track.
```JavaScript
// NOTE: Your audio files must be served from the same domain as your HTML
// file, or served with permissive CORS HTTP headers:
// https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
webamp.setTracksToPlay([
{url: 'https://example.com/track1.mp3'},
{url: 'https://example.com/track2.mp3'},
{url: 'https://example.com/track3.mp3'}
]);
```
### `previousTrack(): void`
Play the previous track.
**Since** 1.3.0
```JavaScript
webamp.previousTrack();
```
### `nextTrack(): void`
Play the next track.
**Since** 1.3.0
```JavaScript
webamp.nextTrack();
```
### `seekForward(seconds): void`
Seek forward n seconds in the current track.
**Since** 1.3.0
```JavaScript
webamp.seekForward(10);
```
### `seekBackward(seconds): void`
Seek backward n seconds in the current track.
**Since** 1.3.0
```JavaScript
webamp.seekBackward(10);
```
### `seekToTime(seconds)`
Seek to a given time within the current track.
**Since** 1.4.0
```JavaScript
webamp.seekToTime(15.5);
```
### `getMediaStatus()`
Get the current "playing" status. The return value is one of: `"PLAYING"`, `"STOPPED"`, or `"PAUSED"`.
**Since** 1.4.0
```JavaScript
const isPlaying = webamp.getMediaStatus() === "PLAYING";
```
### `pause(): void`
Pause the current track.
**Since** 1.3.0
```JavaScript
webamp.pause();
```
### `play(): void`
Play the current track.
**Since** 1.3.0
```JavaScript
webamp.play();
```
### `stop(): void`
Stop the currently playing audio. Equivilant to pressing the "stop" button.
**Since** 1.4.0
```JavaScript
webamp.stop();
```
### `renderWhenReady(domNode: HTMLElement): Promise<void>`
Webamp will wait until it has fetched the skin and fully parsed it, and then render itself into a new DOM node at the end of the `<body>` tag.
If a `domNode` is passed, Webamp will place itself in the center of that DOM node.
A promise is returned which will resolve after the render is complete.
```JavaScript
const container = document.getElementById('winamp-container');
webamp.renderWhenReady(container).then(() => {
console.log('rendered webamp!');
});
```
### `onTrackDidChange(cb: (trackInfo: LoadedURLTrack | null) => void): () => void`
A callback which will be called when a new track starts loading. This can happen on startup when the first track starts buffering, or when a subsequent track starts playing. The callback will be called with an object (`{url: 'https://example.com/track.mp3'}`) containing the URL of the track.
Returns an "unsubscribe" function.
**Note:** If the user drags in a track, the URL may be an [ObjectURL](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL)
```JavaScript
const unsubscribe = webamp.onTrackDidChange((track => {
console.log("New track playing:", track.url);
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `onWillClose(cb: (cancel: () => void) => void): () => void`
A callback which will be called when Webamp is _about to_ close. Returns an "unsubscribe" function. The callback will be passed a `cancel` function which you can use to conditionally prevent Webamp from being closed.
```JavaScript
const unsubscribe = webamp.onWillClose((cancel) => {
if (!window.confirm("Are you sure you want to close Webamp?")) {
cancel();
}
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `onClose(cb: () => void): () => void`
A callback which will be called when Webamp is closed. Returns an "unsubscribe" function.
```JavaScript
const unsubscribe = webamp.onClose(() => {
console.log("Webamp closed");
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `close(): void`
Equivalent to selection "Close" from Webamp's options menu. Once closed, you can open it again with `.reopen()`.
**Since** 1.4.1
### `reopen(): void`
After `.close()`ing this instance, you can reopen it by calling this method.
**Since** 1.3.0
```JavaScript
const icon = document.getElementById('webamp-icon');
webamp.onClose(() => {
icon.addEventListener('click', () => {
webamp.reopen();
});
})
```
### `onMinimize(cb: () => void): () => void`
A callback which will be called when Webamp is minimized. Returns an "unsubscribe" function.
```JavaScript
const unsubscribe = webamp.onMinimize(() => {
console.log("Webamp closed");
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `setSkinFromUrl(url: string): void`
Updates the skin used by the webamp instance. Note that this does not happen immediately. If you want to be notified when the skin load is complete, use `.skinIsLoaded()`, which returns a promise which you can await.
**Since** 1.4.1
### `skinIsLoaded(): Promise<void>`
Returns a promise that resolves when the skin is done loading.
```JavaScript
const start = Date.now();
await webamp.skinIsLoaded();
console.log(`The skin loaded in ${Date.now() - start}`);
```
### `dispose(): void`
**Note:** _This method is not fully functional. It is currently impossible to clean up a Winamp instance. This method makes an effort, but it still leaks the whole instance. In the future the behavior of this method will improve, so you might as well call it._
When you are done with a Webamp instance, call this method and Webamp will attempt to clean itself up to avoid memory leaks.
```JavaScript
webamp.dispose();
```
## Optimizing Bundle Size
**Since** UNRELEASED
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`.
First you'll need to install the dependencies in your project:
```bash
npm install jszip music-metadata-browser@^0.6.1
```
The "lazy" version of Webamp will require that you inject functions for lazily importing these dependencies.
```ts
import Webamp from "webamp/lazy";
const webamp = new Webamp({
initialTracks: [
{
url: "https://example.com/track1.mp3",
metaData: {
artist: "Jordan Eldredge",
title: "Jordan's Song",
},
duration: 95,
},
],
requireJSZip: () => import("jszip/dist/jszip"),
requireMusicMetadata: () => import("music-metadata-browser/dist/index"),
});
```
## Notes
- Internet Explorer is not supported.
- Webamp injects CSS into the page. The CSS is namespaced (every CSS selector is prefixed with `#webamp`), so it should not interfere with anything on the host page.
- Webamp HTML contains somewhat generic IDs and class names. If you have CSS on your page that is not namespaced, it may accidentaly be applied to Webamp. If this happens please reach out. I may be able to resolve it.
- Skin and audio URLs are subject to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS). Please ensure they are either served from the same domain, or that the other domain is served with the correct headers.
- Please reach out to me. I'd love to help you set it up, and understand how it's being used. I plan to expand this API as I learn how people want to use it.
This doc has moved to the Webamps doc page.

10420
yarn.lock
View file

File diff suppressed because it is too large Load diff