xiron - a free video player frontend framework

introduction

this is an extension to ruby which allows to use the xine-library to play media streams. this binding takes advantage from the unique features of ruby to provide an objectoriented, and easy-to-use interface to xine. the goal of the api-design is to be lightweight and as smart as possible but not outsmart the programmer. this api combined with the powerful features of the ruby language itself leads to a powerful development framework which makes the development of new media players surprisingly easy.

xiron also provides some utility classes not directly related to xine but very usable for frontends. currently there is a class to handle mediamarks and playlists of various formats and an osd widget set to easily write purely osd-based front-ends like oxine.

another interesting subproject available is grill, a testing framework for xine written in ruby using xiron. the goal is to test every aspect of xine-lib and make the testing as easy as possible. so the grill package comes bundled with xiron and doesn’t need any installation. simply unpack and run. the latest test report of grill can be found here.

the newest version of xiron can always be found on xiron.sourceforge.net. if you have questions, comments, or a desire help improving the xiron framework, feel free to post on this list or mail me directly.

so relax and enjoy the wonderful world of ruby :-)

requirements and installation

this extension is only tested with ruby 1.8. you should also use the latest cvs-version of xine which fixes some bugs this extension may trigger. ruby should be compiled with —enable-pthread. otherwise you may experience mysterious deadlocks.

to install this ruby extension, check the Makefile for installation prefix and type make install. thats it.

please be sure the used installation path is in RUBYLIB environment variable so it can be required from any ruby script. so put something like this in your .bashrc:

  export RUBYLIB=/usr/local/lib/ruby/site_ruby/1.8:/usr/local/lib/ruby/site_ruby/1.8/i686-linux:$RUBYLIB

to (re)create the documentation, type make doc. the documentation will be built in a subdirectory named rdoc.

first steps

check out the samples subdirectory. these scripts are supposed to give you a feeling how the api of this extensions work:

player:	a simple player which uses the included class SimplePlayer - call as "./player mrl://"
osdplayer:	same as player but adds osd blendings
aaplayer:	same as player but with ascii-art output
regview:	a viewer for the xine config, also requires ruby-gnome2 extension
snapshot:	demonstrates the snapshot function
streaminfo:	prints all available info of given stream
visualization:	demonstrates post plugin rewireing

beside writing scripts, it is also possible to use the xine-lib interactively:

  stefan@droopy media $ irb -r xiron
  irb(main):001:0> include Xiron
  => Object
  irb(main):002:0> s = Stream.new
  => #<Stream:0x402567e0>
  irb(main):003:0> s.play "/some/media.avi"
  => nil
  irb(main):004:0> s.length
  => 341.841
  irb(main):005:0> s.has_video?
  => true
  irb(main):006:0> s.speed = "pause"
  => "pause"
  irb(main):007:0> s.time
  => 63.354
  irb(main):008:0> s.time
  => 63.354
  irb(main):009:0> s.speed = "normal"
  => "normal"
  irb(main):010:0> s.time
  => 66.941
  irb(main):011:0> quit

here you see, it takes only two lines of code to start a media playback. this shows a design goal of this api: try to be as smart as possible. you don’t have to brother instanciating a lot of objects if you don’t have special requirements. here, "Stream.new" implicitely instanciates a VideoPort, an AudioPort and, of course, initializes the xine engine itself. although the api is as smart as possible, it tries to be not smarter as the programmer. all the implicit actions can be overridden by explicit ones.

this script does essentially the same thing as the irb session above:

  #!/usr/bin/ruby

  require 'xiron'
  include Xiron

  s = Stream.new
  s.play ARGV[0]

  s.wait do |event|
    event.id == "playback_finished"
  end

here a stream is created (and implicitely Xine, VideoPort and AudioPort objects) like above. but the script would terminate immediately because the play method returns at once. so we need to wait explititely for the end of the media stream and this is done with the wait method. if this method is called with an associated block of code like here, it waits for the next event sent on this stream and then yields the block with this event. if the block evaluates to "true", wait returns. otherwise it waits for the next event. so we see a "playback_finished"-event here, wait returns and the script terminates.

but what, if we don’t want to wait until the very end? suppose we want the script return at once, if we press ‘q’. every keypress a window receives is sent as events to the associated stream. so we can alter the wait-block to something like this:

  s.wait do |event|
    ["playback_finished","q"].include? event.id
  end

here we wait until the playback is finished or ‘q’ was pressed. another war to accompolish this behavior is to install an event handler for the ‘q’-event like this:

  #!/usr/bin/ruby

  require 'xiron'
  include Xiron

  s = Stream.new
  s.play ARGV[0]

  s.handle("q"){exit}

  s.wait do |event|
    event.id == "playback_finished"
  end

here, wait also waits on events, but if a specific event has an handler installed, wait does not yield its own block but the block given in the handle-call.

so much for the moment. now you can write your own simple media player. try a peek into the api-reference of the Stream-class. there are a lot of attributes you can use to gather information about the media for to alter the behavior of the playback (e.g. s.speed = "pause").