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.

This is browser port of kodi-ws module. You will need webpack/ browserify/other require() aware module loader. If you want to run in node use original kodi-ws.

Install via npm install kodi-websocket

Initiate

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

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-websocket')('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. There is no ready to run build config yet, sorry. You will need to make an html page, npm instll ..., bundle with webpack/browserify/etc. yourself.

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.