From 3083b7fbe2bc6e8dcd935b10bb7a165257c5252b Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Mon, 18 Jan 2016 05:18:09 +0000 Subject: doc: convert to perlpod(1) from Markdown 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. --- Documentation/.gitignore | 1 + Documentation/GNUmakefile | 29 +- Documentation/dtas-archive.pod | 74 +++++ Documentation/dtas-archive.txt | 62 ---- Documentation/dtas-console.pod | 94 ++++++ Documentation/dtas-console.txt | 73 ----- Documentation/dtas-ctl.pod | 78 +++++ Documentation/dtas-ctl.txt | 76 ----- Documentation/dtas-cueedit.pod | 38 +++ Documentation/dtas-cueedit.txt | 36 --- Documentation/dtas-enq.pod | 43 +++ Documentation/dtas-enq.txt | 41 --- Documentation/dtas-env.pod | 75 +++++ Documentation/dtas-env.txt | 60 ---- Documentation/dtas-msinkctl.pod | 61 ++++ Documentation/dtas-msinkctl.txt | 57 ---- Documentation/dtas-player.pod | 126 ++++++++ Documentation/dtas-player.txt | 125 -------- Documentation/dtas-player_effects.pod | 103 +++++++ Documentation/dtas-player_effects.txt | 57 ---- Documentation/dtas-player_protocol.pod | 454 ++++++++++++++++++++++++++++ Documentation/dtas-player_protocol.txt | 326 -------------------- Documentation/dtas-player_sink_examples.pod | 87 ++++++ Documentation/dtas-player_sink_examples.txt | 83 ----- Documentation/dtas-sinkedit.pod | 79 +++++ Documentation/dtas-sinkedit.txt | 69 ----- Documentation/dtas-sourceedit.pod | 86 ++++++ Documentation/dtas-sourceedit.txt | 77 ----- Documentation/dtas-splitfx.pod | 271 +++++++++++++++++ Documentation/dtas-splitfx.txt | 188 ------------ Documentation/dtas-tl.pod | 122 ++++++++ Documentation/dtas-tl.txt | 96 ------ Documentation/dtas-xdelay.pod | 96 ++++++ Documentation/dtas-xdelay.txt | 76 ----- Documentation/update-footer.rb | 24 +- 35 files changed, 1926 insertions(+), 1517 deletions(-) create mode 100644 Documentation/dtas-archive.pod delete mode 100644 Documentation/dtas-archive.txt create mode 100644 Documentation/dtas-console.pod delete mode 100644 Documentation/dtas-console.txt create mode 100644 Documentation/dtas-ctl.pod delete mode 100644 Documentation/dtas-ctl.txt create mode 100644 Documentation/dtas-cueedit.pod delete mode 100644 Documentation/dtas-cueedit.txt create mode 100644 Documentation/dtas-enq.pod delete mode 100644 Documentation/dtas-enq.txt create mode 100644 Documentation/dtas-env.pod delete mode 100644 Documentation/dtas-env.txt create mode 100644 Documentation/dtas-msinkctl.pod delete mode 100644 Documentation/dtas-msinkctl.txt create mode 100644 Documentation/dtas-player.pod delete mode 100644 Documentation/dtas-player.txt create mode 100644 Documentation/dtas-player_effects.pod delete mode 100644 Documentation/dtas-player_effects.txt create mode 100644 Documentation/dtas-player_protocol.pod delete mode 100644 Documentation/dtas-player_protocol.txt create mode 100644 Documentation/dtas-player_sink_examples.pod delete mode 100644 Documentation/dtas-player_sink_examples.txt create mode 100644 Documentation/dtas-sinkedit.pod delete mode 100644 Documentation/dtas-sinkedit.txt create mode 100644 Documentation/dtas-sourceedit.pod delete mode 100644 Documentation/dtas-sourceedit.txt create mode 100644 Documentation/dtas-splitfx.pod delete mode 100644 Documentation/dtas-splitfx.txt create mode 100644 Documentation/dtas-tl.pod delete mode 100644 Documentation/dtas-tl.txt create mode 100644 Documentation/dtas-xdelay.pod delete mode 100644 Documentation/dtas-xdelay.txt (limited to 'Documentation') diff --git a/Documentation/.gitignore b/Documentation/.gitignore index fc2662e..99e2662 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -3,3 +3,4 @@ *.1 *.5 *.7 +*.txt diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile index 88df59e..783cc82 100644 --- a/Documentation/GNUmakefile +++ b/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,20 @@ 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 $@+ $@ + +all :: $(mantxt) + +mantxt = $(addsuffix .txt, $(m1) $(m7)) + +%.txt : %.pod + $(pod2text) $< $@+ && mv $@+ $@ clean:: $(RM) $(man1) $(man7) + $(RM) $(addsuffix .txt.gz, $(m1) $(m7)) diff --git a/Documentation/dtas-archive.pod b/Documentation/dtas-archive.pod new file mode 100644 index 0000000..38f5570 --- /dev/null +++ b/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 can be used to +drop caches for a particular file after L. + +dtas-archive spawns L to archive audio data (likely uncompressed +WAVE) to FLAC and verifies the result using L, 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 check. Default: 1 + +=back + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 CONTACT + +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 SEE ALSO + +L, L diff --git a/Documentation/dtas-archive.txt b/Documentation/dtas-archive.txt deleted file mode 100644 index fdc818d..0000000 --- a/Documentation/dtas-archive.txt +++ /dev/null @@ -1,62 +0,0 @@ -% dtas-archive(1) dtas user manual -% - -# NAME - -dtas-archive - paranoid audio file copy - -# SYNOPSYS - -dtas-archive [OPTIONS] SOURCE DESTINATION - -# 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 posix_fadvise(2) can be used to -drop caches for a particular file after fsync(2). - -dtas-archive spawns sox(1) to archive audio data (likely uncompressed -WAVE) to FLAC and verifies the result using sndfile-cmp(1), a tool -implemented by different than sox and less likely to share the same bugs -(if any) as sox. - -# OPTIONS - --j, \--jobs [JOBS] -: Number of jobs to run in parallel. Incrementing this may hurt - performance on slow storage devices. Default: 1 - --n, \--dry-run -: Print, but do not run the commands to be executed - --s, \--quiet, \--silent -: Silent operation, commands are not printed as executed - --S, \--stats -: Run and save the text output of the sox "stats" effect as - $DESTINATION_FILE_WITHOUT_SUFFIX.stats next to the output file - --k, \--keep-going -: Continue after error - --r, \--repeat [COUNT] -: Number of times to repeat the sndfile-cmp(1) check. Default: 1 - -# COPYRIGHT - -Copyright 2015-2016 all contributors .\ -License: GPL-3.0+ - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# SEE ALSO - -sndfile-cmp(1), sox(1) diff --git a/Documentation/dtas-console.pod b/Documentation/dtas-console.pod new file mode 100644 index 0000000..e7b980c --- /dev/null +++ b/Documentation/dtas-console.pod @@ -0,0 +1,94 @@ +% L 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 for a detailed description of the protocol. + +=head1 KEYBOARD CONTROL + +Key bindings are inspired partially by L + +=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 + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L, L, +L, L diff --git a/Documentation/dtas-console.txt b/Documentation/dtas-console.txt deleted file mode 100644 index 7468ba6..0000000 --- a/Documentation/dtas-console.txt +++ /dev/null @@ -1,73 +0,0 @@ -% dtas-console(1) dtas user manual - -# NAME - -dtas-console - rudimentary curses console client for dtas-player - -# SYNOPSIS - -dtas-console - -# 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 dtas-player_protocol(7) for a detailed description of the protocol. - -# KEYBOARD CONTROL - -Key bindings are inspired partially by mplayer(1) - -- 'j'/'k' - seek backward/forward 5 seconds -- LEFT/RIGHT - seek backward/forward 10 seconds -- UP/DOWN - seek forward/backward 1 minute -- PGUP/PGDWN - seek forward/backward 10 minutes -- SPACE - toggle play/pause state of the playback -- 'p'/'P' - decrease/increase timer resolution -- BACKSPACE - seek to the beginning of the track -- 7/8 - decrease/increase ReplayGain preamp -- 9/0 - decrease/increase software volume -- '=' - set software volume to 1.0 (no adjustment) -- 'm' - mute set software volume to 0.0 (mute) -- 'f'/'F' - decrease/increase ReplayGain fallback_gain value -- 'r'/'R' - cycle forward/backwards through ReplayGain modes -- 'q'/Ctrl-C - exit dtas-console -- 'o' - toggle display between HH:MM:SS and absolute seconds - -# ENVIRONMENT - -DTAS_PLAYER_SOCK - the path to the dtas-player control socket. -This defaults to ~/.dtas/player.sock - -# 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. - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -dtas-player(1), dtas-player_protocol(7), dtas-ctl(1), dtas-sinkedit(1), -dtas-sourceedit(1) diff --git a/Documentation/dtas-ctl.pod b/Documentation/dtas-ctl.pod new file mode 100644 index 0000000..771f6b2 --- /dev/null +++ b/Documentation/dtas-ctl.pod @@ -0,0 +1,78 @@ +% dtas-ctl(1) dtas user manual + +=head1 NAME + +dtas-ctl - low-level client for dtas-player + +=head1 SYNOPSYS + +dtas-ctl [ARGS...] + +=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 L for a detailed description of the protocol. + +=head1 EXAMPLES + +display the currently playing track + + $ dtas-ctl current + +enqueue a file for playback (L is easier to use, here) + + $ dtas-ctl enq /absolute/path/to/file + +toggle the play/pause state of the player + + $ dtas-ctl play_pause + +change the ReplayGain mode + + $ dtas-ctl rg mode=album_gain + # "track_gain", "off" may be used, too + +seek 5 seconds forward + + $ dtas-ctl seek +5 + +seek to an absolute position + + $ dtas-ctl seek 1:00 + +skip to the next track + + $ dtas-ctl skip + +To play the output of an arbitrary command (note the quotes) and usage +of $SOXFMT (see L). + + $ dtas-ctl enq-cmd 'sox -n $SOXFMT - synth 3 pluck' + +=head1 ENVIRONMENT + +DTAS_PLAYER_SOCK - the path to the dtas-player control socket. +This defaults to ~/.dtas/player.sock + +=head1 CONTACT + +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L, L, +L, L diff --git a/Documentation/dtas-ctl.txt b/Documentation/dtas-ctl.txt deleted file mode 100644 index b2cf20b..0000000 --- a/Documentation/dtas-ctl.txt +++ /dev/null @@ -1,76 +0,0 @@ -% dtas-ctl(1) dtas user manual -% - -# NAME - -dtas-ctl - low-level client for dtas-player - -# SYNOPSYS - -dtas-ctl [ARGS...] - -# 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. - -# EXAMPLES - -display the currently playing track - - $ dtas-ctl current - -enqueue a file for playback (dtas-enq(1) is easier to use, here) - - $ dtas-ctl enq /absolute/path/to/file - -toggle the play/pause state of the player - - $ dtas-ctl play_pause - -change the ReplayGain mode - - $ dtas-ctl rg mode=album_gain - # "track_gain", "off" may be used, too - -seek 5 seconds forward - - $ dtas-ctl seek +5 - -seek to an absolute position - - $ dtas-ctl seek 1:00 - -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)). - - $ dtas-ctl enq-cmd 'sox -n $SOXFMT - synth 3 pluck' - -# ENVIRONMENT - -DTAS_PLAYER_SOCK - the path to the dtas-player control socket. -This defaults to ~/.dtas/player.sock - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -dtas-player(1), dtas-player_protocol(7), dtas-enq(1), dtas-sinkedit(1), -dtas-sourceedit(1) diff --git a/Documentation/dtas-cueedit.pod b/Documentation/dtas-cueedit.pod new file mode 100644 index 0000000..669374b --- /dev/null +++ b/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 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 + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L diff --git a/Documentation/dtas-cueedit.txt b/Documentation/dtas-cueedit.txt deleted file mode 100644 index 2fc0510..0000000 --- a/Documentation/dtas-cueedit.txt +++ /dev/null @@ -1,36 +0,0 @@ -% dtas-cueedit(1) dtas user manual -% - -# NAME - -dtas-cueedit - edit embedded cuesheets in audio files - -# SYNOPSYS - -dtas-cueedit /path/to/audio.flac - -# 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 metaflac(1) is required. - -# ENVIRONMENT - -VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset. - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -metaflac(1) diff --git a/Documentation/dtas-enq.pod b/Documentation/dtas-enq.pod new file mode 100644 index 0000000..2611a2e --- /dev/null +++ b/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 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 + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L diff --git a/Documentation/dtas-enq.txt b/Documentation/dtas-enq.txt deleted file mode 100644 index eecb62e..0000000 --- a/Documentation/dtas-enq.txt +++ /dev/null @@ -1,41 +0,0 @@ -% 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(1). dtas-player will start playing the -newly enqueued files in the order given. - -# EXAMPLE - - $ dtas-enq /path/to/your/favorite/album/*.flac - -# ENVIRONMENT - -DTAS_PLAYER_SOCK - the path to the dtas-player listen socket. -This defaults to ~/.dtas/player.sock - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -dtas-player(1), dtas-ctl(1) diff --git a/Documentation/dtas-env.pod b/Documentation/dtas-env.pod new file mode 100644 index 0000000..b16da35 --- /dev/null +++ b/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 +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 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 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 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 +and L 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 + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L diff --git a/Documentation/dtas-env.txt b/Documentation/dtas-env.txt deleted file mode 100644 index 8cbbd0a..0000000 --- a/Documentation/dtas-env.txt +++ /dev/null @@ -1,60 +0,0 @@ -% 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. "gain -6.0"). -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: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2015-2016 all contributors .\ -License: GPL-3.0+ diff --git a/Documentation/dtas-msinkctl.pod b/Documentation/dtas-msinkctl.pod new file mode 100644 index 0000000..b7116ac --- /dev/null +++ b/Documentation/dtas-msinkctl.pod @@ -0,0 +1,61 @@ +% dtas-msinkctl(1) dtas user manual + +=head1 NAME + +dtas-msinkctl - activate/deactivate multiple sinks at once + +=head1 SYNOPSYS + +dtas-msinkctl COMMAND +dtas-msinkctl COMMAND [SINKS...] + +=head1 DESCRIPTION + +dtas-msinkctl is useful for activating/deactivating multiple sinks. + +=head1 EXAMPLES + +Display only active sinks (unlike "dtas-ctl sink ls", which shows all sinks) + + dtas-msinkctl active + +Display only non-blocking sinks + + dtas-msinkctl nonblock + +Enable only SINK1 and SINK3, and close other sinks + + dtas-msinkctl active-set SINK1 SINK3 + +Add the default sink to the active set + + dtas-msinkctl active-add default + +Remove SINK3 from the active set + + dtas-msinkctl active-add SINK3 + +=head1 ENVIRONMENT + +DTAS_PLAYER_SOCK - the path to the dtas-player control socket. +This defaults to ~/.dtas/player.sock + +=head1 CONTACT + +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L, L, +L diff --git a/Documentation/dtas-msinkctl.txt b/Documentation/dtas-msinkctl.txt deleted file mode 100644 index 01a43c5..0000000 --- a/Documentation/dtas-msinkctl.txt +++ /dev/null @@ -1,57 +0,0 @@ -% dtas-msinkctl(1) dtas user manual - -# NAME - -dtas-msinkctl - activate/deactivate multiple sinks at once - -# SYNOPSYS - -dtas-msinkctl COMMAND -dtas-msinkctl COMMAND [SINKS...] - -# DESCRIPTION - -dtas-msinkctl is useful for activating/deactivating multiple sinks. - -# EXAMPLES - -Display only active sinks (unlike "dtas-ctl sink ls", which shows all sinks) - - dtas-msinkctl active - -Display only non-blocking sinks - - dtas-msinkctl nonblock - -Enable only SINK1 and SINK3, and close other sinks - - dtas-msinkctl active-set SINK1 SINK3 - -Add the default sink to the active set - - dtas-msinkctl active-add default - -Remove SINK3 from the active set - - dtas-msinkctl active-add SINK3 - -# ENVIRONMENT - -DTAS_PLAYER_SOCK - the path to the dtas-player control socket. -This defaults to ~/.dtas/player.sock - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -dtas-player(1), dtas-player_protocol(7), dtas-ctl(1), dtas-sinkedit(1) 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 + +=head1 DESCRIPTION + +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 or L is recommended. + +By default, dtas-player uses the L command to decode audio, and +pipes the data to a L 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 +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. + +=head1 TROUBLESHOOTING + +=head2 Audio playback does not start + +The most common problem with dtas-player is the L command +(distributed with SoX) not using the correct audio device/driver. +Ensuring the L command works with dtas-player is important. +Consult SoX documentation and mailing lists for getting L to work, +first. + +Once you find the correct AUDIODEV/AUDIODRIVER environment variables, +you may set them via L: + +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 or L 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 + +=head1 ADVANCED EXAMPLES + +See L for more sink examples. + +=head1 ENVIRONMENT + +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: + + * REPLAYGAIN_TRACK_GAIN + * REPLAYGAIN_ALBUM_GAIN + * REPLAYGAIN_ALBUM_PEAK + * REPLAYGAIN_TRACK_PEAK + +=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 + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L, L, +L, L, L, L, +L, L, L, L diff --git a/Documentation/dtas-player.txt b/Documentation/dtas-player.txt deleted file mode 100644 index c8a17df..0000000 --- a/Documentation/dtas-player.txt +++ /dev/null @@ -1,125 +0,0 @@ -% dtas-player(1) dtas user manual -% - -# NAME - -dtas-player - playback process for dtas - -# SYNOPSYS - -dtas-player - -# DESCRIPTION - -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 -screen(1) or tmux(1) is recommended. - -By default, dtas-player uses the sox(1) command to decode audio, and -pipes the data to a 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 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. - -# 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. - -# TROUBLESHOOTING - - - -## Audio playback does not start - -The most common problem with dtas-player is the play(1) command -(distributed with SoX) not using the correct audio device/driver. -Ensuring the play(1) command works with dtas-player is important. -Consult SoX documentation and mailing lists for getting play(1) to work, -first. - -Once you find the correct AUDIODEV/AUDIODRIVER environment variables, -you may set them via 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 - -## 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 avconv(1) or 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 - -# ADVANCED EXAMPLES - -See dtas_player-sink_examples(7) for more sink examples. - -# ENVIRONMENT - -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: - - * REPLAYGAIN_TRACK_GAIN - * REPLAYGAIN_ALBUM_GAIN - * REPLAYGAIN_ALBUM_PEAK - * REPLAYGAIN_TRACK_PEAK - -# FILES - -~/.dtas/player_state.yml is a human-readable YAML file used to preserve -state across restarts of dtas-player. - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -dtas-player_protocol(7), dtas-ctl(1), dtas-enq(1), dtas-sourceedit(1), -dtas-sinkedit(1), sox(1), play(1), avconv(1), ffmpeg(1), screen(1), tmux(1) diff --git a/Documentation/dtas-player_effects.pod b/Documentation/dtas-player_effects.pod new file mode 100644 index 0000000..149834a --- /dev/null +++ b/Documentation/dtas-player_effects.pod @@ -0,0 +1,103 @@ +% dtas-player_effects(7) dtas user manual + +=head1 NAME + +L effects overview + +=head1 DESCRIPTION + +Effects in dtas-player may be applied either at the source or the sink. +They are applied in the order described. + +=over + +=item 1. source effects + +Source effects are effects which should be applied per-source and do not +rely on inter-track information. + +Examples include: + +=over + +=item ReplayGain (simple gain changes) + +=item anything which does not change the length of the audio: + +gain, stereo, highpass, lowpass, loudness, bass, treble, equalizer, ... + +=back + +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. + +=item 2. sink effects + +Sink effects are any effects which: + +=over + +=item 1) should only be applied to a specific sink + +=item 2) effects which require inter-track information + +(multiband delays/compressors/expanders) + +=item 3) alter the length of the audio + +=back + +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: + +=over + +=item equalizer effects (highpass/bass/treble/equalizer) + +=item loudness + +=item delaying a certain channel or frequency range for time-alignment + +=item compressors/limiters + +=item reverb + +=item gain + +=item remix (for stereo image adjustments) + +=back + +Additionally, effects which are necessary due to the limitation of the +playback hardware are applied at the sink: + +=over + +=item rate + +=item dither + +=item remix (static channel mappings) + +=back + +=back + +=head1 CONTACT + +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L diff --git a/Documentation/dtas-player_effects.txt b/Documentation/dtas-player_effects.txt deleted file mode 100644 index 91e846c..0000000 --- a/Documentation/dtas-player_effects.txt +++ /dev/null @@ -1,57 +0,0 @@ -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 gain changes) - - anything which does not change the length of the audio: - gain, 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 - - gain - - 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) - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ diff --git a/Documentation/dtas-player_protocol.pod b/Documentation/dtas-player_protocol.pod new file mode 100644 index 0000000..cb2d07a --- /dev/null +++ b/Documentation/dtas-player_protocol.pod @@ -0,0 +1,454 @@ +% dtas-player_protocol(7) dtas user manual + +=head1 NAME + +dtas-player_protocol - protocol for controling dtas-player + +=head1 DESCRIPTION + +NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE + +I'm considering a heavy revamp of this protocol. The "OK" responses for +a lot of commands may not be necessary since this is Unix sockets and +not TCP, and I may move away from a request-response model and towards +an entirely listen/notification model. I have little experience in +non-TCP-based application protocols, so this is an area of +experimentation for me. + +This must stay over Unix sockets because filesystem permissions are +needed to enforce code execution permissions. dtas-player is really a +shell in disguise, after all. + +Protocol feedback greatly appreciated, email us at L + +This gives a specification of the dtas-player protocol over a local Unix +SOCK_SEQPACKET socket. The dtas-player protocol should NOT be +considered stable at this point and compatibility will break. + +Inspiration is taken from MPRIS and MPRIS 2.0 specifications (e.g. +play_pause, play, pause), and there will be a proxy in the future to +support MPRIS/MPRIS 2.0 clients. + +The DTAS_PLAYER_SOCK is the standard environment determining the control +socket for L. This defaults to $HOME/.dtas/player.sock +if unset. + +Most low-level commands may be issued using the L command. + +Higher-level commands such as L, L, +L, and L also implement this protocol. + +=head1 ARGUMENT TYPES + +=over + +=item BOOLEAN - must be "true" or "false" + +=item INTEGER - a signed integer in decimal notation (base 10) + +=item UNSIGNED - an unsigned integer in decimal or hex notation + +=item ENVNAME - must be a suitable environment variable (setenv(3)) + +=item ENVVALUE - must be a suitable environment variable (setenv(3)) + +=item COMMAND - command to run + +This may be quoted string passed to sh -c "". +Variable/argument expansion will be performed by the shell + +=item SOURCENAME - "sox" or "av", more backends may be supported in the future + +=item TIMESTAMP - a time stamp formatted in HH:MM:SS.FRAC (for seeking) + +=item TRACKID - a unique unsigned integer in decimal (base-10) + +This represents a track in the tracklist + +=item FILENAME + +An expanded pathname relative to / is recommended since +dtas-player and the client may run in different directories + +=back + +=head1 VARIABLE EXPANSION + +For source and sink "command" arguments, the $SOXFMT and $ECAFMT +environment variables are exported automatically to source to ease +integration with L and L. + +Both $SOXFMT and $ECAFMT are based on the configured "format" of +the dtas-player (see below). + +For all machines, $SOXFMT defaults to: -ts32 -c2 -r44100 +For little-endian machines, $ECAFMT defaults to: -fs32_le,2,44100 + +=head1 COMMANDS + +Commands here should be alphabetized according to `LC_ALL=C sort' + +=over + +=item cd - change the current working directory of the player + +=item clear - clear current queue (current track/command continues running) + +PENDING: this may be renamed to "queue clear" or "queue-clear" + +=item cue - display the index/offsets of the embedded cue sheet + +=item cue next - skip to the next cue sheet offset + +This may skip to the next track if there is +no embedded cue sheet or if playing the last (embedded) track + +=item cue prev - skip to the previous cue sheet offset + +This may just seek to the beginning +if there is no embedded cue sheet or if we are playing the first +(embedded) track. + +=item cue goto INTEGER - go to the cue index denoted by INTEGER + +0 is first track as returned by "cue". +Negative values of INTEGER allows selecting track relative to the last +track (-1 is the last track, -2 is the penultimate, and so on). + +=item current - output information about the current track/command in YAML + +The structure of this is unstable and subject to change. + +=item 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. +PENDING: this may be renamed to "queue add" + +=item enq-cmd "COMMAND" - run the following command for playback + +The COMMAND is expected to output audio in the audio format matching +the current audio format of the player. This may be a shell pipeline +and include multiple commands. The $SOXFMT and $ECAFMT variables are +available here. +PENDING: this may be renamed to "queue add-cmd" + +=item env ENVTOSET=ENVVALUE ENVTOSET2=ENVVALUE2 + +Set environment variables. This affects all future source/sink +processes as well as helper commands dtas-player may spawn +(e.g. L). Environment variables set this way are currently not +preserved across invocations of L, but may change in the +future. + +=item env ENVTOUNSET1# ENVTOUNSET# + +Unset the given environment variable. +PENDING: the '#' is ugly and inconsistent with the per-sink/source. +env. + +=item format FORMATARGS - configure the format between source and sink + +Changing this will affect the $SOXFMT and $ECAFMT environments passed +to source and sink commands. Changing this implies a "restart" +Changing rate to 48000 is probably useful if you plan on playing to some +laptop sound cards. In all cases where "bypass" is supported, it +removes the guarantee of gapless playback as the audio device(s) +will likely need to be restarted. + +=over + +=item channels=(UNSIGNED|bypass) - (default: 2 (stereo)) + +number of channels to use internally. sox will internally invoke the remix +effect when decoding. This supports the value "bypass" (without +quotes) to avoid the automatic remix effect. Using "bypass" mode +removes the guarantee of gapless playback, as the audio device will +likely need to be restarted, introducing an audible gap. + +=item endian=(big|little|swap) - (default: native) + +there is probably no +point in changing this unless you output over a network sink to +a machine of different endianess. + +=item bits=(UNSIGNED|bypass) - (default: implied from type) + +Sample precision (decoded). +This may be pointless and removed in the future, since the sample +precision is implied from type. This supports the value of "bypass" +to avoid dither/truncation in later stages. + +=item rate=(UNSIGNED|bypass) - (default: 44100) - sample rate of audio + +Typical values of rate are 44100, 48000, 88200, 96000. Not all +DSP effects are compatible with all sampling rates/channels. +This supports the value of "bypass" as well to avoid introducing +software resamplers into the playback chain. + +=item type=(s16|s24|s32|u16|u24|u32|f32|f64) - (default: s32) + +Change the raw PCM format. s32 currently offers the best performance +when only sox/play are used. f32 may offer better performance if +piping to/from non-sox applications (e.g. ecasound) + +=back + +=item pause - pause playback + + Player pause state is preserved across dtas-player invocations. + +=item play - restart playback from pause + +Playback sinks will yield control of the audio playback device once no +source is playing. + +=item play_pause - toggle the play/pause state + +This starts playback if paused, and pauses playback if playing. + +=item queue cat - dump the contents of the queue as YAML + +This may include arbitrary commands to be executed, filenames, +and offsets for playback. The format is not intended to be +stable and subject to internal changes in dtas-player. + +=item restart - restarts all processes in the current pipeline + +Playback will be momentarily interrupted while this change occurs. This is +necessary if one of the commands (e.g. sox or ecasound) or loaded +libraries (e.g. a LADSPA plugin) is upgraded. Use "source restart" +instead to only restart the source chain, leaving the sinks +untouched. + +=item rg RGARGS - configure ReplayGain support + +All FLOAT values may be adjusted via '+=' or '-=' instead of simple +assignment ('='). If RGARGS is empty, the current rg state of +non-default values will be dumped in YAML. + +=over + +=item fallback_gain=FLOAT (-6.0) - dB value + +Adjust the volume by this level (usually negative) for tracks +missing ReplayGain tags. This is useful when the queue contains +a mix of tracks with and without ReplayGain tags. + +=item fallback_track=BOOLEAN (true) + +When in album_gain mode, fallback to track_gain if the +REPLAYGAIN_ALBUM_GAIN metadata is missing. + +=item mode=(album_gain|track_gain|track_norm|album_norm|off) + +This controls the ReplayGain tag to use. The *_norm options +are used for peak normalization and not commonly found in other +players. + +=item preamp=FLOAT (0) - dB value + +Adjust the album_gain or track_gain amount by this value (in dB). + +=item norm_level=FLOAT (1.0 == dBFS) + +Controls the level to normalize to when using album_norm or track_norm. + +=back + +=item seek [+-]TIMESTAMP - seek the current track to a specified time. + +This is passed directly as the first argument for the L "trim" +command. See the L manpage for details. +Seeking to a relative time is also supported by prefixing the time +with '+' or '-' + +=item skip - abort current track/command + +This is accomplished via closing the output pipe. +Running the "clear" command before this will abort playback. + +=item sink ls - list names of current sinks + +=item sink cat SINKNAME - dump SINKNAME config in YAML + +=item sink rm SINKNAME - remove SINKNAME + +=item sink ed SINKNAME SINKARGS - create/edit SINKNAME + +This currently does not restart running (active) sinks. +This will stop active sinks if active is set to false, and start +active sinks if active is set to true. +See dtas-sinkedit(1) for an example of using this. + +=over + +=item command=COMMAND - change the command-line used for playback + +=item active=BOOLEAN - whether or not the sink will be in use (default: false) + +=item env.ENVNAME=ENVVALUE - set ENVNAME to ENVVALUE for the sink process + +=item env#ENVNAME - unset ENVNAME in the sink process (only) + +=item prio=INTEGER - priority of the sink, lower values run first + +=item nonblock=BOOLEAN - drop audio data to avoid holding back other sinks + +=item pipe_size=UNSIGNED - set the size of the pipe for the sink (Linux-only) + +=back + +=item source cat SOURCENAME - dump the current source command and env in YAML + +=item source ed SOURCENAME SOURCEARGS - edit the source parameters. + +This changes here will immediately restart the source process. +See the code for dtas-sourceedit(1) for an example of using this. + +=over + +=item command=COMMAND - change the command-line used to decode audio + +=item env.ENVNAME=ENVVALUE - set ENVNAME to ENVVALUE for the source process + +=item env#ENVNAME - unset ENVNAME in the source process (only) + +=item tryorder=INTEGER - lower values are tried first + +=back + +PENDING: tryorder here is wrong and may be removed or changed. +We need to account for at least two variables input file: + +=over + +=item 1. input type (flac/opus/mp3/etc) + +=item 2. transport protocol (local FS/http/ftp/sftp/etc) + +=back + +=item source ls + +Dump the names of sources sorted by tryorder + +=item source restart + +Restart the current source command. +This can be useful if the source file is changed during playback +and the current player process is holding onto an unlinked inode. +This is advantageous over a full "restart" as there is no audible +gap on most systems. + +=item state dump [FILENAME] + +Immediately dump the state of the player. If a FILENAME is specified, +the state is written to that file. Otherwise, the default state file +(configured via DTAS_PLAYER_STATE environment variable, defaulting +to ~/.dtas/player_state.yml) is written to. This does not use +L, users requiring fsync should L that file and +L it themselves if necessary. + +=item tl add FILENAME [TRACKID [BOOLEAN]] + +Add files to the tracklist with one arg, adds FILENAME to the head +of the tracklist. +If TRACKID is specified, FILENAME is added immediately after TRACKID +on the existing tracklist. The final BOOLEAN argument replaces the +currently playing track with the newly-added one. +Returns the TRACKID of the newly added track + +=item tl clear + +Clear current tracklist + +=item tl current + +Display the pathname to the currently playing track + +=item tl current-id + +Display the TRACKID of the currently playing track + +=item tl remove TRACKID + +Remove the track with the given TRACKID from +the track list and returns the FILENAME if successful + +=item tl get [TRACKIDS] + +Returns a list of TRACKIDS mapped to shell-escaped filenames. + +=item tl goto TRACKID [TIMESTAMP] + +Plays the given TRACKID. +An optional timestamp may be added to prevent playing the +same part(s) repeatedly + +=item tl max [MAXIMUM] + +Sets or gets the maximum number of tracks allowed in the tracklist + +=item tl next + +Jump to the next track in the tracklist + +=item tl prev + +Jump to the previous track in the tracklist + +=item tl repeat [BOOLEAN|1] + +Show/or change repeat status of the tracklist. +With no args, this will show "true", "false", or "1" +If set to "1", dtas-player will repeat the current track. +Returns the previous repeat status. + +=item tl shuffle [BOOLEAN] + +Show/or change the current shuffle status of the tracklist. +Returns the previous shuffle status. + +=item tl swap TRACKID_A TRACKID_B + +Swaps the positions of two tracks. + +=item tl tracks + +Returns a list of all TRACKIDS in the tracklist + +=item trim [off|TBEG [TLEN]] + +Limits playback of all tracks in the tracklist to the time starting +at TBEG and ending after TLEN has elapsed. Not specifying TLEN will +cause sox. Like the sox "trim" effect, prefixing TLEN with a '=' +will be interpreted as an absolute stop time. +Both TBEG and TLEN should be specified in seconds, not sample counts. +Specifying "off" (without quotes) disables trim. +This feature is intended to allow users to "zoom-in" on a particular +portion of a track to tweak parameters (either with +L or via playback of splitfx YAML files) and often +combined with looping the tracklist (via "tl repeat"). + +=item watch - adds the client to the passive watch list for notifications. + +It is recommended clients issue no further commands and open +another client socket to issue non-watch commands. + +=back + +=head1 CONTACT + +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L diff --git a/Documentation/dtas-player_protocol.txt b/Documentation/dtas-player_protocol.txt deleted file mode 100644 index 9efd0a1..0000000 --- a/Documentation/dtas-player_protocol.txt +++ /dev/null @@ -1,326 +0,0 @@ -% dtas-player_protocol(7) dtas user manual -% - -# NAME - -dtas-player_protocol - protocol for controling dtas-player - -# DESCRIPTION - -NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - -I'm considering a heavy revamp of this protocol. The "OK" responses for -a lot of commands may not be necessary since this is Unix sockets and -not TCP, and I may move away from a request-response model and towards -an entirely listen/notification model. I have little experience in -non-TCP-based application protocols, so this is an area of -experimentation for me. - -This must stay over Unix sockets because filesystem permissions are -needed to enforce code execution permissions. dtas-player is really a -shell in disguise, after all. - -Protocol feedback greatly appreciated, email us at dtas-all@nongnu.org - -********************************************************* - -This gives a specification of the dtas-player protocol over a local Unix -SOCK_SEQPACKET socket. The dtas-player protocol should NOT be -considered stable at this point and compatibility will break. - -Inspiration is taken from MPRIS and MPRIS 2.0 specifications (e.g. -play_pause, play, pause), and there will be a proxy in the future to -support MPRIS/MPRIS 2.0 clients. - -The DTAS_PLAYER_SOCK is the standard environment determining the control -socket for dtas-player(1). This defaults to $HOME/.dtas/player.sock if -unset. - -Most low-level commands may be issued using the dtas-ctl(1) command. - -Higher-level commands such as dtas-console(1), dtas-sourceedit(1), -dtas-sinkedit(1), and dtas-enq(1) also implement this protocol. - -# 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 -- SOURCENAME - "sox" or "av", more backends may be supported in the future -- TIMESTAMP - a time stamp formatted in HH:MM:SS.FRAC (for seeking) -- TRACKID - a unique unsigned integer in decimal (base-10) representing a - track in the tracklist -- FILENAME - an expanded pathname relative to / is recommended since - dtas-player and the client may run in different directories - -# VARIABLE EXPANSION - -For source and sink "command" arguments, the $SOXFMT and $ECAFMT -environment variables are exported automatically to source to ease -integration with sox(1) and ecasound(1). - -Both $SOXFMT and $ECAFMT are based on the configured "format" of -the dtas-player (see below). - -For all machines, $SOXFMT defaults to: -ts32 -c2 -r44100 -For little-endian machines, $ECAFMT defaults to: -fs32_le,2,44100 - -# COMMANDS - -Commands here should be alphabetized according to `LC_ALL=C sort' - -* cd - change the current working directory of the player - -* clear - clear current queue (current track/command continues running) - PENDING: this may be renamed to "queue clear" or "queue-clear" - -* cue - display the index/offsets of the file based on the embedded - cue sheet, if any - -* cue next - skip to the next section of the track based on the - embedded cue sheet. This may skip to the next track if there is - no embedded cue sheet or if playing the last (embedded) track - -* cue prev - skip to the previous section of the track based on - the embedded cue sheet. This may just seek to the beginning - if there is no embedded cue sheet or if we are playing the first - (embedded) track. - -* cue goto INTEGER - go to the embedded track with cue index denoted - by INTEGER (0 is first track as returned by "cue"). Negative - values of INTEGER allows selecting track relative to the last - track (-1 is the last track, -2 is the penultimate, and so on). - -* current - output information about the currently-playing track/command - in YAML. The structure of this is unstable and subject to change. - -* 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. - PENDING: this may be renamed to "queue add" - -* enq-cmd "COMMAND" - run the following command for playback. - The COMMAND is expected to output audio in the audio format matching - the current audio format of the player. This may be a shell pipeline - and include multiple commands. The $SOXFMT and $ECAFMT variables are - available here. - PENDING: this may be renamed to "queue add-cmd" - -* env ENVTOSET=ENVVALUE ENVTOSET2=ENVVALUE2 - Set environment variables. This affects all future source/sink - processes as well as helper commands dtas-player may spawn - (e.g. soxi(1)). Environment variables set this way are currently not - preserved across invocations of dtas-player(1), but may change in the - future. - -* env ENVTOUNSET1# ENVTOUNSET# - Unset the given environment variable. - PENDING: the '#' is ugly and inconsistent with the per-sink/source. - env. - -* format FORMATARGS - configure the format between source and sink - Changing this will affect the $SOXFMT and $ECAFMT environments passed - to source and sink commands. Changing this implies a "restart" - Changing rate to 48000 is probably useful if you plan on playing to some - laptop sound cards. In all cases where "bypass" is supported, it - removes the guarantee of gapless playback as the audio device(s) - will likely need to be restarted. - - - + channels=(UNSIGNED|bypass) - (default: 2 (stereo)) - number of - channels to use internally. sox will internally invoke the remix - effect when decoding. This supports the value "bypass" (without - quotes) to avoid the automatic remix effect. Using "bypass" mode - removes the guarantee of gapless playback, as the audio device will - likely need to be restarted, introducing an audible gap. - + endian=(big|little|swap) - (default: native) - there is probably no - point in changing this unless you output over a network sink to - a machine of different endianess. - + bits=(UNSIGNED|bypass) - (default: implied from type) - sample precision - (decoded) - This may be pointless and removed in the future, since the sample - precision is implied from type. This supports the value of "bypass" - to avoid dither/truncation in later stages. - + rate=(UNSIGNED|bypass) - (default: 44100) - sample rate of audio - Typical values of rate are 44100, 48000, 88200, 96000. Not all - DSP effects are compatible with all sampling rates/channels. - This supports the value of "bypass" as well to avoid introducing - software resamplers into the playback chain. - + type=(s16|s24|s32|u16|u24|u32|f32|f64) - (default: s32) - change the raw PCM format. s32 currently offers the best performance - when only sox/play are used. f32 may offer better performance if - piping to/from non-sox applications (e.g. ecasound) - -* pause - pause playback - Player pause state is preserved across dtas-player invocations. - -* 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. - -* queue cat - dump the contents of the queue as YAML - This may include arbitrary commands to be executed, filenames, - and offsets for playback. The format is not intended to be - stable and subject to internal changes in dtas-player. - -* restart - restarts all processes in the current pipeline. Playback - will be momentarily interrupted while this change occurs. This is - necessary if one of the commands (e.g. sox or ecasound) or loaded - libraries (e.g. a LADSPA plugin) is upgraded. Use "source restart" - instead to only restart the source chain, leaving the sinks - untouched. - -* rg RGARGS - configure ReplayGain support - All FLOAT values may be adjusted via '+=' or '-=' instead of simple - assignment ('='). If RGARGS is empty, the current rg state of - non-default values will be dumped in YAML. - + fallback_gain=FLOAT (-6.0) - dB value - Adjust the volume by this level (usually negative) for tracks - missing ReplayGain tags. This is useful when the queue contains - a mix of tracks with and without ReplayGain tags. - + fallback_track=BOOLEAN (true) - When in album_gain mode, fallback to track_gain if the - REPLAYGAIN_ALBUM_GAIN metadata is missing. - + mode=(album_gain|track_gain|track_norm|album_norm|off) - This controls the ReplayGain tag to use. The *_norm options - are used for peak normalization and not commonly found in other - players. - + preamp=FLOAT (0) - dB value - Adjust the album_gain or track_gain amount by this value (in dB). - + norm_level=FLOAT (1.0 == dBFS) - Controls the level to normalize to when using album_norm or track_norm. - -* seek [+-]TIMESTAMP - 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. - Seeking to a relative time is also supported by prefixing the time - with '+' or '-' - -* skip - abort current track/command (via closing the output pipe) - 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 - This currently does not restart running (active) sinks. - This will stop active sinks if active is set to false, and start - active sinks if active is set to true. - See dtas-sinkedit(1) for an example of using this. - + command=COMMAND - change the command-line used for playback - + active=BOOLEAN - whether or not the sink will be in use (default: false) - + env.ENVNAME=ENVVALUE - set ENVNAME to ENVVALUE for the sink process - + env#ENVNAME - unset ENVNAME in the sink process (only) - + prio=INTEGER - priority of the sink, lower values run first - + nonblock=BOOLEAN - drop audio data to avoid holding back other sinks - + pipe_size=UNSIGNED - set the size of the pipe for the sink (Linux-only) - -* source cat SOURCENAME - dump the current source command and env in YAML - -* source ed SOURCENAME SOURCEARGS - edit the source parameters. - This changes here will immediately restart the source process. - See the code for dtas-sourceedit(1) for an example of using this. - + command=COMMAND - change the command-line used to decode audio - + env.ENVNAME=ENVVALUE - set ENVNAME to ENVVALUE for the source process - + env#ENVNAME - unset ENVNAME in the source process (only) - + tryorder=INTEGER - lower values are tried first - PENDING: tryorder here is wrong and may be removed or changed. - We need to account for at least two variables input file: - 1. input type (flac/opus/mp3/etc) - 2. transport protocol (local FS/http/ftp/sftp/etc) - -* source ls - dump the names of sources sorted by tryorder - -* source restart - restart the current source command - This can be useful if the source file is changed during playback - and the current player process is holding onto an unlinked inode. - This is advantageous over a full "restart" as there is no audible - gap on most systems. - -* state dump [FILENAME] - Immediately dump the state of the player. If a FILENAME is specified, - the state is written to that file. Otherwise, the default state file - (configured via DTAS_PLAYER_STATE environment variable, defaulting - to ~/.dtas/player_state.yml) is written to. This does not use fsync(2), - users requiring fsync should open(2) that file and fsync(2) it - themselves if necessary. - -* tl add FILENAME [TRACKID [BOOLEAN]] - add files to the tracklist - With one arg, adds FILENAME to the head of the tracklist. - If TRACKID is specified, FILENAME is added immediately after TRACKID - on the existing tracklist. The final BOOLEAN argument replaces the - currently playing track with the newly-added one. - Returns the TRACKID of the newly added track - -* tl clear - clear current tracklist - -* tl current - display the pathname to the currently playing track - -* tl current-id - display the TRACKID of the currently playing track - -* tl remove TRACKID - remove the track with the given TRACKID from - the track list and returns the FILENAME if successful - -* tl get [TRACKIDS] - returns a list of TRACKIDS mapped to shell-escaped filenames. - -* tl goto TRACKID [TIMESTAMP] - plays the given TRACKID - An optional timestamp may be added to prevent playing the - same part(s) repeatedly - -* tl max [MAXIMUM] - sets or gets the maximum number of tracks - allowed in the tracklist - -* tl next - jump to the next track in the tracklist - -* tl prev - jump to the previous track in the tracklist - -* tl repeat [BOOLEAN|1] - show/or change repeat status of the tracklist. - With no args, this will show "true", "false", or "1" - If set to "1", dtas-player will repeat the current track. - Returns the previous repeat status. - -* tl shuffle [BOOLEAN] - show/or change the current shuffle status of - the tracklist. Returns the previous shuffle status. - -* tl swap TRACKID_A TRACKID_B - swaps the positions of two tracks. - -* tl tracks - returns a list of all TRACKIDS in the tracklist - -* trim [off|TBEG [TLEN]] - Limits playback of all tracks in the tracklist to the time starting - at TBEG and ending after TLEN has elapsed. Not specifying TLEN will - cause sox. Like the sox "trim" effect, prefixing TLEN with a '=' - will be interpreted as an absolute stop time. - Both TBEG and TLEN should be specified in seconds, not sample counts. - Specifying "off" (without quotes) disables trim. - This feature is intended to allow users to "zoom-in" on a particular - portion of a track to tweak parameters (either with - dtas-sourceedit(1) or via playback of splitfx YAML files) and often - combined with looping the tracklist (via "tl repeat"). - -* watch - adds the client to the passive watch list for notifications. - It is recommended clients issue no further commands and open - another client socket to issue non-watch commands. - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ diff --git a/Documentation/dtas-player_sink_examples.pod b/Documentation/dtas-player_sink_examples.pod new file mode 100644 index 0000000..da8ea76 --- /dev/null +++ b/Documentation/dtas-player_sink_examples.pod @@ -0,0 +1,87 @@ +% dtas-player_sink_examples(7) dtas user manual + +=head1 NAME + +dtas-player_sink_examples - sink examples for dtas-player + +=head1 SYNOPSIS + +dtas-ctl sink ed SINKNAME command='...' + +dtas-sinkedit SINKNAME + +=head1 EXAMPLES + +=head2 Streaming Ogg-Vorbis to Icecast + +To use L and Icecast, the following sink works. +Warning: the following example will likely expose your Icecast source +password to any local users on the system. + + # set HOST/PORT/PASS via env or directly in the command + --- + name: oggfwd + command: sox $SOXFMT - -t ogg - | oggfwd $HOST $PORT $PASS /dtas.ogg + +=head2 Stream to a remote host via ssh + +Alternatively, if you have L installed on any remote host and +a slow connection using Ogg-Vorbis: + + # Long lines in YAML can be broken up and the subsequent lines + # indented with by spaces + --- + name: ssh-remote + command: sox $SOXFMT - -t ogg - | + ssh $HOST env AUDIODEV=... play -q -t ogg - + + # Note the use of env(1), as the "env" parameter for the sink may not be + # passed via ssh to the remote $HOST depending on the ssh_config(5) + # configuration. + +If you have a fast connection, there is no need to encode using +Ogg-Vorbis. Alternatively, you may also use "flac" instead of "ogg" in +the above Ogg-Vorbis example. + + --- + name: ssh-remote + command: ssh $HOST env AUDIODEV=... play -q $SOXFMT - + +=head2 Dump audio to a file during playback + +To configure a dumper sink (in addition to the "default" sink). Note +the use of $SOXFMT, this will be automatically expanded to match the +internal format of the player. The internal format of the player is +described in L. + + $ dtas-ctl sink ed dumper command='sox $SOXFMT - /tmp/dump.sox' + +Non-"default" sinks are not active by default, but may be made active. + + $ dtas-ctl sink ed dumper active=true + +Changing it again to "active=false" will deactivate the sink. + +=head2 Apply a short delay to low frequencies to improve time-alignment + +See L. + +=head1 CONTACT + +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L, L, +L, L, L, L, L, L diff --git a/Documentation/dtas-player_sink_examples.txt b/Documentation/dtas-player_sink_examples.txt deleted file mode 100644 index 80d33c4..0000000 --- a/Documentation/dtas-player_sink_examples.txt +++ /dev/null @@ -1,83 +0,0 @@ -% dtas-player_sink_examples(7) dtas user manual - -# NAME - -dtas-player_sink_examples - sink examples for dtas-player - -# SYNOPSIS - -dtas-ctl sink ed SINKNAME command='...' -dtas-sinkedit SINKNAME - -# EXAMPLES - -## Streaming Ogg-Vorbis to Icecast - -To use oggfwd(1) and Icecast, the following sink works. -Warning: the following example will likely expose your Icecast source -password to any local users on the system. - - # set HOST/PORT/PASS via env or directly in the command - --- - name: oggfwd - command: sox $SOXFMT - -t ogg - | oggfwd $HOST $PORT $PASS /dtas.ogg - -## Stream to a remote host via ssh - -Alternatively, if you have play(1) installed on any remote host and -a slow connection using Ogg-Vorbis: - - # Long lines in YAML can be broken up and the subsequent lines - # indented with by spaces - --- - name: ssh-remote - command: sox $SOXFMT - -t ogg - | - ssh $HOST env AUDIODEV=... play -q -t ogg - - - # Note the use of env(1), as the "env" parameter for the sink may not be - # passed via ssh to the remote $HOST depending on the ssh_config(5) - # configuration. - -If you have a fast connection, there is no need to encode using -Ogg-Vorbis. Alternatively, you may also use "flac" instead of "ogg" in -the above Ogg-Vorbis example. - - --- - name: ssh-remote - command: ssh $HOST env AUDIODEV=... play -q $SOXFMT - - -## Dump audio to a file during playback - -To configure a dumper sink (in addition to the "default" sink). Note -the use of $SOXFMT, this will be automatically expanded to match the -internal format of the player. The internal format of the player is -described in dtas-player_protocol(7). - - $ dtas-ctl sink ed dumper command='sox $SOXFMT - /tmp/dump.sox' - -Non-"default" sinks are not active by default, but may be made active. - - $ dtas-ctl sink ed dumper active=true - -Changing it again to "active=false" will deactivate the sink. - -## Apply a short delay to low frequencies to improve time-alignment - -See dtas-xdelay(1). - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -dtas-ctl(1), dtas-sinkedit(1), dtas-xdelay(1), -sox(1), play(1), oggfwd(1), ssh(1), ssh_config(5), env(1) diff --git a/Documentation/dtas-sinkedit.pod b/Documentation/dtas-sinkedit.pod new file mode 100644 index 0000000..98dee27 --- /dev/null +++ b/Documentation/dtas-sinkedit.pod @@ -0,0 +1,79 @@ +% dtas-sinkedit(1) dtas user manual + +=head1 NAME + +dtas-sinkedit - edit the command and environment of a sink + +=head1 SYNOPSYS + +dtas-sinkedit SINKNAME + +=head1 DESCRIPTION + +dtas-sinkedit spawns an editor to allow editing of a sink as a YAML file. +See L for details on SINKARGS. + +On Linux machines with the sleepy_penguin RubyGem installed, L +is used to monitor the file for changes while the text exitor is running. +Each time a user finishes saving a file, changes are committed immediately. +This behavior may be disabled by using the -N or --no-watch command-line +switch. + +=head1 OPTIONS + +=over + +=item -N, --no-watch + +Disable L support on Linux systems + +=item -n, --dry-run + +Only print commands which would be sent to dtas-player + +=item -V, --verbose + +Print out commands as they are sent to dtas-player + +=back + +=head1 EXAMPLES + +To get a list of existing sink names + + $ dtas-ctl ls + +Invoking dtas-sinkedit will spawn your favorite text editor on a +given SINKNAME: + + $ dtas-sinkedit SINKNAME + +If SINKNAME was not listed, it will be created (in an inactive state). +Successfully exiting your text editor will send the changes to the +running dtas-player. + +=head1 ENVIRONMENT + +VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset. + +DTAS_PLAYER_SOCK - the path to the dtas-player control socket. +This defaults to ~/.dtas/player.sock + +=head1 CONTACT + +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L, L diff --git a/Documentation/dtas-sinkedit.txt b/Documentation/dtas-sinkedit.txt deleted file mode 100644 index 07f8ecb..0000000 --- a/Documentation/dtas-sinkedit.txt +++ /dev/null @@ -1,69 +0,0 @@ -% dtas-sinkedit(1) dtas user manual -% - -# NAME - -dtas-sinkedit - edit the command and environment of a sink - -# SYNOPSYS - -dtas-sinkedit SINKNAME - -# DESCRIPTION - -dtas-sinkedit spawns an editor to allow editing of a sink as a YAML file. -See dtas-player_protocol(7) for details on SINKARGS. - -On Linux machines with the sleepy_penguin RubyGem installed, inotify(7) -is used to monitor the file for changes while the text exitor is running. -Each time a user finishes saving a file, changes are committed immediately. -This behavior may be disabled by using the -N or --no-watch command-line -switch. - -# OPTIONS --N, \--no-watch -: Disable inotify(7) support on Linux systems - --n, \--dry-run -: Only print commands which would be sent to dtas-player - --V, \--verbose -: Print out commands as they are sent to dtas-player - -# EXAMPLES - -To get a list of existing sink names - - $ dtas-ctl ls - -Invoking dtas-sinkedit will spawn your favorite text editor on a -given SINKNAME: - - $ dtas-sinkedit SINKNAME - -If SINKNAME was not listed, it will be created (in an inactive state). -Successfully exiting your text editor will send the changes to the -running dtas-player. - -# ENVIRONMENT - -VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset. - -DTAS_PLAYER_SOCK - the path to the dtas-player control socket. -This defaults to ~/.dtas/player.sock - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -dtas-player(1), dtas-player_protocol(7), dtas-ctl(1) diff --git a/Documentation/dtas-sourceedit.pod b/Documentation/dtas-sourceedit.pod new file mode 100644 index 0000000..69062b1 --- /dev/null +++ b/Documentation/dtas-sourceedit.pod @@ -0,0 +1,86 @@ +% dtas-sourceedit(1) dtas user manual + +=head1 NAME + +dtas-sourceedit - edit parameters of a source decoder + +=head1 SYNOPSYS + +dtas-sourceedit {sox | av | ff} + +=head1 DESCRIPTION + +dtas-sourceedit spawns an editor to allow editing of a source as a YAML file. +See L for details on SOURCEARGS. If standard input is +a pipe or file, it is parsed as YAML and fed to the L instance +non-interactively. This is useful for loading various profiles from the +filesystem. + +On Linux machines with the sleepy_penguin RubyGem installed, L +is used to monitor the file for changes while the text exitor is running. +Each time a user finishes saving a file, changes are committed immediately. +This behavior may be disabled by using the -N or --no-watch command-line +switch. + +=head1 OPTIONS + +=over + +=item -N, --no-watch + +Disable L support on Linux systems + +=item -n, --dry-run + +Only print commands which would be sent to dtas-player + +=item -V, --verbose + +Print out commands as they are sent to dtas-player + +=back + +=head1 EXAMPLES + +Invoking dtas-sourceedit will spawn your favorite text editor on "sox": + + $ dtas-sourceedit sox + +To load an existing YAML profile for sox. saved.yml could be the output +of a previous "dtas-ctl source cat sox" invocation: + + $ dtas-sourceedit sox < saved.yml + +To change the way dtas-player calls avconv (part of libav): + + $ dtas-sourceedit av + +To change the way dtas-player calls ffmpeg (lightly-tested): + + $ dtas-sourceedit ff + +=head1 ENVIRONMENT + +VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset. + +DTAS_PLAYER_SOCK - the path to the dtas-player control socket. +This defaults to ~/.dtas/player.sock + +=head1 CONTACT + +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L, L diff --git a/Documentation/dtas-sourceedit.txt b/Documentation/dtas-sourceedit.txt deleted file mode 100644 index 8e87008..0000000 --- a/Documentation/dtas-sourceedit.txt +++ /dev/null @@ -1,77 +0,0 @@ -% dtas-sourceedit(1) dtas user manual -% - -# NAME - -dtas-sourceedit - edit parameters of a source decoder - -# SYNOPSYS - -dtas-sourceedit {sox | av | ff} - -# DESCRIPTION - -dtas-sourceedit spawns an editor to allow editing of a source as a YAML file. -See dtas-player_protocol(7) for details on SOURCEARGS. If standard input is -a pipe or file, it is parsed as YAML and fed to the dtas-player(1) instance -non-interactively. This is useful for loading various profiles from the -filesystem. - -On Linux machines with the sleepy_penguin RubyGem installed, inotify(7) -is used to monitor the file for changes while the text exitor is running. -Each time a user finishes saving a file, changes are committed immediately. -This behavior may be disabled by using the -N or --no-watch command-line -switch. - -# OPTIONS - --N, \--no-watch -: Disable inotify(7) support on Linux systems - --n, \--dry-run -: Only print commands which would be sent to dtas-player - --V, \--verbose -: Print out commands as they are sent to dtas-player - -# EXAMPLES - -Invoking dtas-sourceedit will spawn your favorite text editor on "sox": - - $ dtas-sourceedit sox - -To load an existing YAML profile for sox. saved.yml could be the output -of a previous "dtas-ctl source cat sox" invocation: - - $ dtas-sourceedit sox < saved.yml - -To change the way dtas-player calls avconv (part of libav): - - $ dtas-sourceedit av - -To change the way dtas-player calls ffmpeg (lightly-tested): - - $ dtas-sourceedit ff - -# ENVIRONMENT - -VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset. - -DTAS_PLAYER_SOCK - the path to the dtas-player control socket. -This defaults to ~/.dtas/player.sock - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -dtas-player(1), dtas-player_protocol(7), dtas-ctl(1) diff --git a/Documentation/dtas-splitfx.pod b/Documentation/dtas-splitfx.pod new file mode 100644 index 0000000..4ffe24f --- /dev/null +++ b/Documentation/dtas-splitfx.pod @@ -0,0 +1,271 @@ +% dtas-splitfx(1) dtas user manual + +=head1 NAME + +dtas-splitfx - split audio and apply effects to all tracks + +=head1 SYNOPSIS + +dtas-splitfx SPLITFX_FILE.yml [OPTIONS] [TARGETS] [ARGS...] + +=head1 DESCRIPTION + +dtas-splitfx reads as YAML file and can apply effects (including +resampling/dither), split, tag, and encode files in parallel. +dtas-splitfx is intended for splitting recordings from vinyl and live +concerts into separate files. dtas-splitfx is inspired by cuesheets for +CD audio and the L build tool. + +dtas-splitfx primarily uses L, but it is possible to define targets +to use L, too. + +=head1 OPTIONS + +=over + +=item -j, --jobs [JOBS] + +Number of jobs to run in parallel. If no number is specified, all +jobs are run in parallel. + +=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 -D, --no-dither + +Disable automatic setting of the DITHERFX env. This also passes +the option to L via SOX_OPTS. + +=item -O, --outdir OUTDIR + +Set output directory instead of current directory. +User-created targets must allow a placeholder for the +(by default, an empty string) $OUTDIR environment variable +in the output command. + +=item -C, --compression FACTOR + +Set the compression factor passed to L. See L +for more information on how it works across different formats. + +=item -r, --rate RATE + +Override the output sample rate in the specified TARGET + +=item -b, --bits BITS + +Override the output bit depth in the specified TARGET + +=item -t, --trim POSITION + +Passes a POSITION argument to the sox "trim" effect to allow +limiting output to only process a portion of the original. +This bypasses the "tracks" section and of the YAML file and +outputs the result as a single file with the TRACKNUMBER +of "000". For ease-of-typing, commas in this command-line +argument are automatically expanded to spaces when passed to sox. + +=item -p, --sox-pipe + +Used in place of an output target to specify outputting audio data in +the native "sox" format to another L or L command. This +moves printing of output to stderr and disables parallel job invocation. + +=back + +=head1 FILE FORMAT + +=over + +=item infile - string, the pathname of the original audio file + +=item env - ordered hash of environment variables to set for all commands + + env: !omap + FX: gain 3 stats + +=item comments - hash of common tags for all audio (e.g. ARTIST, ALBUM, YEAR) + + comments: + ARTIST: John Smith + ALBUM: Hello World + YEAR: 2013 + +=item track_start - integer, number to start the track count at + +default: 1 + +=item cdda_align - boolean, enforce sector alignment for audio CDs + +default: false + +=item track_zpad - boolean or integer + +Zero-pad the TRACKNUMBER in metadata and +filenames. If an integer, this creates a fixed padding even if the +padding is not necessary. If true, this only pads as needed for the +highest-numbered track. Default: true + +=item tracks - array, see "TRACKS" section + +=item targets - hash, see "TARGETS" section + +=item command - used only by L + +=back + +=head1 TRACKS + +Tracks may be defined by a start time, with the stop time defined +automatically by the start of the next track, stop time, or a skip +segment. + +=over + +=item t TIME TITLE [fade_in/fade_out=FADE_ARGS] + +The start of a new track +at TIME with TITLE. An optional fade_in and fade_out may be specified +for the first/last tracks. + +=item skip TIME - skip a segment starting at TIME + +"skip" segments are +useful for skipping long gaps between tracks (such as flipping vinyl +or intermission at concerts) + +=item stop TIME - stop the last track + +This should be the last directive in the "tracks" array. + +=back + +An example of the tracks array for a 4 track EP follows: + + tracks: + - t 0:21 "This is the first track of an EP" fade_in='t 1' + - t 7:11.6 "Second track of side A of an EP" + - skip 9:18 # this is where I flip the record, comments are allowed + - t 9:41 "3rd track of an EP" + - t 13:36.5 "Final track of the EP" fade_out='t 1' + - stop 18:11 + +=head1 FADES + +dtas-splitfx automatically sets up fade-in/fade-out effects for sox(1) +based on track times. These are to be used in "t" (track) directives in +the "tracks" array: + +=over + +=item fade_in="[TYPE] LENGTH" + +=item fade_out="[TYPE] LENGTH" + +=back + +TYPE is optional, but LENGTH is required. See L for a description +of the fade type. + +=head1 ENVIRONMENT + +dtas-splitfx sets several default environment variables for commands to +use in targets: + +=over + +=item INFILE - this matches the "infile" directive in the YAML file + +=item INDIR - the directory INFILE belongs to, without trailing slash + +=item INBASE - the basename of INFILE + +=item TBEG - the integer sample offset where the L trim effect starts + +=item TLEN - the integer sample count representing the length of the trim + +=item TRIMFX - essential + +Supplies the necessary L trim effect to +each track. In other words, this is: "trim ${TBEG}s ${TLEN}s" + +=item COMMENTS - expands to --comment-file=PATH for L + +=item OUTDIR - placeholder for --outdir, defaults to an empty string + +=item SUFFIX - the suffix of the output format without "." (e.g. "flac", "ogg") + +=item TRACKNUMBER - the track number, useful for comments and filenames + +=item RATEFX - rate effect and arguments for L resampling + +=item DITHERFX - dither effect and arguments for L dithering + +=item FX - any user-specified sox effects which encompases the entire file. + +(e.g. "highpass 35 gain 3 stats") + +=back + +=head1 TARGETS + +The default targets will split audio and avoid applying any effects. +They are named after common audio formats supported by L: + +=over + +=item flac + +=item ogg + +=item mp3 + +=item sox + +=back + +If not specified, "flac" is the default target. + +Additional targets supported by default. + +=over + +=item flac-cdda + +This encodes the audio to "flac" format while being +easily decompressible to a format suitable for being burned to audio CD. + +=back + +Custom targets may easily be defined to apply effects and gain. For +example, the following "flac24" target raises the volume of the left +channel by 9.5dB and the right one by 8.5dB to compensate for channel +imbalance in a live concert recording from the audience: + + targets: + flac24: + command: sox -M + "|sox $INFILE -c1 -p $TRIMFX remix 1v1 gain 9.5" + "|sox $INFILE -c1 -p $TRIMFX remix 2v1 gain 8.5" + $COMMENTS $OUTFMT + ${OUTDIR}bandYYYY-MM-DD.FOO.t0"$TRACKNUMBER.$SUFFIX" + $RATEFX $DITHERFX stats + format: + type: flac + bits: 24 + rate: 48000 + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L, L, L diff --git a/Documentation/dtas-splitfx.txt b/Documentation/dtas-splitfx.txt deleted file mode 100644 index 352c0a5..0000000 --- a/Documentation/dtas-splitfx.txt +++ /dev/null @@ -1,188 +0,0 @@ -% dtas-splitfx(1) dtas user manual - -# NAME - -dtas-splitfx - split audio and apply effects to all tracks - -# SYNOPSIS - -dtas-splitfx SPLITFX_FILE.yml [OPTIONS] [TARGETS] [ARGS...] - -# DESCRIPTION - -dtas-splitfx reads as YAML file and can apply effects (including -resampling/dither), split, tag, and encode files in parallel. -dtas-splitfx is intended for splitting recordings from vinyl and live -concerts into separate files. dtas-splitfx is inspired by cuesheets for -CD audio and the make(1) build tool. - -dtas-splitfx primarily uses sox(1), but it is possible to define targets -to use ecasound(1), too. - -# OPTIONS - --j, \--jobs [JOBS] -: Number of jobs to run in parallel. If no number is specified, all - jobs are run in parallel. - --n, \--dry-run -: Print, but do not run the commands to be executed - --s, \--quiet, \--silent -: Silent operation, commands are not printed as executed - --D, \--no-dither -: Disable automatic setting of the DITHERFX env. This also passes - the option to sox(1) via SOX_OPTS. - --O, \--outdir OUTDIR -: Set output directory instead of current directory. - User-created targets must allow a placeholder for the - (by default, an empty string) $OUTDIR environment variable - in the output command. - --C, \--compression FACTOR -: Set the compression factor passed to sox(1). See soxformat(7) - for more information on how it works across different formats. - --r, \--rate RATE -: Override the output sample rate in the specified TARGET - --b, \--bits BITS -: Override the output bit depth in the specified TARGET - --t, \--trim POSITION -: Passes a POSITION argument to the sox "trim" effect to allow - limiting output to only process a portion of the original. - This bypasses the "tracks" section and of the YAML file and - outputs the result as a single file with the TRACKNUMBER - of "000". For ease-of-typing, commas in this command-line - argument are automatically expanded to spaces when passed to sox. - --p, \--sox-pipe -: Used in place of an output target to specify outputting audio data in - the native "sox" format to another sox(1) or play(1) command. This - moves printing of output to stderr and disables parallel job invocation. - -# FILE FORMAT - -* infile - string, the pathname of the original audio file -* env - ordered hash of environment variables to set for all commands - env: !omap - FX: gain 3 stats -* comments - hash of common tags for all audio (e.g. ARTIST, ALBUM, YEAR) - comments: - ARTIST: John Smith - ALBUM: Hello World - YEAR: 2013 -* track_start - integer, number to start the track count at (default: 1) -* cdda_align - boolean, enforce sector alignment for audio CDs (default: false) -* track_zpad - boolean or integer. Zero-pad the TRACKNUMBER in metadata and - filenames. If an integer, this creates a fixed padding even if the - padding is not necessary. If true, this only pads as needed for the - highest-numbered track (default: true) -* tracks - array, see "TRACKS" section -* targets - hash, see "TARGETS" section -* command - used only by dtas-player(1) - -# TRACKS - -Tracks may be defined by a start time, with the stop time defined -automatically by the start of the next track, stop time, or a skip -segment. - -* t TIME TITLE [fade_in/fade_out=FADE_ARGS] - the start of a new track - at TIME with TITLE. An optional fade_in and fade_out may be specified - for the first/last tracks. -* skip TIME - skip a segment starting at TIME. "skip" segments are - useful for skipping long gaps between tracks (such as flipping vinyl - or intermission at concerts) -* stop TIME - stop the last track This should be the last directive in - the "tracks" array. - -An example of the tracks array for a 4 track EP follows: - - tracks: - - t 0:21 "This is the first track of an EP" fade_in='t 1' - - t 7:11.6 "Second track of side A of an EP" - - skip 9:18 # this is where I flip the record, comments are allowed - - t 9:41 "3rd track of an EP" - - t 13:36.5 "Final track of the EP" fade_out='t 1' - - stop 18:11 - -# FADES - -dtas-splitfx automatically sets up fade-in/fade-out effects for sox(1) -based on track times. These are to be used in "t" (track) directives in -the "tracks" array: - -* fade_in="[TYPE] LENGTH" -* fade_out="[TYPE] LENGTH" - -TYPE is optional, but LENGTH is required. See sox(1) for a description -of the fade type. - -# ENVIRONMENT - -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, without trailing slash -* INBASE - the basename of INFILE -* TBEG - the integer sample offset where the sox(1) trim effect starts -* TLEN - the integer sample count representing the length of the trim -* TRIMFX - essential, this supplys the necessary sox(1) trim effect to - each track. In other words, this is: "trim ${TBEG}s ${TLEN}s" -* COMMENTS - expands to --comment-file=PATH for sox(1) -* OUTDIR - placeholder for --outdir, defaults to an empty string -* 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 gain 3 stats") - -# TARGETS - -The default targets will split audio and avoid applying any effects. -They are named after common audio formats supported by sox(1): - -* flac -* ogg -* mp3 -* sox - -If not specified, "flac" is the default target. - -Additional targets supported by default. - -* flac-cdda - this encodes the audio to "flac" format while being - easily decompressible to a format suitable for being burned to audio CD. - -Custom targets may easily be defined to apply effects and gain. For -example, the following "flac24" target raises the volume of the left -channel by 9.5dB and the right one by 8.5dB to compensate for channel -imbalance in a live concert recording from the audience: - - targets: - flac24: - command: sox -M - "|sox $INFILE -c1 -p $TRIMFX remix 1v1 gain 9.5" - "|sox $INFILE -c1 -p $TRIMFX remix 2v1 gain 8.5" - $COMMENTS $OUTFMT - ${OUTDIR}bandYYYY-MM-DD.FOO.t0"$TRACKNUMBER.$SUFFIX" - $RATEFX $DITHERFX stats - format: - type: flac - bits: 24 - rate: 48000 - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -sox(1), ecasound(1), flac(1), dtas-player(1) diff --git a/Documentation/dtas-tl.pod b/Documentation/dtas-tl.pod new file mode 100644 index 0000000..44bdfbb --- /dev/null +++ b/Documentation/dtas-tl.pod @@ -0,0 +1,122 @@ +% dtas-tl(1) dtas user manual + +=head1 NAME + +dtas-tl - tracklist manipulation for dtas-player (development) + +=head1 SYNOPSYS + +dtas-tl [COMMANDS] + +=head1 DESCRIPTION + +dtas-tl provides utility functions for manipulating the tracklist of the +dtas-player (not the queue, the tracklist is separate from the queue). +It is mainly intended as a development tool and will likely go away in +the future or have its functionality merged into another tool (or MPRIS +client). + +=head1 COMMANDS + +=over + +=item aac - Bdd tracks Bfter Burrent track in the tracklist + +=item addhead - add tracks to the beginning of the tracklist + +=item addtail - add tracks to the end of the tracklist + +=item current - display the current track, "NONE" if not playing + +=item current-id - display the TRACKID of the current track + +"NONE" if not playing + +=item cat - display a newline-delimited list of TRACK_ID=PATH output + +=item clear - remove all tracks from the tracklist + +=item edit - spawn an editor to allow editing the tracklist as a text file + +See EDITING for more information. + +=item goto TRACKID [POS] + +Play TRACKID immediately, optionally seek to POS +TRACKID may be looked up via cat, and POS should be a timestamp in +HH:MM:SS.FRAC format. + +=item reto REGEXP [POS] + +Play first track with path matching REGEXP immediately, +optionally seek to POS. POS should be a timestamp in HH:MM:SS.FRAC format. + +=item next - play the next track in the tracklist + +=item prev - play the previous track in the tracklist + +=item repeat 1 - repeat the current track + +=item repeat false - disable repeat + +=item repeat true - enable repeat of the whole tracklist + +=back + +See L for a detailed description of the protocol. + +=head1 EXAMPLES + +display the current tracklist + + $ dtas-tl cat + +to add an an entire directory of FLAC files + + $ dtas-tl addtail /path/to/directory/*.flac + +to skip forward in the tracklist + + $ dtas-tl next + +to skip backwards in the tracklist + + $ dtas-tl prev + +=head1 EDITING + +It is possible to edit the player tracklist from your favorite text +editor. Existing lines denoting tracks may be rearranged, deleted, +copied or entirely new lines with path names (without a trailing +"=TRACK_ID") may be added. + +Changes to the tracklist are sent to the player when the user exits the +editor. This functionality only works when there is one user editing +the tracklist at a time, and when no files in the tracklist contain rare +newline characters. + +=head1 ENVIRONMENT + +VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset. + +DTAS_PLAYER_SOCK - the path to the dtas-player control socket. +This defaults to ~/.dtas/player.sock + +=head1 CONTACT + +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L, L diff --git a/Documentation/dtas-tl.txt b/Documentation/dtas-tl.txt deleted file mode 100644 index 2ff5ff6..0000000 --- a/Documentation/dtas-tl.txt +++ /dev/null @@ -1,96 +0,0 @@ -% dtas-tl(1) dtas user manual - -# NAME - -dtas-tl - tracklist manipulation for dtas-player (development) - -# SYNOPSYS - -dtas-tl [COMMANDS] - -# DESCRIPTION - -dtas-tl provides utility functions for manipulating the tracklist of the -dtas-player (not the queue, the tracklist is separate from the queue). -It is mainly intended as a development tool and will likely go away in -the future or have its functionality merged into another tool (or MPRIS -client). - -# COMMANDS - -* aac - *A*dd tracks *A*fter *C*urrent track in the tracklist -* addhead - add tracks to the beginning of the tracklist -* addtail - add tracks to the end of the tracklist -* current - display the current track, "NONE" if not playing -* current-id - display the TRACKID of the current track - "NONE" if not playing -* cat - display a newline-delimited list of TRACK_ID=PATH output - Note: this is shell-escaped, multibyte characters may not show up properly. -* clear - remove all tracks from the tracklist -* edit - spawn an editor to allow editing the tracklist as a text file - See EDITING for more information. -* goto TRACKID [POS] - play TRACKID immediately, optionally seek to POS -TRACKID may be looked up via cat, and POS should be a timestamp in -HH:MM:SS.FRAC format. -* reto REGEXP [POS] - play first track with path matching REGEXP immediately, -optionally seek to POS. POS should be a timestamp in HH:MM:SS.FRAC format. -* next - play the next track in the tracklist -* prev - play the previous track in the tracklist -* repeat 1 - repeat the current track -* repeat false - disable repeat -* repeat true - enable repeat of the whole tracklist - -See dtas-player_protocol(7) for a detailed description of the protocol. - -# EXAMPLES - -display the current tracklist - - $ dtas-tl cat - -to add an an entire directory of FLAC files - - $ dtas-tl addtail /path/to/directory/*.flac - -to skip forward in the tracklist - - $ dtas-tl next - -to skip backwards in the tracklist - - $ dtas-tl prev - -# EDITING - -It is possible to edit the player tracklist from your favorite text -editor. Existing lines denoting tracks may be rearranged, deleted, -copied or entirely new lines with path names (without a trailing -"=TRACK_ID") may be added. - -Changes to the tracklist are sent to the player when the user exits the -editor. This functionality only works when there is one user editing -the tracklist at a time, and when no files in the tracklist contain rare -newline characters. - -# ENVIRONMENT - -VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset. - -DTAS_PLAYER_SOCK - the path to the dtas-player control socket. -This defaults to ~/.dtas/player.sock - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -dtas-player(1), dtas-player_protocol(7), dtas-ctl(1) diff --git a/Documentation/dtas-xdelay.pod b/Documentation/dtas-xdelay.pod new file mode 100644 index 0000000..e8628a5 --- /dev/null +++ b/Documentation/dtas-xdelay.pod @@ -0,0 +1,96 @@ +% dtas-xdelay(1) dtas user manual + +=head1 NAME + +dtas-xdelay - play audio with a crossover delay + +=head1 SYNOPSYS + +dtas-xdelay [OPTIONS] INPUT1 INPUT2 DELAY + +=head1 DESCRIPTION + +dtas-xdelay will delay an audio band by a given delay (in seconds or +fractions thereof). This can be useful for tuning a sub/sat speaker +system. It is intended for use a dtas-player sink command as displayed +in the synopsis. + +The INPUT arguments (/dev/fd/lo and /dev/fd/hi) are automatically +changed by dtas-player to match the given file descriptors of the pipes. + +Both descriptors receive the same audio data, but will be split using a +Linkwitz-Riley crossover. The high-band (second argument) will be +delayed by default. + +=head1 EXAMPLE + +To set this via dtas-player to delay the high frequencies by 20ms. + + dtas-ctl sink ed SINKNAME \ + command='dtas-xdelay /dev/fd/lo /dev/fd/hi 0.020' + +=head1 OPTIONS + +=over + +=item -x, --crossover-frequency FREQUENCY + +Frequency at which to set the crossover. This defaults to 80 (Hz). + +=item -l, --lowpass-delay + +Delay the lowpass frequency instead of the highpass one. + +=back + +=head1 ENVIRONMENT + +=over + +=item SOXFMT, CHANNELS + +These environment variables are automatically set if +used as a dtas-player sink + +=item DTAS_PLAYER_SOCK - the path to the dtas-player control socket + +This defaults to ~/.dtas/player.sock + +=item AUDIODEV, AUDIODRIVER + +These influence the device/driver used by L. +Consult L for details. + +=item SOX_OPTS + +This influences options passed to L or L +Consult L for details. + +=back + +=head1 NOTES + +The author of this (Eric Wong) knows little about signal processing and +is just parroting things he's learned on the sox documentation and +mailing list. Corrections to the L mailing list +are greatly appreciated. + +=head1 CONTACT + +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + +No subscription is necessary to post to the mailing list. + +=head1 COPYRIGHT + +Copyright 2013-2016 all contributors L + +License: GPL-3.0+ L + +=head1 SEE ALSO + +L, L, L, +L, L diff --git a/Documentation/dtas-xdelay.txt b/Documentation/dtas-xdelay.txt deleted file mode 100644 index 7253d1f..0000000 --- a/Documentation/dtas-xdelay.txt +++ /dev/null @@ -1,76 +0,0 @@ -% dtas-xdelay(1) dtas user manual -% - -# NAME - -dtas-xdelay - play audio with a crossover delay - -# SYNOPSYS - -dtas-xdelay [OPTIONS] INPUT1 INPUT2 DELAY - -# DESCRIPTION - -dtas-xdelay will delay an audio band by a given delay (in seconds or -fractions thereof). This can be useful for tuning a sub/sat speaker -system. It is intended for use a dtas-player sink command as displayed -in the synopsis. - -The INPUT arguments (/dev/fd/lo and /dev/fd/hi) are automatically -changed by dtas-player to match the given file descriptors of the pipes. - -Both descriptors receive the same audio data, but will be split using a -Linkwitz-Riley crossover. The high-band (second argument) will be -delayed by default. - -# EXAMPLE - -To set this via dtas-player to delay the high frequencies by 20ms. - - dtas-ctl sink ed SINKNAME \ - command='dtas-xdelay /dev/fd/lo /dev/fd/hi 0.020' - -# OPTIONS - --x, \--crossover-frequency FREQUENCY -: Frequency at which to set the crossover. This defaults to 80 (Hz). - --l, \--lowpass-delay -: Delay the lowpass frequency instead of the highpass one. - -# ENVIRONMENT - -SOXFMT, CHANNELS - these environment variables are automatically set if -used as a dtas-player sink - -DTAS_PLAYER_SOCK - the path to the dtas-player control socket. -This defaults to ~/.dtas/player.sock - -AUDIODEV, AUDIODRIVER - these influence the device/driver used by play(1) -Consult play(1) for details. - -SOX_OPTS - this influences options passed to sox(1) or play(1) -Consult sox(1) for details. - -# NOTES - -The author of this (Eric Wong) knows little about signal processing and -is just parroting things he's learned on the sox documentation and -mailing list. Corrections to the mailing list are -greatly appreciated. - -# CONTACT - -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ -No subscription is necessary to post to the mailing list. - -# COPYRIGHT - -Copyright 2013-2016 all contributors .\ -License: GPL-3.0+ - -# SEE ALSO - -dtas-player(1), dtas-player_protocol(7), dtas-ctl(1), sox(1), play(1) diff --git a/Documentation/update-footer.rb b/Documentation/update-footer.rb index a6e16cb..dfc1b1a 100755 --- a/Documentation/update-footer.rb +++ b/Documentation/update-footer.rb @@ -3,22 +3,26 @@ # License: GPL-3.0+ # frozen_string_literal: true contact = %q{ -All feedback welcome via plain-text mail to: \ -Mailing list archives available at and -\ +All feedback welcome via plain-text mail to: L + +Mailing list archives available at L +and L + No subscription is necessary to post to the mailing list. } copyright = %q{ -Copyright %s all contributors .\ -License: GPL-3.0+ +Copyright %s all contributors L + +License: GPL-3.0+ L } ENV['TZ'] = 'UTC' now_year = Time.now.strftime("%Y") ARGV.each do |file| - cmd = %W(git log --reverse --pretty=format:%ad --date=short -- #{file}) - beg_year = IO.popen(cmd, &:gets).split('-')[0] + cmd = %W(git log --follow -M1 --pretty=format:%ad --date=short + -- #{file}) + beg_year = IO.popen(cmd, &:read).split("\n")[-1].split('-')[0] years = beg_year == now_year ? beg_year : "#{beg_year}-#{now_year}" File.open(file, "r+") do |fp| @@ -27,7 +31,7 @@ ARGV.each do |file| sec = { state => ''.dup } fp.each_line do |l| case l - when /^(#.+)$/ + when /^(=head.+)$/ state = $1.freeze sections << state sec[state] = ''.dup @@ -38,8 +42,8 @@ ARGV.each do |file| fp.truncate(0) fp.rewind - sec["# CONTACT"] = contact - sec["# COPYRIGHT"] = sprintf(copyright, years) + sec["=head1 CONTACT"] = contact + sec["=head1 COPYRIGHT"] = sprintf(copyright, years) while section = sections.shift fp.puts(section) if String === section blob = sec[section].sub(/\A\n+/, '').sub(/\n+\z/, '') -- cgit v1.2.3-24-ge0c7