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
TOC »
Description
A CHICKEN Scheme implementation of the JSON-RPC based API (v 6.0) for the XBMC media player.
Author
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:
- 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)procedure
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
- mute JSON-RPC-CONNECTIONprocedure
Used to toggle between mute states
- volume JSON-RPC-CONNECTION VOLUMEprocedure
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.