dtas 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 22d6c76202aedaacaf6ed0beb48a801f4d7f5e45
-  data.tar.gz: f7f54c79b652b9539f8b639c42ffb89bf041b161
+  metadata.gz: 6a8368223a46a5e0444391029757906680b7c542
+  data.tar.gz: b5c51de31c4fcf739c16c177b07ed593897bf83a
 SHA512:
-  metadata.gz: c47a803a3f398c8ceaddfe17f50ff5a23028688effca8baa3d3c0ecaf71d842b8905a91a25b4a8fb2908af00f32bf908f4850011a0bb529e8e218ccbdfcf36f8
-  data.tar.gz: 9fe65caf3eb58e7faefda98952d2ba44f97b10c45f5d6cc5d7a86780d105e4c5b22fc0f04fb55ff4d6ceaa03e77361caca6776e3bf8dd6235701883b52df50b8
+  metadata.gz: 712fb210c0b372c2f3d170345c84f62dce8bd694544c4bc06d04401b5be7eb6e39719d7ad59954f8b2d49aaa9fad24bf20f9b4462c255ece9f864c42fcea6ba3
+  data.tar.gz: 694d7d60ff9d65a2cb23b6904821852f613fac748559930d6d889cfc7ebdcea4e75682237a2b19c092ec4bef30fe6e7b734f66daa0ed593b31d94d3328810d26

data/Documentation/.gitignore

@@ -3,3 +3,4 @@
 *.1
 *.5
 *.7
+*.txt

data/Documentation/GNUmakefile

@@ -3,12 +3,18 @@
 all::
 
 INSTALL = install
-PANDOC = pandoc
-PANDOC_OPTS = -f markdown --email-obfuscation=none
-pandoc = $(PANDOC) $(PANDOC_OPTS)
+POD2MAN = pod2man
+-include ../GIT-VERSION-FILE
+release := dtas $(VERSION)
+POD2MAN_OPTS = -v -r '$(release)' --stderr -d 1994-10-02 -c 'dtas user manual'
+pod2man = $(POD2MAN) $(POD2MAN_OPTS)
+POD2TEXT = pod2text
+POD2TEXT_OPTS = --stderr
+pod2text = $(POD2TEXT) $(POD2TEXT_OPTS)
 
 m1 =
 m1 += dtas-console
+m1 += dtas-cueedit
 m1 += dtas-ctl
 m1 += dtas-enq
 m1 += dtas-msinkctl
@@ -23,6 +29,7 @@ m1 += dtas-archive
 m7 =
 m7 += dtas-player_protocol
 m7 += dtas-player_sink_examples
+m7 += dtas-player_effects
 m7 += dtas-env
 
 man1 := $(addsuffix .1, $(m1))
