XBMC-Client¶ ↑

This is a simple Ruby HTTP-based client for the XBMC Media Center JSON-RPC API.

It does not define all the API methods explicitly, but rather loads and defines them on the fly by pulling the available namespaces and methods from the JSONRPC.Introspect call baked into the XBMC Api and thus has all methods described there available via Xbmc::NAMESPACE.method_name_in_underscore_writing, so for example the JSON RPC call AudioPlayer.PlayPause becomes Xbmc::AudioPlayer.play_pause in Ruby.

Parameters can be passed in to all methods via the optional first argument to each method call, which is expected to be a hash:

Xbmc::AudioLibrary.get_songs(:albumid => 1)

Note that this is a very early release and is considered experimental. There will be bugs.

The client is being developed against Ruby 1.9.2, but should work with Ruby 1.8 as well.

gem install xbmc-client

require 'pp'
require 'xbmc-client'

# Set up the url and auth credentials
Xbmc.base_uri "http://localhost:8435"
Xbmc.basic_auth "xbmc", "xbmc"
Xbmc.load_api! # This will call JSONRPC.Introspect and create all subclasses and methods dynamically

pp Xbmc::AudioLibrary.get_artists
# > [{"artistid"=>1,
#    "fanart"=>"special://masterprofile/Thumbnails/Music/Fanart/c03803be.tbn",
#    "label"=>"The Weakerthans"}, ... ]

pp Xbmc::AudioLibrary.get_songs(:albumid => 1)
# [{"fanart"=>"special://masterprofile/Thumbnails/Music/Fanart/c03803be.tbn",
#   "file"=>
#   "/some/path/to/a/file.mp3",
#   "label"=>"Elegy for Elsabet",
#   "songid"=>20}, ...]

