dtas 0.0.0

data/Documentation/dtas-sinkedit.txt

@@ -0,0 +1,41 @@
+% dtas-sinkedit(1) dtas user manual
+%
+
+# NAME
+
+dtas-sinkedit - edit the command and environment of a sink
+
+# SYNOPSYS
+
+dtas-sinkedit SINKNAME
+
+# DESCRIPTION
+
+dtas-sinkedit spawns an editor to allow editing of a sink as a YAML file.
+See dtas-player_protocol(7) for details on SINKARGS.
+
+# EXAMPLES
+
+To get a list of existing sink names
+
+	$ dtas-ctl ls
+
+Invoking dtas-sinkedit will spawn your favorite text editor on a
+given SINKNAME:
+
+	$ dtas-sinkedit SINKNAME
+
+If SINKNAME was not listed, it will be created (in an inactive state).
+Successfully exiting your text editor will send the changes to the
+running dtas-player.
+
+# ENVIRONMENT
+
+VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset.
+
+DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
+This defaults to ~/.dtas/player.sock
+
+# SEE ALSO
+
+dtas-player(1), dtas-player_protocol(7), dtas-ctl(1)

data/Documentation/dtas-sourceedit.txt

@@ -0,0 +1,33 @@
+% dtas-sourceedit(1) dtas user manual
+%
+
+# NAME
+
+dtas-sourceedit - edit the command and environment of the decoder
+
+# SYNOPSYS
+
+dtas-sourceedit
+
+# DESCRIPTION
+
+dtas-sourceedit spawns an editor to allow editing of a sink as a YAML file.
+See dtas-player_protocol(7) for details on SINKARGS.
+
+# EXAMPLES
+
+Invoking dtas-sourceedit will spawn your favorite text editor on a
+given SINKNAME:
+
+	$ dtas-sourceedit
+
+# ENVIRONMENT
+
+VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset.
+
+DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
+This defaults to ~/.dtas/player.sock
+
+# SEE ALSO
+
+dtas-player(1), dtas-player_protocol(7), dtas-ctl(1)

data/Documentation/dtas-xdelay.txt

@@ -0,0 +1,57 @@
+% dtas-xdelay(1) dtas user manual
+%
+
+# NAME
+
+dtas-xdelay - play audio with a crossover delay
+
+# SYNOPSYS
+
+dtas-xdelay [OPTIONS] INPUT1 INPUT2 DELAY
+
+# DESCRIPTION
+
+dtas-xdelay will delay an audio band by a given delay (in seconds or
+fractions thereof).  This can be useful for tuning a sub/sat speaker
+system.  It is intended for use a dtas-player sink command as displayed
+in the synopsis.
+
+The INPUT arguments (/dev/fd/lo and /dev/fd/hi) are automatically
+changed by dtas-player to match the given file descriptors of the pipes.
+
+Both descriptors receive the same audio data, but will be split using a
+Linkwitz-Riley crossover.  The high-band (second argument) will be
+delayed by default.
+
+# EXAMPLE
+
+To set this via dtas-player to delay the high frequencies by 20ms.
+
+	dtas-ctl sink ed SINKNAME \
+	   command='dtas-xdelay /dev/fd/lo /dev/fd/hi 0.020'
+
+# OPTIONS
+
+-x, \--crossover-frequency FREQUENCY
+:   Frequency at which to set the crossover.  This defaults to 80 (Hz).
+
+-l, \--lowpass-delay
+:   Delay the lowpass frequency instead of the highpass one.
+
+# ENVIRONMENT
+
+SOXFMT - this environment is automatically set if used as a dtas-player
+sink
+
+DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
+This defaults to ~/.dtas/player.sock
+
+# NOTES
+
+The author of this knows little about signal processing and is just
+parroting things he's learned on the sox documentation and mailing list.
+Corrections greatly appreciated (email Eric Wong e@80x24.org)
+
+# SEE ALSO
+
+dtas-player(1), dtas-player_protocol(7), dtas-ctl(1), sox(1)

