muzak 0.0.11 → 0.0.12

data/lib/muzak/instance.rb

@@ -1,8 +1,15 @@
 module Muzak
+  # Encapsulates the entirety of muzak's running state.
   class Instance
     include Cmd
     include Utils
 
+    # Sends a command to the instance.
+    # @param cmd [String] the name of the command
+    # @param args [Array<String>] the command's arguments
+    # @example
+    #   instance.command "enqueue-playlist", "favorites"
+    #   instance.command "pause"
     def command(cmd, *args)
       send Utils.resolve_command(cmd), *args
     end
@@ -12,14 +19,24 @@ module Muzak
       help
     end
 
-    attr_reader :index, :player, :plugins, :playlists
+    # @return [Index] the instance's music index
+    attr_reader :index
+
+    # @return [StubPlayer] the instance's player
+    attr_reader :player
+
+    # @return [Array<StubPlugin>] the instance's plugins
+    attr_reader :plugins
+
+    # @return [Hash{String => Playlist}] the instance's playlists
+    attr_reader :playlists
 
     def initialize(opts = {})
       verbose "muzak is starting..."
 
       @index = Index.new(Config.music, deep: Config.deep_index)
 
-      @player = Player::PLAYER_MAP[Config.player].new(self)
+      @player = Player.load_player!(self)
 
       @plugins = Plugin.load_plugins!
 
@@ -28,6 +45,10 @@ module Muzak
       enqueue_playlist Config.autoplay if Config.autoplay
     end
 
+    # Dispatch an event to all plugins.
+    # @param type [Symbol] the type of event to dispatch
+    # @param args [Array] the event's arguments
+    # @note {Muzak::PLUGIN_EVENTS} contains all valid events.
     def event(type, *args)
       return unless PLUGIN_EVENTS.include?(type)
 

data/lib/muzak/player.rb

@@ -4,10 +4,18 @@ require_relative "player/stub_player"
 Dir.glob(File.join(__dir__, "player/*")) { |file| require_relative file }
 
 module Muzak
+  # The namespace for muzak players.
   module Player
+    # An association of shorthand player "names" to Class objects.
     PLAYER_MAP = {
       "stub" => Player::StubPlayer,
       "mpv" => Player::MPV
-    }
+    }.freeze
+
+    # Returns an instantiated player as specified in `Config.player`.
+    # @return [StubPlayer] the player instance
+    def self.load_player!(instance)
+      PLAYER_MAP[Config.player].new(instance)
+    end
   end
 end

data/lib/muzak/player/mpv.rb

@@ -5,7 +5,9 @@ require "thread"
 
 module Muzak
   module Player
+    # Exposes MPV's IPC to muzak for playback control.
     class MPV < StubPlayer
+      # @return [Boolean] Whether or not the current instance is running.
       def running?
         begin
           !!@pid && Process.waitpid(@pid, Process::WNOHANG).nil?
@@ -14,6 +16,8 @@ module Muzak
         end
       end
 
+      # Activate mpv by executing it and preparing for event processing.
+      # @return [void]
       def activate!
         return if running?
 
@@ -56,6 +60,8 @@ module Muzak
         instance.event :player_activated
       end
 
+      # Deactivate mpv by killing it and cleaning up.
+      # @return [void]
       def deactivate!
         return unless running?
 
@@ -73,38 +79,59 @@ module Muzak
         File.delete(@sock_path) if @sock_path && File.exists?(@sock_path)
       end
 
+      # Tell mpv to begin playback.
+      # @return [void]
+      # @note Does nothing is playback is already in progress.
       def play
         return unless running?
 
         set_property "pause", false
       end
 
+      # Tell mpv to pause playback.
+      # @return [void]
+      # @note Does nothing is playback is already paused.
       def pause
         return unless running?
 
         set_property "pause", true
       end
 
+      # @return [Boolean] Whether or not mpv is currently playing.
       def playing?
         return false unless running?
 
         !get_property "pause"
       end
 
+      # Tell mpv to play the next song in its queue.
+      # @return [void]
+      # @note Does nothing if the current song is the last.
       def next_song
         command "playlist-next"
       end
 
+      # Tell mpv to play the previous song in its queue.
+      # @return [void]
+      # @note Does nothing if the current song is the first.
       def previous_song
         command "playlist-prev"
       end
 
