home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 8 / amigaformatcd08.iso / look_here_1st! / handy_tools / arq / upd.doc < prev   
Text File  |  1991-10-02  |  10KB  |  275 lines
  1. Release 1.00
  2.  
  3.         The minimal player daemon - upd
  4.         ===============================
  5.  
  6.     © 1991 Jonas Petersson & Absolut Software (aka Sirius Soft)
  7.  
  8.  
  9.  
  10. Introduction:
  11. =============
  12.  
  13. Wouldn't it be nice to have a process hanging around to play any
  14. sound file for you on demand instead of you having to do all this
  15. mucking about with audio.device etc? But it really has to be small
  16. and it HAS to be able to play my very large samples anytime...
  17. I must be able to call it simply from anywhere - even from scripts!
  18.  
  19. Tricky, but it can be done.
  20.  
  21. As a feature you can register you favourite sounds in a configuration
  22. file and well behaved programs will use the ones you like right now.
  23. It also has Arexx support - to be truely honest, that the ONLY way to
  24. use it...
  25.  
  26. Current version works rather well along the way I intended.
  27.  
  28.  
  29. Usage:
  30. ======
  31.  
  32.     [run] upd [bufsize [IDfile]]
  33.  
  34. The "run" is ofcourse optional, but daemons really should be in the
  35. background unless you want the see the debugging information.  "bufsize"
  36. is the amount of chip memory that each of the four buffers will use
  37. while playing.  (These are allocated at start to make sure you will be
  38. able to play anytime - as long as you can get hold of the audio
  39. channels...).  Default is 1024 and specifying less than 64 will give you
  40. the default. (I've heard that some people can't ever get anything good
  41. out with less than a 1K buffer - am I really the only one with a quick
  42. enough HD/SCSI interface?) 
  43.  
  44. NOTE: Don't make the buffer bigger than you actually need - a large
  45. buffer also means that the sample will start a little bit later since
  46. more information must be loaded before it can begin!
  47.  
  48. The if the IDfile parameter exists, it will be used instead of the
  49. default s:upd.IDs. Note that you have to set bufsize explicitly to use
  50. this. I agree that it's a bit ugly but most people should really not 
  51. need to use this.
  52.  
  53. The above won't produce any sound as you probably realize.  Once run, the
  54. only way to talk to upd is with Arexx - I even removed the BREAK stuff
  55. that was in it for Zound, since Arexx could hang around waiting for a
  56. reply forever when you interupted the sound that way. The break will
  57. "wait" until the daemon is idle next time.
  58.  
  59. upd currently knows of four commands:
  60.  
  61.     file filepath [options] [anotherfilepath [options]]
  62.     id   id-in-s:upd.IDs
  63.         rescan new-id-file
  64.     exit
  65.  
  66. Well, there is actually one more command: 'Can it, Marvin'. This will 
  67. silently interrupt the current sample. (To be truely honest, ANY command
  68. will interrupt a sample - if it's known, it will be used, otherwise the
  69. sound just stops). Be careful with the 'rescan' command, if there is a 
  70. problem reading the new file, you will loose all your old IDs...
  71.  
  72. The options are the same as for Zound except for the -n option that doesn't
  73. exist here (tell me you need it and I'll fix that too... sigh). Here's the
  74. list:
  75.  
  76.     -r rate    How fast to play the sample. Default is what is in the
  77.         8svx header or 310 if it's a raw file. This is usually
  78.         reasonable - most 'raw' samples I've come across are either
  79.         310 or 155. Lower numbers will play the sample faster.
  80.  
  81.     -v volume    Ranges between 0 and 64, 64 being max and default.
  82.  
  83.     -s start    Possible offset from the beginning. Default 0.
  84.     -l length    Possible length unless you want it all. Default is
  85.         length of the sample. Be careful with these two, or
  86.         you might get undesired results.
  87.  
  88.     -c cycles    How many times to play each buffer. Default 1. Not
  89.         very useful, but you can get a nice "mouse" effect by
  90.         setting this to 2 and playing twice as fast...
  91.  
  92.     -d        Show debug information. Note that this will appear on
  93.         the standard output of the DEAMON, not where you called 
  94.         it from (that is, the ARexx script or wherever).
  95.  
  96.     -L        Play the sample in the left speaker only. If it's a stereo
  97.         sample only the left channel samples are used.
  98.     -R        Same as '-L' but for right speaker.
  99.     -S        Play in both speakers even if it's a mono sample.
  100.         Default for these three options are of course what is in the
  101.         8SVX header or -L if it's a raw sample.
  102.  
  103.  
  104. Example of usage (from WShell etc):
  105.  
  106.     "address play file 'sounds:chopper'
  107.     "address play id 2001
  108.         "address play rescan 'ram:upd.IDs'
  109.     "address play exit
  110.  
  111. NOTE: Arexx normally converts everything to UPPERCASE and might try to
  112. do arithmetics etc on filenames which is why it's generally a good idea
  113. to 'singelquote' all paths, IDs etc. If you're looking for the port
  114. 'the hard way' to send your own message, the name is "PLAY" in uppercase.
  115.  
  116. NOTE2: If you are REALLY in a hurry to get rid of upd you could do this:
  117.  1) Send a any dummy Arexx message (this will stop the sound)
  118.  2) Send a break C to upd - break still works when upd is idle.
  119. or
  120.  A) Send the exit message.
  121.  
  122. The last might sound much easier than the first unless you (like me)
  123. have a trapped DisplayBeep() that 'pings' via upd.  In this case,
  124. producing a DisplayBeep() and a break C is much simpler.  The order is
  125. not relevant since the break is "queued". 
  126.  
  127.  
  128. Hints:
  129. ======
  130.  
  131. Running upd from your SOUNDS: directory is a nice way to get rid of having
  132. you type the FULL path everytime you want to play a sample. (The daemon
  133. has no simple way of knowing WHERE you were when you sent the message 
  134. (that I know of) and therefore assumes it to be in the current directory)
  135.  
  136.  
  137. Files:
  138. ======
  139.  
  140.     s:upd.IDs
  141.  
  142. This file contains the IDs of your favourite samples like a database
  143. the is easily editable. File format:
  144.  
  145.  
  146. # Lines starting with '#' are comments
  147. # Id list for micro player daemon
  148. # Created 910201 Jonas Petersson (zaphod@magrathea.indic.se)
  149. # These sounds could be called for at certains situation
  150. # On severe error
  151. BUG    sounds:explosion -S
  152. # When asked for confirmation
  153. CONFIRM sounds:PressLeftMouseButton -L
  154. # Minor trouble
  155. ERROR   sounds:ImSorryDaveImAfraidICantDoThat -R
  156. # Going down...
  157. GURU    sounds:RoysDeathMonologueFromBladerunner -S
  158. # Personal shortcuts/favourites
  159. 2001    sounds:openpod -L sounds:hal -R
  160.  
  161.  
  162. Removing entries will ofcourse result in no sound (upd might mourn about
  163. it on the standard output though, unless you redirect it). Remember that
  164. ARexx might convert to uppercase unless you quote!
  165.  
  166. Feel free to add whatever you like. Could be nice with some standard though.
  167. Suggestions are welcome. Mjl's Arq is an example of a program that uses
  168. this feature. Read Arq's docs for details.
  169.  
  170. NOTE: It *IS* possible to have white space, lowercase etc in the IDs, but
  171. it might cause confusion if used. Be warned.
  172.  
  173. NOTE2: The file is scanned once when the program starts. If you make any
  174. changes to it, you'll have to restart the deamon.
  175.  
  176.  
  177. Return codes:
  178. =============
  179.  
  180. If the Arexx command returns 20, the secondary result code gives the
  181. reason for the failure:
  182.  
  183. 10    Can't allocate channels.
  184. 17    Can't open s:upd.IDs on request to play by ID.
  185. 18    Requested ID not found.
  186. 19    Trouble reading new ID file.
  187. 20    Error during parse of options.
  188. 21    Can't open file with sample.
  189. 22    File is IFF, but not FORM 8SVX.
  190. 23    Bad IFF file.
  191. 24    Bad CHAN length.
  192. 25    Bad VHDR length.
  193. 26    Can't open file 2nd time. (For stereo possibility)
  194. 30    Can't play backwards. (Wierd options)
  195. 31    Can't allocate IOAudio structs.
  196. 32    Can't open ports for channels.
  197.  
  198. Being interrupted to play another sample is not considered a failure.
  199.  
  200.  
  201. Future enhancements:
  202. ====================
  203.  
  204. Maybe automatic detach (didn't work well in Aztec 5.0a, and I havn't really
  205. tried with 5.0d yet).
  206.  
  207. Probably not very much else - this is a simple sound daemon for minor
  208. background purposes of helping simple programs do more than DisplayBeep().
  209. I'd like to think of it as a complement to SPEAK: - if you want more
  210. you probably want it interactive. (Hmm, that's a thought - a SOUND: device)
  211.  
  212.  
  213.  
  214. Problem history: 
  215. ================
  216.  
  217. 1. If your sample is on a floppy (or a very slow HD) there might be 
  218.    some sounds of silence when the playing rate exceeds the loading
  219.    rate... 
  220. Fix: You can now specify the amount of memory to be used by upd when you
  221.    start the daemon as in: 'upd 2000'. But note that a larger buffer also
  222.    makes a longer delay until you hear the first part of the sound - it
  223.    doesn't start until it has filled the first buffer.
  224.  
  225. 2. Stereo and Fibonachi packed samples not yet supported (there are loading
  226.    problems - play them with 'Zound' instead for now).
  227. Fix: Stereo is OK now if you use the above size option (it actually worked
  228.    in RAM: before too - but I didn't enable it for the prerelease). As for 
  229.    Fibonachi: it's not too hard to fix, but I've never seen anyone using it -
  230.    is it worth the effort? If you happen to have a Fib-sample - PLEASE send it
  231.    to me - I don't have the patience to reconstruct one by hand...
  232.  
  233. 3. Could hang forever if someone stole the channel. 
  234. Fix: So, I didn't check everything in 0.99 - now I do (I hope... ;-)
  235.  
  236. 4. -s and -l wasn't used in 0.99, now it is.
  237.  
  238. Thanks to mjl@alison.at for the idea.
  239.  
  240.  
  241. Distribution
  242. ============
  243.  
  244.   UPD is not public domain. A friend of mine advised me to call it
  245. "Freely Distributable Copyrighted" instead. That's close enough.  
  246. If You wish to include it with a commercial program feel free provided 
  247. that You send me a registered copy.
  248.  
  249.   As always, Fred Fish is free to include it in his library.
  250.  
  251.   Source code? You mean there is something to IMPROVE??? Right, send
  252. me a message then and I'll think about it...
  253.  
  254.  
  255.  
  256.  
  257.  
  258.     Jonas 'Zaphod' Petersson
  259.     Albrektsvagen 113A
  260.     S-603 53  Norrkoping
  261.     SWEDEN
  262.     Phone: +46 11 162517
  263.  
  264.     zaphod@magrathea.indic.se                   /* At home */
  265.     zap@indic.se                    /* At work  */
  266.     zaphod@slaka.sirius.se                   /* Absolute software */
  267.  
  268.  
  269. Feel free to send comments, bug reports (huh?), money, coke, beer, girls...
  270.  
  271. Just a "Hi, I liked your program" is as good as a few bucks - I wrote this
  272. because I needed it, not to make money out of it...
  273.  
  274.  
  275.