about summary refs log tree commit homepage
path: root/lib/dtas
diff options
context:
space:
mode:
authorEric Wong <e@80x24.org>2015-01-20 01:33:38 +0000
committerEric Wong <e@80x24.org>2015-01-20 02:08:44 +0000
commit65bb4baf0e479ff7cfbf0a8422824834c9f06ab1 (patch)
tree9a0bc4866c5d9e3ad5a896ddb814542dd29f902d /lib/dtas
parent51e6240767b394e255d05a0f712a1da853485e82 (diff)
downloaddtas-65bb4baf0e479ff7cfbf0a8422824834c9f06ab1.tar.gz
Hopefully this makes the code less daunting to newcomers
Diffstat (limited to 'lib/dtas')
-rw-r--r--lib/dtas/buffer.rb1
-rw-r--r--lib/dtas/buffer/read_write.rb2
-rw-r--r--lib/dtas/buffer/splice.rb1
-rw-r--r--lib/dtas/command.rb2
-rw-r--r--lib/dtas/cue_index.rb2
-rw-r--r--lib/dtas/format.rb3
-rw-r--r--lib/dtas/parse_time.rb2
-rw-r--r--lib/dtas/partstats.rb3
-rw-r--r--lib/dtas/pipe.rb1
-rw-r--r--lib/dtas/player.rb1
-rw-r--r--lib/dtas/player/client_handler.rb2
-rw-r--r--lib/dtas/process.rb1
-rw-r--r--lib/dtas/replaygain.rb4
-rw-r--r--lib/dtas/serialize.rb2
-rw-r--r--lib/dtas/sigevent/efd.rb3
-rw-r--r--lib/dtas/sigevent/pipe.rb3
-rw-r--r--lib/dtas/sink.rb2
-rw-r--r--lib/dtas/source/common.rb1
-rw-r--r--lib/dtas/splitfx.rb6
-rw-r--r--lib/dtas/state_file.rb2
-rw-r--r--lib/dtas/tracklist.rb1
-rw-r--r--lib/dtas/trimfx.rb2
-rw-r--r--lib/dtas/unix_accepted.rb1
-rw-r--r--lib/dtas/unix_client.rb1
-rw-r--r--lib/dtas/writable_iter.rb1
25 files changed, 42 insertions, 8 deletions
diff --git a/lib/dtas/buffer.rb b/lib/dtas/buffer.rb
index 3259ca0..b03ed8a 100644
--- a/lib/dtas/buffer.rb
+++ b/lib/dtas/buffer.rb
@@ -3,6 +3,7 @@
 require 'io/wait'
 require_relative '../dtas'
 
+# pipe buffer management for -player
 class DTAS::Buffer # :nodoc:
   begin
     raise LoadError, "no splice with _DTAS_POSIX" if ENV["_DTAS_POSIX"]
diff --git a/lib/dtas/buffer/read_write.rb b/lib/dtas/buffer/read_write.rb
index 56eb8a1..a27b823 100644
--- a/lib/dtas/buffer/read_write.rb
+++ b/lib/dtas/buffer/read_write.rb
@@ -4,6 +4,8 @@ require 'io/nonblock'
 require_relative '../../dtas'
 require_relative '../pipe'
 
+# compatibility code for systems lacking "splice" support via the
+# "io-splice" RubyGem.  Used only by -player
 module DTAS::Buffer::ReadWrite # :nodoc:
   MAX_AT_ONCE = 512 # min PIPE_BUF value in POSIX
   attr_accessor :buffer_size
diff --git a/lib/dtas/buffer/splice.rb b/lib/dtas/buffer/splice.rb
index 3f2484b..c83b87b 100644
--- a/lib/dtas/buffer/splice.rb
+++ b/lib/dtas/buffer/splice.rb
@@ -5,6 +5,7 @@ require 'io/splice'
 require_relative '../../dtas'
 require_relative '../pipe'
 
+# Used by -player on Linux systems with the "io-splice" RubyGem installed
 module DTAS::Buffer::Splice # :nodoc:
   MAX_AT_ONCE = 4096 # page size in Linux
   MAX_AT_ONCE_1 = 65536
