xbmc-client

= 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: http://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 {"media": "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 {"directory": "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 {"directory": "/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 {"message": "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.

== Copyright

Copyright (c) 2010 Christoph Olszowka. See LICENSE for details.