ref: 3528b912b5bca3c5aa51a6ca165c5e8d4e6c5b77
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),
.I @
the current playback position,
.I ↺
the starting loop point,
.I -
the ending loop point, and
.I ‡
the cursor (last left click).
The last 4 timestamps are displayed in
[hh:mm:ss.tt] format (see
.IR tmdate (2)),
or the number of stereo samples so far if toggled.
.PP
When the selected range is the entire data and only the
.I @
timestamp is displayed.
The
.I ‡
timestamp is displayed if a cursor has been set
see section "Loop points and selection" below).
.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
Middle-clicking either left or right of the current playback position cursor
sets respectively the start or end loop point.
Left-clicking within the 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 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 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.
Each of them runs concurrently in the background
and updates the then selected range once done.
Upon exit,
.I pplay
will wait for subcommands to end and exit first.
.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
.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
An external command that never exits will freeze
.I pplay
forever on exit due to the reliance on
.BR thread (2).
Subprocess abnormal exits are completely unhandled.
Edits in a range while a shell command affecting it is running,
or the case of multiple shell commands on intersecting ranges,
are not serialized or protected in any way.
.PP
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 don't restore the previous selection correctly,
and most editing operations don't do set the new selection well enough.