ref: 79cda97b806baf2adfc0045537675684d1edfe75
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 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 and most editing operations do not reset the selected
range in a natural enough way.