# 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/) - An example that just uses a ` ``` ## 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
``` ## 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. 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 recommended to check this before you attempt to instantiate an instance of `Winamp`. ```JavaScript 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. ```JavaScript 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. (Default: `false`) Should double size mode be enabled? 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