about summary refs log tree commit homepage
path: root/Documentation
diff options
context:
space:
mode:
authorEric Wong <normalperson@yhbt.net>2013-08-24 23:58:08 +0000
committerEric Wong <normalperson@yhbt.net>2013-08-24 23:58:08 +0000
commit97b851b0dad8f6a3c3352bdff8f4a3aac539d354 (patch)
tree4a324e416932f51012a283cfeb4b208d2b6fd8ec /Documentation
parent09178fca7320ed4919b7c5e845598f9ad998d6d3 (diff)
downloaddtas-97b851b0dad8f6a3c3352bdff8f4a3aac539d354.tar.gz
We should probably document this before we forget it.
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/GNUmakefile12
-rw-r--r--Documentation/dtas-console.1.txt42
-rw-r--r--Documentation/dtas-ctl.1.txt64
-rw-r--r--Documentation/dtas-cueedit.1.txt24
-rw-r--r--Documentation/dtas-enq.1.txt10
-rw-r--r--Documentation/dtas-msinkctl.1.txt45
-rw-r--r--Documentation/dtas-player.1.txt110
-rw-r--r--Documentation/dtas-player_protocol.7.txt176
-rw-r--r--Documentation/dtas-sinkedit.1.txt41
-rw-r--r--Documentation/dtas-sourceedit.1.txt33
-rw-r--r--Documentation/dtas-xdelay.1.txt57
11 files changed, 573 insertions, 41 deletions
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
index 0353ec7..37411e5 100644
--- a/Documentation/GNUmakefile
+++ b/Documentation/GNUmakefile
@@ -4,7 +4,17 @@ PANDOC = pandoc
 PANDOC_OPTS = -f markdown --email-obfuscation=none
 pandoc = $(PANDOC) $(PANDOC_OPTS)
 
-man1 := $(addsuffix .1,dtas-enq)
+ones =
+ones += dtas-console
+ones += dtas-ctl
+ones += dtas-enq
+ones += dtas-msinkctl
+ones += dtas-player
+ones += dtas-xdelay
+ones += dtas-sinkedit
+ones += dtas-sourceedit
+
+man1 := $(addsuffix .1, $(ones))
 man7 := $(addsuffix .7,dtas-player_protocol)
 
 all:: man
