about summary refs log tree commit homepage
path: root/Documentation/dtas-player.pod
diff options
authorEric Wong <e@80x24.org>2016-01-18 05:18:09 +0000
committerEric Wong <e@80x24.org>2016-01-18 07:02:39 +0000
commit3083b7fbe2bc6e8dcd935b10bb7a165257c5252b (patch)
treeaf5d87ea9a2ea161df619c2305ef951cb18d087a /Documentation/dtas-player.pod
parent0699498e5eb717a351c223e6a5a6a3bd3d3c6cde (diff)
perlpod(1) is already installed by default on Debian and
RedHat-based systems; and probably most modern *nixes; pandoc(1)
(and Haskell) are not.

POD also more standardized than Markdown (which flavor? :P),
especially for generating manpages.  So save any potential
documentation editors some disk space by not forcing them to install
Haskell and pandoc.

Finally, I'm a mildly proficient in Perl and do not know Haskell
at all and have a better chance at reading/hacking the source if
the document generator breaks.
Diffstat (limited to 'Documentation/dtas-player.pod')
1 files changed, 126 insertions, 0 deletions
diff --git a/Documentation/dtas-player.pod b/Documentation/dtas-player.pod
new file mode 100644
index 0000000..a146868
--- /dev/null
+++ b/Documentation/dtas-player.pod
@@ -0,0 +1,126 @@
+% dtas-player(1) dtas user manual
+=head1 NAME
+dtas-player - playback process for dtas
+=head1 SYNOPSYS
+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
+L<screen(1)> or L<tmux(1)> is recommended.
+By default, dtas-player uses the L<sox(1)> command to decode audio, and
+pipes the data to a L<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 L<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.
+=head1 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.
+=head2 Audio playback does not start
+The most common problem with dtas-player is the L<play(1)> command
+(distributed with SoX) not using the correct audio device/driver.
+Ensuring the L<play(1)> command works with dtas-player is important.
+Consult SoX documentation and mailing lists for getting L<play(1)> to work,
+Once you find the correct AUDIODEV/AUDIODRIVER environment variables,
+you may set them via L<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
+=head2 Seeking/playing audio from large video containers (e.g. VOB) fails
+This is a problem with large VOBs.  We recommend breaking up the
+VOB into smaller files or using L<avconv(1)> or L<ffmpeg(1)> to extract
+the desired audio stream.
+      avconv -analyzeduration 2G -probesize 2G \
+        -i input.vob -vn -sn -c:a copy -map 0:$STREAM_NR output.ext
+See L<dtas_player-sink_examples(7)> for more sink examples.
+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:
+=head1 FILES
+~/.dtas/player_state.yml is a human-readable YAML file used to preserve
+state across restarts of dtas-player.
+=head1 CONTACT
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+No subscription is necessary to post to the mailing list.
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+=head1 SEE ALSO
+L<dtas-player_protocol(7)>, L<dtas-ctl(1)>, L<dtas-enq(1)>,
+L<dtas-sourceedit(1)>, L<dtas-sinkedit(1)>, L<sox(1)>, L<play(1)>,
+L<avconv(1)>, L<ffmpeg(1)>, L<screen(1)>, L<tmux(1)>