From 65bb4baf0e479ff7cfbf0a8422824834c9f06ab1 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Tue, 20 Jan 2015 01:33:38 +0000 Subject: doc: describe most classes a bit Hopefully this makes the code less daunting to newcomers --- lib/dtas/buffer.rb | 1 + lib/dtas/buffer/read_write.rb | 2 ++ lib/dtas/buffer/splice.rb | 1 + lib/dtas/command.rb | 2 +- lib/dtas/cue_index.rb | 2 ++ lib/dtas/format.rb | 3 ++- lib/dtas/parse_time.rb | 2 ++ lib/dtas/partstats.rb | 3 ++- lib/dtas/pipe.rb | 1 + lib/dtas/player.rb | 1 + lib/dtas/player/client_handler.rb | 2 ++ lib/dtas/process.rb | 1 + lib/dtas/replaygain.rb | 4 ++-- lib/dtas/serialize.rb | 2 ++ lib/dtas/sigevent/efd.rb | 3 +++ lib/dtas/sigevent/pipe.rb | 3 +++ lib/dtas/sink.rb | 2 +- lib/dtas/source/common.rb | 1 + lib/dtas/splitfx.rb | 6 ++++-- lib/dtas/state_file.rb | 2 ++ lib/dtas/tracklist.rb | 1 + lib/dtas/trimfx.rb | 2 ++ lib/dtas/unix_accepted.rb | 1 + lib/dtas/unix_client.rb | 1 + lib/dtas/writable_iter.rb | 1 + 25 files changed, 42 insertions(+), 8 deletions(-) (limited to 'lib') 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 -- cgit v1.2.3-24-ge0c7