plllayer 0.0.1 → 0.0.2

data/lib/plllayer/single_player.rb

@@ -1,4 +1,7 @@
 class Plllayer
+  # Raise this exception when the file at the given track path doesn't exist.
+  FileNotFoundError = Class.new(ArgumentError)
+
   # A SinglePlayer takes care of playing a single track, and controlling the
   # playback with commands like pause, resume, seek, and so on. It probably
   # starts an external audio player process to do this job. This class is an
@@ -9,7 +12,7 @@ class Plllayer
   # All methods that perform an action should return false if the action isn't
   # applicable, and return a truthy value otherwise.
   class SinglePlayer
-    # Returns true if a track is currently loaded, i.e. either playing or
+    # Return true if a track is currently loaded, i.e. either playing or
     # paused.
     def playing?
       raise NotImplementedError
@@ -22,7 +25,8 @@ class Plllayer
 
     # Begin playing a track. The track_path should be a String representing a
     # path to an audio file. The &on_end callback should be called when the track
-    # is finished playing.
+    # is finished playing. Should raise FileNotFoundError if the audio file
+    # doesn't exist.
     def play(track_path, &on_end)
       raise NotImplementedError
     end
@@ -32,12 +36,12 @@ class Plllayer
       raise NotImplementedError
     end
 
-    # Pauses playback.
+    # Pause playback.
     def pause
       raise NotImplementedError
     end
 
-    # Resumes playback.
+    # Resume playback.
     def resume
       raise NotImplementedError
     end
@@ -59,30 +63,30 @@ class Plllayer
       end
     end
 
-    # Gets the current playback speed. The speed is a multiplier. For example,
+    # Get the current playback speed. The speed is a multiplier. For example,
     # double speed is 2 and half-speed is 0.5. Normal speed is 1.
     def speed
       raise NotImplementedError
     end
 
-    # Sets the playback speed. The speed is a multiplier. For example, for
+    # Set the playback speed. The speed is a multiplier. For example, for
     # double speed you'd set it to 2 and for half-speed you'd set it to 0.5. And
     # for normal speed: 1.
     def speed=(new_speed)
       raise NotImplementedError
     end
 
-    # Returns true if audio is muted.
+    # Return true if audio is muted.
     def muted?
       raise NotImplementedError
     end
 
-    # Mutes the audio player.
+    # Mute the audio player.
     def mute
       raise NotImplementedError
     end
 
-    # Unmutes the audio player.
+    # Unmute the audio player.
     def unmute
       raise NotImplementedError
     end
@@ -92,17 +96,17 @@ class Plllayer
       raise NotImplementedError
     end
 
-    # Set the volume as a percentage. The player is automatically unmuted.
+    # Set the volume as a percentage. The player may be automatically unmuted.
     def volume=(new_volume)
       raise NotImplementedError
     end
 
-    # Returns the current time into the song, in milliseconds.
+    # Return the current time into the song, in milliseconds.
     def position
       raise NotImplementedError
     end
 
-    # Returns the length of the current track, in milliseconds.
+    # Return the length of the current track, in milliseconds.
     def track_length
       raise NotImplementedError
     end

data/lib/plllayer/single_players/mplayer.rb

@@ -27,42 +27,41 @@ class Plllayer
         # Make sure we're only playing one song at any one time.
         _quit
 
-        if File.exists? track_path
-          # Run the mplayer process in slave mode, passing it the location of
-          # the track's audio file.
-          cmd = ["mplayer", "-slave", "-quiet", track_path]
-          @pid, @stdin, @stdout, @stderr = Open4.popen4(*cmd)
-
-          # This should skip past mplayer's initial lines of output so we can
-          # start reading its replies to our commands.
-          until @stdout.gets["playback"]
-          end
+        # Make sure the audio file exists.
+        raise FileNotFoundError, "file '#{track_path}' doesn't exist" unless File.exists? track_path
 
-          @paused = false
-          @track_path = track_path
-
-          # Persist the previous speed, volume, and mute properties into this
-          # process.
-          self.speed = @speed
-          self.volume = @volume
-          mute if @muted
-
-          # Start a thread that waits for the mplayer process to end, then calls
-          # the end of song callback. If the #quit method is called, this thread
-          # will be killed if it's still waiting for the process to end.
-          @quit_hook_active = false
-          @quit_hook = Thread.new do
-            Process.wait(@pid)
-            @quit_hook_active = true
-            @paused = false
-            @track_path = nil
-            on_end.call
-          end
+        # Run the mplayer process in slave mode, passing it the location of
+        # the track's audio file.
+        cmd = ["mplayer", "-slave", "-quiet", track_path]
+        @pid, @stdin, @stdout, @stderr = Open4.popen4(*cmd)
 
