Skip to main content

Webamp Constructor

The Webamp 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 v2.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 v2.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 v1.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 v1.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 v1.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 v2.2.0

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

requireButterchurnPresets?: () => Promise<Preset[]>​

Since unreleased

Milkdrop (Butterchurn) presets to be used. If not specified, the default presets included in the bundle will be used.

Presets are expected to be in Butterchurn's JSON format. You can find these .json files in: