Skip to content

GitLab

Commit 1fb4b04b authored by Monty Montgomery's avatar Monty Montgomery
Browse files
Options

Blank the manpage for now; having the old Postfish 1 manpage around 

with Postfish 2 is useless and confusing



git-svn-id: https://svn.xiph.org/trunk/postfish@6775 0101bb08-14d6-0310-b084-bc0e0c8e3800
parent affc4a72
Hide whitespace changes
Inline Side-by-side
Showing with 0 additions and 398 deletions
postfish.1
View file @ 1fb4b04b
.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@xiph.org>
.B postfish
lives at cvs.xiph.org:/usr/local/cvsroot, username 'anoncvs', password
\'anoncvs', module 'postfish'. Sorry, no homepage.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment