From a910d2ce86fa2cee0bed31e801173a981330fac1 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Tue, 10 Sep 2013 10:08:47 +0000 Subject: document dtas-tl(1) and the "tl" commands in the protocol Everything should be documented, even if it's a work-in-progress. I reserve the right to change them... --- Documentation/GNUmakefile | 1 + Documentation/dtas-player_protocol.txt | 29 ++++++++++++- Documentation/dtas-tl.txt | 75 ++++++++++++++++++++++++++++++++++ 3 files changed, 104 insertions(+), 1 deletion(-) create mode 100644 Documentation/dtas-tl.txt (limited to 'Documentation') 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 \ +Mailing list archives available at \ +No subscription is necessary to post to the mailing list. + +# COPYRIGHT + +Copyright 2013, Eric Wong and all contributors.\ +License: GPLv3 or later + +# SEE ALSO + +dtas-player(1), dtas-player_protocol(7), dtas-ctl(1) -- cgit v1.2.3-24-ge0c7