data/Documentation/troubleshooting.txt

@@ -0,0 +1,13 @@
+dtas-player troubleshooting guide
+---------------------------------
+
+dtas-player is heavily dependent on external commands such as sox(1)/play(1)
+and ecasound(1).
+
+* problem: audio playback does not start
+
+  Since dtas-player just runs the play(1) command, the first step is to
+  ensure play(1) works without dtas-player.
+
+  Consult SoX documentation and mailing lists for getting play(1) to work,
+  first.

data/GIT-VERSION-GEN

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# Copyright (C) 2013, Eric Wong <normalperson@yhbt.net>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+CONSTANT = "DTAS::VERSION"
+RVF = "lib/dtas/version.rb"
+DEF_VER = "v0.0.0"
+vn = DEF_VER
+
+# First see if there is a version file (included in release tarballs),
+# then try git-describe, then default.
+if File.exist?(".git")
+  describe = `git describe --abbrev=4 HEAD 2>/dev/null`.strip
+  case describe
+  when /\Av[0-9]*/
+    vn = describe
+    system(*%w(git update-index -q --refresh))
+    unless `git diff-index --name-only HEAD --`.chomp.empty?
+      vn << "-dirty"
+    end
+    vn.tr!('-', '.')
+  end
+end
+
+vn = vn.sub!(/\Av/, "")
+new_ruby_version = "#{CONSTANT} = '#{vn}'\n"
+cur_ruby_version = File.read(RVF) rescue nil
+if new_ruby_version != cur_ruby_version
+  File.open(RVF, "w") { |fp| fp.write("# :enddoc:\n#{new_ruby_version}") }
+end
+puts vn if $0 == __FILE__

data/GNUmakefile

@@ -0,0 +1,9 @@
+all::
+include pkg.mk
+
+check: test
+coverage: export COVERAGE=1
+coverage:
+	> coverage.dump
+	$(MAKE) check
+	$(RUBY) ./test/covshow.rb

data/HACKING

@@ -0,0 +1,12 @@
+serialization (dtas-player)
+---------------------------
+
+* objects serialize using the "to_hsh" method (like "to_hash", but omits
+  default values) and then to YAML.  We avoid exposing the fact we use
+  Ruby (or any programming language) in any formats.
+
+* every serializable class defines a "load" singleton method which takes the
+  output Hash of "to_hsh"
+
+* we avoid serializing default values to make the state file shorter and
+  more suitable for human viewing and editing.

data/INSTALL

@@ -0,0 +1,53 @@
+Uncommon for audio software, dtas is implemented in Ruby.
+
+The latest stable release of Ruby is recommended, currently 2.0.0-p247.
+However, Ruby 1.9.3 should work, too.  Older versions of Ruby are not
+recommended.
+
+SoX is a dependency of dtas-player.  While not _strictly_ required, the
+dtas-player uses SoX by default and you will need it unless you've
+reconfigured dtas-player to use something else.
+
+mp3gain is required if you use ReplayGain with MP3s
+
+If you only intend to use dtas-cueedit, you will need metaflac(1) from
+the FLAC package.
+
+Debian users can install sox, mp3gain, and flac dependencies easily:
+
+  apt-get install sox libsox-fmt-all mp3gain flac
+
+= installing dtas RubyGem on GNU/Linux (Linux kernel 2.6.32+)
+
+  Be sure to have Ruby development headers and a working C compiler.
+  This will pull in the io_splice and sleepy_penguin RubyGems for minor
+  speedups.  If you cannot be bothered to have a development
+  environment, just use "gem install dtas"
+
+    gem install dtas-linux
+
+  This should pull in the "io_splice" and "sleepy_penguin" RubyGems
+
+  For future upgrades of dtas (upgrades to dtas-linux will be infrequent)
+
+    gem update dtas
+
+= installing the dtas RubyGem on non-GNU/Linux or old GNU/Linux systems
+
+  gem install dtas
+
+= installing dtas via tarball and setup.rb
+
+  Grab the latest tarball from our HTTP site:
+
+  http://dtas.80x24.org/2013/dtas-0.0.0.tar.gz
+
+  $ tar zxvf dtas-0.0.0.tar.gz
+  $ cd dtas-0.0.0
+  $ ruby setup.rb
+
+  GNU/Linux users may optionally install "io_splice" and
+  "sleepy_penguin" packages:
+
+  io_splice - http://bogomips.org/ruby_io_splice/
+  sleepy_penguin - http://bogomips.org/sleepy_penguin/

