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.