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
    artworkData: "base64…"    // present if the artwork permission is granted
  },
  playerState: 2,             // 1 = stopped, 2 = playing, 3 = paused
  playerType: "appleMusic",   // or "spotify"
  volume: 75,                 // 0–100
  isMuted: false,
  shuffleEnabled: false,
  repeatMode: "off",          // "off", "one", or "all"
  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.

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 reference Settings schema →