home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.0 / NeXTSTEP3.0.iso / NextDeveloper / Headers / sound / atcsound.h < prev    next >
Text File  |  1992-03-16  |  5KB  |  122 lines
  1. /*
  2.  *    atcsound.h - features related to Audio Transform Compression (ATC).
  3.  */
  4.  
  5. /*
  6.  * In all functions below, the return value is 0 for success and
  7.  * nonzero for failure.  A failure return generally means the feature is
  8.  * not available (e.g., on non-NeXT hardware).
  9.  */
  10.  
  11. int SNDGetNumberOfATCBands(int *nBandsP);
  12. /*
  13.  * Get number of frequency bands used by ATC (40 in release 3.0).
  14.  * The band frequencies correspond roughly to the critical
  15.  * bands of hearing.  Band 0 is "D.C.", meaning it is centered
  16.  * at 0 Hz.  At higher frequencies the bands are wider and 
  17.  * spaced farther apart.  The band width and spacing are approximately
  18.  * 20% of the band center-frequency above 500 Hz, and uniform
  19.  * below 500 Hz.  These remarks apply to the standard 44.1 kHz sampling rate.
  20.  * At other sampling rates, the bands frequencies are scaled so that the same
  21.  * number of bands covers 0 Hz to half the sampling rate, whatever it is.
  22.  */
  23.  
  24.  
  25. int SNDGetATCBandFrequencies(int nBands, float *centerFreqs);
  26. int SNDGetATCBandwidths(int nBands, float *bandwidths);
  27. /*
  28.  * Get center-frequency or bandwidth in Hertz for each band used by ATC.
  29.  * Assumes a 44.1 kHz sampling-rate.
  30.  */
  31.  
  32.  
  33. int SNDGetATCEqualizerGains(int nBands, float *gains);
  34. int SNDSetATCEqualizerGains(int nBands, float *gains);
  35. int SNDScaleATCEqualizerGains(int nBands, float *gainScales);
  36. /*
  37.  * Get/set/scale graphic-equalizer gains for ATC playback.
  38.  * Obtain nBands from SNDGetNumberOfATCBands().  Each gain specifies a
  39.  * factor to be multiplied times the band amplitude during sound playback.
  40.  * The gain can be any nonnegative number, although there is an 
  41.  * internal maximum limit. Only gains between 0.0 and 1.0 will not 
  42.  * cause output overflow under all conditions.  If overflow occurs, the
  43.  * result will be clipped.  The system default gain is 1.0 in each band 
  44.  * (no equalization).  Changes take effect for the next sound played, i.e.,
  45.  * any currently playing sound is unaffected.
  46.  */
  47.  
  48.  
  49. int SNDGetATCSquelchThresholds(int nBands, float *thresh);
  50. int SNDSetATCSquelchThresholds(int nBands, fBSq *thresh);
  51.  
  52. int SNDUseDefaultATCSquelchThresholds(void);
  53. /*
  54.  * Get/set "squelch" levels used in ATC encoding.
  55.  * Obtain nBands from SNDGetNumberOfATCBands().  Each level specifies a
  56.  * threshold below which sound amplitudes are set to zero.
  57.  * Tbe band frequencies are the same as those used in the graphic equalizer.
  58.  * 
  59.  * The squelch thresholds trade sound quality for greater compression.
  60.  * The higher the squelch thresholds, the greater the compression.  
  61.  * However, setting the thresholds too high will introduce sonic artifacts.
  62.  *
  63.  * It is possible to use the squelch threshold to suppress noise in 
  64.  * a recording, especially when that noise is steady, such as tape hiss
  65.  * or static hum.
  66.  * 
  67.  * A squelch threshold of 1.0 is considered to be the nominal maximum.
  68.  * Therefore, a value of 1.0 for thresh[i] 
  69.  * implies band i is rejected almost always.  A value of -120.0
  70.  * ensures band i is never squelched.  
  71.  *
  72.  * The system default squelch thresholds are set to the estimated threshold 
  73.  * of hearing in each band, assuming a normal listening level for the sound 
  74.  * output.  The system default can always be restored by calling
  75.  * SNDUseDefaultATCSquelchThresholds().
  76.  *
  77.  * Changes take effect for the next sound encoded, i.e.,
  78.  * any currently compressing sound is unaffected.
  79.  */
  80.  
  81.  
  82. int SNDGetATCGain(float *oLevelP);
  83. int SNDSetATCGain(float oLevel);
  84. /*
  85.  * Get/set overall sound output level for ATC sound playback (in decibels).
  86.  * A value of 1.0 means no change.  A value of 0.0 will silence any sound.
  87.  * Note that this volume setting affects "line out" as well as the speaker
  88.  * output.  (It is implemented as a scaling of the ATC equalizer gains.)
  89.  * Changes take effect for the next sound played.
  90.  */
  91.  
  92. int SNDDropATCSamples(int nSamples, int bySamples);
  93. int SNDInsertATCSamples(int nSamples, int bySamples);
  94. /*
  95.  * These functions provide a crude level of support for ATC sound 
  96.  * synchronization. By dropping or inserting samples,
  97.  * time can be "warped" in the playback of an ATC sound.
  98.  * To determine when to insert or drop samples, SNDSamplesProcessed()
  99.  * can be called to obtain an estimate of how many samples have been
  100.  * played out, and this can be compared to some other source of
  101.  * time in units of samples at the current sampling rate.
  102.  *
  103.  * If bySamples is zero, the samples are inserted or dropped when
  104.  * coBSrient by the algorithm (one sample per 256-sample frame).
  105.  * Otherwise, an attempt is made to add or drop the requested number
  106.  * of samples within bySamples samples.  Outrageous requests may produce
  107.  * outrageous results.
  108.  * 
  109.  * If bySamples is negative, the drop or insert request is repeated
  110.  * indefinitely.  It is equivalent to renewing the request every 
  111.  * abs(bySamples) samples.  This hack can be used to effect a speed control.
  112.  * The formula is dropSamples = (int)(((float)bySamples)*(1. - 1./speed)+0.5),
  113.  * where speed==1.0 means no change, speed==2.0 means play twice as fast, etc.
  114.  * 
  115.  * Inserting or dropping samples should not cause a click in the 
  116.  * sound, but it will cause some distortion.
  117.  * 
  118.  * The samples to insert or drop are selected randomly by system software
  119.  * at the time the call is received.  An ATC sound must be actively playing
  120.  * for these calls to have effect.
  121.  */
  122.