diff --git a/lib/dtas/command.rb b/lib/dtas/command.rb
index 0b5f7ec..3f27c61 100644
--- a/lib/dtas/command.rb
+++ b/lib/dtas/command.rb
@@ -1,9 +1,9 @@
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
-# common code for wrapping SoX/ecasound/... commands
 require_relative 'serialize'
 require 'shellwords'
 
+# common code for wrapping SoX/ecasound/... commands
 module DTAS::Command # :nodoc:
   include DTAS::Serialize
   attr_reader :pid
diff --git a/lib/dtas/cue_index.rb b/lib/dtas/cue_index.rb
index 83f5bed..b23dae3 100644
--- a/lib/dtas/cue_index.rb
+++ b/lib/dtas/cue_index.rb
@@ -1,6 +1,8 @@
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
 require_relative '../dtas'
+
+# embedded CUE sheet representation for -player
 class DTAS::CueIndex
   attr_reader :offset
   attr_reader :index
diff --git a/lib/dtas/format.rb b/lib/dtas/format.rb
index bc58ab1..a76b893 100644
--- a/lib/dtas/format.rb
+++ b/lib/dtas/format.rb
@@ -1,10 +1,11 @@
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
-# class represents an audio format (type/bits/channels/sample rate/...)
 require_relative '../dtas'
 require_relative 'process'
 require_relative 'serialize'
 
+# class represents an audio format (type/bits/channels/sample rate/...)
+# used throughout dtas
 class DTAS::Format # :nodoc:
   include DTAS::Process
   include DTAS::Serialize
diff --git a/lib/dtas/parse_time.rb b/lib/dtas/parse_time.rb
index 95ffd18..7dd41c6 100644
--- a/lib/dtas/parse_time.rb
+++ b/lib/dtas/parse_time.rb
@@ -1,7 +1,9 @@
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
 require_relative '../dtas'
+
 module DTAS::ParseTime
+  # convert a string time to seconds, returning a Flot or Integer
   def parse_time(time)
     case time
     when /\A\d+\z/
diff --git a/lib/dtas/partstats.rb b/lib/dtas/partstats.rb
index b669d33..9d3312b 100644
--- a/lib/dtas/partstats.rb
+++ b/lib/dtas/partstats.rb
@@ -1,12 +1,13 @@
 # -*- encoding: binary -*-
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
-# Unlike the stuff for dtas-player, dtas-partstats is fairly tied to sox
 require_relative '../dtas'
 require_relative 'xs'
 require_relative 'process'
 require_relative 'sigevent'
 
+# backend for the dtas-partstats(1) command
+# Unlike the stuff for dtas-player, dtas-partstats is fairly tied to sox
 class DTAS::PartStats
   CMD = 'sox "$INFILE" -n $TRIMFX $SOXFX stats $STATSOPTS'
   include DTAS::Process
diff --git a/lib/dtas/pipe.rb b/lib/dtas/pipe.rb
index 03c13af..22ab85e 100644
--- a/lib/dtas/pipe.rb
+++ b/lib/dtas/pipe.rb
@@ -7,6 +7,7 @@ end
 require_relative '../dtas'
 require_relative 'writable_iter'
 
+# pipe wrapper for -player sinks
 class DTAS::Pipe < IO # :nodoc:
   include DTAS::WritableIter
   attr_accessor :sink
diff --git a/lib/dtas/player.rb b/lib/dtas/player.rb
index d0cec6b..d63bc8a 100644
--- a/lib/dtas/player.rb
+++ b/lib/dtas/player.rb
@@ -18,6 +18,7 @@ require_relative 'rg_state'
 require_relative 'state_file'
 require_relative 'tracklist'
 
+# the core of dtas-player(1)
 class DTAS::Player # :nodoc:
   require_relative 'player/client_handler'
   include DTAS::XS
diff --git a/lib/dtas/player/client_handler.rb b/lib/dtas/player/client_handler.rb
index cd70f37..68f1d80 100644
--- a/lib/dtas/player/client_handler.rb
+++ b/lib/dtas/player/client_handler.rb
@@ -1,6 +1,8 @@
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
 require_relative '../xs'
