ref: 38230eaac9e5abc55f7dce0f6fce0b9542a54258
dir: /pplay.man/
.TH PPLAY 1 .SH NAME pplay \- visual PCM audio player and editor .SH SYNOPSIS .B audio/pplay [ .B -Dbc ] [ .B pcmfile ] .SH DESCRIPTION .I Pplay 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 raw format used by the audio device (see .IR audio (3)). .PP At startup, all input is loaded in its entirety into memory, either from .B pcmfile if provided, or from standard in. It then writes samples to .BR /dev/audio , unless .B -c is specified. .SS "Command line parameters" .TF "-D" .TP .B -D Turn verbose debugging info on immediately .TP .B -b Use inverted colors (dark background) .TP .B -c Write audio to standard out instead of .B /dev/audio .PD .SS "Keyboard and mouse commands" Key commands: .TF "Esc" .TP .B q Quit .TP .B D Toggle debug tracing and draws .TP .B S Toggle stereo display (default left channel only) .TP .B ␣ Toggle play/pause .TP .B b Jump to loop start .TP .B Esc Reset selection .TP .B = Zoom in .TP .B - Zoom out .TP .B + Fine zoom in .TP .B _ Fine zoom out .TP .B ↵ Zoom into the entire dot .TP .B z Reset zoom to entire buffer .TP .B ← Pan left by screenful .TP .B → Pan right by screenful .PD .PP Mouse buttons: .TF "1 " .TP .B 1 Set cursor .TP .B 2 Set left or right dot bound .TP .B 3 Pan view horizontally .PD .SS "Dot and cursor position" .I Pplay 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 displays on the y axis the maximal and minimal signed value among all samples packed in each pixel column for one audio channel. .PP 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 into dot .TP .BI ^\ cmd Pipe dot to a shell command and read back its output into dot .TP .BI |\ cmd Pipe dot to a shell command .TP .B c Set snarf buffer to the contents of the dot .TP .B d Cut dot, replacing snarf buffer .TP .B p Paste snarf buffer into dot or insert at the cursor .TP .BI r\ file Read file into dot or at the cursor .TP .B s Show dot by piping it to a new .IR pplay (1) instance .TP .B u Undo an edit and dot change .TP .BI w\ file Write dot to file .TP .B x Crop to dot (exclusive cut); does .B not touch the snarf buffer .PD .PP Upon typing a key not part of the set of keyboard shortcuts, a text entry appears to enter commands in. Commands are single character codes, and all following text is used as an arguments list. .PP 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 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 .B u (undo) command reverts a single indel and restores the dot as it were before. 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 command. .PP Commands .BR < ,\ ^\ and\ | need a valid .IR rc (1) expression, which is then passed uninterpreted. In other words, expressions such as: .IP .EX | 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. Consequently, commands and i/o may fail once actually executed; in case .I pplay was reading from a file or pipe, the partial content already loaded will not be discarded. .SS Memory management No data loaded into memory is ever freed unless it can be guaranteed to never be used again. While refcounting is already being done, currently no attempt to keep guarantees is made and nothing is ever freed. However, memory is never duplicated. Therefore, it is dangerous to load large amounts of data, but once loaded, memory usage will not grow much. .SH EXAMPLES Use .IR play (1) to decode any known audio format: .IP .EX ; play -o /fd/1 file | audio/pplay .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 Undo is still unreliable. .PP Drawing halts while playback is paused. .PP Mousing, in particular for panning, can be uncomfortable or annoying. .PP There are no safeguards against races when writing to file. .PP The data structure implementation underlying the editing commands is, despite much effort to the contrary, still prone to off-by-ones and other bugs. Trust, but save often. .PP Any unintended interruption in playback due to scheduling, or slower than instaneous redraws, are considered bugs, and drawing ones are still there -- crawling, slithering, glistening in the dark, poisoning my dreams and turning them into nightmares.