-          true
-        else
-          false
+        # This should skip past mplayer's initial lines of output so we can
+        # start reading its replies to our commands.
+        until @stdout.gets["playback"]
         end
+
+        @paused = false
+        @track_path = track_path
+
+        # Persist the previous speed, volume, and mute properties into this
+        # process.
+        self.speed = @speed
+        self.volume = @volume
+        mute if @muted
+
+        # Start a thread that waits for the mplayer process to end, then calls
+        # the end of song callback. If the #quit method is called, this thread
+        # will be killed if it's still waiting for the process to end.
+        @quit_hook_active = false
+        @quit_hook = Thread.new do
+          Process.wait(@pid)
+          @quit_hook_active = true
+          @paused = false
+          @track_path = nil
+          on_end.call
+        end
+
+        true
       end
 
       def stop
@@ -201,8 +200,10 @@ class Plllayer
           _command "quit"
           @paused = false
           @track_path = nil
+          true
+        else
+          false
         end
-        true
       end
 
       # Check if the mplayer process is still around.

data/lib/plllayer/time_helpers.rb

@@ -0,0 +1,37 @@
+class Plllayer
+  module TimeHelpers
+    # Helper method to format a number of milliseconds as a string like
+    # "1:03:56.555". The only option is :include_milliseconds, true by default. If
+    # false, milliseconds won't be included in the formatted string.
+    def format_time(milliseconds, options = {})
+      ms = milliseconds % 1000
+      seconds = (milliseconds / 1000) % 60
+      minutes = (milliseconds / 60000) % 60
+      hours = milliseconds / 3600000
+
+      if ms.zero? || options[:include_milliseconds] == false
+        ms_string = ""
+      else
+        ms_string = ".%03d" % [ms]
+      end
+
+      if hours > 0
+        "%d:%02d:%02d%s" % [hours, minutes, seconds, ms_string]
+      else
+        "%d:%02d%s" % [minutes, seconds, ms_string]
+      end
+    end
+
+    # Helper method to parse a string like "1:03:56.555" and return the number of
+    # milliseconds that time length represents.
+    def parse_time(string)
+      parts = string.split(":").map(&:to_f)
+      parts = [0] + parts if parts.length == 2
+      hours, minutes, seconds = parts
+      seconds = hours * 3600 + minutes * 60 + seconds
+      milliseconds = seconds * 1000
+      milliseconds.to_i
+    end
+  end
+end
+

data/lib/plllayer.rb

@@ -1,16 +1,46 @@
 require "open4"
 
+require "plllayer/time_helpers.rb"
 require "plllayer/single_player"
 require "plllayer/single_players/mplayer"
 
+# Plllayer provides an interface to an external media player, such as mplayer. It
+# contains a playlist of tracks, which may be as simple as an Array of paths to
+# some audio files. You can then control the playback of this playlist by calling
+# various command-like methods, like play, pause, seek, skip, shuffle, and so on.
 class Plllayer
+  # This pulls in the Plllayer.parse_time and Plllayer.format_time helper methods.
+  # See plllayer/time_helpers.rb.
+  extend TimeHelpers
+
+  SINGLE_PLAYERS = {
+    mplayer: Plllayer::SinglePlayers::MPlayer
+  }
+
   attr_reader :repeat_mode
 
+  # Create a new Plllayer. Optionally, you can pass in an initial playlist to be
+  # loaded (won't start playing until you call #play). You can also pass the
+  # :external_player option to specify the preferred external player to use.
+  # Otherwise, it will try to figure out what external players are available, and
+  # attempt to use the best one available.
+  #
+  # However, only mplayer is supported at the moment, so this option isn't useful
+  # right now.
+  #
+  # TODO: check if external player is available before trying to use it.
   def initialize(*args)
     options = {}
     options = args.pop if args.last.is_a? Hash
+    options[:external_player] ||= :mplayer
+
+    # Look up the single player class, raise error if it doesn't exist.
+    single_player_class = SINGLE_PLAYERS[options[:external_player].to_sym]
+    if single_player_class.nil?
+      raise NotImplementedError, "external player #{options[:external_player]} not supported"
+    end
 
-    @single_player = Plllayer::SinglePlayers::MPlayer.new
+    @single_player = single_player_class.new
     @playlist = []
     append(args.first) unless args.empty?
     @index = nil
@@ -18,34 +48,47 @@ class Plllayer
     @playing = false
     @repeat_mode = nil
 
+    # Make sure the music stops playing once the Ruby script is exited.
     at_exit { stop }
   end
 
-  def load(playlist = nil)
-    clear
-    append(playlist)
-  end
-
+  # Append tracks to the playlist. Can be done while the playlist is playing.
+  # A track is either a String containing the path to the audio file, or an
+  # object with a #location method that returns the path to the audio file.
+  # An ArgumentError is raised when you try to pass a non-track.
+  #
+  # This method is aliased as the << operator.
   def append(tracks)
