about summary refs log tree commit homepage
path: root/Documentation
diff options
context:
space:
mode:
authorEric Wong <e@80x24.org>2015-01-19 07:05:00 +0000
committerEric Wong <e@80x24.org>2015-01-19 09:58:47 +0000
commit72977765a3c30f2a8a89ccbf23fde8289c81bdf9 (patch)
tree7345d5d89b6cae5baea569c38450a8c7b883a959 /Documentation
parent3e392aa8edf36a471f951b880e421be056d72587 (diff)
downloaddtas-72977765a3c30f2a8a89ccbf23fde8289c81bdf9.tar.gz
This rounds out the documentation a bit and hopefully
introduces/encourages some commonality between the playback
and processing/production components of dtas.

Clarify some splitfx-related environment variables while
we're at it.
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/GNUmakefile1
-rw-r--r--Documentation/dtas-env.txt60
-rw-r--r--Documentation/dtas-splitfx.txt7
3 files changed, 65 insertions, 3 deletions
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
index d8a648c..ac7df77 100644
--- a/Documentation/GNUmakefile
+++ b/Documentation/GNUmakefile
@@ -22,6 +22,7 @@ m1 += dtas-splitfx
 m7 =
 m7 += dtas-player_protocol
 m7 += dtas-player_sink_examples
+m7 += dtas-env
 
 man1 := $(addsuffix .1, $(m1))
 man7 := $(addsuffix .7, $(m7))
diff --git a/Documentation/dtas-env.txt b/Documentation/dtas-env.txt
new file mode 100644
index 0000000..e081b7a
--- /dev/null
+++ b/Documentation/dtas-env.txt
@@ -0,0 +1,60 @@
+% dtas-env(7) dtas user manual
+%
+
+# NAME
+
+dtas-env - environment variables used through DTAS
+
+# DESCRIPTION
+
+As dtas uses Bourne shell and exposes it to users, dtas should have
+a cohesive set of common environment variables across its audio
+production and playback environments.  This attempts to document
+them.  Most of these environments are set and managed by dtas
+itself, but users editing commands (e.g. via dtas-sourcedit(1)
+should be aware of them.
+
+# ENVIRONMENT
+
+ECAFMT - an snippet of command-line switches for ecasound describing
+audio format parameters (such as word length, channels, sample rate),
+see dtas-player_protocol(7) for more info. (e.g. "-fs32_le,2,44100")
+
+INFILE - the primary input file for playback or processing.
+(e.g. "/path/to/ex.flac")
+
+RGFX - the sox effect used for applying ReplayGain compensation.
+Only used during playback in dtas-player.  (e.g. "vol -6.0dB").
+Removing this prevents ReplayGain from working and may damage
+playback equipment with loudly mastered music.
+
+SOXFMT - an snippet of command-line switches for sox describing
+audio format parameters (such as word length, channels, sample rate),
+see dtas-player_protocol(7) for more info. (e.g. "-ts32 -c2 -r44100")
+
+TRIMFX - the sox effect used for seeking during playback with dtas-player
+and track offsets for dtas-splitfx.  (e.g. "trim 36000s")
+
+Additionally, dtas-splitfx(1) documents more environment variables
+which are not used elsewhere.
+
+# ENVIRONMENT FOR OTHER EXECUTABLES
+
+By virtue of running other programs, dtas indirectly uses many
+commonly-accepted environment variables such as EDITOR / VISUAL for
+selecting a text editor, and SOX_OPTS, AUDIODEV, AUDIODRIVER for sox(1)
+and play(1) commands and LADSPA_PATH for anything using LADSPA plugins
+(including sox).  The TMPDIR environment variable controls where
+temporary files are placed for most programs.
+
+# CONTACT
+
+All feedback welcome via plain-text mail to <dtas-all@nongnu.org>\
+Mailing list archives available at <ftp://lists.gnu.org/dtas-all/>
+and <http://80x24.org/dtas-all/>\
+No subscription is necessary to post to the mailing list.
+
+# COPYRIGHT
+
+Copyright 2015, all contributors <dtas-all@nongnu.org>.\
+License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
diff --git a/Documentation/dtas-splitfx.txt b/Documentation/dtas-splitfx.txt
index 0fd2f3a..beee4bf 100644
--- a/Documentation/dtas-splitfx.txt
+++ b/Documentation/dtas-splitfx.txt
@@ -99,17 +99,18 @@ dtas-splitfx sets several default environment variables for commands to
 use in targets:
 
 * INFILE - this matches the "infile" directive in the YAML file
-* INDIR - the directory INFILE belongs to
+* INDIR - the directory INFILE belongs to, without trailing slash
 * INBASE - the basename of INFILE
 * TRIMFX - essential, this supplys the necessary sox(1) trim effect to
   each track.
 * COMMENTS - expands to --comment-file=PATH for sox(1)
-* OUTFMT - sox(1) arguments for the output format (e.g. "-ts32 -c2 -r44100"
+* OUTFMT - sox(1) arguments for the output format (e.g. "-ts32 -c2 * -r44100")
 * SUFFIX - the suffix of the output format without "." (e.g. "flac", "ogg")
 * TRACKNUMBER - the track number, useful for comments and filenames
 * RATEFX - rate effect and arguments for sox(1) resampling
 * DITHERFX - dither effect and arguments for sox(1) dithering
-
+* FX - any user-specified sox effects which encompases the entire file.
+  (e.g. "highpass 35 vol +3dB stats")
 # TARGETS
 
 The default targets will split audio and avoid applying any effects.