+      # Tell mpv to add the given song to its queue.
+      # @param song [Song] the song to add
+      # @return [void]
+      # @note Activates mpv if not already activated.
       def enqueue_song(song)
         activate! unless running?
 
         load_song song, song.best_guess_album_art
       end
 
+      # Tell mpv to add the given album to its queue.
+      # @param album [Album] the album to add
+      # @return [void]
+      # @note Activates mpv if not already activated.
       def enqueue_album(album)
         activate! unless running?
 
@@ -113,6 +140,10 @@ module Muzak
         end
       end
 
+      # Tell mpv to add the given playlist to its queue.
+      # @param playlist [Playlist] the playlist to add
+      # @return [void]
+      # @note Activates mpv if not already activated.
       def enqueue_playlist(playlist)
         activate! unless running?
 
@@ -121,6 +152,9 @@ module Muzak
         end
       end
 
+      # Get mpv's internal queue.
+      # @return [Array<Song>] all songs in mpv's queue
+      # @note This includes songs already played.
       def list_queue
         entries = get_property "playlist/count"
 
@@ -133,18 +167,24 @@ module Muzak
         playlist
       end
 
+      # Shuffle mpv's internal queue.
+      # @return [void]
       def shuffle_queue
         return unless running?
 
         command "playlist-shuffle"
       end
 
+      # Clears mpv's internal queue.
+      # @return [void]
       def clear_queue
         return unless running?
 
         command "playlist-clear"
       end
 
+      # Get mpv's currently playing song.
+      # @return [Song] the currently playing song
       def now_playing
         return unless running? && playing?
 
@@ -201,6 +241,8 @@ module Muzak
               # somehow.
               song = Song.new(get_property "path")
               instance.event :song_loaded, song
+            when "end-file"
+              instance.event :song_unloaded
             end
           end
         end

data/lib/muzak/player/stub_player.rb

@@ -1,70 +1,121 @@
 module Muzak
   module Player
+    # A no-op player that all players inherit from.
     class StubPlayer
       include Utils
 
+      # @return [Instance] the instance associated with this player
       attr_reader :instance
 
+      # @param instance [Instance] the instance associated with the player
       def initialize(instance)
         @instance = instance
       end
 
+      # @return [false] whether or not the player is running
+      # @note NO-OP
       def running?
         debug "#running?"
+        false
       end
 
+      # Activates the player.
+      # @return [void]
+      # @note NO-OP
       def activate!
         debug "#activate!"
       end
 
+      # Deactivates the player.
+      # @return [void]
+      # @note NO-OP
       def deactivate!
         debug "#deactivate!"
       end
 
+      # Starts playback.
+      # @return [void]
+      # @note NO-OP
       def play
         debug "#play"
       end
 
+      # Ends playback.
+      # @return [void]
+      # @note NO-OP
       def pause
         debug "#pause"
       end
 
+      # @return [false] whether or not the player is currently playing
+      # @note NO-OP
       def playing?
         debug "#playing?"
+        false
       end
 
+      # Moves to the next song.
+      # @return [void]
+      # @note NO-OP
       def next_song
         debug "#next_song"
       end
 
+      # Moves to the previous song.
+      # @return [void]
+      # @note NO-OP
       def previous_song
         debug "#previous_song"
       end
 
+      # Enqueues the given song.
+      # @param song [Song] the song to enqueue
+      # @return [void]
+      # @note NO-OP
       def enqueue_song(song)
         debug "#enqueue_song"
       end
 
+      # Enqueues the given album.
+      # @param album [Album] the album to enqueue
+      # @return [void]
+      # @note NO-OP
       def enqueue_album(album)
         debug "#enqueue_album"
       end
 
+      # Enqueues the given playlist.
+      # @param playlist [Playlist] the playlist to enqueue
+      # @return [void]
+      # @note NO-OP
       def enqueue_playlist(playlist)
         debug "#enqueue_playlist"
       end
 
+      # List the player's queue.
+      # @return [void]
+      # @note NO-OP
       def list_queue
         debug "#list_queue"
       end
 
+      # Shuffle the player's queue.
+      # @return [void]
+      # @note NO-OP
       def shuffle_queue
         debug "#shuffle_queue"
       end
 
+      # Clear the player's queue.
+      # @return [void]
+      # @note NO-OP
       def clear_queue
         debug "#clear_queue"
       end
 
+      # Get the currently playing song.
+      # @return [void]
+      # @note NO-OP
       def now_playing
         debug "#now_playing"
       end