-    tracks = Array(tracks).dup
-    tracks.select! { |track| track.respond_to?(:location) || (track.is_a?(String) && File.exists?(track)) }
+    tracks = Array(tracks)
+    tracks.each do |track|
+      if !track.is_a?(String) && !track.respond_to?(:location)
+        raise ArgumentError, "a #{track.class} is not a track (try adding a #location method)"
+      end
+    end
     @playlist += tracks
     @playlist.dup
   end
   alias :<< :append
 
+  # Returns a copy of the playlist.
   def playlist
     @playlist.dup
   end
 
+  # Get the currently-playing track, or the track that's about to play if
+  # you're paused between tracks. Returns nil if playback is stopped.
   def track
     @index ? @playlist[@index] : nil
   end
 
+  # Get the index of the currently-playing track, or of the track that's
+  # about to play if you're paused between tracks. Returns nil if playback
+  # is stopped.
   def track_index
     @index
   end
 
+  # Get the path to the audio file of the currently-playing track.
   def track_path
     if track.respond_to? :location
       track.location
@@ -54,22 +97,29 @@ class Plllayer
     end
   end
 
+  # Stop playback and empty the playlist.
   def clear
     stop
     @playlist.clear
     true
   end
 
+  # Check if playback is paused.
   def paused?
     @paused
   end
 
+  # Check if the playlist is being played. Whether playback is paused doesn't
+  # affect this. False is only returned if either (1) #play was never called,
+  # (2) #stop has been called, or (3) playback stopped after finishing playing
+  # all the songs.
   def playing?
     @playing
   end
 
+  # Start playing the playlist from beginning to end.
   def play
-    unless @playlist.empty?
+    if !@playlist.empty? && !playing?
       @playing = true
       @paused = false
       @index = 0
@@ -80,17 +130,23 @@ class Plllayer
     end
   end
 
+  # Stop playback.
   def stop
-    @single_player.stop
-    @track = nil
-    @index = nil
-    @paused = false
-    @playing = false
-    true
+    if playing?
+      @single_player.stop
+      @track = nil
+      @index = nil
+      @paused = false
+      @playing = false
+      true
+    else
+      false
+    end
   end
 
+  # Pause playback.
   def pause
-    if playing?
+    if playing? && !paused?
       @paused = true
       @single_player.pause
     else
@@ -98,14 +154,14 @@ class Plllayer
     end
   end
 
+  # Resume playback.
   def resume
-    if playing?
+    if playing? && paused?
       @paused = false
       if @single_player.playing?
         @single_player.resume
       else
         play_track @track
-        @playlist_paused = false
         true
       end
     else
@@ -113,6 +169,13 @@ class Plllayer
     end
   end
 
+  # Set the repeat behaviour of the playlist. There are three possible values:
+  #
+  #   :one    repeat a single track over and over
+  #   :all    repeat the whole playlist, treating it like a circular array
+  #   :off    play songs consecutively, stop playback when done
+  #
+  # The default, of course, is :off.
   def repeat(one_or_all_or_off)
     case one_or_all_or_off
     when :one
@@ -121,22 +184,41 @@ class Plllayer
       @repeat_mode = :all
     when :off
       @repeat_mode = nil
+    else
+      raise ArgumentError
     end
     true
   end
 
+  # Play the currently-playing track from the beginning.
   def restart
     change_track(0)
   end
 
+  # Play the previous track. Pass a number to go back that many tracks. Treats
+  # the playlist like a circular array if the repeat mode is :all.
   def back(n = 1)
     change_track(-n)
   end
 
+  # Play the next track. Pass a number to go forward that many tracks. Treats
+  # the playlist like a circular array if the repeat mode is :all.
   def skip(n = 1)
     change_track(n)
   end
 
+  # Seek to a particular position within the currently-playing track. There are
+  # multiple ways to specify where to seek to:
+  #
+  #   seek 10000         # seek 10000 milliseconds forward, relative to the current position
+  #   seek -5000         # seek 5000 milliseconds backward
+  #   seek "3:45"        # seek to the absolute position 3 minutes and 45 seconds
+  #   seek "1:03:45.123" # seek to 1 hour, 3 minutes, 45 seconds, 123 milliseconds
+  #   seek 3..45         # syntax sugar for seeking to "3:45"
+  #   seek 3..45.123     # syntax sugar for seeking to "3:45.123"
+  #   seek abs: 150000   # seek to the absolute position 150000 milliseconds
+  #   seek percent: 80   # seek to 80% of the way through the track
+  #
   def seek(where)
     if paused? && !@single_player.playing?
       resume
@@ -150,7 +232,7 @@ class Plllayer
       seconds = where.begin * 60 + where.end
       @single_player.seek(seconds * 1000, :absolute)
     when String
