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 v1.3.0

webamp.previousTrack();

nextTrack(): void​

Play the next track.

Since v1.3.0

webamp.nextTrack();

seekForward(seconds: number): void​

Seek forward n seconds in the current track.

Since v1.3.0

webamp.seekForward(10);

seekBackward(seconds: number): void​

Seek backward n seconds in the current track.

Since v1.3.0

webamp.seekBackward(10);

seekToTime(seconds: number): void​

Seek to a given time within the current track.

Since v1.4.0

webamp.seekToTime(15.5);

getMediaStatus(): MediaStatus | null​

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

Since v1.4.0

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

getPlayerMediaStatus(): PlayerMediaStatus​

Get the current "playing" status of the player. Similar to getMediaStatus(), but can differentiate between different reasons why the player might not be playing, such as "ENDED" when the end of the playlist has been reached or "CLOSED" when the player has been closed.

The return value is one of: "PLAYING", "STOPPED", "PAUSED", "ENDED", or "CLOSED".

Since v2.2.0

const playerStatus = webamp.getPlayerMediaStatus();
if (playerStatus === "ENDED") {
  console.log("Playlist has ended");
} else if (playerStatus === "CLOSED") {
  console.log("Player is closed");
}

pause(): void​

Pause the current track.

Since v1.3.0

webamp.pause();

play(): void​

Play the current track.

Since v1.3.0

webamp.play();

stop(): void​

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

Since v1.4.0

webamp.stop();

setVolume(volume: number): void​

Set volume from 0 - 100.

Since v1.3.0

webamp.setVolume(75);

setCurrentTrack(index: number): void​

Set the current track to 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 v2.1.0

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

getPlaylistTracks(): PlaylistTrack[]​

Get the current playlist in order.

Since v2.1.0

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

isShuffleEnabled(): boolean​

Check if shuffle is enabled.

Since v2.1.0

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

toggleShuffle(): void​

Toggle shuffle mode between enabled and disabled.

Since v2.2.0

webamp.toggleShuffle();

isRepeatEnabled(): boolean​

Check if repeat is enabled.

Since v2.1.0

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

toggleRepeat(): void​

Toggle repeat mode between enabled and disabled.

Since v2.2.0

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("webamp-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 selecting "Close" from Webamp's options menu. Once closed, you can open it again with .reopen().

Since v1.4.1

reopen(): void​

After .close()ing this instance, you can reopen it by calling this method.

Since v1.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 minimized");
});

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


### `skinIsLoaded(): Promise<void>`

Returns a promise that resolves when the skin is done loading.

```ts
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 Webamp 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();