ref: dbaac92cf534e42ee7e5a7b291a354f7b81bd835
dir: /pplay.man/
.TH PPLAY 1
.SH NAME
pplay \- PCM audio player and editor
.SH SYNOPSIS
.B audio/pplay
[
.B -bc
] [
.B pcmfiles..
]
.SH DESCRIPTION
.I Pplay
is an interactive audio player and editor for PCM files
(16-bit stereo audio at 44.1 kHz sampling rate, see
.IR audio (3)),
displaying each channel's waveform and the current playback position.
.PP
Playback loops forever between two positional markers,
initially the beginning and end of the data
(see section
.I Loop points and selection
below).
.SS "Command line parameters"
.TF "-b"
.TP
.B -b
Use inverted colors (dark background)
.TP
.B -c
Write audio to standard out instead of
.B /dev/audio
.PD
.SS "Graphical interface"
.I Pplay
visualizes a window of data by splitting it in chunks of samples
by pixel column on the x axis and extracting the minimal and maximal values.
The y axis is the entire range of values from -32768 to 32767, bottom to top.
If stereo display is enabled, the view is split in two, with the right channel on the bottom.
Otherwise only the left channel is shown.
.PP
Time information is displayed on the bottom left,
with
.I T
the sample period (stereo samples per pixel),
then the current playback position,
and, if set, the start and end loop points and cursor (last left click).
Timestamps are displayed in
[hh:mm:ss.tt] format (see
.IR tmdate (2)),
or the number of stereo samples so far if toggled.
.PP
The view can be moved horizontally with the cursor keys,
or by holding the right mouse button.
Zooming in decreases the sample period (and vice-versa)
via keyboard shortcuts, the mouse scroll buttons,
or by holding the left mouse button while panning.
.SS "Loop points and selection"
Playback is constrained to a range defined by two positional markers,
the start and end loop points, initially the entire data.
This range also acts as a selection for editing operations.
No selection can be made outside of this range.
.PP
The start and end loop points are both set with the middle mouse button.
Only one of them can be set at a time, by default the start loop point.
The
.I 1
and
.I 2
keyboard keys are used to switch between the two.
Setting the start loop point after or the end loop point
before the current playback position
will reset playback at the start loop point.
Swapping start and end loop points is disallowed.
.PP
Left-clicking within the selected range sets the current playback position.
The last left click is stored as another positional marker ("cursor")
for some commands.
Reseting the loop points selects the entire data again and removes the cursor.
Loop points may also be set to a specific sample number or timestamp
via commands (see below).
.SS "Keyboard and mouse commands"
Key commands:
.TF "Esc"
.TP
.B ␣
Toggle play/pause
.TP
.B S
Toggle stereo channel display (default: left only)
.TP
.B Tab
Toggle visible mono or top channel
.TP
.B t
Toggle time display in samples
.TP
.B Esc
Reset selection
.TP
.B 1
Toggle setting start loop point
.TP
.B 2
Toggle setting end loop point
.TP
.B b
Jump to loop start
.TP
.B =
Zoom in
.TP
.B -
Zoom out
.TP
.B +
Fine zoom in
.TP
.B _
Fine zoom out
.TP
.B ↵
Zoom into current selection
.TP
.B z
Reset zoom to entire buffer
.TP
.B ←
Pan left by screenful
.TP
.B →
Pan right by screenful
.TP
.B D
Kill spawned reader process if it exists
.TP
.B Del
Kill any spawned external processes
.TP
.B q
Quit
.PD
.PP
Any other key opens up a command prompt (see Commands section below).
.PP
Mouse buttons:
.TF "1 "
.TP
.B 1
Set current playback position
.TP
.B 2
Set start or end loop point
.TP
.B 3
Hold to pan view horizontally
.PD
.SS "Editing commands"
Typing any key that isn't a shortcut opens a command prompt.
Commands are single characters followed by optional arguments.
.PP
.TF "L sample"
.TP
.B c
Copy selection (sets hold buffer)
.TP
.B d
Cut selection (sets hold buffer)
.TP
.B x
Crop to selection (exclusive cut; does not set hold buffer)
.TP
.B p
Replace selection or insert at cursor from hold buffer
.TP
.BI <\ cmd
Replace selection with output of shell command
.TP
.BI ^\ cmd
Pipe selection to shell command and replace with its output
.TP
.BI |\ cmd
Pipe selection to a shell command
.TP
.BI r\ file
Replace selection or insert at cursor with the contents of
.I file
.TP
.BI !\ cmd
Execute shell command without any i/o
.TP
.BI w\ file
Write selection to
.I file
.TP
.B u
Undo edit
.TP
.B U
Redo edit
.TP
.BI j\ sample
Jump and set current position to
.I sample
.TP
.BI L\ sample
Set start loop point to
.I sample
.TP
.BI R\ sample
Set end loop point to
.I sample
.TP
.B s
Open selection in a new instance of
.IR pplay (1).
.PD
.PP
Some of the cut/copy commands set the contents of a "hold" buffer
which may be later inserted or pasted over the current selection
any number of times.
.PP
Note that if a cursor (last left click) has been set,
some commands will use its position alone instead of the entire range.
Setting a cursor thus allows one to insert data at a position rather than
paste over an entire range.
.PP
Shell commands are passed verbatim to
.IR rc (1)
and may be any valid expression including function definitions.
Commands which spawn a process which will write data back
.RB ( < ,
.BR ^ ,
.BR r )
disable all commands which may also modify the data
until the process exits.
.I rc
commands which do not exit on their own,
for instance when reading from a pipe,
can be interrupted with the
.B D
shortcut.
Commands which do not read in data
.RB ( | ,
.BR ! ,
.BR w )
will be left alone on exit, allowing them to finish.
.PP
Undo is infinite.
.SH EXAMPLES
Use
.IR play (1)
to decode any known audio format and pass it on standard in:
.IP
.EX
; play -o /fd/1 files.. | audio/pplay
.EE
.PP
Timestretch selection, normalize volume and save as a WAV file:
.IP
.EX
|stretch -r1.2 | norm -f 2 | audio/wavenc > seymourbutz.wav
.EE
.PP
Apply fadeout to selection:
.IP
.EX
^pcmenv 1 0 1.1
.EE
.PP
Record arbitrary amount of data from a pipe:
.IP
.EX
</dev/audio
.EE
Use the
.B D
shortcut to interrupt the reader process and paste the data read so far.
.SH "SEE ALSO"
.IR audio (1),
.IR play (1),
.IR rc (1),
.IR audio (3)
.SH HISTORY
.I Pplay
first spawned on 9front (October, 2017), beyond the environment.
.SH BUGS
The front may fall off if attempting to load data
which cannot entirely fit in available memory.
The maximum size of a single buffer is bound by the limits of
.IR malloc (2).
.PP
Undo/redo and most editing operations do not reset the selected
range in a natural enough way.