shithub: pplay

--- a/pplay.man

+++ b/pplay.man

@@ -4,18 +4,18 @@

 .SH SYNOPSIS

 .B audio/pplay

-.B -Dc

+.B -Dbc

] [

 .B pcmfile

 .SH DESCRIPTION

 .I Pplay

-is a PCM audio player which shows a time-domain graphical plot of the data

+is a PCM audio player which displays a time-domain graphical plot of the data

 and allows for some simple editing operations.

-It operates on the same format used by the audio device (see

+It operates on the same raw format used by the audio device (see

 .IR audio (3)).

.PP

-At startup, all input data is loaded in its entirety into memory,

+At startup, all input is loaded in its entirety into memory,

 either from

 .B pcmfile

 if provided, or from standard in.

@@ -25,27 +25,27 @@

 .B -c

 is specified.

 .SS "Command line parameters"

-.TF "pcmfile"

+.TF "-D"

.TP

 .B -D

-Turn verbose debugging info on

+Turn verbose debugging info on immediately

.TP

+.B -b

+Use inverted colors (light background)

+.TP

 .B -c

 Write audio to standard out instead of

 .B /dev/audio

-.TP

-.B pcmfile

-Read file instead of standard in

.PD

 .SS "Keyboard and mouse commands"

 Key commands:

-.TF "="

+.TF "Esc"

.TP

 .B q

 Quit

.TP

 .B D

-Toggle debug draws

+Toggle debug tracing and draws

.TP

 .B S

 Toggle stereo display (default left channel only)

@@ -56,6 +56,9 @@

 .B b

 Jump to loop start

.TP

+.B Esc

+Reset selection

+.TP

 .B =

 Zoom in

.TP

@@ -95,59 +98,49 @@

.PD

 .SS "Dot and cursor position"

 .I Pplay

-loops an interval, referred to as the

-.IR dot ,

-indefinitely.

-The current position (cursor) in the buffer is shown by an orangle vertical line,

-which can be set by clicking with the left mouse button

-anywhere within the dot.

-The dot is set by default to the entire file,

-and is shown by two vertical grey lines on either side of the cursor.

-With the middle mouse button,

-the left or right bound is set depending on whether a middle mouse button click

-occurred resp. on the left or on the right of the cursor.

-The cursor may never escape the dot.

+loops indefinitely an interval referred to as the

+.IR dot .

+The dot is simply the start and end loop points,

+by default the data's start and end.

+The current playback position within it is refered to as the

+.IR cursor .

+The dot is set using the middle mouse button and with respect to the cursor:

+if clicking to its left, the left loop point is set,

+if to the right, the right loop point is set.

+The cursor is set with the left mouse button

+and may never escape the dot.

+The last left mouse click is saved as the

+.I anchor

+point, used in editing.

+Dot, cursor and anchor are indicated

+by distinctly colored vertical lines.

 .SS "Display"

-The graphical plot shows the maximal and minimal sample value

-among the pixels packed in each pixel column,

-by default for the left channel only.

+The graphical plot displays on the y axis

+the maximal and minimal signed value

+among all samples packed in each pixel column

+for one audio channel.

.PP

-A line of status text on the bottom left of the graphical view

-displays timing information, the cursor and the dot,

-in number of

-.I samples

-rather than bytes.

-It is of the form:

-.TF "__n"

-.TP

-.BI T\  n

-Number of samples per pixel column

-.TP

-.BI @\  n

-Time in hh:mm:ss.tt format (see

-.IR tmdate (2)

-.TP

-.BI ( n )

-Absolute cursor position in number of samples

-.TP

-.BI ·\  n

-Left bound of the dot

-.TP

-.BI ↺\  n

-Right bound of the dot, or

-.B ∞

-if unbounded

-.PD

-.PP

-By default, the entire buffer is displayed, spanning the width of the window.

-The y axis spans the entire range of possible of a sample,

-with positive values above the midpoint.

+The x axis is time in number of samples,

+and is described in a text bar

+on the bottom left (mono)

+or in the middle (stereo) of the graphical view.

+The first value is the

+.IR period ,

+or number of samples per vertical pixel column.

+The next fields are offsets from the start of the data

+given in the form

+.IR [hh:mm:ss.tt]\ (samples) ,

+where the first part is in time format (see

+.IR tmdate (2),

+and the second in number of samples.

+The first field is for the current position.

+If set, either the dot or only the anchor follow it.

 .SS "Editing"

 Commands:

 .TF "r file"

.TP

 .BI <\  cmd

-Pipe output of a shell command replacing dot or inserting at the cursor (∗)

+Pipe output of a shell command into dot

.TP

 .BI ^\  cmd

 Pipe dot to a shell command and read back its output into dot

@@ -156,16 +149,16 @@

 Pipe dot to a shell command

.TP

 .B c

-Set snarf buffer to the contents of the dot (‡)

+Set snarf buffer to the contents of the dot

.TP

 .B d

-Cut dot, replacing snarf buffer (‡)

+Cut dot, replacing snarf buffer

.TP

 .B p

-Paste snarf buffer into dot or insert at the cursor (∗)

+Paste snarf buffer into dot or insert at the cursor

.TP

 .BI r\  file

-Read file into dot or at the cursor (∗)

+Read file into dot or at the cursor

.TP

 .B s

 Show dot by piping it to a new

@@ -181,7 +174,7 @@

 .B x

 Crop to dot (exclusive cut); does

 .B not

-touch the snarf buffer (‡)

+touch the snarf buffer

.PD

.PP

 Upon typing a key not part of the set of keyboard shortcuts,

@@ -189,31 +182,34 @@

 Commands are single character codes,

 and all following text is used as an arguments list.

.PP

-Editing is performed either on the dot,

-its complement (everything excluding the dot),

-or at the position of the cursor if the dot is in its default state.

+Editing is performed upon a range or at a position:

+the dot if a bound is set, or the anchor if iet is set, or the entire data.

+.PP

 Operations are entirely decomposable into a series of one or more

 insertions or deletions

 .RI ( indels ).

 Insertions place new data at an offset from the start,

-either the left bound of the dot if set, or the cursor's position.

-Deletions act on and thus require a valid dot,

-smaller than the size of the buffer.

-Commands above marked with a star (∗) change their behavior

-depending on whether the dot is set or not;

-those marked with a dagger (‡) always require a valid dot.

+either the left bound of the dot or the anchor.

+Deletions act upon a range, either the dot or the entire data.

+The

+.BR < ,

+.BR r ,

+and

+.B p

+commands either insert new data at the anchor point,

+or replace the contents of the dot.

+In the latter case, two operations occur, first to delete the dot,

+then to insert the new data.

.PP

The

-.I u

+.B u

 (undo) command reverts a single indel and restores the dot as it were before.

-In other words, complex operations that are a series of several indels

-require multiple

-.I undo

-commands to be unrolled completely.

+Compound operations are not undone in one go.

+For example, undoing a paste/replace command will require two commands.

 .I Undo

 is not infinite and there currently is no

 .I redo

-implementation.

+command.

.PP

 Commands

 .BR < ,\  ^\ and\ |

@@ -223,11 +219,14 @@

 In other words, expressions such as:

.IP

.EX

-|stretch -r1.2 | norm -f 2 | audio/wavenc > seymourbutz.wav

+| stretch -r1.2 | norm -f 2 | audio/wavenc > seymourbutz.wav

.EE

.PP

 will be passed as a single string to and evaluated in a subshell,

 with the dot written to its standard in.

+.I Pplay

+does not handle any subprocess' abnormal exits in any way.

+.PP

 File i/o commands

 .BR r ,\  w

 prompt for a pathname which is also uninterpreted.

@@ -262,6 +261,8 @@

 .I Pplay

 first spawned on 9front (October, 2017), beyond the environment.

 .SH BUGS

+Undo is still unreliable.

+.PP

 Drawing halts while playback is paused.

.PP

 Mousing, in particular for panning, can be uncomfortable or annoying.