Webamp Constructor

The Winamp class is constructed with an options object. All config properties are optional.

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.

initialTracks

An array of tracks to prepopulate the playlist with. The url must be served with the correct CORS headers.

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.

const webamp = new Webamp({
  initialTracks: [
    {
      url: "./path/to/track.mp3",
      metaData: {
        artist: "Artist Name",
        title: "Track Title",
      },
      duration: 120, // Track duration in seconds
    },
  ],
  // ...other config options
});

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.

const webamp = new Webamp({
  initialSkin: {
    url: "./path/to/skin.wsz",
  },
  // ...other config options
});

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.

tip

You can find skins to download at the Winamp Skin Museum.

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

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.

const webamp = new Webamp({
  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,
    },
  },
  // ...other config options
});

enableDoubleSizeMode

Since 2.0.0

A boolean indicating if double size mode should be enabled. Default: false.

const webamp = new Webamp({
  enableDoubleSizeMode: true,
  // ...other config options
});

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.

const webamp = new Webamp({
  enableHotkeys: true,
  // ...other config options
});

For a list of hotkeys, see the hotkeys documentation.

zIndex

An integer representing the zIndex that Webamp should use. Default: 99999.

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 tracks, 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.

const webamp = new Webamp({
  filePickers: [
    {
      contextMenuName: "My File Picker...",
      filePicker: () =>
        Promise.resolve([
          {
            url: "./rick_roll.mp3",
          },
        ]),
      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.

The function should return an array of Track objects or null to get the default drop behavior.

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.

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.

const webamp = new Webamp({
  handleLoadListEvent: async () => {
    return [
      /* array of Tracks */
    ];
  },
  // ...other config options
});

handleSaveListEvent

Since 1.4.1 Provide a way to extend the behavior of the playlist button SAVE LIST.

const webamp = new Webamp({
  handleSaveListEvent: (tracks) => {
    // Perform custom save logic with the current tracks.
  },
  // ...other config options
});

enableMediaSession

Since 2.1.3

Have Webamp connect to the browser's Media Session API, if the browser supports it. Default: false.

This allows OS/hardware level media controls like play/pause/next/previous and lock screen "current track" information to work with Webamp.

const webamp = new Webamp({
  enableMediaSession: true,
  // ...other config options
});

__butterchurnOptions

Webamp's Milkdrop window is powered by the third party library Butterchurn. 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.

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 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

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 };
      });
    },
  },
});