muzak 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3bbc4c6526a315ebd1d0c6cb7dd3edf77809d7ae
-  data.tar.gz: 21ac18f09286fd7ba229081247d17ef7311fd881
+  metadata.gz: 38d02c02227daac78a8a7d7b7aa219c99bec2843
+  data.tar.gz: 993d13e33b8484b6fb8053231e2015c0268c5d47
 SHA512:
-  metadata.gz: e12366f7b35680c4c46dbcb2067bc1a65e4bf7472b160cc693114d0be26e9e68a4c874d1b1c6ae29ec920d2df6549c7650841bf04e33a8ce37ff1355c8f03a2d
-  data.tar.gz: 28b3ab33bd145f695c2c433e3120da0903237fe8c76607cf543eebb2570f88cac1e325d7e146d3437a17c8d17fc55754c38da58b7bdda841d5c16a63072cd55d
+  metadata.gz: 3394c2f9f00ffbb1fb3ecaeca71a29544690bbb743dacd89bbf7d3faca7329623e4cf7574c42cbf68e1970dd9a77f03971a0429383bb1d4676387b719f333b9a
+  data.tar.gz: e7872463a13c5997c9521e1bf65e3a456a64678309836d3834ac47f3c57819cd60c9be69de7c858af43ba25fffd187714545dcfdfaf1d9862d51aeea5bf3ab97

data/.yardopts

@@ -1 +1 @@
---tag command:"muzak command" --tag cmdexample:"example invocation" --no-private --markup-provider=redcarpet --markup=markdown - README.md COMMANDS.md LICENSE
+--tag command:"muzak command" --tag cmdexample:"example invocation" --no-private --markup-provider=redcarpet --markup=markdown - *.md LICENSE

data/CONFIGURATION.md