data/lib/muzak/playlist.rb

@@ -1,19 +1,33 @@
 module Muzak
   class Playlist
-    attr_accessor :filename, :songs
+    # @return [String] the absolute path to the playlist on disk
+    attr_accessor :filename
 
+    # @return [Array<Song>] the playlist's songs
+    attr_accessor :songs
+
+    # @param pname [String] the playlist's name
+    # @return [String] the absolute path to the given playlist name
     def self.path_for(pname)
       File.join(PLAYLIST_DIR, pname) + ".yml"
     end
 
+    # @param pname [String] the playlist's name
+    # @return [Boolean] whether or not the given playlist name already exists
     def self.exist?(pname)
       File.exist?(path_for(pname))
     end
 
+    # Deletes the given playlist from disk.
+    # @param pname [String] the playlist's name
+    # @return [void]
+    # @note If already instantiated, the playlist may still be present in
+    #   memory (and may reappear on disk if modified in memory)
     def self.delete!(pname)
       File.delete(path_for(pname)) if exist? pname
     end
 
+    # @return [Array<String>] the names of all currently available playlists
     def self.playlist_names
       Dir.entries(PLAYLIST_DIR).reject do |ent|
         ent.start_with?(".")
@@ -22,6 +36,9 @@ module Muzak
       end
     end
 
+    # Instantiates all playlists by loading them from disk.
+    # @return [Hash{String => Playlist}] an association of playlist names to
+    #   {Playlist} instances
     def self.load_playlists!
       playlists = {}
       playlists.default_proc = proc { |h, k| h[k] = Playlist.new(k) }
@@ -33,6 +50,9 @@ module Muzak
       playlists
     end
 
+    # Create a new {Playlist} with the given name, or load one by that
+    #   name if it already exists.
+    # @param pname [String] the playlist's name
     def initialize(pname)
       @filename = self.class.path_for pname
 
@@ -46,10 +66,13 @@ module Muzak
       sync!
     end
 
+    # @return [String] the playlist's name
     def name
       File.basename(@filename, File.extname(@filename))
     end
 
+    # @param songs [Song, Array<Song>] one or more songs to add to the playlist
+    # @return [void]
     def add(songs)
       # coerce a single song into an array
       [*songs].each do |song|
@@ -60,20 +83,30 @@ module Muzak
       sync!
     end
 
+    # @param songs [Song, Array<Song>] one or more songs to delete from the
+    #   playlist
+    # @return [void]
     def delete(songs)
       [*songs].each { |song| @songs.delete(song) }
 
       sync!
     end
 
+    # Shuffles the internal order of the playlist's songs.
+    # @return [void]
     def shuffle!
       @songs.shuffle!
     end
 
+    # Synchronizes the current instance with its disk representation.
+    # @return [void]
+    # @note You shouldn't need to call this.
     def sync!
       File.open(@filename, "w") { |io| io.write to_hash.to_yaml }
     end
 
+    # Provides a hash representation of the current instance.
+    # @return [Hash{String => Array<Song>}] the instance's state
     def to_hash
       { "songs" => @songs }
     end

data/lib/muzak/plugin.rb

@@ -5,25 +5,32 @@ require_relative "plugin/stub_plugin"
 Dir.glob(File.join(__dir__, "plugin/*")) { |file| require_relative file }
 
 module Muzak
+  # The namespace for muzak plugins.
   module Plugin
     # load plugins included by the user
     Dir.glob(File.join(USER_PLUGIN_DIR, "*")) { |file| require file }
 
+    # @return [Array<Class>] all plugin classes visible under Plugin
     def self.plugin_classes
       constants.map(&Plugin.method(:const_get)).grep(Class)
     end
 
+    # @return [Array<String>] the names of all plugin classes under Plugin
+    # @see StubPlugin.plugin_name
     def self.plugin_names
       plugin_classes.map do |pk|
         pk.plugin_name
       end
     end
 
+    # Instantiates all configured plugins and returns them.
+    # @return [Array<StubPlugin>] the instantiated plugins
     def self.load_plugins!
       pks = Plugin.plugin_classes.select { |pk| Config.plugin? pk.plugin_name }
-      pks.map { |pk| pk.new(self) }
+      pks.map { |pk| pk.new }
     end
 
+    # An association of plugin names to their Class objects.
     PLUGIN_MAP = plugin_names.zip(plugin_classes).to_h.freeze
   end
 end