muzak 0.0.11 → 0.0.12

data/lib/muzak/plugin/stub_plugin.rb

@@ -1,16 +1,16 @@
 module Muzak
   module Plugin
+    # A no-op plugin that all real plugins inherit from.
     class StubPlugin
       include Utils
 
+      # The plugin's human friendly name.
+      # @return [String] the name
       def self.plugin_name
         name.split("::").last.downcase
       end
 
-      attr_reader :instance
-
-      def initialize(instance)
-        @instance = instance
+      def initialize
         debug "loading #{self.class}"
       end
 

data/lib/muzak/song.rb

@@ -1,11 +1,39 @@
 require "taglib"
 
 module Muzak
+  # Represents a single song for muzak.
   class Song
     include Utils
 
-    attr_reader :path, :title, :artist, :album, :year, :track, :genre, :comment, :length
+    # @return [String] the fully-qualified path to the song
+    attr_reader :path
 
+    # @return [String] the title of the song, identified from metadata
+    # @note if metadata is missing, the basename of the path is used instead
+    attr_reader :title
+
+    # @return [String, nil] the artist of the song, identified from metadata
+    attr_reader :artist
+
+    # @return [String, nil] the album of the song, identified from metadata
+    attr_reader :album
+
+    # @return [Integer, 0] the year of the song, identified from metadata
+    attr_reader :year
+
+    # @return [Integer, 0] the track number of the song, identified from metadata
+    attr_reader :track
+
+    # @return [String, nil] the genre of the song, identified from metadata
+    attr_reader :genre
+
+    # @return [String, nil] any comments in the song's metadata
+    attr_reader :comment
+
+    # @return [Integer] the length of the song, in seconds
+    attr_reader :length
+
+    # @param path [String] the path of the song to load
     def initialize(path)
       @path = path
 
@@ -26,6 +54,9 @@ module Muzak
       @track ||= 0 # we'll need to sort by track number
     end
 
+    # @return [String] A best guess path for the song's cover art
+    # @example
+    #   song.best_guess_album_art # => "/path/to/song/directory/cover.jpg"
     def best_guess_album_art
       album_dir = File.dirname(path)
 
@@ -33,6 +64,10 @@ module Muzak
       File.join(album_dir, art) unless art.nil?
     end
 
+    # @return [String] the "full" title of the song, including artist and album
+    #   if available.
+    # @example
+    #   song.full_title # => "Song by Artist on Album"
     def full_title
       full = title.dup
       full << " by #{artist}" if artist

data/lib/muzak/utils.rb

@@ -1,29 +1,52 @@
 module Muzak
+  # A collection of convenience utilities for use throughout muzak.
   module Utils
+    # Convert the given command into a method (kebab to camel case).
+    # @param cmd [String] the command to convert
+    # @return [String] the method corresponding to the command
+    # @example
+    #   resolve_command "do-something" # => "do_something"
     def self.resolve_command(cmd)
       cmd.tr "-", "_"
     end
 
+    # Convert the given method into a command (camel to kebab case).
+    # @param meth [String, Symbol] the method to convert
+    # @return [String] the command corresponding to the method
+    # @example
+    #   resolve_method "do_something" # => "do-something"
     def self.resolve_method(meth)
       meth.to_s.tr "_", "-"
     end
 
+    # Tests whether the given filename is likely to be music.
+    # @param filename [String] the filename to test
+    # @return [Boolean] whether or not the file is a music file
     def music?(filename)
       [".mp3", ".flac", ".m4a", ".wav", ".ogg", ".oga", ".opus"].include?(File.extname(filename.downcase))
     end
 
+    # Tests whether the given filename is likely to be album art.
+    # @param filename [String] the filename to test
+    # @return [Boolean] whether or not the file is an art file
     def album_art?(filename)
       File.basename(filename) =~ /(cover)|(folder).(jpg)|(png)/i
     end
 
+    # @return [Boolean] whether or not muzak is running in debug mode
     def debug?
       Config.debug
     end
 
+    # @return [Boolean] whether or not muzak is running in verbose mode
     def verbose?
       Config.verbose
     end
 