diff --git a/Documentation/dtas-console.1.txt b/Documentation/dtas-console.1.txt
new file mode 100644
index 0000000..e41ee87
--- /dev/null
+++ b/Documentation/dtas-console.1.txt
@@ -0,0 +1,42 @@
+% dtas-console(1) dtas user manual
+
+# NAME
+
+dtas-console - rudimentary curses console client for dtas-player
+
+# SYNOPSIS
+
+dtas-console
+
+# DESCRIPTION
+
+dtas-console displays the elapsed decoder time of the track, which can be
+used as an approximation of the current playback time of a track.
+
+It cannot display an accurate playback time due to variable buffering
+in the sinks and pipes.
+
+See dtas-player_protocol(7) for a detailed description of the protocol.
+
+# KEYBOARD CONTROL
+
+Key bindings are inspired partially by mplayer(1)
+
+- 'j'/'k' - seek backward/forward 5 seconds
+- LEFT/RIGHT - seek backward/forward 10 seconds
+- UP/DOWN - seek forward/backward 1 minute
+- PGUP/PGDWN - seek forward/backward 10 minutes
+- SPACE - toggle play/pause state of the playback
+- 'p'/'P' - decrease/increase timer resolution
+- BACKSPACE - seek to the beginning of the track
+- Ctrl-C - exit dtas-console
+
+# ENVIRONMENT
+
+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), dtas-sinkedit(1),
+dtas-sourceedit(1)
diff --git a/Documentation/dtas-ctl.1.txt b/Documentation/dtas-ctl.1.txt
new file mode 100644
index 0000000..68b6c74
--- /dev/null
+++ b/Documentation/dtas-ctl.1.txt
@@ -0,0 +1,64 @@
+% dtas-ctl(1) dtas user manual
+%
+
+# NAME
+
+dtas-ctl - low-level client for dtas-player
+
+# SYNOPSYS
+
+dtas-ctl [ARGS...]
+
+# DESCRIPTION
+
+dtas-ctl passes command-line arguments as-is to dtas-player.  It is mainly
+useful for simple commands such as ("current", "play_pause", "pause", "play",
+"rg RGARGS", "seek HH:MM:SS", "skip").
+
+See dtas-player_protocol(7) for a detailed description of the protocol.
+
+# EXAMPLES
+
+display the currently playing track
+
+        $ dtas-ctl current
+
+enqueue a file for playback (dtas-enq(1) is easier to use, here)
+
+        $ dtas-ctl enq /absolute/path/to/file
+
+toggle the play/pause state of the player
+
+        $ dtas-ctl play_pause
+
+change the ReplayGain mode
+
+        $ dtas-ctl rg mode=album_gain
+        # "track_gain", "off" may be used, too
+
+seek 5 seconds forward
+
+        $ dtas-ctl seek +5
+
+seek to an absolute position
+
+        $ dtas-ctl seek 1:00
+
+skip to the next track
+
+        $ dtas-ctl skip
+
+To play the output of an arbitrary command (note the quotes) and usage
+of $SOXFMT (see dtas-player_protocol(7)).
+
+        $ dtas-ctl enq-cmd 'sox -n $SOXFMT - synth 3 pluck'
+
+# ENVIRONMENT
+
+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-enq(1), dtas-sinkedit(1),
+dtas-sourceedit(1)
diff --git a/Documentation/dtas-cueedit.1.txt b/Documentation/dtas-cueedit.1.txt
new file mode 100644
index 0000000..4d73721
--- /dev/null
+++ b/Documentation/dtas-cueedit.1.txt
@@ -0,0 +1,24 @@
+% dtas-cueedit(1) dtas user manual
+%
+
+# NAME
+
+dtas-cueedit - edit embedded cuesheets in audio files
+
+# SYNOPSYS
+
+dtas-cueedit /path/to/audio.flac
+
+# DESCRIPTION
+
+dtas-cueedit spawns an editor to edit the embedded cuesheet in FLAC files.
+In the future, other audio formats with embedded cuesheets may be supported.
+Use with the metaflac(1) is required.
+
+# ENVIRONMENT
+
+VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset.
+
+# SEE ALSO
+
+metaflac(1)
diff --git a/Documentation/dtas-enq.1.txt b/Documentation/dtas-enq.1.txt
index 0e36bb5..1ef636c 100644
--- a/Documentation/dtas-enq.1.txt
+++ b/Documentation/dtas-enq.1.txt
@@ -12,9 +12,13 @@ dtas-enq [FILE...]
 # DESCRIPTION
 
 dtas-enq will enqueue a list of files given on the command-line to a
-running instance of dtas-player.  dtas-player will start playing the
+running instance of dtas-player(1).  dtas-player will start playing the
 newly enqueued files in the order given.
 
