.TH CONVERT 1carl CARL
.SH NAME
convert - time-varying and arbitrary sample-rate conversion
.SH SYNOPSIS
.B convert -rN [-flags] [filename]
< floatsams > floatsams
.sp
.nf
flags:
r = output sample rate (must be specified)
t = minimum time increment (time-varying only)
Q = quality factor (1, 2, 3, or 4: default = 2)
R = input sample rate (automatically read from stdin)
b = starting sample (0)
e = final sample (end of input)
.fi
.SH DESCRIPTION
This program out-performs the standard \fIsrconv\fR program
in three different ways:
.IP
1) For simple integer-ratio sample-rate conversion, it produces
a result equivalent to the %% specification of \fIsrconv\fR with less
computation.
.IP
2) It performs arbitrary sample-rate conversions which are impossible
with \fIsrconv\fR.
.IP
3) It performs time-varying sample rate conversions which are impossible
with \fIsrconv\fR.
.PP
For non-time-varying applications, \fIconvert\fR requires only that the
desired output sample rate be specified via the -r flag.  For example,
.IP
sndin file1 | convert -r24K | sndout file2
.LP
will produce a file2 which is a 24KHz sample-rate version of file1,
regardless of what the sample rate of file1 may be.  The default
quality factor should be good for virtually any application, and 
persons using a higher setting should be prepared to prove their
ability to hear the difference in a blind listening test!
.PP
For time-varying sample-rate conversion, the situation is more
complicated.  The time-varying specifications are input via a
unix file (specified on the command line after whatever flags
may be present) of x,y pairs where x is the time in seconds.  The
y values may either be desired_output_sample_rate_at_time_x,
or (input_sample_rate / desired_output_sample_rate_at_time_x).
.PP
If the y values are of the first form (i.e., output_rate), then
the -r flag has no real meaning.  However, its presence is still
mandatory. In this case, the -r flag MUST specify the minimum
output sample rate (i.e., the minimum y value in the file).
.PP
If the y values are of the second form (i.e., input_rate / output_rate)
then the -r flag MUST be replaced by the -t flag.  This is the only
case in which the -r flag is not used and the only case in which the 
-t flag is used.  Furthermore, the -t flag MUST specify the minimum
y value in the file.  
.PP
The advantage to this second form is that when using \fIconvert\fR
after the phase vocoder to change a time-varying time-scaling
into a time-varying pitch-transposition, the same x,y pairs
can be used to control both \fIpvoc\fR and \fIconvert\fR. 
For example, to produce an upward glissando of one octave over
four seconds:
.IP
gen4 -L100 0 1  0  4 2 | btoa -t -R25 | atob > gliss
.IP
sndin file | pvoc -T1 gliss | sndout temp
.IP
sndin temp | convert -t1 gliss | sndout file
.PP
When using \fIconvert\fR after the phase vocoder to change a fixed
time-scaling into a fixed pitch-transposition, a little bit of
subterfuge is required.  For example, to produce a pitch transposition
of 1.01 the following steps would be necessary:
.IP
sndin file | pvoc -N1024 -I101 -D100 | sndout temp
.IP
sndin temp | convert -R16547.8 -r16K | sndout file
.LP
The first step produces a time expansion of exactly 1.01 (I/D where
I and D are integers chosen to be as large as possible but still less
than N/8).  If the input file had a sample rate of 16K, then the file
"temp" also has a sample rate of 16K.  However, if the file "temp" is
played at a sample rate of 16547.8 (1.01*16K), then it will be transposed
in pitch by a factor 1.01 and shortened back to the duration of the input
file.  But we want "temp" to sound transposed when played at a sample
rate of 16K.  Hence, the trick is to sample-rate-convert "temp" from
16547.8 to 16K.  Since \fIconvert\fR normally reads the input sample rate
from the header of the input soundfile, the -R flag is used to override
the information in the header.
.SH DIAGNOSTICS
.SH AUTHOR
Mark Dolson
.SH FILES
.SH BUGS