@@ -0,0 +1,213 @@
+Muzak configuration
+===================
+
+This is the user-facing documentation for muzak's configuration.
+
+For the developer documentation, see {Muzak::Config}.
+
+## General behavior
+
+All of muzak's configuration is kept in {Muzak::Config}, which is read
+during load-time (i.e., during `require`) from {Muzak::CONFIG_FILE}, which
+is YAML-formatted.
+
+Muzak loads configuration keys just like commands, translating them from
+`kebab-case` to `snake_case`. For example, take the following configuration:
+
+```yaml
+---
+debug: true
+verbose: true
+music: "/home/william/mnt/fortuna/music/"
+player: mpv
+art-geometry: 300x300
+jukebox-size: 100
+deep-index: true
+```
+
+This is exposed in `Muzak::Config` as follows:
+
+```ruby
+Muzak::Config.debug # => true
+Muzak::Config.verbose # => true
+Muzak::Config.music # => "/home/william/mnt/fortuna/music/"
+Muzak::Config.player # => "mpv"
+Muzak::Config.art_geometry # => "300x300"
+Muzak::Config.jukebox_size # => 100
+Muzak::Config.deep_index # => true
+```
+
+Since {Muzak::Config} is populated whenever `muzak` is loaded via `require`,
+it can be used within both scripts and clients. As such, it should be preferred
+over custom configuration solutions for external programs that interact
+primarily with muzak.
+
+{Muzak::Config} resolves undefined keys to `false`, allowing a pattern like
+this:
+
+```ruby
+something_special Config.special_key if Config.special_key
+```
+
+## A note on plugin configuration
+
+Muzak loads a plugin if and only if `plugin-$name` is present in the
+configuration, where `$name` is the lowercased class name of the plugin
+(see {Muzak::Plugin::StubPlugin.plugin_name} and {Muzak::Config.plugin?}).
+
+For example, to enable the made-up "foo" plugin, your configuration should
+include something like this.
+
+```
+plugin-foo:
+  foo-option-1: bar
+  foo-option-2: baz
+```
+
+Plugins can, of course, access their configuration through {Muzak::Config}:
+
+```
+Muzak::Config.plugin_foo["foo-option-1"] # => "bar"
+```
+
+## Core configuration
+
+These are the configuration keys observed by muzak's "core," particularly
+{Muzak::Instance} any everything it controls.
+
+In no particular order:
+
+### `debug`
+
+*Optional.*
+
+*Default:* `false`
+
+If `debug: true` is set in the configuration file, then muzak operates in
+debugging mode. This includes printing debug messages and not forking `muzakd`
+into the background.
+
+### `verbose`
+
+*Optional.*
+
+*Default:* `true`
+
+If `verbose: true` is set in the configuration file, then muzak operates in
+verbose mode. This includes printing informational messages and not forking
+`muzakd` into the background.
+
+### `music`
+
+*Mandatory.*
+
+*Default:* `~/music`
+
+`music: <directory>` should be set to the directory of the music library.
+Muzak uses this key to point the indexer at the correct directory.
+
+### `player`
+
+*Mandatory.*
+
+*Default:* `mpv`
+
+`player: <player>` should be set to the short name of the user's music player.
+Muzak uses this key to find the correct {Muzak::Player} underclass to
+initialize and control.
+
+The short names of supported players can be found in
+{Muzak::Player::PLAYER_MAP}.
+
+### `index-autobuild`
+
+*Optional.*
+
+*Default:* `86400`
+
+`index-autobuild: <span>` should be set to maximum number of seconds before
+an index is considered outdated (based on its {Muzak::Index#timestamp} field).
+
+When an outdated index is loaded and this key is set, muzak will automatically
+rebuild the index.
+
+**Note:** This is *not* an interval - the outdated index is only rebuilt
+when a new {Muzak::Instance} or {Muzak::Index} is instantiated.
+
+### `deep-index`
+
+*Optional.*
+
+*Default:* `false`
+
+If `deep-index: true` is set in the configuration file, then muzak will
+build a "deep" index. This involves opening each music file and reading metadata
+from it, which can take substantially longer than just a shallow filesystem
+index.
+
+This primary benefit of this is caching - having all the song metadata in the
+index allows muzak to make fewer disk accesses, which may be expensive over
+a remote disk.
+
+### `jukebox-size`
+
+*Mandatory.*
+
+*Default:* `100`
+
+`jukebox-size: <size>` should be set to the number of random songs to enqueue
+by default with the `jukebox` size.
+
+### `art-geometry`
+
+*Optional.*
+
+*No default.*
+
+`art-geometry: <geometry>` should be set to the desired size of displayed
+album art, in "WxH" format. If not set, album art will be displayed at
+any size the player pleases.
+
+It's entirely up to the user's player to obey this value.
+
+### `autoplay`
+
+*Optional.*
+
+*No default.*
+
+`autoplay: <playlist>` should be set to a playlist that the user wishes to
+automatically start when muzak starts. If not set, no playlist is automatically
+played.
+
+## Daemon/client configuration
+
+These are configuration keys observed by muzak's interface(s).
+
+### `daemon-port`
+
+*Optional.*
+
+*Default:* `2669`
+
+`daemon-port: <port>` should be set to a valid port number for `muzakd` to
+listen on.
+
+### `daemon-host`
+
+*Optional.*
+
+*Default:* `localhost`
+
+`daemon-host: <hostname>` should be set to the hostname for `muzakd` to
+listen on.
+
+### `dmenu-exec`
+
+*Optional.*
+
+*No default.*
+
+`dmenu-exec: <command args...>` can be used to alter `muzak-dmenu`'s
+invocation of `dmenu`. It can also be used to substitute a dmenu-compatible
+prompt like `rofi -dmenu`.

data/README.md

@@ -1,10 +1,12 @@
 muzak
 =====
 
+[![Gem Version](https://badge.fury.io/rb/muzak.svg)](https://badge.fury.io/rb/muzak)
+
 muzak is an attempt at a metamusic player.
 
 It indexes a filesystem tree, providing metadata to a user's preferred media
-player. It also provides a pseudo-shell for controlling the indexed files
+player. It also provides a command API for controlling the indexed files
 and the state of the player.
 
 ### Screenshot
@@ -24,7 +26,10 @@ $ ruby -Ilib bin/muzak-cmd enqueue-artist "The Beatles"
 
 API documentation can be found on [RubyDoc](http://www.rubydoc.info/gems/muzak/).
 
-Documentation for user commands can be found under [COMMANDS.md](./COMMANDS.md),
+User documentation for commands can be found under [COMMANDS](COMMANDS.md),
+as well as on RubyDoc.
+
+User documentation for configuration can be found under [CONFIGURATION](CONFIGURATION.md),
 as well as on RubyDoc.
 
 ### TODO

data/lib/muzak/config.rb

@@ -8,6 +8,7 @@ module Muzak
   # @example
   #   # corresponds to `art-geometry: 300x300` in configuration
   #   Config.art_geometry # => "300x300"
+  # @see file:CONFIGURATION.md User Configuration
   class Config
     if File.exist?(CONFIG_FILE)
       @config = YAML::load_file(CONFIG_FILE)
@@ -46,6 +47,8 @@ module Muzak
       false
     end
 
+    # Synchronizes the in-memory configuration with {CONFIG_FILE}.
+    # @return [void]
     def self.sync!
       File.open(CONFIG_FILE, "w") { |io| io.write @config.to_yaml }
     end

data/lib/muzak/const.rb

@@ -1,6 +1,6 @@
 module Muzak
   # Muzak's current version
-  VERSION = "0.1.4".freeze
+  VERSION = "0.1.5".freeze
 
   # The root directory for all user configuration, data, etc
   CONFIG_DIR = File.expand_path("~/.config/muzak").freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: muzak
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - William Woodruff
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-03 00:00:00.000000000 Z
+date: 2017-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: taglib-ruby
@@ -35,6 +35,7 @@ extra_rdoc_files: []
 files:
 - ".yardopts"
 - COMMANDS.md
+- CONFIGURATION.md
 - LICENSE
 - README.md
 - bin/muzak-cmd