xbmc-client 0.1.0 → 0.1.1

data/Gemfile

@@ -2,6 +2,7 @@ source :rubygems
 
 gemspec
 
+# Additional gems required for development (i.e. running tests etc)
 group :development do
 
 end

data/README.rdoc

@@ -1,15 +1,17 @@
 = XBMC-Client
 
-This is a simple Ruby client for the XBMC (XBox Media Center) JSON-RPC API.
+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
+on the fly by pulling the available namespaces and methods from the <code>JSONRPC.Introspect</code>
 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`.
+<code>Xbmc::NAMESPACE.method_name_in_underscore_writing</code>, so for example the JSON RPC call 
+<code>AudioPlayer.PlayPause</code> becomes <code>Xbmc::AudioPlayer.play_pause</code> 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)`
+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.
@@ -47,8 +49,8 @@ The client is being developed against Ruby 1.9.2, but should work with Ruby 1.8
   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
+As you'll notice, it tries to automatically pull the correct collection for <code>get_xyz</code>
+calls, which means that you don't have to go to the subcollection <code>[:result][:artists]</code> 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!
@@ -56,6 +58,376 @@ 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 <code>rake rdoc:apidoc</code>
+
+=== 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

data/Rakefile

@@ -5,8 +5,8 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "xbmc-client"
-    gem.summary = %Q{A simple API client for the XBMC JSON-RPC API}
-    gem.description = %Q{A simple API client for the XBMC JSON-RPC API}
+    gem.summary = %Q{A simple API client for the XBMC Media Center JSON-RPC API}
+    gem.description = %Q{A simple API client for the XBMC Media Center JSON-RPC API}
     gem.email = "christoph at olszowka de"
     gem.homepage = "http://github.com/colszowka/xbmc-client"
     
@@ -57,3 +57,22 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
+
+namespace :rdoc do
+  desc "Generates an RDOC-formatted list of available commands"
+  task :apidoc do
+    require File.join(File.dirname(__FILE__), 'lib/xbmc-client')
+    # Configure to your settings!
+    Xbmc.base_uri "http://localhost:8435"
+    Xbmc.basic_auth "xbmc", "xbmc"
+    
+    puts "== Available API Methods", ""
+    puts "Please note that the API is loaded dynamically and thus this ultimately depends on your version of XBMC. This listing is generated automatically using <code>rake rdoc:apidoc</code>", ""
+    
+    Xbmc.commands.each do |command|
+      puts "=== #{command.klass_name}.#{command.method_name}"
+      puts "\n#{command.description}" if command.description.present?
+      puts
+    end
+  end
+end

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/examples/audio_library.rb

@@ -1,10 +1,6 @@
-require 'pp'
-require './' + File.join(File.dirname(__FILE__), '../lib', 'xbmc-client')
+# Some example calls for interacting with the Audio Library in XBMC
 
-Xbmc.base_uri "http://localhost:8435"
-Xbmc.basic_auth "xbmc", "xbmc"
-
-Xbmc.load_api!
+require "./" + File.join(File.dirname(__FILE__), 'example_environment')
 
 pp Xbmc::AudioLibrary.get_artists
 puts "="*60