-      @single_player.seek(parse_time(where), :absolute)
+      @single_player.seek(Plllayer.parse_time(where), :absolute)
     when Hash
       if where[:abs]
         if where[:abs].is_a? Integer
@@ -161,37 +243,51 @@ class Plllayer
       elsif where[:percent]
         @single_player.seek(where[:percent], :percent)
       end
+    else
+      raise ArgumentError, "seek doesn't take a #{where.class}"
     end
   end
 
+  # Get the playback speed as a Float. 1.0 is normal speed, 2.0 is double speed,
+  # 0.5 is half-speed, and so on.
   def speed
     @single_player.speed || 1.0
   end
 
+  # Set the playback speed as a Float. 1.0 is normal speed, 2.0 is double speed,
+  # 0.5 is half-speed, and so on.
   def speed=(new_speed)
     @single_player.speed = new_speed
   end
 
+  # Mute the volume.
   def mute
     @single_player.mute
   end
 
+  # Unmute the volume.
   def unmute
     @single_player.unmute
   end
 
+  # Check if volume is muted.
   def muted?
     @single_player.muted?
   end
 
+  # Get the volume, as a percentage.
   def volume
     @single_player.volume
   end
 
+  # Set the volume, as a percentage.
   def volume=(new_volume)
     @single_player.volume = new_volume
   end
 
+  # Shuffle the playlist. If this is done while the playlist is playing, the
+  # current song will go to the top of the playlist and the rest of the songs
+  # will be shuffled.
   def shuffle
     current_track = track
     @playlist.shuffle!
@@ -203,6 +299,10 @@ class Plllayer
     true
   end
 
+  # Sorts the playlist. Delegates to Array#sort, so a block may be passed to
+  # specify what the tracks should be sorted by.
+  #
+  # This method is safe to call while the playlist is playing.
   def sort(&by)
     current_track = track
     @playlist.sort! &by
@@ -212,14 +312,18 @@ class Plllayer
     true
   end
 
+  # Returns the current position of the currently-playing track, in milliseconds.
   def position
     @single_player.position || 0
   end
 
+  # Returns the current position of the currently-playing track, as a String
+  # like "1:23".
   def formatted_position(options = {})
-    format_time(position, options)
+    Plllayer.format_time(position, options)
   end
 
+  # Returns the length of the currently-playing track, in milliseconds.
   def track_length
     if paused? && !@single_player.playing?
       resume
@@ -228,9 +332,10 @@ class Plllayer
     @single_player.track_length
   end
 
+  # Returns the length of the currently-playing track, as a String like "1:23".
   def formatted_track_length(options = {})
     if length = track_length
-      format_time(length, options)
+      Plllayer.format_time(length, options)
     end
   end
 
@@ -270,38 +375,5 @@ class Plllayer
     @paused = false
     true
   end
-
-  # Helper method to format a number of milliseconds as a string like
-  # "1:03:56.555". The only option is :include_milliseconds, true by default. If
-  # false, milliseconds won't be included in the formatted string.
-  def format_time(milliseconds, options = {})
-    ms = milliseconds % 1000
-    seconds = (milliseconds / 1000) % 60
-    minutes = (milliseconds / 60000) % 60
-    hours = milliseconds / 3600000
-
-    if ms.zero? || options[:include_milliseconds] == false
-      ms_string = ""
-    else
-      ms_string = ".%03d" % [ms]
-    end
-
-    if hours > 0
-      "%d:%02d:%02d%s" % [hours, minutes, seconds, ms_string]
-    else
-      "%d:%02d%s" % [minutes, seconds, ms_string]
-    end
-  end
-
-  # Helper method to parse a string like "1:03:56.555" and return the number of
-  # milliseconds that time length represents.
-  def parse_time(string)
-    parts = string.split(":").map(&:to_f)
-    parts = [0] + parts if parts.length == 2
-    hours, minutes, seconds = parts
-    seconds = hours * 3600 + minutes * 60 + seconds
-    milliseconds = seconds * 1000
-    milliseconds.to_i
-  end
 end
 

data/plllayer.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name = "plllayer"
-  s.version = "0.0.1"
-  s.date = "2012-12-06"
+  s.version = "0.0.2"
+  s.date = "2013-01-31"
   s.summary = "An audio playback library for Ruby."
   s.description = "plllayer is an audio playback library for Ruby. It is a Ruby interface to some external media player, such as mplayer."
   s.author = "Jeremy Ruten"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plllayer
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-06 00:00:00.000000000 Z
+date: 2013-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -72,6 +72,7 @@ files:
 - plllayer.gemspec
 - lib/plllayer/single_player.rb
 - lib/plllayer/single_players/mplayer.rb
+- lib/plllayer/time_helpers.rb
 - lib/plllayer.rb
 homepage: http://github.com/yjerem/plllayer
 licenses: