ref: 0f7b10c3990c5efd1fa1ef266b48cec8366417e9
parent: 3c9475870a081bd6e13872a17f417c85de978416
author: qwx <qwx@sciops.net>
date: Fri Feb 10 22:22:45 EST 2023
update manpage
--- 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.