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.

Install

gem install xbmc-client

Usage

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

Available API Methods

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

Xbmc::JSONRPC.introspect

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

Xbmc::JSONRPC.version

Retrieve the jsonrpc protocol version

Xbmc::JSONRPC.permission

Retrieve the clients permissions

Xbmc::JSONRPC.ping

Ping responder

Xbmc::JSONRPC.announce

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

Xbmc::Player.get_active_players

Returns all active players IDs

Xbmc::AudioPlayer.state

Returns Current Playback state

Xbmc::AudioPlayer.play_pause

Pauses or unpause playback, returns new state

Xbmc::AudioPlayer.stop

Stops playback

Xbmc::AudioPlayer.skip_previous

Skips to previous item on the playlist

Xbmc::AudioPlayer.skip_next

Skips to next item on the playlist

Xbmc::AudioPlayer.big_skip_backward

Xbmc::AudioPlayer.big_skip_forward

Xbmc::AudioPlayer.small_skip_backward

Xbmc::AudioPlayer.small_skip_forward

Xbmc::AudioPlayer.rewind

Rewind current playback

Xbmc::AudioPlayer.forward

Forward current playback

Xbmc::AudioPlayer.get_time

Retrieve time

Xbmc::AudioPlayer.get_time_ms

Retrieve time in MS

Xbmc::AudioPlayer.get_percentage

Retrieve percentage

Xbmc::AudioPlayer.seek_time

Seek to a specific time. Parameter integer in seconds

Xbmc::AudioPlayer.seek_percentage

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

Xbmc::AudioPlayer.record

Xbmc::VideoPlayer.state

Returns Current Playback state

Xbmc::VideoPlayer.play_pause

Pauses or unpause playback, returns new state

Xbmc::VideoPlayer.stop

Stops playback

Xbmc::VideoPlayer.skip_previous

Skips to previous item on the playlist

Xbmc::VideoPlayer.skip_next

Skips to next item on the playlist

Xbmc::VideoPlayer.big_skip_backward

Xbmc::VideoPlayer.big_skip_forward

Xbmc::VideoPlayer.small_skip_backward

Xbmc::VideoPlayer.small_skip_forward

Xbmc::VideoPlayer.rewind

Rewind current playback

Xbmc::VideoPlayer.forward

Forward current playback

Xbmc::VideoPlayer.get_time

Retrieve time

Xbmc::VideoPlayer.get_time_ms

Retrieve time in MS

Xbmc::VideoPlayer.get_percentage

Retrieve percentage

Xbmc::VideoPlayer.seek_time

Seek to a specific time. Parameter integer in seconds

Xbmc::VideoPlayer.seek_percentage

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

Xbmc::PicturePlayer.play_pause

Pauses or unpause slideshow

Xbmc::PicturePlayer.stop

Stops slideshow

Xbmc::PicturePlayer.skip_previous

Skips to previous picture in the slideshow

Xbmc::PicturePlayer.skip_next

Skips to next picture in the slideshow

Xbmc::PicturePlayer.move_left

If picture is zoomed move viewport left otherwise skip previous

Xbmc::PicturePlayer.move_right

If picture is zoomed move viewport right otherwise skip previous

Xbmc::PicturePlayer.move_down

If picture is zoomed move viewport down

Xbmc::PicturePlayer.move_up

If picture is zoomed move viewport up

Xbmc::PicturePlayer.zoom_out

Zoom out once

Xbmc::PicturePlayer.zoom_in

Zoom in once

Xbmc::PicturePlayer.zoom

Zooms current picture. Parameter integer of zoom level

Xbmc::PicturePlayer.rotate

Rotates current picture

Xbmc::VideoPlaylist.play

Xbmc::VideoPlaylist.skip_previous

Xbmc::VideoPlaylist.skip_next

Xbmc::VideoPlaylist.get_items

Xbmc::VideoPlaylist.add

Xbmc::VideoPlaylist.clear

Clear video playlist

Xbmc::VideoPlaylist.shuffle

Shuffle video playlist

Xbmc::VideoPlaylist.un_shuffle

UnShuffle video playlist

Xbmc::AudioPlaylist.play

Xbmc::AudioPlaylist.skip_previous

Xbmc::AudioPlaylist.skip_next

Xbmc::AudioPlaylist.get_items

Xbmc::AudioPlaylist.add

Xbmc::AudioPlaylist.clear

Clear audio playlist

Xbmc::AudioPlaylist.shuffle

Shuffle audio playlist

Xbmc::AudioPlaylist.un_shuffle

UnShuffle audio playlist

Xbmc::Playlist.create

Creates a virtual playlist from a given one from a file

Xbmc::Playlist.destroy

Destroys a virtual playlist

Xbmc::Playlist.get_items

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

Xbmc::Playlist.add

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

Xbmc::Playlist.remove

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

Xbmc::Playlist.swap

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

Xbmc::Playlist.shuffle

Shuffle playlist

Xbmc::Playlist.un_shuffle

UnShuffle playlist

Xbmc::Files.get_sources

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

Xbmc::Files.download

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

Xbmc::Files.get_directory

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

Xbmc::AudioLibrary.get_artists

Retrieve all artists

Xbmc::AudioLibrary.get_albums

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

Xbmc::AudioLibrary.get_songs

Retrieve all songs from specified album, artist or genre

Xbmc::AudioLibrary.scan_for_content

Xbmc::VideoLibrary.get_movies

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

Xbmc::VideoLibrary.get_tv_shows

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

Xbmc::VideoLibrary.get_seasons

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

Xbmc::VideoLibrary.get_episodes

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

Xbmc::VideoLibrary.get_music_videos

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

Xbmc::VideoLibrary.get_recently_added_movies

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

Xbmc::VideoLibrary.get_recently_added_episodes

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

Xbmc::VideoLibrary.get_recently_added_music_videos

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

Xbmc::VideoLibrary.scan_for_content

Xbmc::System.shutdown

Xbmc::System.suspend

Xbmc::System.hibernate

Xbmc::System.reboot

Xbmc::System.get_info_labels

Retrieve info labels about the system

Xbmc::System.get_info_booleans

Retrieve info booleans about the system

Xbmc::XBMC.get_volume

Retrieve the current volume

Xbmc::XBMC.set_volume

Set volume. Parameter integer between 0 amd 100

Xbmc::XBMC.toggle_mute

Toggle mute

Xbmc::XBMC.play

Starts playback

Xbmc::XBMC.start_slideshow

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

Xbmc::XBMC.log

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

Xbmc::XBMC.quit

Quit xbmc

Issues

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.

Note on Patches/Pull Requests

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.