home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / audio / players / agms.lzh / AGMSPlaySound.doc next >
Encoding:
Text File  |  1992-02-07  |  8.7 KB  |  195 lines
  1. AGMSPlaySound is a Modula-2 program which plays sound samples from disk.
  2.  
  3. Sound Samples
  4.  
  5. Since AGMSPlaySound doesn't load the whole sample into memory, you can
  6. play samples longer than your memory size (up to 2 gigabytes).  It also
  7. leaves lots of memory free for other uses (such as running several other
  8. AGMSPlaySounds simultaneously, for quadraphonic sound :-).  Unlike some
  9. other sound playing programs, AGMSPlaySound can play from floppy disk
  10. without annoying pauses.  It achieves this performance by processing the
  11. IFF file headers and locating the sound data before starting to play.
  12. It also opens all the files before playing so that no time is wasted
  13. during playback.
  14.  
  15. Files
  16.  
  17. If you don't have huge sound files, you can specify several smaller
  18. samples to be played one after the other.  You can even have the parts
  19. on different disk devices.  Yes, this program supports floppies too!
  20. Note that floppies can only play back data at a rate of at most 10000 Hz
  21. (disable any disk caching programs, they waste CPU time when reading
  22. files larger than the cache).
  23.  
  24. The files to be played can be specified with wildcard patterns since
  25. this program uses the ARP library.  You can even specify the ALL keyword
  26. to recursively play all the files in all directories (note that since
  27. all files stay open until the program has finished, you may run out of
  28. fast memory if you have lots of files, not to mention the memory used
  29. for storing the full path name of the files!).  I've found and fixed the
  30. bug that caused memory trashing with ALL, apparently ARP expects an
  31. undocumented parameter to the FindFirst function when it is used
  32. recursively.  It was documented in 1987 and was then taken out from the
  33. documentation.  Unfortunately, they kept on using it in arp.library
  34. version 39.1.  Hence the trashing problem.
  35.  
  36. Help
  37.  
  38. Most of the arguments to the program are obvious.  Just type a ? as the
  39. argument to get the standard ARP / AmigaDOS command template.  A second
  40. ? typed at the template prompt will print the program credits.  The
  41. Verbose option also explains in more detail what the current settings
  42. are.  Ok, maybe they aren't obvious.  I'll describe the parameters in
  43. detail near the end of this message.
  44.  
  45. Stolen Channels
  46.  
  47. The program supports audio priorities and recovers gracefully from
  48. stolen audio channels (waits until a channel is free or the user types
  49. control-C).  In fact, if you are playing more than one sample, it will
  50. backtrack over multiple files to the one which was being played when the
  51. sound channel was stolen (one of the advantages to keeping all the files
  52. open until the program ends).  By the way, I've set it up to give
  53. preference for using the right hand sound channels before the left hand
  54. ones.
  55.  
  56. Bug Fixes
  57.  
  58. I've found a bug in the M2Sprint IFFR.mod module for reading IFF files
  59. containing CAT objects.  Fortunately, M2Sprint includes the source code
  60. for the libraries so I was able to fix it in the December 27 1990
  61. version.  I like that.  The problem comes from not using the listContext
  62. that was carefully set up to read the CAT.  Instead, they use the
  63. clientContext parameter to get the address of the procedure to call.
  64. For CAT objects, clientContext is nil so some random memory address gets
  65. called.  Where did I find it? AmigaVision uses CAT objects for
  66. containing the elements of your program.  Now if someone out there has
  67. IFF files with LIST or PROP objects, I'd appreciate a copy for
  68. testing...
  69.  
  70. Also fixed (a feature really :-) is the file closing algorithm.  Files
  71. that were examined but have no sounds are now closed after examination
  72. rather than at the end of the program.  The memory used for their path
  73. names is also freed at this time.  This should make it easier to play
  74. all the sounds on your hard disk without running out of memory.
  75.  
  76. Feedback
  77.  
  78. If you have any feature requests or find any bugs, please send me a
  79. message.  I'm on several of the Ottawa BBX's (a BBS written by SteveX)
  80. and my commercial info service names are listed in the program's
  81. second help message.
  82.  
  83.  
  84. Files/...
  85.  
  86. This argument to the program is a list of file names.  The files will be
  87. played in the order listed.  Each name can include wildcards (standard
  88. Amiga plus ARP style), if it selects more than one file, that group of
  89. files will be played in seemingly random order.  If you want to repeat a
  90. sound sample, just specify its name several times.
  91.  
  92. Buffers/K
  93.  
  94. This parameter specifies the number of chip ram buffers to use for the
  95. sound.  You need at least 2.  While the system is playing one buffer,
  96. the others can be filled from disk.  The default is 5.  Try the verbose
  97. command switch to watch the buffers being filled and to see how changing
  98. the number of buffers affects performance.
  99.  
  100. Size/K
  101.  
  102. This parameter sets the size of each chip ram sound buffer.  The default
  103. is 10000 bytes, the maximum is 131072 bytes.  So, if you have 5 buffers
  104. and each is 10000 bytes then you will use a total of 50000 bytes of chip
  105. ram.  There is also a small amount of fast ram used for each buffer
  106. (message records and other small things).  For best performance, use
  107. large buffers.  That is because DOS can read a large chunk of data
  108. faster than several small chunks (less overhead).
  109.  
  110. Hz/K
  111.  
  112. This parameter controls the playback rate for raw sound samples (in
  113. other words, when AGMSPlaySound can't figure out the speed which the
  114. sample was recorded with).  It is in units of samples per second, or
  115. bytes per second since each sample is one byte long (compact disks have
  116. 2 byte samples and thus sound better).  The default is about 10000hz.
  117.  
  118. It is internally translated into a code value for the hardware.  Since
  119. the hardware doesn't have all that many code values, only a few
  120. frequencies are actually available.  A frequency near the one you
  121. specified will be picked.
  122.  
  123. IFFLikeRaw/S
  124.  
  125. If this switch is specified, IFF sound samples will be treated a bit
  126. like raw samples.  The IFF header information about the playback
  127. frequency and volume level will be ignored; the default Hz and Volume
  128. parameters will be used instead.  This is useful if you want to hear an
  129. IFF file at lower or higher pitch than it was recorded with.  Also, the
  130. full chunk size will be used instead of the size specified in the IFF
  131. sound parameters for one shot sounds.
  132.  
  133. Volume/K
  134.  
  135. This specifies the volume level of the playback.  0 means quiet, 64 is
  136. loud.  IFF files contain their own volume settings which override this
  137. parameter.
  138.  
  139. Verbose/S
  140.  
  141. When this command switch is used, lots of interesting messages will be
  142. displayed.  When examining IFF files, the structure and contents will be
  143. shown (even for non-sound files like pictures - try it on a picture to
  144. see what I mean).  All the parameter settings will be shown.  The
  145. parsing of your wildcards will be shown.  And during playback, the
  146. program will describe what it is doing (useful for seeing if your buffer
  147. settings are good).
  148.  
  149. Priority/K
  150.  
  151. No, this is not the task priority.  This is the priority that
  152. AGMSPlaySound uses when it is fighting with another program for control
  153. of an audio channel.  Larger positive values give more priority.  Some
  154. programs (like the Sonix player) grab the channels with priority 127
  155. (the maximum).  With that high a priority, no other program can take
  156. over the channel (other users with priority 127 have to wait).  The
  157. default value is -90, good for background music.
  158.  
  159. When a higher priority request comes in, the lower priority sound
  160. channel user looses the channel (the channel is "stolen").
  161. AGMSPlaySound will detect the theft and put in a fresh request for the
  162. sound channel.  That request will stay pending until the high priority
  163. hog has finished making noise (oink, oink!), then AGMSPlaySound will be
  164. woken up by the Amiga OS and will resume playing from where it was cut
  165. off.
  166.  
  167. All/S
  168.  
  169. This switch will turn on recursive directory searching.  Normally, when
  170. you specify a directory or one is encountered during wildcard checking,
  171. the directory will be skipped.  When ALL is used, the directory contents
  172. will be examined for sound files.
  173.  
  174. NoRaw/S
  175.  
  176. The last switch! This one will disable the playing of raw (non-IFF)
  177. files.  Useful when you use wildcards to play a bunch of files and you
  178. only want to hear the ones with IFF sounds in them.
  179.  
  180. Control-C Etc.
  181.  
  182. Control-C will abort the program as soon as it has finished whatever it
  183. is doing.
  184.  
  185. Control-E can be used during the file examining stage to start playing
  186. sound samples (stops the file examining activity).  During sound
  187. playback, it will skip reading in the rest of the sample currently being
  188. read.  The data that has been already read for the current sample will
  189. finish playing before the next sample is heard.
  190.  
  191. Control-F used during sample playing makes AGMSPlaySound move backwards
  192. to re-read the previous sound sample.
  193.  
  194. - Alex
  195.