@@ -12,4 +8,4 @@ pp Xbmc::AudioLibrary.get_albums(:artistid => Xbmc::AudioLibrary.get_artists.fir
 puts "="*60
 pp Xbmc::AudioLibrary.get_songs(:albumid => 1)
 
-pp Xbmc::AudioPlayer.play_pause
+pp Xbmc::AudioPlayer.play_pause

data/examples/example_environment.rb

@@ -0,0 +1,8 @@
+# Sets up the environment for all examples by loading the library and configuring it
+require 'pp'
+require File.join(File.dirname(__FILE__), '../lib', 'xbmc-client')
+
+Xbmc.base_uri "http://localhost:8435"
+Xbmc.basic_auth "xbmc", "xbmc"
+
+Xbmc.load_api!

data/lib/xbmc-client.rb

@@ -35,7 +35,7 @@ class Xbmc
 
     # Returns an array of available api commands instantiated as Xbmc::Command objects
     def commands
-      @commands ||= invoke_and_process("JSONRPC.Introspect", :getdescriptions => true)[:commands].map {|c| Xbmc::Command.new(c[:command])}
+      @commands ||= invoke_and_process("JSONRPC.Introspect", :getdescriptions => true)[:commands].map {|c| Xbmc::Command.new(c)}
     end
 
     # Loads the available commands via JSONRPC.Introspect and defines the namespace classes and corresponding methods

data/lib/xbmc/command.rb

@@ -1,9 +1,12 @@
 # Representation of a XBMC JSON RPC method
 class Xbmc::Command
-  attr_reader :command, :namespace, :method_name, :original_method
+  attr_reader :command, :namespace, :method_name, :original_method, :description
 
-  def initialize(command)
-    @command = command
+  # Initializes a new command from the meta data hash given in JSONRPC.Introspect
+  def initialize(command_meta)
+    @command_meta = command_meta.with_indifferent_access
+    @description = command_meta[:description]
+    @command = command_meta[:command]
     parse_command!
   end
 
@@ -11,7 +14,12 @@ class Xbmc::Command
   def invoke(params={})
     process_result(Xbmc.invoke_and_process(command, params))
   end
-
+  
+  # The ruby class name this command should end up in
+  def klass_name
+    "Xbmc::#{namespace}"
+  end
+  
   private
 
   # Extract the namespace and method names from the given JSON RPC raw command name
@@ -23,7 +31,6 @@ class Xbmc::Command
   # Will create the corresponding class for namespace if not defined yet
   # and also define the given method
   def define_method!
-    klass_name = "Xbmc::#{namespace}"
     begin
       klass = klass_name.constantize
     rescue NameError => err
@@ -31,7 +38,9 @@ class Xbmc::Command
       klass = klass_name.constantize
     end
   
+    # Need to assign instance to local var because "self" is out of scope inside the method definition
     command_object = self
+    # Define class method in corresponding namespace class
     klass.metaclass.send(:define_method, method_name.to_sym) do |*args|
       command_object.invoke(*args)
     end

data/xbmc-client.gemspec

@@ -5,12 +5,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{xbmc-client}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Christoph Olszowka"]
   s.date = %q{2010-11-25}
-  s.description = %q{A simple API client for the XBMC JSON-RPC API}
+  s.description = %q{A simple API client for the XBMC Media Center JSON-RPC API}
   s.email = %q{christoph at olszowka de}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -27,6 +27,7 @@ Gem::Specification.new do |s|
      "Rakefile",
      "VERSION",
      "examples/audio_library.rb",
+     "examples/example_environment.rb",
      "lib/ruby_ext.rb",
      "lib/xbmc-client.rb",
      "lib/xbmc/command.rb",
@@ -38,11 +39,12 @@ Gem::Specification.new do |s|
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.7}
-  s.summary = %q{A simple API client for the XBMC JSON-RPC API}
+  s.summary = %q{A simple API client for the XBMC Media Center JSON-RPC API}
   s.test_files = [
     "test/helper.rb",
      "test/test_xbmc-client.rb",
-     "examples/audio_library.rb"
+     "examples/audio_library.rb",
+     "examples/example_environment.rb"
   ]
 
   if s.respond_to? :specification_version then

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Christoph Olszowka
@@ -90,7 +90,7 @@ dependencies:
         version: 2.10.3
   type: :development
   version_requirements: *id005
-description: A simple API client for the XBMC JSON-RPC API
+description: A simple API client for the XBMC Media Center JSON-RPC API
 email: christoph at olszowka de
 executables: []
 
@@ -110,6 +110,7 @@ files:
 - Rakefile
 - VERSION
 - examples/audio_library.rb
+- examples/example_environment.rb
 - lib/ruby_ext.rb
 - lib/xbmc-client.rb
 - lib/xbmc/command.rb
@@ -147,8 +148,9 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: A simple API client for the XBMC JSON-RPC API
+summary: A simple API client for the XBMC Media Center JSON-RPC API
 test_files: 
 - test/helper.rb
 - test/test_xbmc-client.rb
 - examples/audio_library.rb
+- examples/example_environment.rb