# You can interact with the raw api with:
Xbmc.invoke_method('JSONRPC.Introspect', :getdescriptions => 'true') # Will return the raw response
Xbmc.invoke_and_process('JSONRPC.Introspect, :getdescriptions => 'true') # Will return the JSON-parsed response body's result subcollection

As you’ll notice, it tries to automatically pull the correct collection for get_xyz calls, which means that you don’t have to go to the subcollection [:result][:artists] in the above example like you would if the response would be returned unprocessed.

See the examples directory in the repository for further usage examples!

Also, be sure to check out the API docs at the XBMC wiki: wiki.xbmc.org/index.php?title=JSON_RPC

Please note that the API is loaded dynamically and thus this ultimately depends on your version of XBMC. This listing is generated automatically using rake rdoc:apidoc

Enumerates all actions and descriptions. Parameter example {“getdescriptions”: true, “getpermissions”: true, “filterbytransport”: true }. All parameters optional

Retrieve the jsonrpc protocol version

Retrieve the clients permissions

Ping responder

Announce to other connected clients. Parameter example {“sender”: “foo”, “message”: “bar”, “data”: “somedata” }. data is optional

Returns all active players IDs

Returns Current Playback state

Pauses or unpause playback, returns new state

Stops playback

Skips to previous item on the playlist

Skips to next item on the playlist

Rewind current playback

Forward current playback

Retrieve time

Retrieve time in MS

Retrieve percentage

Seek to a specific time. Parameter integer in seconds

Seek to a specific percentage. Parameter float or integer from 0 to 100

Returns Current Playback state

Pauses or unpause playback, returns new state

Stops playback

Skips to previous item on the playlist

Skips to next item on the playlist

Rewind current playback

Forward current playback

Retrieve time

Retrieve time in MS

Retrieve percentage

Seek to a specific time. Parameter integer in seconds

Seek to a specific percentage. Parameter float or integer from 0 to 100

Pauses or unpause slideshow

Stops slideshow

Skips to previous picture in the slideshow

Skips to next picture in the slideshow

If picture is zoomed move viewport left otherwise skip previous

If picture is zoomed move viewport right otherwise skip previous

If picture is zoomed move viewport down

If picture is zoomed move viewport up

Zoom out once

Zoom in once

Zooms current picture. Parameter integer of zoom level

Rotates current picture

Clear video playlist

Shuffle video playlist

UnShuffle video playlist

Clear audio playlist

Shuffle audio playlist

UnShuffle audio playlist

Creates a virtual playlist from a given one from a file

Destroys a virtual playlist

Retrieve items in the playlist. Parameter example {“playlist”: “music” }. playlist optional.

Add items to the playlist. Parameter example {“playlist”: “music”, “file”: “/foo/bar.mp3” }. playlist optional.

Remove items in the playlist. Parameter example {“playlist”: “music”, “item”: 0 }. playlist optional.

Swap items in the playlist. Parameter example {“playlist”: “music”, “item1”: 0, “item2”: 1 }. playlist optional.

Shuffle playlist

UnShuffle playlist

Get the sources of the media windows. Parameter example {“media”: “video”}. Media can be video, music, pictures or files

Specify a file to download to get info about how to download it, i.e a proper URL

Retrieve the specified directory. Parameter example {“directory”: “foo/bar”, “media”: “video”}. Media can be video, music, pictures or files

Retrieve all artists

Retrieve all albums from specified artist or genre, Fields: album_description, album_theme, album_mood, album_style, album_type, album_label, album_artist, album_genre, album_rating, album_title

Retrieve all songs from specified album, artist or genre

Retrieve all movies. Parameter example { “fields”: [“plot”], “sortmethod”: “title”, “sortorder”: “ascending”, “start”: 0, “end”: 3}. fields, sortorder, sortmethod, start and end are optional

Parameter example { “fields”: [“plot”], “sortmethod”: “label”, “sortorder”: “ascending”, “start”: 0, “end”: 3}. sortorder, sortmethod, start and end are optional

Parameter example { “tvshowid”: 0, “fields”: [“season”], “sortmethod”: “label”, “sortorder”: “ascending”, “start”: 0, “end”: 3}. sortorder, sortmethod, start and end are optional

Parameter example { “tvshowid”: 0, “season”: 1, “fields”: [“plot”], “sortmethod”: “episode”, “sortorder”: “ascending”, “start”: 0, “end”: 3}. sortorder, sortmethod, start and end are optional

Parameter example { “artistid”: 0, “albumid”: 0, “fields”: [“plot”], “sortmethod”: “artistignorethe”, “sortorder”: “ascending”, “start”: 0, “end”: 3}. sortorder, sortmethod, start and end are optional

Retrieve all recently added movies. Parameter example { “fields”: [“plot”], “sortmethod”: “title”, “sortorder”: “ascending”, “start”: 0, “end”: 3}. fields, sortorder, sortmethod, start and end are optional

Retrieve all recently added episodes. Parameter example { “fields”: [“plot”], “sortmethod”: “title”, “sortorder”: “ascending”, “start”: 0, “end”: 3}. fields, sortorder, sortmethod, start and end are optional

Retrieve all recently added music videos. Parameter example { “fields”: [“plot”], “sortmethod”: “title”, “sortorder”: “ascending”, “start”: 0, “end”: 3}. fields, sortorder, sortmethod, start and end are optional

Retrieve info labels about the system

Retrieve info booleans about the system

Retrieve the current volume

Set volume. Parameter integer between 0 amd 100

Toggle mute

Starts playback

Starts slideshow. Parameter example {“directory”: “/foo/”, “random”: true, “recursive”: true} or just string to recursively and random run directory

Logs a line in the xbmc.log. Parameter example {“message”: “foo”, “level”: “info”} or just a string to log message with level debug

Quit xbmc

• No unit tests

• No parameter validation

• Fields (i.e. album details etc.) should be automatically requested by the api, but this would currently require the JSONRPC.Introspect Api method to return a collection of available fields for each method.

• Fork the project.

• Make your feature addition or bug fix.

• Add tests for it. This is important so I don’t break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

• Send me a pull request. Bonus points for topic branches.

Copyright © 2010 Christoph Olszowka. See LICENSE for details.