data/README

@@ -0,0 +1,103 @@
+= dtas - duct tape audio suite for *nix
+
+Free Software command-line tools for audio playback, mastering, and
+whatever else related to audio.  dtas follows the worse-is-better
+philosophy and acts as duct tape to combine existing command-line tools
+for flexibility and ease-of-development.  dtas is currently implemented
+in Ruby (and some embedded shell), but may use other languages in the
+future.
+
+Primary executables available are:
+
+* dtas-player - gapless music player (or pipeline/process manager :P)
+* dtas-cueedit - embedded cuesheet editor (FLAC-only for now)
+
+The centerpiece is dtas-player, a gapless music player designed to aid
+in writing scripts for sox/ecasound use.  Unlike monolithic music
+players, dtas-player is close to a *nix shell in functionality, allowing
+for the execution of arbitrary commands as sources, filters, and sinks
+for audio.  dtas-player supports:
+
+* any DSP effects offered by SoX, ecasound, LADSPA, LV2, etc..
+* multiple outputs for playback (including dumping audio to
+  files or piping to arbitrary commands)
+* ReplayGain (including fallback gain and peak normalization)
+
+dtas-player is a *nix pipeline and process manager.  It may be used
+spawn and pipe to abitrary Unix commands, not just audio-related
+commands.  It can interactively restart/replace the source (audio
+decoder) component of a pipeline while keeping the sink (playback
+endpoint) running.
+
+Users of dtas-player will also be interested in the following scripts:
+
+* dtas-ctl - "raw" command-line scripting interface for dtas-player
+* dtas-enq - enqueue files/commands for dtas-player
+* dtas-msinkctl - enable/disable multiple sinks with one command
+* dtas-console - rudimentary curses interface for dtas-player
+* dtas-sinkedit - edit sinks (playback targets) for dtas-player
+* dtas-sourceedit - edit source (decoder process parameters) for dtas-player
+* dtas-xdelay - alternative sink for dtas-player
+
+All scripts have some documentation in the Documentation/ directory or
+manpages distributed with the gem.  dtas exposes no public APIs outside
+of command-line and YAML text.  dtas is aimed at users familiar with the
+*nix command-line and editing text files.  Familiarity with the Ruby
+programming language is absolutely NOT required.
+
+Coming:
+
+* MPRIS/MPRIS 2.0 bridge for partial dtas-player control
+* tracklist support in dtas-player (maybe?)
+* whatever command-line tools come to mind...
+* native ffmpeg/avconv/gst support in dtas-player
+* better error handling, many bugfixes, etc...
+* better documentation
+
+== Source code
+
+  git clone git://80x24.org/dtas
+
+Please use git-format-patch(1) and git-send-email(1) distributed with
+the git(7) suite for generating and sending patches.  Please format
+pull requests with the git-request-pull(1) script (also distributed
+with git(7)) and send them via email.
+
+See http://www.git-scm.com/ for more information on git.
+
+== Contact
+
+Feedback (results, bug reports, patches, pull-requests) via plain-text
+email is very much appreciated.
+
+Please send plain-text email to Eric Wong <normalperson@yhbt.net>,
+HTML will not be read.  dtas is for GUI-phobes, by GUI-phobes.
+Public mailing list coming soon.
+
+== License
+
+dtas is copyrighted Free Software by all contributors, see logs
+in revision control for names and email addresses of all of them.
+
+dtas is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 3 of the License, or (at your
+option) any later version.
+
+dtas is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, see https://www.gnu.org/licenses/gpl-3.0.txt
+
+dtas is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for more details.
+
+Note: The GPL does not and can not apply to external commands run by
+dtas scripts, so users _may_ run any non-Free Software you want via dtas
+(just like one may do so via bash).  However, the dtas project does not
+endorse nor support the use of any non-Free Software.

