manifest.json reference

Every widget has a manifest.json at the root of its .nepget bundle. It tells NepTunes how to load and present the widget.

Required fields

Optional fields

Showing without playback

A widget is on screen only while a track is playing or paused. When playback stops (including at the end of the queue, when the player still reports the last track), or the music app quits, NepTunes orders it out, and it comes back with the next track. For a widget about the current track that’s usually what you want. For one that isn’t (a chart, a scrobble count, a calendar of your listening) it isn’t, so the manifest can say the widget copes with nothing playing. Either of two keys does it:

"alwaysVisible": true

for a widget whose content doesn’t depend on the current track. It stays on screen with nothing playing, even with no music app running.

"supportsNoPlayback": true

for a now-playing widget with a good empty state. It keeps following playback, but the user can choose to keep it up.

Either key gives the widget a Show setting in NepTunes: While music is playing or Always. With alwaysVisible it starts at Always, with supportsNoPlayback at While music is playing, and the user can change it either way. A widget with neither key gets no Show setting and follows playback.

• NepTunes still has to be running, with desktop widgets turned on and the widget active, and widgets still need NepTunes Pro. Show lifts only the playback rule.
• Other widgets keep following playback. Only yours stays up.
• NepTunes draws no placeholder for you. With nothing playing your widget still gets statechange, with no track (NepTunes.track is null), and no playerType when no player is running (NepTunes.playerType is null). playerState is then usually 0 (unknown), not 1. A player stopped at the end of its queue still sends the last track, with playerState 1 (stopped). Show your own empty state rather than waiting for a track.
• Clicking the empty state should call NepTunes.activatePlayer(). It brings the current player forward or, when none is running, launches the preferred player if the user set one in Settings, otherwise the one they last listened in. It needs the playerActivation permission.
• NepTunes before 4.1 ignores both keys, as it does any key it doesn’t know, and hides the widget with playback as before. You don’t need to raise minNepTunesVersion to use them.

Motion artwork

Many Apple Music albums have motion artwork: a short, silent video loop of the cover. A widget that shows the cover can ask for it:

"supportsMotionArtwork": true,
"permissions": ["artwork"]

• It rides on the artwork permission. There’s no new permission and no new consent on update. Without artwork the key does nothing, and widget-tools.mjs validate reports the pair.
• The widget’s settings in NepTunes gain an Animated cover switch, on by default. When the user turns it off, your widget gets no loop and NepTunes downloads nothing for it.
• NepTunes before 4.1 ignores the key and your widget shows static artwork, so you don’t need minNepTunesVersion for it.
• Changing the key rebuilds the widget’s window, so bump version as for any manifest change.

The loop reaches your widget as track.motionArtworkURL; see Motion artwork in the JavaScript API for when it’s there and how to play it.

bundle.sig, the manifest’s signature sidecar

A signed bundle carries a second file next to manifest.json: bundle.sig, holding the author’s Ed25519 signature over the SHA-256 hash of every file in the bundle , manifest.json included. You never hand-write it; embed-sign generates it (widget-tools.mjs , Updates & signing explains how to get it and where keygen puts your keys):

node widget-tools.mjs embed-sign MyWidget.nepget \
  --key .keys/my-widget-author.pem
node widget-tools.mjs embed-verify MyWidget.nepget

Two rules tie the two files together, and NepTunes enforces both at install time:

• manifest.authorPublicKey must equal bundle.sig’s authorPublicKey.
• A manifest that declares authorPublicKey with no bundle.sig is rejected , claiming an identity without proving it is worse than claiming none.

Because the manifest is itself covered by the signature, any manifest edit (a version bump, a new permission) means re-running embed-sign. The full format, the exact bytes the signature covers, and the verification order are in Updates & signing.

Complete example

This is the manifest from the “Now Playing” widget in the gallery:

{
  "manifestVersion": 1,
  "id": "pl.micropixels.neptunes.widget.now-playing",
  "name": "Now Playing",
  "version": "1.9.0",
  "author": "NepTunes",
  "description": "Displays the currently playing track with playback controls",
  "license": "MIT",
  "homepage": "https://neptunesmac.app",
  "entry": "index.html",
  "defaultSize": { "width": 368, "height": 220 },
  "minSize": { "width": 328, "height": 200 },
  "resizable": false,
  "preview": "preview.jpg",
  "permissions": ["artwork", "playbackControl"],
  "settings": {
    "schema": [
      {
        "id": "showArtwork",
        "type": "checkbox",
        "label": "Show Album Artwork",
        "default": true
      },
      {
        "id": "theme",
        "type": "radio",
        "label": "Theme",
        "options": [
          { "value": "dark", "label": "Dark" },
          { "value": "light", "label": "Light" }
        ],
        "default": "dark"
      }
    ]
  }
}

← Quick startJavaScript API →