about summary refs log tree commit homepage
path: root/Documentation
diff options
context:
space:
mode:
authorEric Wong <normalperson@yhbt.net>2013-09-10 10:08:47 +0000
committerEric Wong <normalperson@yhbt.net>2013-09-10 10:08:47 +0000
commita910d2ce86fa2cee0bed31e801173a981330fac1 (patch)
treee24c1ca2133cb3b9010b2dca11b19e83860ad2f4 /Documentation
parentc99901cd8b985b930ffba3745382bc13af703a0a (diff)
downloaddtas-a910d2ce86fa2cee0bed31e801173a981330fac1.tar.gz
Everything should be documented, even if it's a work-in-progress.
I reserve the right to change them...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/GNUmakefile1
-rw-r--r--Documentation/dtas-player_protocol.txt29
-rw-r--r--Documentation/dtas-tl.txt75
3 files changed, 104 insertions, 1 deletions
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
index 431e856..4e0fcf9 100644
--- a/Documentation/GNUmakefile
+++ b/Documentation/GNUmakefile
@@ -16,6 +16,7 @@ m1 += dtas-player
 m1 += dtas-xdelay
 m1 += dtas-sinkedit
 m1 += dtas-sourceedit
+m1 += dtas-tl
 
 m7 =
 m7 += dtas-player_protocol
diff --git a/Documentation/dtas-player_protocol.txt b/Documentation/dtas-player_protocol.txt
index b431180..7fecec1 100644
--- a/Documentation/dtas-player_protocol.txt
+++ b/Documentation/dtas-player_protocol.txt
@@ -53,6 +53,9 @@ dtas-sinkedit(1), and dtas-enq(1) also implement this protocol.
 - 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
 
@@ -161,7 +164,7 @@ Commands here should be alphabetized according to `LC_ALL=C sort'
     + 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.
+* 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
@@ -211,6 +214,30 @@ Commands here should be alphabetized according to `LC_ALL=C sort'
   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 remove TRACKID - remove the track with the given TRACKID from
+  the track list
+
+* tl get [TRACKIDS]
+  returns a list of TRACKIDS mapped to filenames.
+
+* tl goto TRACKID [TIMESTAMP] - plays the given TRACKID
+  An optional timestamp may be added to prevent playing the
+  same part(s) repeated.y
+
+* 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.
+
+* tl tracks
+  returns a list of all TRACKIDS in the tracklist
+
 * 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.
diff --git a/Documentation/dtas-tl.txt b/Documentation/dtas-tl.txt
new file mode 100644
index 0000000..7c54f10
--- /dev/null
+++ b/Documentation/dtas-tl.txt
@@ -0,0 +1,75 @@
+% 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
+
+* addhead - add multiple tracks to the beginning of the tracklist
+* addtail - add multiple 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
+* clear - remove all tracks from the tracklist
+* 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.
+* next - play the next track in the tracklist
+* previous - 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 previous
+
+# 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 <dtas-all@nongnu.org>\
+Mailing list archives available at <ftp://lists.gnu.org/dtas-all/>\
+No subscription is necessary to post to the mailing list.
+
+# COPYRIGHT
+
+Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
+License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
+
+# SEE ALSO
+
+dtas-player(1), dtas-player_protocol(7), dtas-ctl(1)