data/Rakefile

@@ -0,0 +1,97 @@
+load "./GIT-VERSION-GEN"
+manifest = "Manifest.txt"
+gitidx = File.stat(".git/index") rescue nil
+if ! File.exist?(manifest) || File.stat(manifest).mtime < gitidx.mtime
+  system("git ls-files > #{manifest}")
+  File.open(manifest, "a") do |fp|
+    fp.puts "NEWS"
+    fp.puts "lib/dtas/version.rb"
+
+    if system("make -C Documentation")
+      require 'fileutils'
+      FileUtils.rm_rf 'man'
+      if system("make -C Documentation gem-man")
+        `git ls-files -o man`.split(/\n/).each do |man|
+          fp.puts man
+        end
+      else
+        warn "failed to install manpages for distribution"
+      end
+    else
+      warn "failed to build manpages for distribution"
+    end
+  end
+  File.open("NEWS", "w") do |fp|
+    `git tag -l`.split(/\n/).each do |tag|
+      %r{\Av([\d\.]+)} =~ tag or next
+      version = $1
+      header, subject, body = `git cat-file tag #{tag}`.split(/\n\n/, 3)
+      header = header.split(/\n/)
+      tagger = header.grep(/\Atagger /)[0]
+      time = Time.at(tagger.split(/ /)[-2].to_i).utc
+      date = time.strftime("%Y-%m-%d")
+
+      fp.write("=== #{version} / #{date}\n\n#{subject}\n\n#{body}")
+    end
+    fp.flush
+    if fp.size <= 5
+      fp.puts "Unreleased"
+    end
+  end
+end
+
+require 'hoe'
+Hoe.plugin :git
+include Rake::DSL
+
+h = Hoe.spec('dtas') do |p|
+  developer 'Eric Wong', 'e@80x24.org'
+
+  self.readme_file = 'README'
+  self.history_file = 'NEWS'
+  self.urls = %w(http://dtas.80x24.org/)
+  self.summary = x = File.readlines("README")[0].split(/\s+/)[1].chomp
+  self.description = self.paragraphs_of("README", 1)
+  # no public APIs, no HTML, either
+  self.need_rdoc = false
+  self.extra_rdoc_files = []
+  license "GPLv3+"
+end
+
+task :rsync_docs do
+  dest = "80x24.org:/srv/dtas/"
+  system("rsync --chmod=Fugo=r --files-from=.rsync_doc -av ./ #{dest}")
+  system("rsync --chmod=Fugo=r -av ./Documentation/*.txt #{dest}")
+end
+
+task :coverage do
+  env = {
+    "COVERAGE" => "1",
+    "RUBYOPT" => "-r./test/helper",
+  }
+  File.open("coverage.dump", "w").close # clear
+  pid = Process.spawn(env, "rake")
+  _, status = Process.waitpid2(pid)
+  require './test/covshow'
+  exit status.exitstatus
+end
+
+base = "dtas-#{h.version}"
+task tarball: "pkg/#{base}" do
+  Dir.chdir("pkg") do
+    tgz = "#{base}.tar.gz"
+    tmp = "#{tmp}.#$$"
+    cmd = "tar cf - #{base} | gzip -9 > #{tmp}"
+    system(cmd) or abort "#{cmd}: #$?"
+    File.rename(tmp, tgz)
+  end
+end
+
+task dist: [ :tarball, :package ] do
+  Dir.chdir("pkg") do
+    %w(dtas-linux dtas-mpris).each do |gem|
+      cmd = "gem build ../#{gem}.gemspec"
+      system(cmd) or abort "#{cmd}: #$?"
+    end
+  end
+end