Commits

Tim van der Linden committed 07f4609

Added wiki page.

Comments (0)

Files changed (1)

+[[tags: egg]]
+
+== xbmc-api
+
+[[toc:]]
+
+=== Description
+
+A CHICKEN Scheme implementation of the JSON-RPC based API (v 6.0) for the XBMC media player.
+
+=== Author
+
+[[/users/tim-van-der-linden|Tim van der Linden]]
+
+=== Repository
+
+The code is hosted on an external repository and can be found [[https://bitbucket.org/Timusan/xbmc-api/|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 [[http://wiki.xbmc.org/index.php?title=JSON-RPC_API/v6|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>
+<procedure>(audio-library JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))</procedure>
+<procedure>(files JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))</procedure>
+<procedure>(gui JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))</procedure>
+<procedure>(input JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))</procedure>
+<procedure>(jsonrpc JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))</procedure>
+<procedure>(pvr JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))</procedure>
+<procedure>(player JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))</procedure>
+<procedure>(playlist JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))</procedure>
+<procedure>(xbmc-system JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))</procedure>
+<procedure>(video-library JSON-RPC-CONNECTION 'METHOD #!key (PARAMETERS '()) #!key (VERSION 6))</procedure>
+<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
+
+<procedure>(mute JSON-RPC-CONNECTION)</procedure>: Used to toggle between mute states
+<procedure>(volume JSON-RPC-CONNECTION VOLUME)</procedure>: 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 [[http://wiki.call-cc.org/eggref/4/json-rpc|JSON-RPC egg]].
+
+Open up your REPL (csi) and run this code (replace the IP address with yours):
+
+<enscript highlight="scheme">
+; Load in the needed eggs
+(use json-rpc-client tcp xbmc-api)
+; 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))
+; Switch off the TCP connection timeout
+(tcp-read-timeout #f)
+</enscript>
+
+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:
+
+<enscript highlight="scheme">
+(application xbmc-conn 'mute parameters: '(mute: #t))
+</enscript>
+
+This will now mute the box listening on the "xbmc-conn" connection. To un-mute this box, switch the boolean:
+
+<enscript highlight="scheme">
+(application xbmc-conn 'mute parameters: '(mute: #f))
+</enscript>
+
+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:
+
+<enscript highlight="scheme">
+(mute xbmc-conn)
+</enscript>
+
+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:
+
+<enscript highlight="scheme">
+(gui xbmc-conn 'show-notification parameters: '(title: "Hello" message: "Hello world."))
+</enscript>
+
+Checking the permission for the current connection:
+
+<enscript highlight="scheme">
+(json-rpc xbmc-conn 'permission)
+</enscript>
+
+=== 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.