@@ -47,8 +54,24 @@ install-man: man
 	$(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
 	$(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
 	$(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
-%.1 %.7 : %.txt
-	$(pandoc) -s -t man < $< > $@
+
+%.1 : %.pod
+	$(pod2man) -s 1 $< $@+ && mv $@+ $@
+
+%.7 : %.pod
+	$(pod2man) -s 7 $< $@+ && mv $@+ $@
+
+mantxt = $(addsuffix .txt, $(m1) $(m7))
+
+txt :: $(mantxt)
+
+all :: txt
+
+%.txt : %.pod
+	$(pod2text) $< $@+
+	touch -r $< $@+ 2>/dev/null || true # GNU-ism
+	mv $@+ $@
 
 clean::
 	$(RM) $(man1) $(man7)
+	$(RM) $(addsuffix .txt.gz, $(m1) $(m7))

data/Documentation/dtas-archive.pod

@@ -0,0 +1,74 @@
+% dtas-archive(1) dtas user manual
+
+=head1 NAME
+
+dtas-archive - paranoid audio file copy
+
+=head1 SYNOPSYS
+
+dtas-archive [OPTIONS] SOURCE DESTINATION
+
+=head1 DESCRIPTION
+
+dtas-archive is intended for archiving audio data to/from laptops,
+marginal USB ports, and computers without ECC memory, attempting
+to read data multiple times in an attempt to detect memory or
+bus corruption.  dtas-archive may only be effective on machines
+running the Linux kernel where L<posix_fadvise(2)> can be used to
+drop caches for a particular file after L<fsync(2)>.
+
+dtas-archive spawns L<sox(1)> to archive audio data (likely uncompressed
+WAVE) to FLAC and verifies the result using L<sndfile-cmp(1)>, a tool
+implemented by different than sox and less likely to share the same bugs
+(if any) as sox.
+
+=head1 OPTIONS
+
+=over
+
+=item -j, --jobs [JOBS]
+
+Number of jobs to run in parallel.  Incrementing this may hurt
+performance on slow storage devices.  Default: 1
+
+=item -n, --dry-run
+
+Print, but do not run the commands to be executed
+
+=item -s, --quiet, --silent
+
+Silent operation, commands are not printed as executed
+
+=item -S, --stats
+
+Run and save the text output of the sox "stats" effect as
+$DESTINATION_FILE_WITHOUT_SUFFIX.stats next to the output file
+
+=item -k, --keep-going
+
+Continue after error
+
+=item -r, --repeat [COUNT]
+
+Number of times to repeat the L<sndfile-cmp(1)> check.  Default: 1
+
+=back
+
+=head1 COPYRIGHT
+
+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 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.
+
+=head1 SEE ALSO
+
+L<sndfile-cmp(1)>, L<sox(1)>

data/Documentation/dtas-console.pod

@@ -0,0 +1,94 @@
+% L<dtas-console(1)> dtas user manual
+
+=head1 NAME
+
+dtas-console - rudimentary curses console client for dtas-player
+
+=head1 SYNOPSIS
+
+dtas-console
+
+=head1 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 L<dtas-player_protocol(7)> for a detailed description of the protocol.
+
+=head1 KEYBOARD CONTROL
+
+Key bindings are inspired partially by L<mplayer(1)>
+
+=over
+
+=item 'j'/'k' - seek backward/forward 5 seconds
+
+=item LEFT/RIGHT - seek backward/forward 10 seconds
+
+=item UP/DOWN - seek forward/backward 1 minute
+
+=item PGUP/PGDWN - seek forward/backward 10 minutes
+
+=item SPACE - toggle play/pause state of the playback
+
+=item 'p'/'P' - decrease/increase timer resolution
+
+=item BACKSPACE - seek to the beginning of the track
+
+=item 7/8 - decrease/increase ReplayGain preamp
+
+=item 9/0 - decrease/increase software volume
+
+=item '=' - set software volume to 1.0 (no adjustment)
+
+=item 'm' - mute set software volume to 0.0 (mute)
+
+=item 'f'/'F' - decrease/increase ReplayGain fallback_gain value
+
+=item 'r'/'R' - cycle forward/backwards through ReplayGain modes
+
+=item 'q'/Ctrl-C - exit dtas-console
+
+=item 'o' - toggle display between HH:MM:SS and absolute seconds
+
+=back
+
+=head1 ENVIRONMENT
+
+DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
+This defaults to ~/.dtas/player.sock
+
+=head1 CAVEATS
+
+Increasing timer resolution increases the number of CPU wakeups and
+power consumption.   This defeats the efforts of dtas-player
+configurations which use large buffers (especially in the sink) to
+reduce wakeups and power consumption.
+
+In rare cases (or poorly-configured systems), increased wakeups from
+dtas-console will also increase contention with the sound card,
+negatively affecting audio quality even if CPU utilization is not
+a problem.
+
+=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.
+
+=head1 COPYRIGHT
+
+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(1)>, L<dtas-player_protocol(7)>, L<dtas-ctl(1)>,
+L<dtas-sinkedit(1)>, L<dtas-sourceedit(1)>

data/Documentation/{dtas-ctl.txt → dtas-ctl.pod}

@@ -1,29 +1,28 @@
 % dtas-ctl(1) dtas user manual
-%
 
-# NAME
+=head1 NAME
 
 dtas-ctl - low-level client for dtas-player
 
-# SYNOPSYS
+=head1 SYNOPSYS
 
 dtas-ctl [ARGS...]
 
-# DESCRIPTION
+=head1 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.
+See L<dtas-player_protocol(7)> for a detailed description of the protocol.
 
-# EXAMPLES
+=head1 EXAMPLES
 
 display the currently playing track
 
         $ dtas-ctl current
 
-enqueue a file for playback (dtas-enq(1) is easier to use, here)
+enqueue a file for playback (L<dtas-enq(1)> is easier to use, here)
 
         $ dtas-ctl enq /absolute/path/to/file
 
@@ -49,28 +48,31 @@ 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)).
+of $SOXFMT (see L<dtas-player_protocol(7)>).
 
 	$ dtas-ctl enq-cmd 'sox -n $SOXFMT - synth 3 pluck'
 
-# ENVIRONMENT
+=head1 ENVIRONMENT
 
 DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
 This defaults to ~/.dtas/player.sock
 
-# CONTACT
+=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/>
 
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
 No subscription is necessary to post to the mailing list.
 
-# COPYRIGHT
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
 
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
 
-# SEE ALSO
+=head1 SEE ALSO
 
-dtas-player(1), dtas-player_protocol(7), dtas-enq(1), dtas-sinkedit(1),
-dtas-sourceedit(1)
+L<dtas-player(1)>, L<dtas-player_protocol(7)>, L<dtas-enq(1)>,
+L<dtas-sinkedit(1)>, L<dtas-sourceedit(1)>

data/Documentation/dtas-cueedit.pod

@@ -0,0 +1,38 @@
+% dtas-cueedit(1) dtas user manual
+
+=head1 NAME
+
+dtas-cueedit - edit embedded cuesheets in audio files
+
+=head1 SYNOPSYS
+
+dtas-cueedit /path/to/audio.flac
+
+=head1 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 L<metaflac(1)> is required.
+
+=head1 ENVIRONMENT
+
+VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset.
+
+=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.
+
+=head1 COPYRIGHT
+
+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<metaflac(1)>

data/Documentation/dtas-enq.pod

@@ -0,0 +1,43 @@
+% dtas-enq(1) dtas user manual
+
+=head1 NAME
+
+dtas-enq - enqueue audio files for playback with dtas-player
+
+=head1 SYNOPSYS
+
+dtas-enq [FILE...]
+
+=head1 DESCRIPTION
+
+dtas-enq will enqueue a list of files given on the command-line to a
+running instance of L<dtas-player(1)>.  dtas-player will start playing
+the newly enqueued files in the order given.
+
+=head1 EXAMPLE
+
+        $ dtas-enq /path/to/your/favorite/album/*.flac
+
+=head1 ENVIRONMENT
+
+DTAS_PLAYER_SOCK - the path to the dtas-player listen socket.
+This defaults to ~/.dtas/player.sock
+
+=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.
+
+=head1 COPYRIGHT
+
+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(1)>, L<dtas-ctl(1)>

data/Documentation/dtas-env.pod

@@ -0,0 +1,75 @@
+% dtas-env(7) dtas user manual
+
+=head1 NAME
+
+dtas-env - environment variables used through DTAS
+
+=head1 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 L<dtas-sourcedit(1)>
+should be aware of them.
+
+=head1 ENVIRONMENT
+
+=over
+
+=item ECAFMT
+
+A snippet of command-line switches for ecasound describing
+audio format parameters (such as word length, channels, sample rate),
+see L<dtas-player_protocol(7)> for more info. (e.g. "-fs32_le,2,44100")
+
+=item INFILE
+
+The primary input file for playback or processing. (e.g. "/path/to/ex.flac")
+
+=item RGFX
+
+The sox effect used for applying ReplayGain compensation.
+Only used during playback in dtas-player.  (e.g. "gain -6.0").
+Removing this prevents ReplayGain from working and may damage
+playback equipment with loudly mastered music.
+
+=item SOXFMT
+
+A snippet of command-line switches for sox describing
+audio format parameters (such as word length, channels, sample rate),
+see L<dtas-player_protocol(7)> for more info. (e.g. "-ts32 -c2 -r44100")
+
+=item TRIMFX
+
+The sox effect used for seeking during playback with dtas-player
+and track offsets for dtas-splitfx.  (e.g. "trim 36000s")
+
+Additionally, L<dtas-splitfx(1)> documents more environment variables
+which are not used elsewhere.
+
+=back
+
+=head1 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 L<sox(1)>
+and L<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.
+
+=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.
+
+=head1 COPYRIGHT
+
+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>