home *** CD-ROM | disk | FTP | other *** search
/ Sound, Music & MIDI Collection 2 / SMMVOL2.bin / WAVUTIL / SOX7.ZIP / ST.MAN < prev    next >
Encoding:
Text File  |  1993-02-11  |  6.1 KB  |  195 lines
  1. .de Sh
  2. .br
  3. .ne 5
  4. .PP
  5. \fB\\$1\fR
  6. .PP
  7. ..
  8. .de Sp
  9. .if t .sp .5v
  10. .if n .sp
  11. ..
  12. .TH ST 1
  13. .SH NAME
  14. st - Sound Tools - sound sample file and effects libraries.
  15. .SH SYNOPSIS
  16. .B cc \fIfile.c\fB -o \fIfile \fBlibst.a
  17. .SH DESCRIPTION
  18. .I Sound\ Tools
  19. is a library of sound sample file format readers/writers
  20. and sound effects processors.
  21. .P
  22. Sound Tools includes skeleton C
  23. files to assist you in writing new formats and effects.  
  24. The full skeleton driver, skel.c, helps you write drivers 
  25. for a new format which has data structures.  
  26. The simple skeleton drivers
  27. help you write a new driver for raw (headerless) formats, or
  28. for formats which just have a simple header followed by raw data.
  29. .P
  30. Most sound sample formats are fairly simple: they are just a string
  31. of bytes or words and are presumed to be sampled at a known data rate.
  32. Most of them have a short data structure at the beginning of the file.
  33. .SH INTERNALS
  34. The Sound Tools formats and effects operate on an internal buffer format
  35. of signed 32-bit longs.
  36. The data processing routines are called with buffers of these
  37. samples, and buffer sizes which refer to the number of samples
  38. processed, not the number of bytes.
  39. File readers translate the input samples to signed longs
  40. and return the number of longs read.
  41. For example, data in linear signed byte format is left-shifted 24 bits.
  42. .P
  43. This does cause problems in processing the data.  
  44. For example:
  45. .br
  46.     *obuf++ = (*ibuf++ * *ibuf++)/2;
  47. .br
  48. would
  49. .I not
  50. mix down left and right channels into one monophonic channel,
  51. because the resulting samples would overflow 32 bits.
  52. Instead, the ``avg'' effects must use:
  53. .br
  54.     *obuf++ = *ibuf++/2 * *ibuf++/2;
  55. .br
  56. .P
  57. Stereo data is stored with the left and right speaker data in
  58. successive samples.
  59. Quadraphonic data is stored in this order: 
  60. left front, right front, left rear, right rear.
  61. .SH FORMATS
  62. A 
  63. .I format 
  64. is responsible for translating between sound sample files
  65. and an internal buffer.  The internal buffer is store in signed longs
  66. with a fixed sampling rate.  The 
  67. .I format
  68. operates from two data structures:
  69. a format structure, and a private structure.
  70. .P
  71. The format structure contains a list of control parameters for
  72. the sample: sampling rate, data size (bytes, words, floats, etc.),
  73. style (unsigned, signed, logarithmic), number of sound channels.
  74. It also contains other state information: whether the sample file
  75. needs to be byte-swapped, whether fseek() will work, its suffix,
  76. its file stream pointer, its 
  77. .I format
  78. pointer, and the 
  79. .I private
  80. structure for the 
  81. .I format .
  82. .P
  83. The 
  84. .I private 
  85. area is just a preallocated data array for the 
  86. .I format
  87. to use however it wishes.  
  88. It should have a defined data structure
  89. and cast the array to that structure.  
  90. See voc.c for the use of a private data area.  
  91. Voc.c has to track the number of samples it 
  92. writes and when finishing, seek back to the beginning of the file
  93. and write it out.
  94. The private area is not very large.
  95. The ``echo'' effect has to malloc() a much larger area for its
  96. delay line buffers.
  97. .P
  98. A 
  99. .I format
  100. has 6 routines:
  101. .TP 20
  102. startread
  103. Set up the format parameters, or read in
  104. a data header, or do what needs to be done.
  105. .TP 20
  106. read
  107. Given a buffer and a length: 
  108. read up to that many samples, 
  109. transform them into signed long integers,
  110. and copy them into the buffer.
  111. Return the number of samples actually read.
  112. .TP 20
  113. stopread
  114. Do what needs to be done.
  115. .TP 20
  116. startwrite
  117. Set up the format parameters, or write out 
  118. a data header, or do what needs to be done.
  119. .TP 20
  120. write
  121. Given a buffer and a length: 
  122. copy that many samples out of the buffer,
  123. convert them from signed longs to the appropriate
  124. data, and write them to the file.
  125. If it can't write out all the samples,
  126. fail.
  127. .TP 20
  128. stopwrite
  129. Fix up any file header, or do what needs to be done.
  130. .SH EFFECTS
  131. An effects loop has one input and one output stream.
  132. It has 5 routines.
  133. .TP 20
  134. getopts
  135. is called with a character string argument list for the effect.
  136. .TP 20
  137. start
  138. is called with the signal parameters for the input and output
  139. streams.
  140. .TP 20 
  141. flow
  142. is called with input and output data buffers,
  143. and (by reference) the input and output data sizes.
  144. It processes the input buffer into the output buffer,
  145. and sets the size variables to the numbers of samples
  146. actually processed.
  147. It is under no obligation to fill the output buffer.
  148. .TP 20 
  149. drain
  150. is called after there are no more input data samples.
  151. If the effect wishes to generate more data samples
  152. it copies the generated data into a given buffer
  153. and returns the number of samples generated.
  154. If it fills the buffer, it will be called again, etc.
  155. The echo effect uses this to fade away.
  156. .TP 20
  157. stop
  158. is called when there are no more input samples to process.
  159. .I stop
  160. may generate output samples on its own.
  161. See echo.c for how to do this, 
  162. and see that what it does is absolutely bogus.
  163. .SH COMMENTS
  164. Theoretically, formats can be used to manipulate several files 
  165. inside one program.  Multi-sample files, for example the download
  166. for a sampling keyboard, can be handled cleanly with this feature.
  167. .SH PORTABILITY PROBLEMS
  168. Many computers don't supply arithmetic shifting, so do multiplies
  169. and divides instead of << and >>.  The compiler will do the right
  170. thing if the CPU supplies arithmetic shifting.
  171. .P
  172. Do all arithmetic conversions one stage at a time.
  173. I've had too many problems with "obviously clean" combinations.
  174. .P
  175. In general, don't worry about "efficiency".  
  176. The sox.c base translator
  177. is disk-bound on any machine (other than a 8088 PC with an SMD disk 
  178. controller).  
  179. Just comment your code and make sure it's clean and simple.
  180. You'll find that DSP code is extremely painful to write as it is.
  181. .SH BUGS
  182. The HCOM format is not re-entrant; it can only be used once in a program.
  183. .P
  184. The program/library interface is pretty weak.
  185. There's too much ad-hoc information which a program is supposed to
  186. gather up.
  187. Sound Tools wants to be an object-oriented dataflow architecture.
  188. .P
  189. The human ear can't really hear better than 20 bits.
  190. With an internal format of 16 bits, we will eventually
  191. destroy information when used to mix CD's.
  192. The internal format should be 24-bit signed data.
  193. But, with 24 bits you still have to be careful multiplying.
  194. Check the ``vibro'' effect for how it handles this problem.
  195.