From 3e09ac0c10c95bb24a08af62393b4f761e2743d0 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Sat, 24 Aug 2013 09:54:45 +0000 Subject: initial commit --- Documentation/.gitignore | 3 ++ Documentation/GNUmakefile | 24 ++++++++++ Documentation/dtas-enq.1.txt | 27 +++++++++++ Documentation/dtas-player_effects.txt | 45 +++++++++++++++++++ Documentation/dtas-player_protocol.7.txt | 77 ++++++++++++++++++++++++++++++++ Documentation/troubleshooting.txt | 13 ++++++ 6 files changed, 189 insertions(+) create mode 100644 Documentation/.gitignore create mode 100644 Documentation/GNUmakefile create mode 100644 Documentation/dtas-enq.1.txt create mode 100644 Documentation/dtas-player_effects.txt create mode 100644 Documentation/dtas-player_protocol.7.txt create mode 100644 Documentation/troubleshooting.txt (limited to 'Documentation') 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. -- cgit v1.2.3-24-ge0c7