Skip to main content

Instance Methods

Once you have constructed a Webamp instance, the instance has methods you can use to get the state of the player, control playback, and manage tracks, register event listeners, and more.

import Webamp from "webamp";

const webamp = new Webamp({
  // ... options
});

The webamp instance has the following instance methods:

appendTracks(tracks: Track[]): void​

Add an array of Tracks to the end of the playlist.

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.

setTracksToPlay(tracks: Track[]): void​

Replace the playlist with an array of Tracks and begin playing the first track.

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.

previousTrack(): void​

Play the previous track.

Since 1.3.0

webamp.previousTrack();

nextTrack(): void​

Play the next track.

Since 1.3.0

webamp.nextTrack();

seekForward(seconds): void​

Seek forward n seconds in the current track.

Since 1.3.0

webamp.seekForward(10);

seekBackward(seconds): void​

Seek backward n seconds in the current track.

Since 1.3.0

webamp.seekBackward(10);

seekToTime(seconds)​

Seek to a given time within the current track.

Since 1.4.0

webamp.seekToTime(15.5);

getMediaStatus()​

Get the current "playing" status. The return value is one of: "PLAYING", "STOPPED", or "PAUSED".

Since 1.4.0

const isPlaying = webamp.getMediaStatus() === "PLAYING";

pause(): void​

Pause the current track.

Since 1.3.0

webamp.pause();

play(): void​

Play the current track.

Since 1.3.0

webamp.play();

stop(): void​

Stop the currently playing audio. Equivilant to pressing the "stop" button.

Since 1.4.0

webamp.stop();

setVolume(volume: number): void​

Set volume from 0 - 100.

Since 1.3.0

webamp.setVolume(75);

setCurrentTrack(index: number): void​

Set the current track a specific track in the playlist by zero-based index.

Note: If Webamp is currently playing, the track will begin playing. If Webamp is not playing, the track will not start playing. You can use webamp.pause() before calling this method or webamp.play() after calling this method to control whether the track starts playing.

Since 2.1.0

// Play the third track in the playlist
webamp.setCurrentTrack(2);

getPlaylistTracks(): PlaylistTrack[]​

Get the current playlist in order.

Since 2.1.0

const tracks = webamp.getPlaylistTracks();
console.log(`Playlist has ${tracks.length} tracks`);

isShuffleEnabled(): boolean​

Check if shuffle is enabled.

Since 2.1.0

if (webamp.isShuffleEnabled()) {
  console.log("Shuffle is enabled");
}

toggleShuffle(): void​

Toggle shuffle mode between enabled and disabled.

Since 2.1.3

webamp.toggleShuffle();

isRepeatEnabled(): boolean​

Check if repeat is enabled.

Since 2.1.0

if (webamp.isRepeatEnabled()) {
  console.log("Repeat is enabled");
}

toggleRepeat(): void​

Toggle repeat mode between enabled and disabled.

Since 2.1.3

webamp.toggleRepeat();

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.

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

const unsubscribe = webamp.onTrackDidChange((track) => {
  if (track == null) {
    document.title = "Webamp";
  } else {
    document.title = `${track.metaData.title} - ${track.metaData.artist} \u00B7 Webamp`;
  }
});

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

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.

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

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.

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.

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.

webamp.dispose();