[xiph-cvs] r6775 - trunk/postfish

[xiphmont at xiph.org]

Author: xiphmont
Date: 2004-05-28 21:20:41 -0400 (Fri, 28 May 2004)
New Revision: 6775

Added:
   trunk/postfish/postfish.1
Removed:
   trunk/postfish/postfish.1
Log:
Blank the manpage for now; having the old Postfish 1 manpage around
with Postfish 2 is useless and confusing

<p><p>Deleted: trunk/postfish/postfish.1
===================================================================
--- trunk/postfish/postfish.1	2004-05-29 01:17:47 UTC (rev 6774)
+++ trunk/postfish/postfish.1	2004-05-29 01:20:41 UTC (rev 6775)
@@ -1,398 +0,0 @@
-.TH POSTFISH 1 "01 Dec 2002"
-.SH NAME
-postfish \- a lightweight, ncurses-based live recording postprocessor
-.SH SYNOPSIS
-.B postfish
-[
-.B \< input WAV 
-]
-[ 
-.B input WAV list 
-]
-[
-.B \> WAV file or device
-]
-.SH DESCRIPTION
-
-.B postfish
-takes a live stream or input file on stdin (or a list of contiguous
-WAV files in an argument list), optionally performs one or all of
-spectral noise gating, equalization, amplitude attenuation, dynamic
-range attenuation, and limiting.  The processed audio is sent to
-stdout as a WAV, which may be redirected to a file, redirected to an
-audio device or piped to another process.  
-
-Input is a WAV format data on stdin or as a list or arguments; if
-input appears on stdin, the argument list is ignored. If input is
-specified as a file list, Postfish assumes that the files are
-matching, contiguous WAVs, as would be produced by Beaverphonic; the
-audio in these files will be treated as a single, seamless audio
-stream during processing and navigation.
-.B postfish
-is not capable of setting up a recording audio device, nor the
-real-time scheduling necessary to guard against skips when sampling;
-input can not be taken directly from a audio device.
-
-If stdout is directed to a file or piped to another application,
-output will be in 16 bit WAV format with the same sampling rate and
-number of channels as input.  If stdout is redirected to an audio
-device, this device will be used for real-time playback.  If stdout is
-neither piped nor redirected,
-.B postfish 
-assumes audio device output on /dev/dsp.
-
-.SH OPTIONS
-
-None.  The application is interactive via an ncurses interface.
-
-.SH UI NAVIGATION
-
-Configurable fields nominally appear in 
-.B bold
-or
-.B high intensity
-text.  The field that currently responds to editing is represented in
-reverse video. The arrow keys can be used to move the edit cursor
-left, right, up and down; tab moves to the next field.  A selected
-numeric field is incremented/decremented slowly via the '=' and '-'
-keys.  For fast increment/decrement, use '+' and '_'.  The A and B
-time cue fields can be edited directly like a text input area with a
-text cursor.
-
-Toggle fields are marked on-screen with the key used to activate or
-toggle the field value in brackets.  For example, the equalizer is
-turned on/off by pressing 'e'.  Toggle keys do not move the edit
-cursor.
-
-.SH NOISE GATING
-
-A noise gate is used to attenuate/eliminate noise from a recording;
-this noise might be white electrical noise or background room noise.
-The 
-.B postfish
-noise gate is an FFT threshold-based rejector; any spectral line value
-less than the interactively chosen threshold value is rejected
-entirely.  The lines on the graph displayed during playback are
-dB-scale average-to-max values for that spectral band relative to the
-desired threshold value.  For example, if the input spectral energy
-of a given band exceeds the threshold, the spectral line will extend
-to the right past the center graph line.  If the spectral band is
-being rejected completely, the spectral line will lie entirely to the
-left of the center line.  If the band is currently only being
-partially rejected, the spectral line will straddle the center line.
-
-Each quarter-octave band has an independent, configurable threshold
-value; these values are absolute dB values of the input signal
-relative to the maximum possible signal level (0dB).  A lower (more
-negative) value supplies less rejection; A higher (more positive)
-value specifies more rejection.
-
-.TP
-.RB [ n ]
-toggles the noise gate on and off.  When off, the noise gate is still
-editable but
-.B postfish
-does not perform gating. The on-screen graph is primarily intended to
-assist in selecting configuration settings and is unaltered by the
-noise gate being active or inactive.
-.TP
-.RB [ N ]
-toggles the noise gate edit mode between narrow-band and wideband mode.
-In narrow-band mode, incrementing/decrementing a band threshold level
-affects only that band.  Wideband mode allows 'painting with a broader
-brush' and allows the increment/decrement to also pull up or push down
-the values of neighboring bins into a wide, smooth bump or pit in the
-spectrum.
-
-.SH EQUALIZATION
-
-An equalizer is used to adjust or correct the frequency
-response/spectral bias of a recording, or to implement special effects
-(such as a broad boost to bass).  
-
-.B postfish
-implements a 35 band quarter-octave equalizer that allows up to 30 dB
-of cut/boost per band.  The center line of the EQ graph is perturbed
-left or right to reflect the configured cut/boost.  A horizontal
-signal level line spans from average to maximum signal level in that
-band.  The displayed signal is post-gating/post-eq and prior any
-attenuation or limiting.
-
-.TP
-.RB [ e ]
-toggles the equalizer on and off.  When off, the equalizer is still
-editable, but
-.B postfish
-does not perform equalization.  The on-screen graph displays spectral
-data according to equalizer mode; if equalization is inactive, the
-graph represents unequalized data.
-.TP
-.RB [ E ]
-toggles the equalizer edit mode between narrow-band and wideband mode.
-In narrow-band mode, incrementing/decrementing a band level affects
-only that band.  Wideband mode allows 'painting with a broader brush'
-and allows the increment/decrement to also pull up or push down the
-values of neighboring bins into a wide, smooth bump or pit in the
-spectrum.
-
-.SH MASTER AMPLITUDE ATTENUATION
-
-A fancy name for a volume knob.  The attenuation is performed after
-gating and EQ, but before any limiting.  The upper single-bar graph on
-the far right hand side of the terminal displays the peak output
-signal level after any attenuation and before any limiting.  The bar
-represents the instantaneous peak and the number to the right of the
-bar displays peak signal since playback began.
-
-Note that +0dB is the maximum representable output signal level; if
-the signal level reaches 0dB, it begins to clip (see
-limiting/soft-clipping below).
-
-Master attenuation is expressed in dB; positive dB will increase
-the signal, negative dB will decrease it.
-
-.TP
-.RB [ m ]
-toggles Master Attenuation on and off.  Even when off, 
-.B postfish 
-updates the bargraph with unattenuated signal level.
-
-.SH DYNAMIC RANGE ATTENUATION
-
-Dynamic range attenuation is used to shrink or expand to total signal
-depth of a recording.
-
-A shallow signal depth (negative attenuation) makes sound levels
-of different elements of a recording sound closer together in
-amplitude, typically resulting in making softer elements sound louder,
-but keeping already loud aspects the same.  Most 'pop' music has
-substantial negative dynamic range attenuation.
-
-Deepening signal depth (positive attenuation) broadens the perceived
-volume range of a recording.  This can be used to restore depth to a
-recording that has previously had its dynamic range shrunk, or to hide
-low level noise by growing the range, making soft noise even softer.
-
-Dynamic range attenuation is performed at the same time as amplitude
-attenuation (after gating/EQ and before limiting). The upper
-single-bar graph on the far right hand side of the terminal displays
-the peak output signal level after attenuation and before any
-limiting.  The bar represents the instantaneous peak and the number to
-the right of the bar displays peak signal since playback began.
-
-Note that +0dB is the maximum representable output signal level; if
-the signal level reaches 0dB, it begins to clip (see
-limiting/soft-clipping below).
-
-.TP
-.RB [ r ]
-toggles Dynamic Range attenuation on and off.  Even when off, 
-.B postfish 
-updates the bargraph with unattenuated signal level.
-
-.SH FRAME SIZE
-
-.B postfish
-performs most processing operations in the frequency domain.  Data is
-taken from PCM representation to frequency domain via a windowed,
-50%-lapped FFT transform.  An FFT must operate on frames of data at a
-time; the size of these frames is configurable here.
-
-Unlike all other
-.B postfish
-configuration fields which take effect immediately during
-playback/processing, frame size configuration takes effect only when
-playback/processing is stopped.  To change frame size during playback,
-alter the requested frame size, then pause and restart playback (such
-as by hitting
-.RB [ space ]
-twice).
-
-The choice of frame size represents a tradeoff between time
-resolution and frequency resolution.  For most applications, there's a
-nice wide sweet-spot of appropriate frame sizes in the middle of the
-range.  In summary:
-
-.TP
-a larger frame size yields higher-quality, more stable output
-(especially for noise gating), but the filters 'react' more slowly.
-.TP
-a smaller frame size yields faster 'reactions', but because the
-smaller transform is more prone to sidelobe energy leakage, the
-filters are lower quality and can produce increasingly odd artifacts
-when used aggressively.
-
-.SH LIMITING / SOFT CLIPPING
-
-When a digital PCM signal exceeds exactly 0dB, the loudest
-representable sound, it hits a brick wall.  It can get no louder and
-instantly saturates, creating a sharp 'corner' in the waveform that
-shows up as potentially very high energy, spread-spectrum noise.
-
-One generally strives to avoid audio intentionally exceeding
-representation range.  However, attenuating an entire recording of
-soft music, for example, to avoid clipping during applause at the end
-may be undesirable.  Dynamic limiting is an easy, effective way to
-cheat.
-.B postfish
-offers two limiter types: a block attenuator and a soft-clipper. 
-
-Soft Clip applies a non-linear function directly to the
-instantaneous waveform amplitude. At amplitudes under the configured
-threshold, the waveform is linear as normal.  At amplitudes over the
-threshold, the waveform amplitude is rolled off in a standard 1/x
-inverse relationship asymptotically approaching 0dB.  The end result
-is to 'round off' the corners of any clipping that would have
-happened.  Soft clipping doesn't eliminate clipping noise, but it can
-substantially hide it.
-
-Block Attenuation works on frames of data and behaves much like the
-\'record-auto-level' feature on portable tape recorders.  It selects
-the peak amplitude seen over a configurable time period (the Block
-Period setting), determines a scaling value for the entire
-current frame by applying the same nonlinear transfer function as in
-the Soft Clipper to the peak value and then attenuating the
-entire frame by that scaling value.  The effect is much like a
-hyper-fast volume knob (how fast can be configured using the Block Period
-field) keeping the output data from clipping.
-
-The second single-bar graph on the far right hand side of the terminal
-shows output level after applying limiting.  As the graph is most
-useful for configuration, it is updated as if limiting occurred even
-when the Limiter is turned off.  The center line of the graph, marked
-\'A', denotes the limiter threshold where the inverse roll-off begins.
-The numeric value to the right of the bargraph indicates the largest
-peak-limited amplitude since playback began.
-
-.TP
-.RB [ l ]
-flips between the three possible Limiter modes: Soft Clip, Block
-Attenuate and Off.
-
-.SH CUEING / FILE NAVIGATION
-
-If the input is a seekable file or files, 
-.B postfish
-provides seeking and cueing functions in the form of editable A and B
-cue points, A-B looped playback mode, and ten settable cue 'tabs'.
-
-The A and B fields may be edited directly by selecting via
-.RB [ tab ]
-or the arrow keys, and then entering a numeric value using the keyboard.
-The time fields are expressed in HH:MM:SS.FF format where HH is hours,
-MM is minutes, SS is seconds and FF is hundredths of a second.
-
-In addition, the A and B fields, if empty, may be set directly from
-the playback time cursor (displayed below A and B) by pressing
-.RB [ a ]
-or
-.RB [ b ].
-If the A field already contains a time, pressing
-.RB [ a ]
-will instantly cue the playback cursor to the time in the A field.  If
-playback is in progress, playback will jump directly to A.  If
-playback is stopped, the playback cursor will cue to A but playback
-will not begin.  If both A and B contain times, playback will be in
-\'A-B' mode, in which playback will continuously loop between points A
-and B. Pressing 
-.RB [ A ] 
-or 
-.RB [ B ]
-will clear the time fields A and B, respectively.  Clearing the B field
-will exit A-B loop mode.
-
-The cue tabs behave like the A field, but are not keyboard
-editable. Set a cue tab from the current playback cursor by pressing
-.RB [ 0-9 ]
-to select an empty cue tab.  If a cue tab is already set, pressing 
-.RB [ 0-9 ]
-will instantly cue the playback cursor to that time.  Cue tabs may be
-cleared using
-.RB [ )-( ],
-that is, 0 through 9 shifted.
-
-Other playback navigation controls are included below.
-.TP
-.RB [ < ]
-Jump back one minute
-.TP
-.RB [ > ]
-Jump ahead one minute
-.TP
-.RB [ , ]
-Jump back five seconds
-.TP
-.RB [ . ]
-Jump ahead five seconds
-.TP
-.RB [ space ]
-Toggle between playback and pause.  Does not affect cueing.
-.TP
-.RB [ Backspace ]
-halt playback and cue playback cursor to time in field A.
-.TP
-.RB [ a ]
-If A is empty, store current playback cursor in A.  Else, cue playback
-cursor to A.
-.TP
-.RB [ A ]
-Clear field A.
-.TP
-.RB [ b ]
-If B is empty, store current playback cursor in B; this places
-playback in A-B loop mode.
-.TP
-.RB [ B ]
-Clear field B.
-.TP
-.RB [ 0-9 ]
-If cue tab is empty, store current playback cursor in tab.  Else, cue
-playback cursor to tab.
-.TP
-.RB [ )-( ]
-Clear cue tab.
-
-.SH CONFIGURATION BANKING
-
-.B postfish
-allows a user to flip back and forth quickly amongst several
-configurations.  These configurations are stored in a bank-like
-system.  Switching from bank to bank requires a single keypress and
-the new configuration applies to playback instantly.  All noise gate,
-EQ, attenuation and limiting parameters are handled by bank.  Time
-queueing information and edit modes are global settings and not stored
-by bank.
-
-The five configuration banks are labelled v through z and may be
-selected by pressing
-.RB [ v-z ].  
-Visible settings are stored in the configuration bank marked
-\'Current'.  Selecting another bank marked \'full' will switch
-instantly to the configuration in that bank.  Returning to the
-previous bank will restore the previous settings.  Selecting an empty
-bank will switch to that bank, but retain current configuration.  This
-interface prevents any accidental loss of data when switching banks;
-the current configuration is always stored somewhere upon a switch.
-
-Clear a bank by pressing 
-.RB [ V-Z ].
-When a current bank is cleared, it reverts to default settings.
-
-All configuration data, including all banks, the current active bank
-and all global configuration is saved into the file \'.postfishrc' in
-the current working directory upon quitting the application with
-.RB [ q ].
-This configuration file is loaded upon application startup.  The
-\'.postfishrc' allows the new
-.RB postfish
-process to pick up exactly where the previous one left off.  The only
-unsaved parameters are the current playback cursor and the current
-edit cursor position.
-
-.P
-.SH AUTHOR
-Monty <monty at xiph.org>
-
-.B postfish 
-lives at cvs.xiph.org:/usr/local/cvsroot, username 'anoncvs', password
-\'anoncvs', module 'postfish'. Sorry, no homepage.

Added: trunk/postfish/postfish.1
===================================================================

--- >8 ----
List archives:  http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body.  No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.