home *** CD-ROM | disk | FTP | other *** search
/ Sound, Music & MIDI Collection 2 / SMMVOL2.bin / DOS / DOS_MIS / AUDHNDLR.ZIP / AUDIO.DOC < prev    next >
Encoding:
Text File  |  1995-08-01  |  6.5 KB  |  192 lines
  1. Audio-Handler
  2.  
  3. THIS INFORMATION IS PROVIDED "AS IS"; NO WARRANTIES ARE MADE.
  4. ALL USE IS AT YOUR OWN RISK, AND NO LIABILITY OR 
  5. RESPONSIBILITY IS ASSUMED.
  6.  
  7. The audio-handler is the DOS Interface to the audio hardware and its
  8. associated audio.device. It is opened (for example) by using Open()
  9. with the name
  10.  
  11. AUD:
  12.  
  13. The mountlist entry does look like the following:
  14.  
  15. /* Mountlist for Audio Handler */
  16.  
  17. AUD:    Handler = L:Audio-Handler
  18.     Priority = 5
  19.     StackSize = 2000
  20.     GlobVec = -1
  21. #
  22.  
  23. This is a generic device. Any channel will be allocated when the 
  24. device is opened, but you will keep the same channel when you feed
  25. more data into AUD: after opening, so that sound output will be
  26. continuous. A different channel might be allocated if the original
  27. channel is stolen by another, higher priority allocation request
  28. by another audio handler task or another program using audio.device.
  29.  
  30. Once opened, you can feed audio bytes into the handler by using the
  31. AmigaDOS Write() library call. This call will not block if there is
  32. enough space left in the sound buffer. Multiple writes are played
  33. sequentially without glitch. There is no limit in the size of the
  34. write packets.
  35.  
  36. You will have enough time to supply more data because written data
  37. is immediately processed and the write request is replied immediately
  38. as long there is space in the sound buffers. Guaranteed available time
  39. ranges between number_of_written_bytes/frequency and about 
  40. buffer_size/frequency, where buffer_size is at least 2 kByte.
  41.  
  42. Of course you can also use the dos packet-level interface and feed
  43. the handler dos write packets. This has the advantage that you can 
  44. wait for write completion as well as other signals. See [2], page 639
  45. for an example of using asynchronous dos packets to copy a file.
  46. There is no limit in the number of packets you can send simultaneously.
  47.  
  48. Parameters can be given with the device name, to control the volume,
  49. period and priority of the sound output. The syntax is similar to
  50. console names:
  51.  
  52. AUD:[/OPTIONS]
  53.  
  54. For a quick test, feed your favourite sample to the audio-handler:
  55.  
  56. copy audio-handler L:
  57. mount AUD: from mountlist.aud
  58. copy <your_favourite_sample> AUD:
  59.  
  60. You can also put the AUD icon into your devs:DosDrivers drawer so
  61. it will be automatically mounted when your Amiga executes the
  62. startup-sequence.
  63.  
  64.  
  65. OPTIONS may be one or more of the following:
  66.  
  67. PERIOD p
  68. sets the sampling period (inverse of frequency) of the waveform
  69. to play. The default is to play the sound at 8 kHz sampling frequency.
  70. The minimum period is 124 because of hardware reasons (custom chip DMA
  71. allocation). The maximum is 65535 (size of the WORD custom chip register).
  72. This value goes into the AUDxPER custom chip register. Computing this
  73. value is explained in [3], pages 140-143. You can also specify the
  74. sampling frequency instead with the option explained below. 
  75.  
  76. FREQENCY f
  77. sets the sampling frequency of the waveform to play.
  78. This is an alternative to specifying PERIOD. The maximum usable
  79. frequency is 28603, the minimum is 55. This value gives the
  80. number of samples (bytes) per second to play.
  81.  
  82. VOLUME v
  83. sets the overall volume of the sound. Valid numbers range from
  84. 0 (silent) to 64 (loudest), which is the default.
  85.  
  86. PRIORITY pri
  87. is the priority used for precedence managment within the
  88. audio.device. Audio channels with low priority may be 'stolen' by
  89. other applications or different invocations of the audio-handler.
  90. Valid priorities range from -128 (always stoppable) to 127 (unstoppable).
  91. The default value is 0. See [1], page 22 for a suggested value of
  92. priority for different types of sound.
  93.  
  94. BUFFER size
  95. is the buffer size allocated for sound. As explained above, this
  96. restricts how much time you have to update the buffer (write the
  97. next bunch of samples). The minimum is 4kB to allow for a safe
  98. continuation of play, the maximum is 256kB, allowing for double
  99. buffers of each 128kB, which is the maximum possible for the
  100. Amiga hardware. The buffers use CHIP memory.
  101.  
  102. DEBUG n
  103. This is an option not normally used which outputs event information
  104. about incoming packets and io requests to the serial port. n is a
  105. number which is added to each information to show which handler
  106. task is doing the output.
  107.  
  108. The following are special channel requests.
  109.  
  110. CHANNEL n
  111. is an optional number between 0 and 3 (or maybe up to the number
  112. of supported channels, if ever implemented).
  113.  
  114. LEFT
  115. The sample is to be played on one of the left channels.
  116.  
  117. RIGHT
  118. The sample is to be played on one of the right channels.
  119.  
  120. STEREO
  121. The sample is a stereo sample (alternating bytes) and is to be
  122. played at one left and one right channel simultaneously.
  123. (Not yet implemented)
  124.  
  125. 16BIT
  126. This is set to specify that samples are Words instead of bytes.
  127. This is not yet implemented, anyway, the Amiga Audio hardware
  128. doesn't support it.
  129.  
  130.  
  131. Examples:
  132.  
  133. Playing a sample with a sampling frequency of 4 kHz on a right
  134. channel only:
  135.  
  136. AUD:FREQUENCY4000/RIGHT
  137.  
  138. Playing a sample with a smaller buffer (8 KB total, 2 buffers of
  139. 4 KB each) and low priority:
  140.  
  141. AUD:buffer0x2000/priority-100
  142.  
  143.  
  144. Technical details:
  145.  
  146. * Lattice C 5.10 was used to compile the source.
  147.  
  148. * Stolen channels are not automatically given away, but the lock
  149.   protocol is used. When another process wants to steal the channel,
  150.   the audio handler frees the channel at the next best time.
  151.   This assures that the sample can be played glitch-free, if
  152.   the handler can immediately allocate another channel, and it
  153.   guarantees no sound is lost before the handler can allocate
  154.   a channel again.
  155.  
  156. * Each invocation of AUD: creates a new handler process, but the
  157.   code and data segment is shared between all processes (resident).
  158.  
  159.  
  160. TODO:
  161.  
  162. * Implement stereo samples.
  163.  
  164. * Implement 16 bit samples. Might be interesting for 16 bit sound
  165. cards if they have a device similar to audio.device.
  166.  
  167. * If sampling is implemented at some time, the audio handler might
  168. also be used for reading (sampling) from audio sources. This will
  169. require the user process to read data fast enough to keep in pace
  170. with the sampler.device delivering samples. Might as well use
  171. the parallel.device for well known samplers. 
  172.  
  173. * Makefiles for other compilers. Volunteers?
  174.  
  175.  
  176. The source and executable may be freely used in projects, but a
  177. notice of its origin must be given. If the program is to be included
  178. on a CDRom or disk being sold, one sample must be given to the author.
  179.  
  180. Comments, ideas, bug reports please to (e-mail preferred):
  181.  
  182. Martin Brenner
  183. Kaiserstr. 83
  184. 52134 Herzogenrath  
  185. martin@ego.oche.de
  186.  
  187. References:
  188.  
  189. [1] AMIGA ROM Kernel Reference Manual: Devices, 3rd edition
  190. [2] Ralph Babel: The Amiga Guru Book
  191. [3] AMIGA Hardware Reference Manual, 3rd edition
  192.