initial commit

6 files changed, 189 insertions, 0 deletions

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644
index 0000000..56fdc90
--- /dev/null
+++ b/Documentation/.gitignore
@@ -0,0 +1,3 @@
+*.1
+*.5
+*.7
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
new file mode 100644
index 0000000..0353ec7
--- /dev/null
+++ b/Documentation/GNUmakefile
@@ -0,0 +1,24 @@
+all::
+
+PANDOC = pandoc
+PANDOC_OPTS = -f markdown --email-obfuscation=none
+pandoc = $(PANDOC) $(PANDOC_OPTS)
+
+man1 := $(addsuffix .1,dtas-enq)
+man7 := $(addsuffix .7,dtas-player_protocol)
+
+all:: man
+
+man: $(man1) $(man7)
+
+install-man: man
+        mkdir -p ../man/man1
+        install -m 644 $(man1) ../man/man1
+
+%.1: %.1.txt
+        $(pandoc) -s -t man < $< > $@+ && mv $@+ $@
+%.7: %.7.txt
+        $(pandoc) -s -t man < $< > $@+ && mv $@+ $@
+
+clean::
+        $(RM) $(man1)
diff --git a/Documentation/dtas-enq.1.txt b/Documentation/dtas-enq.1.txt
new file mode 100644
index 0000000..0e36bb5
--- /dev/null
+++ b/Documentation/dtas-enq.1.txt
@@ -0,0 +1,27 @@
+% dtas-enq(1) dtas user manual
+%
+
+# NAME
+
+dtas-enq - enqueue audio files for playback with dtas-player
+
+# SYNOPSYS
+
+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
+newly enqueued files in the order given.
+
+# ENVIRONMENT
+
+DTAS_PLAYER_SOCK - the path to the dtas-player listen socket.
+This defaults to ~/.dtas/player.sock
+
+# SEE ALSO
+
+* dtas-player(1)
+* dtas-player(7)
+* dtas-ctl(1)
diff --git a/Documentation/dtas-player_effects.txt b/Documentation/dtas-player_effects.txt
new file mode 100644
index 0000000..b6aab2b
--- /dev/null
+++ b/Documentation/dtas-player_effects.txt
@@ -0,0 +1,45 @@
+Effects in dtas-player may be applied either at the source or the sink.
+They are applied in the order described.
+
+1. source effects
+
+  Source effects are effects which should be applied per-source and do not
+  rely on inter-track information.
+
+  Examples include:
+  - ReplayGain (simple vol/gain changes)
+  - anything which does not change the length of the audio:
+    vol, stereo, highpass, lowpass, loudness, bass, treble, equalizer, ...
+
+  Modifying source effects should introduce no extra gaps in playback.
+  Effects which modify the length of the audio is not recommended here,
+  as seek functionality will be impaired.
+
+2. sink effects
+
+  Sink effects are any effects which:
+
+  1) should only be applied to a specific sink
+  2) effects which require inter-track information
+     (multiband delays/compressors/expanders)
+  3) alter the length of the audio
+
+  In a multi-zone audio system (where each zone has its own sink), sink
+  effects may also customize the sound of a certain zone while not
+  affecting others.
+
+  Examples include:
+  - equalizer effects (highpass/bass/treble/equalizer)
+  - loudness
+  - delaying a certain channel or frequency range for time-alignment
+  - compressors/limiters
+  - reverb
+  - vol
+  - remix (for stereo image adjustments)
+
+  Additionally, effects which are necessary due to the limitation of the
+  playback hardware are applied at the sink:
+
+  - rate
+  - dither
+  - remix (static channel mappings)
diff --git a/Documentation/dtas-player_protocol.7.txt b/Documentation/dtas-player_protocol.7.txt
new file mode 100644
index 0000000..6af8fc4
--- /dev/null
+++ b/Documentation/dtas-player_protocol.7.txt
@@ -0,0 +1,77 @@
+% dtas-player_protocol(7) dtas user manual
+%
+
+# NAME
+        dtas-player_protocol - protocol for controlling dtas-player
+
+# ARGUMENT TYPES
+
+- BOOLEAN - must be "true" or "false"
+- INTEGER - a signed integer in decimal notation (base 10)
+- UNSIGNED - an unsigned integer in decimal or hex notation
+- ENVNAME - must be a suitable environment variable (setenv(3))
+- ENVVALUE - must be a suitable environment variable (setenv(3))
+- COMMAND, this may be quoted string passed to sh -c "",
+           variable/argument expansion will be performed by the shell
+- FILENAME - an expanded pathname relative to / is recommended since
+             dtas-player and the client may run in different directories
+
+# COMMANDS
+
+* 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.
+
+* pause - pause playback
+
+* play - restart playback from pause.  Playback sinks will yield
+  control of the audio playback device once no source is playing.
+
+* play_pause - toggle the play/pause state.  This starts playback if
+  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.
+  This is passed directly as the first argument for the sox(1) "trim"
+  command.   See the sox(1) manpage for details.
+
+* 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
+  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)
+
+* rg.fallback_track=BOOLEAN (true)
+
+* rg.norm_level=FLOAT (1.0 == dBFS)
diff --git a/Documentation/troubleshooting.txt b/Documentation/troubleshooting.txt
new file mode 100644
index 0000000..e46b873
--- /dev/null
+++ b/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.