+    # Formats a string with ANSI colors.
+    # @param color [Symbol] the color to use on the string
+    # @param str [String] the string to format
+    # @return [String] the color-formatted string
     def pretty(color = :none, str)
       colors = {
         none: 0,
@@ -36,39 +59,68 @@ module Muzak
       "\e[#{colors[color]}m#{str}\e[0m"
     end
 
+    # Outputs a boxed message and arguments.
+    # @param box [String] the string to box
+    # @param args [Array<String>] the trailing strings to print
+    # @return [void]
     def output(box, *args)
       msg = args.join(" ")
       puts "[#{box}] #{msg}"
     end
 
+    # Outputs a boxed informational message.
+    # @param args [Array<String>] the message(s)
+    # @return [void]
     def info(*args)
       output pretty(:green, "info"), args
     end
 
+    # Outputs a boxed warning message.
+    # @param args [Array<String>] the message(s)
+    # @return [void]
     def warn(*args)
       output pretty(:yellow, "warn"), args
     end
 
+    # Outputs a boxed error message.
+    # @param args [Array<String>] the message(s)
+    # @return [void]
     def error(*args)
       output pretty(:red, "error"), "[#{self.class.name}]", args
     end
 
+    # Outputs a boxed debugging message.
+    # @param args [Array<String>] the message(s)
+    # @return [void]
     def debug(*args)
       return unless debug?
 
       output pretty(:yellow, "debug"), "[#{self.class.name}]", args
     end
 
+    # Outputs a boxed verbose message.
+    # @param args [Array<String>] the message(s)
+    # @return [void]
     def verbose(*args)
       return unless verbose?
 
       output pretty(:blue, "verbose"), args
     end
 
+    # Outputs a boxed warning message unless the arity of the given arguments
+    #   equals the expected arity.
+    # @param args [Array<String>] the arguments
+    # @param arity [Integer] the expected arity
+    # @return [void]
     def warn_arity(args, arity)
       warn "expected #{arity} arguments, got #{args.length}" unless args.length == arity
     end
 
+    # Outputs a boxed failure message unless the arity of the given arguments
+    #   equals the expected arity.
+    # @param args [Array<String>] the arguments
+    # @param arity [Integer] the expected arity
+    # @return [void]
     def fail_arity(args, arity)
       error "needed #{arity} arguments, got #{args.length}" unless args.length == arity
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: muzak
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.0.12
 platform: ruby
 authors:
 - William Woodruff
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-20 00:00:00.000000000 Z
+date: 2016-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: taglib-ruby
@@ -34,6 +34,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - LICENSE
 - README.md
 - bin/muzak
@@ -57,13 +58,10 @@ files:
 - lib/muzak/player/stub_player.rb
 - lib/muzak/playlist.rb
 - lib/muzak/plugin.rb
-- lib/muzak/plugin/cava.rb
-- lib/muzak/plugin/notify.rb
-- lib/muzak/plugin/scrobble.rb
 - lib/muzak/plugin/stub_plugin.rb
 - lib/muzak/song.rb
 - lib/muzak/utils.rb
-homepage: https://github.com/woodruffw/muzak
+homepage: https://github.com/muzak-project/muzak
 licenses:
 - MIT
 metadata: {}

data/lib/muzak/plugin/cava.rb

@@ -1,44 +0,0 @@
-require "shellwords"
-
-module Muzak
-  module Plugin
-    class Cava < StubPlugin
-      include Utils
-
-      def initialize(instance)
-        super
-        @term_args = Shellwords.split Config.plugin_cava
-        @pid = nil
-      end
-
-      def player_activated
-        start_cava! unless cava_running?
-      end
-
-      def player_deactivated
-        stop_cava! if cava_running?
-      end
-
-      private
-
-      def cava_running?
-        begin
-          !!@pid && Process.waitpid(@pid, Process::WNOHANG).nil?
-        rescue Errno::ECHILD
-          false
-        end
-      end
-
-      def start_cava!
-        args = [*@term_args, "-e", "cava"]
-        @pid = Process.spawn(*args)
-      end
-
-      def stop_cava!
-        Process.kill :TERM, @pid
-        Process.wait @pid
-        @pid = nil
-      end
-    end
-  end
-end

data/lib/muzak/plugin/notify.rb

@@ -1,16 +0,0 @@
-module Muzak
-  module Plugin
-    class Notify < StubPlugin
-      def song_loaded(song)
-        notify song.full_title
-      end
-
-      private
-
-      def notify(msg)
-        pid = Process.spawn("notify-send", "muzak", msg)
-        Process.detach(pid)
-      end
-    end
-  end
-end

data/lib/muzak/plugin/scrobble.rb

@@ -1,81 +0,0 @@
-require "net/http"
-require "digest"
-
-module Muzak
-  module Plugin
-    class Scrobble < StubPlugin
-      include Utils
-
-      def initialize(instance)
-        super
-        @username, @password_hash = Config.plugin_scrobble.split(":")
-      end
-
-      def song_loaded(song)
-        if song.title.nil? || song.artist.nil?
-          debug "cowardly refusing to scrobble a song ('#{song.path}') with missing metadata"
-          return
-        end
-
-        scrobble song
-      end
-
-      private
-
-      def scrobble(song)
-        if @username.nil? || @password_hash.nil?
-          error "missing username or password"
-          return
-        end
-
-        handshake_endpoint = "http://post.audioscrobbler.com/"
-        handshake_params = {
-          "hs" => true,
-          "p" => 1.1,
-          "c" => "lsd",
-          "v" => "1.0.4",
-          "u" => @username
-        }
-
-        uri = URI(handshake_endpoint)
-        uri.query = URI.encode_www_form(handshake_params)
-
-        resp = Net::HTTP.get_response(uri)
-
-        status, token, post_url, int = resp.body.split("\n")
-
-        unless status =~ /UP(TO)?DATE/
-          error "bad handshake, got '#{status}'"
-          return
-        end
-
-        session_token = Digest::MD5.hexdigest(@password_hash + token)
-
-        request_params = {
-          "u" => @username,
-          "s" => session_token,
-          "a[0]" => song.artist,
-          "t[0]" => song.title,
-          "b[0]" => song.album,
-          "m[0]" => "", # we don't know the MBID, so send an empty one
-          "l[0]" => song.length,
-          "i[0]" => Time.now.gmtime.strftime("%Y-%m-%d %H:%M:%S")
-        }
-
-        uri = URI(URI.encode(post_url))
-        # uri.query = URI.encode_www_form(request_params)
-
-        resp = Net::HTTP.post_form(uri, request_params)
-
-        status, int = resp.body.split("\n")
-
-        case status
-        when "OK"
-          debug "scrobble of '#{song.title}' successful"
-        else
-          debug "scrobble of '#{song.title}' failed, got '#{status}'"
-        end
-      end
-    end
-  end
-end