about summary refs log tree commit homepage
path: root/Documentation/dtas-player_protocol.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/dtas-player_protocol.txt')
-rw-r--r--Documentation/dtas-player_protocol.txt181
1 files changed, 181 insertions, 0 deletions
diff --git a/Documentation/dtas-player_protocol.txt b/Documentation/dtas-player_protocol.txt
new file mode 100644
index 0000000..7c5d57f
--- /dev/null
+++ b/Documentation/dtas-player_protocol.txt
@@ -0,0 +1,181 @@
+% dtas-player_protocol(7) dtas user manual
+%
+
+# NAME
+
+dtas-player_protocol - protocol for controling dtas-player
+
+# DESCRIPTION
+
+This gives a specification of the dtas-player protocol over a local Unix
+SOCK_SEQPACKET or SOCK_DGRAM 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
+- 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
+
+* 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"
+
+* 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.
+
+    + channels=UNSIGNED - (default: 2 (stereo)) - number of channels
+      to use internally.  sox will internally invoke the remix effect
+      when decoding.
+    + 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 - (default: implied from type) - sample precision (decoded)
+      This may be pointless and removed in the future, since the sample
+      precision is implied from type.
+    + rate=UNSIGNED - (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.
+    + 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.
+
+* 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.
+
+* 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 [+-]HH:MM:SS.FRAC - seek the current track to a specified time.
+  This is passed directly as the first argument for the sox(1) "trim"
+  command.   See the sox(1) manpage for details.
+  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 - dump the current source command and env in YAML
+
+* source ed SOURCEARGS - edit the source (decoder) command and environment.
+  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)
+
+* 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.