JavaScript API

Every widget has access to a global window.NepTunes object. It’s your single entry point for reading player state, reacting to changes, and controlling playback.

State accessors

Convenience getters for the most common values:

NepTunes.state         // the full state object (below)
NepTunes.track         // current track info, or null
NepTunes.isPlaying     // Boolean
NepTunes.isPaused      // Boolean
NepTunes.isStopped     // Boolean
NepTunes.volume        // Number, 0–100
NepTunes.isMuted       // Boolean
NepTunes.playerType    // "appleMusic" or "spotify"
NepTunes.capabilities  // what the current player supports (see below)

The state object

NepTunes.state (and the value passed to statechange) looks like this:

{
  track: {
    title: "Song Title",
    artist: "Artist Name",
    album: "Album Name",
    albumArtist: "Album Artist",
    duration: 180.5,          // seconds
    isLoved: true,            // Apple Music only
    isAdvertisement: true,    // present only during a Spotify ad
    artworkData: "base64…"    // present if the artwork permission is granted
  },
  playerState: 2,             // 0 = unknown, 1 = stopped, 2 = playing, 3 = paused
  playerType: "appleMusic",   // or "spotify"
  volume: 75,                 // 0–100
  isMuted: false,
  shuffleEnabled: false,
  repeatMode: 1,              // 1 = all, 2 = one, 3 = off
  rating: 80,                 // 0–100, Apple Music only
  isLoved: true,
  isDisliked: false,
  playerPosition: 45.2,       // seconds into the track
  capabilities: {
    canLove: true,
    canDislike: true,
    canRate: true,
    canAddToLibrary: false,
    hasThreeStateRepeat: true
  }
}

track is null when nothing is playing — always check for it before reading track.title.

Spotify advertisements

During a Spotify ad, track.isAdvertisement is true. The key is omitted entirely at every other time, so !track.isAdvertisement is a safe check in older widgets.

An ad is still a track — audio is playing, and title/artist carry whatever Spotify reports, which is usually the advertiser’s own copy rather than anything song-like. Treat it as unidentified: show a neutral placeholder instead of the title, and disable anything that acts on the track. Skipping and seeking are refused by Spotify during an ad, and lastFm.loveTrack / lastFm.unloveTrack are rejected when the requested track and artist match the ad that is playing — loving a different track from the user’s history still works normally.

NepTunes.on('statechange', (state) => {
    const track = state?.track;
    const isAd = !!track?.isAdvertisement;

    document.getElementById('title').textContent =
        isAd ? 'Advertisement' : (track?.title || 'Not Playing');
    document.getElementById('artist').textContent =
        isAd ? '' : (track?.artist || '');

    prevBtn.disabled = isAd;
    nextBtn.disabled = isAd;
});

Widgets that bundle neptunes-kit.js can call NTKit.displayInfo(state), which returns { title, artist } with the ad-collapsing already applied.

Actions

Each action requires the matching permission. Calling an action without its permission is a no-op.

Playback — playbackControl

NepTunes.playPause();   // toggle play / pause
NepTunes.next();        // skip to next track
NepTunes.previous();    // skip to previous track

Volume — volumeControl

NepTunes.increaseVolume();
NepTunes.decreaseVolume();
NepTunes.toggleMute();
NepTunes.setVolume(50);     // 0–100

Love & ratings — love / ratingControl

NepTunes.toggleLove();
NepTunes.toggleDislike();
NepTunes.increaseRating();
NepTunes.decreaseRating();
NepTunes.removeRating();
NepTunes.setRating(80);     // 0–100, Apple Music

Shuffle & repeat — shuffleRepeatControl

NepTunes.toggleShuffle();
NepTunes.toggleRepeat();    // cycles off → all → one

Player — playerActivation

NepTunes.activatePlayer();  // bring the music player to the front
NepTunes.switchPlayer();    // switch between Apple Music and Spotify

Events

// Fires whenever track or playback state changes
NepTunes.on('statechange', (state) => {
  /* state is the new state object */
});

// Fires when the user changes this widget's settings
NepTunes.on('settingschange', (settings) => {
  /* settings is the new settings object */
});

// Stop listening
NepTunes.off('statechange', myCallback);

Settings

Read the current values of your declared settings, keyed by their id:

const settings = NepTunes.settings;
if (settings.showArtwork) {
  /* … */
}

Artwork

When the artwork permission is granted, get a ready-to-use data URL for the current album art:

const url = NepTunes.getArtworkDataURL();
if (url) {
  document.getElementById('artwork').src = url;
}

← manifest.json referenceSettings schema →