+
+# client protocol handling for -player
 module DTAS::Player::ClientHandler # :nodoc:
   include DTAS::XS
 
diff --git a/lib/dtas/process.rb b/lib/dtas/process.rb
index f71838b..ab4b2d5 100644
--- a/lib/dtas/process.rb
+++ b/lib/dtas/process.rb
@@ -4,6 +4,7 @@ require 'io/wait'
 require_relative '../dtas'
 require_relative 'xs'
 
+# process management helpers
 module DTAS::Process # :nodoc:
   PIDS = {}
   include DTAS::XS
diff --git a/lib/dtas/replaygain.rb b/lib/dtas/replaygain.rb
index f8d0079..cc96d54 100644
--- a/lib/dtas/replaygain.rb
+++ b/lib/dtas/replaygain.rb
@@ -1,7 +1,7 @@
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
-#
-# Represents ReplayGain metadata for a DTAS::Source
+
+# Represents ReplayGain metadata for a DTAS::Source, only used by -player
 # cleanup/validate values to prevent malicious files from making us
 # run arbitrary commands
 # *_peak values are 0..inf (1.0 being full scale, but >1 is possible
diff --git a/lib/dtas/serialize.rb b/lib/dtas/serialize.rb
index dc956dc..1a7d477 100644
--- a/lib/dtas/serialize.rb
+++ b/lib/dtas/serialize.rb
@@ -1,5 +1,7 @@
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+
+# used to serialize player state to the state file
 module DTAS::Serialize # :nodoc:
   def ivars_to_hash(ivars, rv = {})
     ivars.each { |k| rv[k] = instance_variable_get("@#{k}") }
diff --git a/lib/dtas/sigevent/efd.rb b/lib/dtas/sigevent/efd.rb
index dc526f2..26c8025 100644
--- a/lib/dtas/sigevent/efd.rb
+++ b/lib/dtas/sigevent/efd.rb
@@ -1,5 +1,8 @@
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+
+# used in various places for safe wakeups from IO.select via signals
+# This requires a modern Linux system and the "sleepy_penguin" RubyGem
 class DTAS::Sigevent < SleepyPenguin::EventFD # :nodoc:
   def self.new
     super(0, :CLOEXEC)
diff --git a/lib/dtas/sigevent/pipe.rb b/lib/dtas/sigevent/pipe.rb
index f510385..4f42909 100644
--- a/lib/dtas/sigevent/pipe.rb
+++ b/lib/dtas/sigevent/pipe.rb
@@ -1,5 +1,8 @@
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+
+# used in various places for safe wakeups from IO.select via signals
+# A fallback for non-Linux systems lacking the "sleepy_penguin" RubyGem
 class DTAS::Sigevent # :nodoc:
   attr_reader :to_io
 
diff --git a/lib/dtas/sink.rb b/lib/dtas/sink.rb
index efd6705..70d6861 100644
--- a/lib/dtas/sink.rb
+++ b/lib/dtas/sink.rb
@@ -8,7 +8,7 @@ require_relative 'command'
 require_relative 'format'
 require_relative 'serialize'
 
-# this is a sink (endpoint, audio enters but never leaves)
+# this is a sink (endpoint, audio enters but never leaves), used by -player
 class DTAS::Sink # :nodoc:
   attr_accessor :prio    # any Integer
   attr_accessor :active  # boolean
diff --git a/lib/dtas/source/common.rb b/lib/dtas/source/common.rb
index 5bf5ad7..2fdcea8 100644
--- a/lib/dtas/source/common.rb
+++ b/lib/dtas/source/common.rb
@@ -5,6 +5,7 @@ module DTAS::Source::Common # :nodoc:
   attr_reader :dst
   attr_accessor :requeued
 
+  # buf - a DTAS::Buffer object (pipe)
   def dst_assoc(buf)
     @dst = buf
     @dst_zero_byte = buf.bytes_xfer + buf.inflight
