Introduction
NepTunes web widgets are small, always-on panels that sit on your desktop and react to whatever you’re playing in Apple Music or Spotify. A widget is just HTML, CSS and JavaScript — if you can build a web page, you can build a widget.
Each widget runs in its own transparent WebView and talks to the app through a single
global object, window.NepTunes, which exposes the current
track, playback state, and actions like play, pause and love.
The .nepget bundle
A widget ships as a .nepget bundle — a folder with a specific extension. At minimum
it contains:
MyWidget.nepget/
├── manifest.json # metadata, size, permissions, settings
├── index.html # the entry point (set via "entry")
├── styles.css # your styles (optional)
├── script.js # your logic (optional)
└── preview.jpg # a preview image for the picker (optional)The manifest.json describes the widget — its name, version,
default size, the permissions it needs, and any user-configurable
settings. The entry HTML file is what NepTunes loads.
Installing a widget
Double-click a .nepget bundle and NepTunes installs it. Widgets live in:
~/Library/Application Support/NepTunes/Widgets/Once installed, a widget appears on your desktop where you can position and (if it allows) resize it.
Desktop widgets require NepTunes Pro
The on-screen web-widget system is part of NepTunes Pro. Anyone can build and share widgets, and downloads from the gallery are free — running them on your desktop unlocks with Pro inside the app.