webamp/docs/usage.md

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.

Examples

If you would like to look as some examples check out the examples directory were you will find:

• Minimal - An example that just uses a <script> tag that points to a CDN. No install required.
• Webpack - An example that installs Webamp via NPM, and bundles it into an applicaiton using Webpack.

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:

<!-- You can use this URL, or download it and check it into your own project -->
<script src="https://unpkg.com/webamp@0.0.6/built/winamp.bundle.min.js"></script>

Create a container

Create a DOM element somewhere in your HTML document. This will eventually contain Webamp

<div id='winamp-container'></div>

Initialize the 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?")
}

const webamp = new Webamp({
  initialTracks: [{
    metaData: {
      artist: "DJ Mike Llama",
      title: "Llama Whippin' Intro",
    },
    // Can be downloaded from: https://github.com/captbaritone/webamp/raw/master/mp3/llama-2.91.mp3
    url: "path/to/mp3/llama-2.91.mp3"
  }],
  initialSkin: {
    // Can be downloaded from https://github.com/captbaritone/webamp/raw/master/skins/base-2.91.wsz
    url: "path/to/skins/base-2.91.wsz"
  },
});
// Render after the skin has loaded.
webamp.renderWhenReady(document.getElementById('winamp-container'));

API

Many methods on the winamp instance deal with tracks. Here is the shape of a track:

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.
    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.
    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 recomended to check this before you attempt to instantiate an instance of Winamp.

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.

const options = {
    // Required. An object representing the initial skin to use.
    // 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 the with correct CORs headers.
    availableSkins: [
      { url: "./green.wsz", name: "Green Dimension V2" },
      { url: "./osx.wsz", name: "Mac OSX v1.5 (Aqua)" }
    ],

    // Optional. (Default: `false`) Should global hotkeys be enabled?
    enableHotkeys: true,

    // Optional. An array of additional file pickers.
    // These will appear in the "Options" menu under "Play".
    // In the offical version. 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
    }]
};
const winamp = new Winamp(options);

Instance Methods

The Winamp class has the following instance methods:

appendTracks(tracks)

Add an array of tracks (see above) to the end of the playlist.

winamp.appendTracks([
    {url: 'https://example.com/track1.mp3'},
    {url: 'https://example.com/track2.mp3'},
    {url: 'https://example.com/track3.mp3'}
]);

setTracksToPlay(tracks)

Replace the playlist with an array of tracks (see above) and begin playing the first track.

winamp.setTracksToPlay([
    {url: 'https://example.com/track1.mp3'},
    {url: 'https://example.com/track2.mp3'},
    {url: 'https://example.com/track3.mp3'}
]);

renderWhenReady(domNode)

Webamp will wait until it has fetch the skin and fully parsed it, and then render itself into the given container. A promise is returned which will resolve after the render is complete.

const container = document.getElementById('winamp-container');
winamp.renderWhenReady(container).then(() => {
    console.log('rendered winamp!');
});

onClose(callback)

A callback which will be called when Webamp is closed. Returns an "unsubscribe" function.

const unsubscribe = winamp.onClose(() => {
    console.log("Winamp closed");
});

// If at some point in the future you want to stop listening to these events:
unsubscribe();

onMinimize(callback)

A callback which will be called when Webamp is minimized. Returns an "unsubscribe" function.

const unsubscribe = winamp.onClose(() => {
    console.log("Winamp closed");
});

// If at some point in the future you want to stop listening to these events:
unsubscribe();

Notes

• Internet Explorer is not supported.
• Webamp injects CSS into the page. The CSS is namespaced (every CSS selector is prefixed with #winamp2-js), 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 accidently 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. 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.