mopidy

library1.3.0jsnpmunverified

Client library for controlling a Mopidy music server via WebSocket and JSON-RPC. Current stable version is 1.3.0. Released on npm with TypeScript types included. Key differentiator: provides a unified API for both browser and Node.js, handling WebSocket reconnection with exponential backoff, and exposing Mopidy's core API methods dynamically. Minimal dependencies, lightweight (~12 kB minified).

productivity

npm install mopidy

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MOPIDY

mopidy

productivityjavascriptv1.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Mopidy

✓ import Mopidy from 'mopidy'

✗ import { Mopidy } from 'mopidy'

Default import only; named import will fail because the package uses CommonJS module.exports. ESM import works due to bundler interop.

Mopidy

✓ const Mopidy = require('mopidy')

✗ const { Mopidy } = require('mopidy')

Class is the default export via module.exports = Mopidy, not an object property.

Mopidy

✓ import Mopidy from 'mopidy'

✗ import * as Mopidy from 'mopidy'

Namespace import results in an object with no default export, use default import. Works with TypeScript if esModuleInterop is enabled.

Connects to a Mopidy server via WebSocket, listens for state and track change events, and calls a core API method.

import Mopidy from 'mopidy'; async function main() { const mopidy = new Mopidy({ webSocketUrl: 'ws://localhost:6680/mopidy/ws/', autoConnect: true }); // Wait for the WebSocket to open mopidy.on('state', (state) => { if (state === 'connected') { console.log('Connected!'); // List playback history mopidy.playback.getCurrentTlTrack().then(track => { console.log('Current track:', track); }).catch(err => { console.error('Error:', err); }); } }); // Listen for events (e.g., when track changes) mopidy.on('event:trackPlaybackStarted', (event) => { console.log('Now playing:', event.tl_track.track.name); }); } main();

Debug

Known issues

gotchaAuto-connect enabled by default. If you create new Mopidy instance without options, it attempts to connect to /mopidy/ws/ on the current host, which may fail if not served by Mopidy's built-in web server.

fix

Set autoConnect: false and call connect() after configuring webSocketUrl, or pass webSocketUrl explicitly.

affects: >=1.0.0

deprecatedMopidy's 'event:' prefix for events is deprecated? (Check if still valid; some old docs use it, but newer versions may remove it).

fix

Use 'event:' naming consistently; check your Mopidy version for event naming.

affects: >=1.0.0

gotchaMopidy instance must be connected before calling most methods; calling methods before connection returns rejected promise with 'WebSocket not open' error.

fix

Wait for 'state' event with value 'connected' before making API calls.

affects: >=1.0.0

breakingMopidy.js v1.0+ dropped support for Node.js <10; older versions used callbacks, now all methods return Promises.

fix

Update Node.js to >=10 and migrate from callbacks to Promises or async/await.

affects: >=1.0.0

gotchaWebSocket URL must be absolute in Node.js; relative URLs like '/mopidy/ws/' may not resolve correctly.

fix

Use full URL format: 'ws://host:port/mopidy/ws/'

affects: >=1.0.0

Errors

Common errors & fixes

WebSocket not open

Called Mopidy API methods before the WebSocket connection is established.

fix

Subscribe to the 'state' event and wait for 'connected', or use the 'onOpen' callback if available.

String.indexOf is not a function

Passing wrong argument type (e.g., array) to a method that expects a string (like tracklist.filter).

fix

Check API signature; use appropriate data types as specified in Mopidy docs.

Cannot find module 'mopidy'

Package not installed or incorrect import path in non-Node environment (e.g., browser without bundler).

fix

Run 'npm install mopidy' or use the prebuilt bundle from GitHub releases.

Mopidy is not a constructor

Using namespace import (import * as Mopidy) instead of default import.

fix

Use default import: import Mopidy from 'mopidy'

Uncaught (in promise) ReferenceError: Mopidy is not defined

Forgot to import Mopidy class or using global variable from CDN incorrectly.

fix

Ensure library is loaded and accessible; check script tags or bundler configuration.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/mopidy/mopidy.js ↗

packagemopidy ↗

homepagehttps://mopidy.com/ ↗