README.md

KODI JSON-RPC Websocket client

This module provides a simple way to communicate with an Kodi media center installation. It should not be restricted to a specific version of kodi, as it pulls all its information about the available methods from JSONRPC.Introspect.

Install via npm install kodi-ws

Initiate

var kodi = require('kodi-ws');

kodi('localhost', 9090).then(function(connection) {
	/* Do something with the connection */
});

Connection Object

Events

The connection object emits the following events:

error

Emitted whenever the underlying websocket throws an error or a server response cannot be parsed.

close

Emitted if the underlying socket is closed.

Methods

.notification(method, cb)

Assigns a handler to a notfication sent by connection. The cb function will be passed a single argument containing the notifications data. method should be a string containing the notifications name.

connection.notification('Player.OnPause', function() {
	console.log('Paused');
});

Shorthand:

connection.Player.OnPause(function() {
	console.log('Paused');
})

.run(method, args...)

Runs the specified method. This function can be passed Parameters:

connection.run('Application.SetMute', true);

Shorthand:

connection.Application.SetMute(true);

The method returns a promise, which will be fulfilled as soon as the server responds. Multiple arguments can be passed either by order, or as an object by name:

var movies = connection.VideoLibrary.GetMovies(['title', 'rating', 'year'], {"start" : 0, "end": 2});

Arguments by name:

var movies = connection.VideoLibrary.GetMovies({
	properties: ['title', 'rating', 'year'],
	limits: {"start" : 0, "end": 2}
});

Batch Requests

You can send batch requests like so:

var batch = connection.batch();

var movies = batch.VideoLibrary.GetMovies({properties: ['title']});
var shows = batch.VideoLibrary.GetTVShows({properties: ['title']});

batch.send();

Promise.all([movies, shows]).then(function(data) {
	/* Movies */
	console.log(data[0]);
	/* TVShows */
	console.log(data[1]);
});

Notice the Promise.all() is optional and used here to have simpler sample code.

Await/Async Example

And just for good measure an example which uses ES7 async functions.

let kodi = require('kodi-ws')('localhost', 9090);

async function doStuff() {
	let con = await kodi;

	console.log(await con.VideoLibrary.GetMovies({properties: ['title']}));
	console.log(await con.VideoLibrary.GetTVShows({properties: ['title']}));
}

doStuff().catch(e => console.error(e));

More examples

Look for more examples in the examples directory.

Kodi's JSON-RPC API

You can find kodi's official documentation of the JSON-RCP API here and the full list of available commands (for protocol version 6) here.