+# EXAMPLE
+
+        $ dtas-enq /path/to/your/favorite/album/*.flac
+
 # ENVIRONMENT
 
 DTAS_PLAYER_SOCK - the path to the dtas-player listen socket.
@@ -22,6 +26,4 @@ This defaults to ~/.dtas/player.sock
 
 # SEE ALSO
 
-* dtas-player(1)
-* dtas-player(7)
-* dtas-ctl(1)
+dtas-player(1), dtas-ctl(1)
diff --git a/Documentation/dtas-msinkctl.1.txt b/Documentation/dtas-msinkctl.1.txt
new file mode 100644
index 0000000..d6acb4c
--- /dev/null
+++ b/Documentation/dtas-msinkctl.1.txt
@@ -0,0 +1,45 @@
+% dtas-msinkctl(1) dtas user manual
+
+# NAME
+
+dtas-msinkctl - activate/deactivate multiple sinks at once
+
+# SYNOPSYS
+
+dtas-msinkctl COMMAND
+dtas-msinkctl COMMAND [SINKS...]
+
+# DESCRIPTION
+
+dtas-msinkctl is useful for activating/deactivating multiple sinks.
+
+# EXAMPLES
+
+Display only active sinks (unlike "dtas-ctl sink ls", which shows all sinks)
+
+    dtas-msinkctl active
+
+Display only non-blocking sinks
+
+    dtas-msinkctl nonblock
+
+Enable only SINK1 and SINK3, and close other sinks
+
+    dtas-msinkctl active-set SINK1 SINK3
+
+Add the default sink to the active set
+
+    dtas-msinkctl active-add default
+
+Remove SINK3 from the active set
+
+    dtas-msinkctl active-add SINK3
+
+# ENVIRONMENT
+
+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), dtas-sinkedit(1)
diff --git a/Documentation/dtas-player.1.txt b/Documentation/dtas-player.1.txt
new file mode 100644
index 0000000..7e8fbe4
--- /dev/null
+++ b/Documentation/dtas-player.1.txt
@@ -0,0 +1,110 @@
+% dtas-player(1) dtas user manual
+%
+
+# NAME
+
+dtas-player - playback process for dtas
+
+# SYNOPSYS
+
+dtas-player
+
+# DESCRIPTION
+
+dtas-player is intended as a music player, but implemented as Unix
+process and pipeline manager, so it may run arbitrary commands and route
+data to just about any process.
+
+dtas-player is currently only queue-based, enqueued tracks are played
+only once.  It only runs in a foreground console, so usage with
+screen(1) or tmux(1) is recommended.
+
+By default, dtas-player uses the sox(1) command to decode audio, and
+pipes the data to a play(1) process (also distributed with sox).  It may
+be configured to output to multiple/arbitrary processes, and may invoke
+arbitrary commands for outputting audio (or any other data).
+
+dtas-player is controlled by a Unix socket, see dtas-player_protocol(7)
+for details.  Given the power of dtas-player to run arbitrary commands,
+this socket is created with restricted permissions and is only
+accessible by the user who invoked dtas-player.
+
+dtas-player maintains state across restarts with a state file.
+
+# EXAMPLE
+
+Starting dtas-player is easy, it takes no arguments:
+
+    $ dtas-player
+
+In a different terminal, enqueue your favorite track for playback:
+
+    $ dtas-enq /path/to/your/favorite/music.flac
+
+In the terminal running dtas-player, some diagnostic information
+should be printed, as will any errors which occur.
+
+To see information about the currently playing track in YAML:
+
+    $ dtas-ctl current
+
+As you should be able to see, a "default" sink is automatically
+created and playing the audio.
+
+# TROUBLESHOOTING
+
+The most common problem with dtas-player is the play(1) command
+(distributed with SoX) not using the correct audio device.  Ensuring the
+play(1) command works with dtas-player is important.  See the play(1)
+documentation for details.
+
+Once you find the correct AUDIODEV/AUDIODRIVER environment variables,
+you may set them via dtas-ctl(1):
+
+To play audio on my favorite USB DAC directly to ALSA, I use:
+
+    $ dtas-ctl sink ed default env.AUDIODEV=hw:DAC env.AUDIODRIVER=alsa
+
+# ADVANCED EXAMPLES
+
+To configure a dumper sink (in addition to the "default" sink).  Note
+the use of $SOXFMT, this will be automatically expanded to match the
+internal format of the player.  The internal format of the player is
+described in dtas-player_protocol(7).
+
+    $ dtas-ctl sink ed dumper command='sox $SOXFMT - /tmp/dump.sox'
+
+Non-"default" sinks are not active by default, but may be made active.
+
+    $ dtas-ctl sink ed dumper active=true
+
+Changing it again to "active=false" will deactivate the sink.
+
+# ENVIRONMENT
+
+DTAS_PLAYER_SOCK - the path to the dtas-player listen socket.
+This defaults to ~/.dtas/player.sock
+
+DTAS_PLAYER_STATE - the state file of the dtas-player
+This defaults to ~/.dtas/player_state.yml
+
+dtas-player will automatically populate $SOXFMT and $ECAFMT when
+invoking sink and source commands.
+
+ReplayGain values are also exported to the source command if they
+exist in the source file:
+
+    * REPLAYGAIN_TRACK_GAIN
+    * REPLAYGAIN_ALBUM_GAIN
+    * REPLAYGAIN_ALBUM_PEAK
+    * REPLAYGAIN_TRACK_PEAK
+
+# FILES
+
+~/.dtas/player_state.yml is a human-readable YAML file used to preserve
+state across restarts of dtas-player.
+
+# SEE ALSO
+
+dtas-player_protocol(7), dtas-ctl(1), dtas-enq(1), dtas-sourceedit(1),
+dtas-sinkedit(1), sox(1), play(1), screen(1), tmux(1)
diff --git a/Documentation/dtas-player_protocol.7.txt b/Documentation/dtas-player_protocol.7.txt
index 6af8fc4..7c5d57f 100644
--- a/Documentation/dtas-player_protocol.7.txt
+++ b/Documentation/dtas-player_protocol.7.txt
@@ -2,7 +2,27 @@
 %
 
 # NAME
-        dtas-player_protocol - protocol for controlling dtas-player
+
+dtas-player_protocol - protocol for controling dtas-player
+
+# DESCRIPTION
+
+This gives a specification of the dtas-player protocol over a local Unix
+SOCK_SEQPACKET or SOCK_DGRAM socket.  The dtas-player protocol should NOT be
+considered stable at this point and compatibility will break.
+
+Inspiration is taken from MPRIS and MPRIS 2.0 specifications (e.g.
+play_pause, play, pause), and there will be a proxy in the future to
+support MPRIS/MPRIS 2.0 clients.
+
+The DTAS_PLAYER_SOCK is the standard environment determining the control
+socket for dtas-player(1).  This defaults to $HOME/.dtas/player.sock if
+unset.
+
+Most low-level commands may be issued using the dtas-ctl(1) command.
+
+Higher-level commands such as dtas-console(1), dtas-sourceedit(1),
+dtas-sinkedit(1), and dtas-enq(1) also implement this protocol.
 
 # ARGUMENT TYPES
 
@@ -16,13 +36,77 @@
 - FILENAME - an expanded pathname relative to / is recommended since
              dtas-player and the client may run in different directories
 
+# VARIABLE EXPANSION
+
+For source and sink "command" arguments, the $SOXFMT and $ECAFMT
+environment variables are exported automatically to source to ease
+integration with sox(1) and ecasound(1).
+
+Both $SOXFMT and $ECAFMT are based on the configured "format" of
+the dtas-player (see below).
+
+For all machines, $SOXFMT defaults to: -ts32 -c2 -r44100
+For little-endian machines, $ECAFMT defaults to: -fs32_le,2,44100
+
 # COMMANDS
 
+* cd - change the current working directory of the player
+
+* clear - clear current queue (current track/command continues running)
+  PENDING: this may be renamed to "queue clear" or "queue-clear"
+
+* current - output information about the currently-playing track/command
+  in YAML.  The structure of this is unstable and subject to change.
+
 * enq FILENAME - enqueue the given FILENAME for playback
   An expanded (full) pathname relative to '/' is recommended, as
   dtas-player and the client may be in different directories.
+  PENDING: this may be renamed to "queue add"
+
+* enq-cmd "COMMAND" - run the following command for playback.
+  The COMMAND is expected to output audio in the audio format matching
+  the current audio format of the player.  This may be a shell pipeline
+  and include multiple commands.  The $SOXFMT and $ECAFMT variables are
+  available here.
+  PENDING: this may be renamed to "queue add-cmd"
+
+* env ENVTOSET=ENVVALUE ENVTOSET2=ENVVALUE2
+  Set environment variables.  This affects all future source/sink
+  processes as well as helper commands dtas-player may spawn
+  (e.g. soxi(1)).  Environment variables set this way are currently not
+  preserved across invocations of dtas-player(1), but may change in the
+  future.
+
+* env ENVTOUNSET1# ENVTOUNSET#
+  Unset the given environment variable.
+  PENDING: the '#' is ugly and inconsistent with the per-sink/source.
+  env.
+
+* format FORMATARGS - configure the format between source and sink
+  Changing this will affect the $SOXFMT and $ECAFMT environments passed
+  to source and sink commands.  Changing this implies a "restart"
+  Changing rate to 48000 is probably useful if you plan on playing to some
+  laptop sound cards.
+
+    + channels=UNSIGNED - (default: 2 (stereo)) - number of channels
+      to use internally.  sox will internally invoke the remix effect
+      when decoding.
+    + endian=(big|little|swap) - (default: native) - there is probably no
+      point in changing this unless you output over a network sink to
+      a machine of different endianess.
+    + bits=UNSIGNED - (default: implied from type) - sample precision (decoded)
+      This may be pointless and removed in the future, since the sample
+      precision is implied from type.
+    + rate=UNSIGNED - (default: 44100) - sample rate of audio
+      Typical values of rate are 44100, 48000, 88200, 96000.  Not all
+      DSP effects are compatible with all sampling rates/channels.
+    + type=(s16|s24|s32|u16|u24|u32|f32|f64) - (default: s32)
+      change the raw PCM format.  s32 currently offers the best performance
+      when only sox/play are used.  f32 may offer better performance if
+      piping to/from non-sox applications (e.g. ecasound)
 
 * pause - pause playback
+  Player pause state is preserved across dtas-player invocations.
 
 * play - restart playback from pause.  Playback sinks will yield
   control of the audio playback device once no source is playing.
@@ -31,47 +115,67 @@
   paused, and pauses playback if playing.
 
 * restart - restarts all processes in the current pipeline.  Playback
-  will be momentarily interrupted while this change occurs.  This may
-  be necess
-
-* seek HH:MM:SS.FRAC - seek the current track to a specified time.
+  will be momentarily interrupted while this change occurs.  This is
+  necessary if one of the commands (e.g. sox or ecasound) or loaded
+  libraries (e.g. a LADSPA plugin) is upgraded.
+
+* rg RGARGS - configure ReplayGain support
+  All FLOAT values may be adjusted via '+=' or '-=' instead of simple
+  assignment ('=').  If RGARGS is empty, the current rg state of
+  non-default values will be dumped in YAML.
+    + fallback_gain=FLOAT (-6.0) - dB value
+      Adjust the volume by this level (usually negative) for tracks
+      missing ReplayGain tags.  This is useful when the queue contains
+      a mix of tracks with and without ReplayGain tags.
+    + fallback_track=BOOLEAN (true)
+      When in album_gain mode, fallback to track_gain if the
+      REPLAYGAIN_ALBUM_GAIN metadata is missing.
+    + mode=(album_gain|track_gain|track_norm|album_norm|off)
+      This controls the ReplayGain tag to use.  The *_norm options
+      are used for peak normalization and not commonly found in other
+      players.
+    + preamp=FLOAT (0) - dB value
+      Adjust the album_gain or track_gain amount by this value (in dB).
+    + norm_level=FLOAT (1.0 == dBFS)
+      Controls the level to normalize to when using album_norm or track_norm.
+
+* seek [+-]HH:MM:SS.FRAC - seek the current track to a specified time.
   This is passed directly as the first argument for the sox(1) "trim"
   command.   See the sox(1) manpage for details.
+  Seeking to a relative time is also supported by prefixing the time
+  with '+' or '-'
 
-* enq-cmd "COMMAND" - run the following command for playback.
-  The COMMAND is expected to output audio in the format compatible with
-  the current audio format of the player.  This may be a shell pipeline
-  and include multiple commands.
-
-* clear - clear current queue (current song continues playing)
-
-* skip - abort current track
+* skip - abort current track/command (via closing the output pipe)
   Running the "clear" command before this will abort playback.
 
 * sink ls - list names of current sinks
-* sink cat SINKNAME - dump SINKNAME config in YAML
-* sink rm SINKNAME - remove SINKNAME
-* sink ed SINKNAME SINKARGS - create/edit SINKNAME
 
-  SINKARGS:
-    command=COMMAND
-    active=BOOLEAN
-    env.ENVNAME=ENVVALUE
-    prio=INTEGER
-    nonblock=BOOLEAN
-    pipe_size=UNSIGNED
-
-* env ENVTOSET=ENVVALUE ENVTOUNSET1# ENVTOSET2=ENVVALUE2
-
-ReplayGain state
-----------------
-
-* rg.mode=(album_gain|track_gain|track_norm|album_norm|off)
-
-* rg.preamp=DB_VALUE  (0)
-
-* rg.fallback_gain=DB_VALUE (-6.0)
+* sink cat SINKNAME - dump SINKNAME config in YAML
 
-* rg.fallback_track=BOOLEAN (true)
+* sink rm SINKNAME - remove SINKNAME
 
-* rg.norm_level=FLOAT (1.0 == dBFS)
+* sink ed SINKNAME SINKARGS - create/edit SINKNAME
+  This currently does not restart running (active) sinks.
+  This will stop active sinks if active is set to false, and start
+  active sinks if active is set to true.
+  See dtas-sinkedit(1) for an example of using this.
+    + command=COMMAND - change the command-line used for playback
+    + active=BOOLEAN - whether or not the sink will be in use (default: false)
+    + env.ENVNAME=ENVVALUE - set ENVNAME to ENVVALUE for the sink process
+    + env#ENVNAME - unset ENVNAME in the sink process (only)
+    + prio=INTEGER - priority of the sink, lower values run first
+    + nonblock=BOOLEAN - drop audio data to avoid holding back other sinks
+    + pipe_size=UNSIGNED - set the size of the pipe for the sink (Linux-only)
+
+* source cat - dump the current source command and env in YAML
+
+* source ed SOURCEARGS - edit the source (decoder) command and environment.
+  This changes here will immediately restart the source process.
+  See the code for dtas-sourceedit(1) for an example of using this.
+    + command=COMMAND - change the command-line used to decode audio
+    + env.ENVNAME=ENVVALUE - set ENVNAME to ENVVALUE for the source process
+    + env#ENVNAME - unset ENVNAME in the source process (only)
+
+* watch - adds the client to the passive watch list for notifications.
+  It is recommended clients issue no further commands and open
+  another client socket to issue non-watch commands.
diff --git a/Documentation/dtas-sinkedit.1.txt b/Documentation/dtas-sinkedit.1.txt
new file mode 100644
index 0000000..892320a
--- /dev/null
+++ b/Documentation/dtas-sinkedit.1.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)
diff --git a/Documentation/dtas-sourceedit.1.txt b/Documentation/dtas-sourceedit.1.txt
new file mode 100644
index 0000000..1f5101b
--- /dev/null
+++ b/Documentation/dtas-sourceedit.1.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)
diff --git a/Documentation/dtas-xdelay.1.txt b/Documentation/dtas-xdelay.1.txt
new file mode 100644
index 0000000..e6544f1
--- /dev/null
+++ b/Documentation/dtas-xdelay.1.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)