home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / c / agmsplaysound.doc < prev    next >
Text File  |  1995-02-27  |  11KB  |  259 lines

  1.                           AGMSPlaySound
  2.  
  3. AGMSPlaySound is a Modula-2 program by Alexander G. M. Smith which
  4. plays arbitrarily large IFF and raw sound samples from disk.
  5.  
  6. Sound Samples
  7.  
  8. Since AGMSPlaySound doesn't load the whole sample into memory, you can
  9. play samples longer than your memory size (up to 2 gigabytes).  It also
  10. leaves lots of memory free for other uses (such as running several other
  11. AGMSPlaySounds simultaneously, for quadraphonic sound :-).  Unlike some
  12. other sound playing programs, AGMSPlaySound can play from floppy disk
  13. without annoying pauses.  It achieves this performance by processing the
  14. IFF file headers and locating the sound data before starting to play.
  15. It also opens all the files before playing so that no time is wasted
  16. during playback.
  17.  
  18.  
  19. Files
  20.  
  21. In addition to playing huge sound files, you can specify several samples
  22. to be played one after the other by listing the file names in the order
  23. you want to hear them (useful for combining phoneme samples to make
  24. spoken words).  You can even have the parts on different disk devices.
  25. Yes, this program supports floppies too! Note that floppies can only
  26. play back data at a rate of at most 10000 Hz (disable any disk caching
  27. programs, they waste CPU time when reading files larger than the cache).
  28.  
  29. The files to be played can be specified with wildcard patterns since
  30. this program uses the ARP library.  You can even specify the ALL keyword
  31. to recursively play all the files in all directories (note that since
  32. all files stay open until the program has finished, you may run out of
  33. fast memory if you have lots of files, not to mention the memory used
  34. for storing the full path name of the files!).  I've found and fixed the
  35. bug that caused memory trashing with ALL, apparently ARP expects an
  36. undocumented parameter to the FindFirst function when it is used
  37. recursively.  It was documented in 1987 and was then taken out from the
  38. documentation.  Unfortunately, they kept on using it in arp.library
  39. version 39.1.  Hence the trashing problem.
  40.  
  41. How do you get those big sound files? Either use a sound digitizer and
  42. an Amiga with lots of memory or use AGMSRecordSound.  AGMSRecordSound
  43. multitasks while it records arbitrarily long sounds directly to hard
  44. disk.
  45.  
  46.  
  47. Help
  48.  
  49. Most of the arguments to the program are obvious.  Just type a ? as the
  50. argument to get the standard ARP / AmigaDOS command template.  A second
  51. ? typed at the template prompt will print the program credits (now in
  52. AmigaDOS 2.0 compatible ANSI text).  The Verbose option also explains in
  53. more detail what the current settings are.  Ok, maybe they aren't
  54. obvious.  I'll describe the parameters in detail near the end of this
  55. message.
  56.  
  57.  
  58. Stolen Channels
  59.  
  60. The program supports audio priorities and recovers gracefully from
  61. stolen audio channels (waits until a channel is free or the user types
  62. control-C).  In fact, if you are playing more than one sample, it will
  63. backtrack over multiple files to the one which was being played when the
  64. sound channel was stolen (one of the advantages to keeping all the files
  65. open until the program ends).  By the way, I've set it up to give
  66. preference for using the right hand sound channels before the left hand
  67. ones (sorry, I haven't had time to do Stereo, have a look at several
  68. other newer player programs (OmniPlay, DSound, etc) which do).
  69.  
  70.  
  71. Bug Fixes and New Features
  72.  
  73. I've found a bug in the M2Sprint IFFR.mod module for reading IFF files
  74. containing CAT objects.  Fortunately, M2Sprint includes the source code
  75. for the libraries so I was able to fix it in the December 27 1990
  76. version.  I like that.  The problem comes from not using the listContext
  77. that was carefully set up to read the CAT.  Instead, they use the
  78. clientContext parameter to get the address of the procedure to call.
  79. For CAT objects, clientContext is nil so some random memory address gets
  80. called.  Where did I find it? AmigaVision uses CAT objects for
  81. containing the elements of your program.  Now if someone out there has
  82. IFF files with LIST or PROP objects, I'd appreciate a copy for
  83. testing...  Never mind, AGMSMakeFilm generates that kind of file.  By
  84. the way, if you want to do video off a hard disk with a stereo sound
  85. track, try out the AGMS*Film series.
  86.  
  87. Also fixed (a feature really :-) is the file closing algorithm.  Files
  88. that were examined but have no sounds are now closed after examination
  89. rather than at the end of the program.  The memory used for their path
  90. names is also freed at this time.  This should make it easier to play
  91. all the sounds on your hard disk without running out of memory.
  92.  
  93. The NoWait option was added in the September 6, 1992 version.
  94.  
  95. Faster disk access (got rid of some unnecessary seeks - really huge
  96. sound files will be examined much more quickly), 2.0 compatible ANSI
  97. text and swapping of control-E and control-F were added in the
  98. June 13, 1993 version.
  99.  
  100. While working on AGMSTranscribeSound (a player that lets you go
  101. backwards and forwards and set bookmarks), I found the AmigaDOS 2.0
  102. lockup bug, AbortIO sometimes hangs!  You tell it to abort an audio
  103. write request and it just sits there.  Fortunately, stealing the channel
  104. will wake it up (run another program that steals channels, like most mod
  105. players).  I've worked around it in the July 17 1993 version by doing a
  106. CMD_FLUSH before doing any AbortIOs. 
  107.  
  108.  
  109. Feedback
  110.  
  111. If you have any feature requests or find any bugs, please send me a
  112. message.  I'm on several of the Ottawa BBX's (a BBS written by SteveX)
  113. and my commercial info service names are listed in the program's second
  114. help message (agmsmith@BIX.com, 71330.3173@CompuServe.com).
  115.  
  116.  
  117. Distribution
  118.  
  119. AGMSPlaySound is FreeWare.  Copyright (c) 1993 by Alexander G. M. Smith. 
  120. That means that you can use it freely, can't blame me for anything that
  121. goes wrong (there are probably a few bugs left), can't claim that you
  122. wrote it, and you shouldn't expect more from it than you paid me for it. 
  123.  
  124.  
  125. Files/...
  126.  
  127. This argument to the program is a list of file names.  The files will be
  128. played in the order listed.  Each name can include wildcards (standard
  129. Amiga plus ARP style), if it selects more than one file, that group of
  130. files will be played in alphabetical order.  If you want to repeat a
  131. sound sample, just specify its name several times.
  132.  
  133.  
  134. Buffers/K
  135.  
  136. This parameter specifies the number of chip ram buffers to use for the
  137. sound.  You need at least 2.  While the system is playing one buffer,
  138. the others can be filled from disk.  The default is 5.  Try the verbose
  139. command switch to watch the buffers being filled and to see how changing
  140. the number of buffers affects performance.
  141.  
  142.  
  143. Size/K
  144.  
  145. This parameter sets the size of each chip ram sound buffer.  The default
  146. is 10000 bytes, the maximum is 131072 bytes.  So, if you have 5 buffers
  147. and each is 10000 bytes then you will use a total of 50000 bytes of chip
  148. ram.  There is also a small amount of fast ram used for each buffer
  149. (message records and other small things).  For best performance, use
  150. large buffers.  That is because DOS can read a large chunk of data
  151. faster than several small chunks (less overhead).
  152.  
  153.  
  154. Hz/K
  155.  
  156. This parameter controls the playback rate for raw sound samples (in
  157. other words, when AGMSPlaySound can't figure out the speed which the
  158. sample was recorded with).  It is in units of samples per second, or
  159. bytes per second since each sample is one byte long (compact disks have
  160. 2 byte samples and thus sound better).  The default is about 10000hz.
  161.  
  162. It is internally translated into a code value for the hardware.  Since
  163. the hardware doesn't have all that many code values, only a few
  164. frequencies are actually available.  A frequency near the one you
  165. specified will be picked.
  166.  
  167.  
  168. IFFLikeRaw/S
  169.  
  170. If this switch is specified, IFF sound samples will be treated a bit
  171. like raw samples.  The IFF header information about the playback
  172. frequency and volume level will be ignored; the default Hz and Volume
  173. parameters will be used instead.  This is useful if you want to hear an
  174. IFF file at lower or higher pitch than it was recorded with.  Also, the
  175. full chunk size will be used instead of the size specified in the IFF
  176. sound parameters for one shot sounds.
  177.  
  178.  
  179. Volume/K
  180.  
  181. This specifies the volume level of the playback.  0 means quiet, 64 is
  182. loud.  IFF files contain their own volume settings which override this
  183. parameter.
  184.  
  185.  
  186. Verbose/S
  187.  
  188. When this command switch is used, lots of interesting messages will be
  189. displayed.  When examining IFF files, the structure and contents will be
  190. shown (even for non-sound files like pictures - try it on a picture to
  191. see what I mean).  All the parameter settings will be shown.  The
  192. parsing of your wildcards will be shown.  And during playback, the
  193. program will describe what it is doing (useful for seeing if your buffer
  194. settings are good).
  195.  
  196.  
  197. Priority/K
  198.  
  199. No, this is not the task priority.  This is the priority that
  200. AGMSPlaySound uses when it is fighting with another program for control
  201. of an audio channel.  Larger positive values give more priority.  Some
  202. programs (like the Sonix player) grab the channels with priority 127
  203. (the maximum).  With that high a priority, no other program can take
  204. over the channel (other users with priority 127 have to wait).  The
  205. default value is -90, good for background music.
  206.  
  207. When a higher priority request comes in, the lower priority sound
  208. channel user looses the channel (the channel is "stolen").
  209. AGMSPlaySound will detect the theft and put in a fresh request for the
  210. sound channel.  That request will stay pending until the high priority
  211. hog has finished making noise (oink, oink!), then AGMSPlaySound will be
  212. woken up by the Amiga OS and will resume playing from where it was cut
  213. off.
  214.  
  215.  
  216. All/S
  217.  
  218. This switch will turn on recursive directory searching.  Normally, when
  219. you specify a directory or one is encountered during wildcard checking,
  220. the directory will be skipped.  When ALL is used, the directory contents
  221. will be examined for sound files.
  222.  
  223.  
  224. NoRaw/S
  225.  
  226. This one will disable the playing of raw (non-IFF) files.  Useful when
  227. you use wildcards to play a bunch of files and you only want to hear the
  228. ones with IFF sounds in them.
  229.  
  230.  
  231. NoWait/S
  232.  
  233. The last switch! Normally AGMSPlaySound will wait for an audio channel
  234. to become free before playing.  If NoWait is specified, AGMSPlaySound
  235. will terminate if there are no audio channels free.  This means that you
  236. won't hear (or see, unless Verbose is on) anything if a higher priority
  237. sound is playing in all channels.  Similarly, if the channel being used
  238. gets stolen, AGMSPlaySound will try to find another one, and if it can't
  239. it will exit rather than waiting for another one.  Added on September 6,
  240. 1992 to satisfy James Atwill's wish for a Cron cuckoo clock that didn't
  241. collect up cuckoos while Experiment-IV was playing SoundTracker modules.
  242.  
  243.  
  244. Control-C Etc.
  245.  
  246. Control-C will abort the program as soon as it has finished whatever it
  247. is doing.
  248.  
  249. Control-E can be used during the file examining stage to start playing
  250. sound samples (stops the file examining activity).  During sound
  251. playback, it will move backwards and play the previous sound sample.
  252. The data that has been already read for the current sample will finish
  253. playing before the previous sample is heard.
  254.  
  255. Control-F used during sample playing makes AGMSPlaySound move forwards
  256. to the next sound sample.
  257.  
  258. - Alex
  259.