Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

xbmc-api
  1. Outdated egg!
  2. xbmc-api
    1. Description
    2. Author
    3. Repository
    4. Documentation and examples
      1. Introduction
      2. Usage
      3. High level API
        1. Application section
      4. Real life example
      5. Random examples (low level)
    5. Version history
    6. License

Description

A CHICKEN Scheme implementation of the JSON-RPC based API (v 6.0) for the XBMC media player.

Author

Tim van der Linden

Repository

The code is hosted on an external repository and can be found here.

Documentation and examples

Introduction

This API features both a low level and a high level implementation.

The low level version can be almost directly compared with the XBMC's version 6 API and implements all of the methods as is, only providing a slightly simpler way of invoking them. This version of the API is considered the main goal of this egg.

The high level API, on the other hand, is there to provide more abstract features for your XBMC machine which are not (directly) provided by default.

Usage

Following the same method categorization as the upstream XBMC API there are 13 procedures you can invoke to alter different parts of your box:

[procedure] (addons JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (audio-library JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (files JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (gui JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (input JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (jsonrpc JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (pvr JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (player JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (playlist JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (xbmc-system JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (video-library JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))
[procedure] (xbmc JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))

As you can see, these are all almost identical, differing only in the section of the API which they address.

The optional parameters that some methods require should be input as a LIST containing keywords and/or vectors. As it would be redundant to list them here, consult the official XBMC documentation to find out which parameters a given method supports or requires.

See below for some real-life examples of parameter usage.

High level API

As I continue to develop this egg I will add more high level procedures. Currently I develop only the features that seem fit for my personal use or seem like straight forward upgrades to the upstream API. If you are using this API (thank you!) and wish to see a certain abstraction become reality, dig in or drop me a line and I'll see what I can do.

Currently the following abstractions are made:

Application section
[procedure] (mute JSON-RPC-CONNECTION)

Used to toggle between mute states

[procedure] (volume JSON-RPC-CONNECTION VOLUME)

Used to set the volume using an INTEGER ranging from 0 to 100

Real life example

Let me demonstrate how you could use this API with your XBMC box.

First you need to allow you box to be controlled via remote. In version 12 of XBMC (Frodo) you can enable this by going to Settings > Services > Remote Control and then tick the option that says "Allow programs on other systems to control XBMC". Or, when you are using this API on the same machine as XBMC is running, tick the option "Allow programs on this system to control XBMC".

Now start to play some music or video, so you could notice the API interacting with your XBMC installation.

Next you need to establish a JSON-RPC connection with your box. This API expects a JSON-RPC connection as established by the JSON-RPC egg.

Open up your REPL (csi) and run this code (replace the IP address with yours):

; Load in the needed eggs
(use json-rpc-client tcp xbmc-api)
; Switch off the TCP connection timeout
(tcp-read-timeout #f)
; Setup a TCP connection to your box
(define-values (input output) 
  (tcp-connect "192.168.0.115" 9090))
; Define the JSON-RPC connection
(define xbmc-conn (json-rpc-server input output))

Let us now mute the sound. As you could read before, the "mute" method has both a high and a low level implementation. To send such a mute command, using the normal low level API, you can use the "application" procedure together with the connection to your XBMC box (in our case called "xbmc-conn"), the "mute" method and the correct parameters like so:

(application xbmc-conn 'mute parameters: '(mute: #t))

This will now mute the box listening on the "xbmc-conn" connection. To un-mute this box, switch the boolean:

(application xbmc-conn 'mute parameters: '(mute: #f))

And now your box will blast sound again. To simplify this process you could also use the high level implementation which simply toggles between the mute states:

(mute xbmc-conn)

You will notice the high level approach is *much* less typing and does the switching for you with only one command.

Random examples (low level)

Sending a message to be displayed on your box:

(gui xbmc-conn 'show-notification parameters: '(title: "Hello" message: "Hello world."))

Checking the permission for the current connection:

(json-rpc xbmc-conn 'permission)

Getting a Scheme listing of your movie libraries:

(video-library xbmc-conn 'get-movies)

Version history
0.1
Initial Chicken 4 release.

License

 
 Copyright (c) 2013, Tim van der Linden
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 
 Neither the name of the author nor the names of its contributors may
 be used to endorse or promote products derived from this software
 without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.