lms-cli-notifications

Node module for subscribing to and receiving notifications through Logitech Media Server's CLI.

Where in CLI, you subscribe to notifications as follows:

// Telnet to LMS
$ telnet <server_address>:<cli_port>

// Subscribe to 'mixer' notifications
# subscribe mixer

// Also subscribe to 'play' and 'pause' notifications
# subscribe mixer,play,pause

// Unsubscribe from 'play' notifications
# subscribe mixer,pause

// Output when player volume changes:
40%3A61%3A86%3Af0%3A8f%3A19 mixer volume 80

In Node.JS, you would do this:

// ESM
import { NotificationListener } from 'lms-cli-notifications';
// CJS
const { NotificationListener } = require('lms-cli-notifications');

const server = {
  host: '<server_address>',
  port: '<cli_port>'
};

const notificationListener = new NotificationListener({
  server,
  subscribe: 'mixer' // Subscribe to 'mixer' notifications
});

notificationListener.on('notification', (data) => {
  const {playerId, notification, params} = data;
  console.log({playerId, notification, params});
});

await notificationListener.start();

// Also subscribe to 'play' and 'pause' notifications
await notificationListener.subscribe(['play', 'pause']);

// Unsubscribe from 'play' notifications
await notificationListener.unsubscribe('play');

...

// Output when player volume changes:
{
  playerId: '40:61:86:f0:8f:19',
  notification: 'mixer',
  params: [ 'volume', '50' ]
}

Do not confuse subscription in this context with the subscribe tag in queries (which this library does not support).

Install

npm install --save lms-cli-notifications

API

Class: NotificationListener

A NotificationListener encapsulates the process of connecting to a Logitech Media Server's CLI, subscribing to notifications and receiving them (communicating back by way of Events). You would begin by first creating a NotificationListener instance.

Creates a NotificationListener instance and associates it with server, or 127.0.0.1:9090 if not specified.

Params

• params: (NotificationListenerParams) (optional and all properties optional)
  • server:
    • host: (string) address of server to connect to (default: '127.0.0.1`).
    • port: (string) server's CLI port (default: '9090').
    • username: (string) username for login - omit if not applicable.
    • password: (string) password for login - omit if not applicable.
  • subscribe: (string | Array<string>)
    • If string, the notification to subscribe to.
    • If array, the list of notifications to subscribe to.

The subscribe param is included merely for convenience. You can subscribe to notifications at any stage by calling subscribe(). So the following:

const server = { ... };
const notifications = ['client', 'mixer'];

const notificationListener = new NotificationListener({ 
  server,
  subscribe: notifications
});
notificationListener.start();

has the same effect as:

...
const notificationListener = new NotificationListener({ server });
notificationListener.subscribe(notifications);

notificationListener.start();

Establishes connection with the server and subscribes to the notification(s) specified at construction time.

Returns

Promise that resolves to true on success.

Terminates connection with the server.

Returns

Promise that resolves to true on success.

Whether the NotificationListener instance is connected to the server.

Returns

Boolean

Subscribes to notification.

If server is not yet connected, subscription will be deferred until connection is established.

Params

• notification (string | Array<string>):
  • If string, a single notification to subscribe to.
  • If array, the list of notifications to subscribe to.

Returns

• If server is not yet connected, a Promise that resolves after adding notification to the list of pending subscriptions.
• If server is already connected, a Promise that resolves on successful subscription.

Unsubscribes from notification.

Params

• notification (string | Array<string>):
  • If string, a single notification to unsubscribe from.
  • If array, the list of notifications to unsubscribe from.

Returns

• If server is not yet connected, a Promise that resolves when notification is removed from the list of pending subscriptions.
• If server is already connected, a Promise that resolves on successful unsubscription.

Returns the list of currently-subscribed notifications. The list will be empty if there is no connection with the server.

Returns

Array<string>

Events

Emitted when connection to server is established.

Listener Params

• server:
  • host: (string)
  • port: (string)

Emitted when server is disconnected.

Listener Params

• server:
  • host: (string)
  • port: (string)

Emitted when a subscribed notification is received.

NotificationListener parses the raw message received from the server and converts it from something like this:

08%3A00%3A27%3Aa0%3Ad1%3A2c mixer volume 70

into this:

|Property |Value | |------------------------------|------------------------------------------------| |playerId <string>* |'08:00:27:a0:d1:2c' | |notification <string> |'mixer' | |params <Array> |['volume', '70'] | |raw <string> |'08%3A00%3A27%3Aa0%3Ad1%3A2c mixer volume 70' | |server <Object> |{ host: ..., port: ... } |

Listener Params

• data: (Notification)
  • playerId: (string)
  • notification: (string)
  • params: (Array<string>)
  • raw: (string) unprocessed notification message
  • server: (object)
    • host: (string)
    • port: (string)

Notifications that are not associated with a specific player, such as 'rescan', will not have the playerId param.

Errors

In v0.x, error codes are defined as standalone constants.

In v1.x, they are defined in the NotificationListenerErrorCode enum.

notificationListener.start()
  .then(() => {
    ...
  })
  .catch((err) => {
    ...
  });

Where an error is an instance of NotificationListenerError, you can obtain more information about it:

if (err instanceof NotificationListenerError) {
  console.log(`
    Error: ${ err.message },
    Code: ${ err.code },   // Can be undefined
    Cause: ${ err.cause }  // Underlying error (can be undefined)
  `);
  ...
}

Error codes

| Enum: NotificationListenerErrorCode | Description | |-------------------------|---------------------------------------------------------------------------------------------------------------------| |AuthError | Login attempt failed for a password-protected server. | |SendCommandError | A command could not be sent to the server. The underlying error can be obtained from err.cause. | |CommandResponseTimeout | After sending a command to the server, a response is expected but not received within a timeout period of 5 seconds.|

Running the Example

// ESM
npm run example -- -h [server address] -p [server CLI port] -u [username] -pw [password]

// CJS
node index.cjs -h [server address] -p [server CLI port] -u [username] -pw [password]

Only include options that are applicable. Generally, you do not have to specify -p since most LMS installations use the default 9090 port for CLI.

Changelog

1.0.0:

• Migrate to TypeScript and package as ESM / CJS hybrid module

0.1.2:

• Fix blank credentials causing login timeout

0.1.1:

• Fix example

0.1.0:

• Initial release

License

MIT