NAME

	pplay – PCM audio player and editor

SYNOPSIS

	audio/pplay [ –bc ] [ pcmfiles.. ]

DESCRIPTION

Pplay is an interactive audio player and editor for PCM files (16–bit stereo audio at 44.1 kHz sampling rate, see audio(3)), displaying each channel's waveform and the current playback position. Playback loops forever between two positional markers, initially the beginning and end of the data (see section Loop points and selection below). Command line parameters –b   Use inverted colors (dark background) –c   Write audio to standard out instead of /dev/audio Graphical interface 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. Time information is displayed on the bottom left, with T the sample period (stereo samples per pixel), @ the current playback position, ↺ the starting loop point, – the ending loop point, and ‡ the cursor (last left click). The last 4 timestamps are displayed in [hh:mm:ss.tt] format (see tmdate(2)), or the number of stereo samples so far if toggled. When the selected range is the entire data and only the @ timestamp is displayed. The ‡ timestamp is displayed if a cursor has been set see section "Loop points and selection" below). 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. 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). Keyboard and mouse commands Key commands: ␣     Toggle play/pause S     Toggle stereo channel display (default: left only) Tab   Toggle visible mono or top channel t     Toggle time display in samples Esc   Reset selection b     Jump to loop start =     Zoom in –     Zoom out +     Fine zoom in _     Fine zoom out ↵     Zoom into current selection z     Reset zoom to entire buffer ←     Pan left by screenful →     Pan right by screenful q     Quit Any other key opens up a command prompt (see Commands section below). Mouse buttons: 1    Set current playback position 2    Set start or end loop point 3    Hold to pan view horizontally Editing commands Typing any key that isn't a shortcut opens a command prompt. Commands are single characters followed by optional arguments. c          Copy selection (sets hold buffer) d          Cut selection (sets hold buffer) x          Crop to selection (exclusive cut; does not set hold buffer) p          Replace selection or insert at cursor from hold buffer < cmd      Replace selection with output of shell command ^ cmd      Pipe selection to shell command and replace with its output | cmd      Pipe selection to a shell command r file       Replace selection or insert at cursor with the contents of file ! cmd      Execute shell command without any i/o w file       Write selection to file u          Undo edit U          Redo edit j sample    Jump and set current position to sample L sample    Set start loop point to sample R sample    Set end loop point to sample s          Open selection in a new instance of pplay(1). 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. 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. Shell commands are passed verbatim to 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, pplay will wait for subcommands to end and exit first. Undo is infinite.

EXAMPLES

	Use play(1) to decode any known audio format and pass it on standard in: ; play –o /fd/1 files.. | audio/pplay Timestretch selection, normalize volume and save as a WAV file: |stretch –r1.2 | norm –f 2 | audio/wavenc > seymourbutz.wav Apply fadeout to selection: ^pcmenv 1 0 1.1

SEE ALSO

	audio(1), play(1), rc(1), audio(3)

HISTORY

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

BUGS

An external command that never exits will freeze pplay forever on exit due to the reliance on 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. 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 malloc(2). Undo/redo don't restore the previous selection correctly, and most editing operations don't do set the new selection well enough.