diff --git a/lib/dtas/splitfx.rb b/lib/dtas/splitfx.rb
index d3d3efb..022fbfe 100644
--- a/lib/dtas/splitfx.rb
+++ b/lib/dtas/splitfx.rb
@@ -1,12 +1,14 @@
 # Copyright (C) 2013-2015 all contributors <dtas-all@nongnu.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
-# Unlike the stuff for dtas-player, dtas-splitfx is fairly tied to sox
-# (but we may still pipe to ecasound or anything else)
 require_relative '../dtas'
 require_relative 'format'
 require_relative 'process'
 require_relative 'xs'
 require 'tempfile'
+
+# The backend for dtas-splitfx(1) command, but also supported by dtas-player
+# Unlike the stuff for dtas-player, dtas-splitfx is fairly tied to sox
+# (but we may still pipe to ecasound or anything else)
 class DTAS::SplitFX # :nodoc:
   CMD = 'sox "$INFILE" $COMMENTS $OUTFMT "$TRACKNUMBER.$SUFFIX" '\
         '$TRIMFX $FX $RATEFX $DITHERFX'
diff --git a/lib/dtas/state_file.rb b/lib/dtas/state_file.rb
index c671764..26f588f 100644
--- a/lib/dtas/state_file.rb
+++ b/lib/dtas/state_file.rb
@@ -2,6 +2,8 @@
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
 require 'yaml'
 require 'tempfile'
+
+# state file preserves state across restarts of dtas-player
 class DTAS::StateFile # :nodoc:
   attr_reader :path
 
diff --git a/lib/dtas/tracklist.rb b/lib/dtas/tracklist.rb
index e3777ec..c008204 100644
--- a/lib/dtas/tracklist.rb
+++ b/lib/dtas/tracklist.rb
@@ -3,6 +3,7 @@
 require_relative '../dtas'
 require_relative 'serialize'
 
+# the a tracklist object for -player
 # this is inspired by the MPRIS 2.0 TrackList spec
 class DTAS::Tracklist # :nodoc:
   include DTAS::Serialize
diff --git a/lib/dtas/trimfx.rb b/lib/dtas/trimfx.rb
index 3e3ccc5..33b21ca 100644
--- a/lib/dtas/trimfx.rb
+++ b/lib/dtas/trimfx.rb
@@ -5,6 +5,8 @@ require_relative 'parse_time'
 require_relative 'format'
 require 'shellwords'
 
+# this will represent a trim section inside -splitfx for applying
+# effects to only a part of the output
 class DTAS::TrimFX
   include DTAS::ParseTime
 
diff --git a/lib/dtas/unix_accepted.rb b/lib/dtas/unix_accepted.rb
index a590bbe..c08d431 100644
--- a/lib/dtas/unix_accepted.rb
+++ b/lib/dtas/unix_accepted.rb
@@ -3,6 +3,7 @@
 require 'socket'
 require 'io/wait'
 
+# an accepted (client) socket in dtas-player server
 class DTAS::UNIXAccepted # :nodoc:
   attr_reader :to_io
 
diff --git a/lib/dtas/unix_client.rb b/lib/dtas/unix_client.rb
index 6724501..fbb1510 100644
--- a/lib/dtas/unix_client.rb
+++ b/lib/dtas/unix_client.rb
@@ -6,6 +6,7 @@ require 'socket'
 require 'io/wait'
 require 'shellwords'
 
+# a socket connection used by dtas-player clients (e.g. dtas-ctl)
 class DTAS::UNIXClient # :nodoc:
   attr_reader :to_io
 
diff --git a/lib/dtas/writable_iter.rb b/lib/dtas/writable_iter.rb
index 7f4d00a..9ddcb30 100644
--- a/lib/dtas/writable_iter.rb
+++ b/lib/dtas/writable_iter.rb
@@ -2,6 +2,7 @@
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
 require_relative '../dtas'
 
+# used to manage writable state for -player pipes
 module DTAS::WritableIter # :nodoc:
   attr_accessor :on_writable
   # we may use the ready_write flag to avoid an extra IO.select