ref: 4979c45ce6223b28b1129fc79f3f007f6c3bb766
dir: pplay/pplay.man
.TH PPLAY 1 .SH NAME pplay \- visual PCM audio player and editor .SH SYNOPSIS .B audio/pplay [ .B -bc ] [ .B pcmfiles.. ] .SH DESCRIPTION .I Pplay is a PCM audio player displaying a time-domain graphical plot of the data and allowing for some simple editing operations or piping to/from external programs. It operates on raw PCM audio, the same format used by the audio device (see .IR audio (3)). .PP All input is fully loaded into memory, either from one or more input files .BR pcmfiles , or from standard in if run without arguments. It loops through the entire buffer or a selected portion forever, writing samples to .B /dev/audio unless .B -c is specified. .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 "Keyboard and mouse commands" Key commands: .TF "Esc" .TP .B q Quit .TP .B D Toggle drawing cut/insert positions in the buffer .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 (left) and end (right) loop points, by default the data's beginning 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 referred to as the .I anchor point. 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 beginning 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 "L sample" .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 .BI L\ sample Set left bound/loop point to .I sample .TP .BI R\ sample Set right bound/loop point to .I sample .TP .B U Redo an edit and restore dot .TP .B c Set snarf buffer to the contents of the dot .TP .B d Cut dot, replacing snarf buffer .TP .BI j\ sample Jump and set current position to .I sample .TP .B p Paste snarf buffer into dot or insert at the cursor .TP .BI r\ file Read .I file into dot or at the cursor .TP .B s Replicate 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 .I 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's range if the left or right bound is set, else at the anchor if it exists, else on the entire data. .PP Behavior depends on the dot. If a left or right bound is set, inserts replace the range and deletions delete it. Otherwise, if an anchor point exists, insertion inserts a buffer at its position while deletion is disallowed. If nothing is set, insertion replaces the entire buffer, and deletion is also disallowed. .PP .BR < , .BR r\ (read), and .BR p\ (paste) insert data from an external command or the copy buffer, following the rules above. .PP The .BR u\ (undo) command reverts a single indel and restores the dot as it were before, and .BR U\ (redo) similarly replays the last action that was undone. Undo is infinite. .PP Commands .BR < ,\ ^\ and\ | require a valid .IR rc (1) expression, passed uninterpreted (quoting is unnecessary). In other words, expressions such as: .IP .EX | stretch -r1.2 | norm -f 2 | audio/wavenc > seymourbutz.wav .EE .PP are passed as a single string and then 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\ and\ 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. External commands launched from within .I pplay .B are not interrupted on exit, causing it to appear stuck. Multiple commands may run concurrently. .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. The maximum size of a single buffer is bound by the limits of .IR malloc (2). .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 may irreversibly duplicate buffer contents, and there are still some issues with what is used as a dot when replacing content. Trust, but save often. .PP An external command that never exits will freeze .I pplay forever on exit due to the reliance on .BR thread (2). .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.