dtas 0.13.1 → 0.14.0

data/Documentation/dtas-enq.txt

@@ -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: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-dtas-player(1), dtas-ctl(1)

data/Documentation/dtas-env.txt

@@ -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: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2015-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>

data/Documentation/dtas-player_effects.txt

@@ -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: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>

data/Documentation/dtas-player_protocol.txt

@@ -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: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>