home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format 19 / af019.adf / player / Play590.doc < prev    next >
Text File  |  1978-04-04  |  24KB  |  437 lines
  1.  
  2.                    PLAY590 VERSION 1.0 RELEASE DOCUMENTATION
  3.  
  4.                  Written November 13th 1990 by Mark Everingham
  5.  
  6.  
  7.    INTRODUCTION
  8.  
  9.         The quality of sound obtainable from the Amiga using a sound-sampler
  10.    is truly amazing, often being completely indistinguishable from  the real
  11.    thing.  However,  the  main  problem  with sound sampling is that it does
  12.    require huge amounts of memory. At a reasonable sample speed,  say 16Khz,
  13.    the maximum  length sample on an unexpanded A500, is about half a minute,
  14.    and even with 3Mb of ram, two minutes is about the limit. I recently (and
  15.    so it  would seem from letters in Format did many readers) bought an A590
  16.    hard-disk, and imagined just what could be done with all that disk-space.
  17.    Imagine, with  a 20Mb  hard-disk, you could have a continuous sample over
  18.    twenty minutes long, and  with a  40Mb drive  you could  digitize a whole
  19.    album in  one go!  With these  thoughts in  mind, I  wrote Play590, which
  20.    allows you to play mono or stereo samples at speeds up to  32KHz from any
  21.    AmigaDOS  file.  Although  the  program  works  best with a hard-disk, as
  22.    reflected by the name, Play590 will also work with floppy-disks at speeds
  23.    up to about 12KHz, and can be used to play samples from fast ram by using
  24.    any standard ram-disk driver, for example RAM, RAD  or VD0.  There are no
  25.    limits imposed  on the  length of the samples to be played other than the
  26.    capacity of the storage device they  are kept  on. By  sampling chunks of
  27.    sound using  a standard  sampler package, then saving to disk and linking
  28.    together  using  the  AmigaDOS  JOIN  command,  samples  of theoretically
  29.    infinite length  can be  created. I  currently have two 6Mb samples on my
  30.    hard-drive!
  31.  
  32.         Amazingly, Play590 is also very friendly from a  multi-tasking point
  33.    of view.  Playing from  an A590  hard-disk at 16Khz the program only uses
  34.    about 2% processor time although floppy-disk access requires considerably
  35.    more processor  time. If  you boost Play590's priority to above zero, you
  36.    can fiddle with workbench,  generate  a  few  mandelbrots  and  even load
  37.    programs  off   the  same  hard-disk  Play590  is  using  while  enjoying
  38.    continuous uninterrupted  music. Doing  a bit  of DTP  with PageSetter II
  39.    while Handel's  water-music plays  away in  the background,  or drawing a
  40.    mandelbrot set to the tune of J.M Jarre's  "Oxygene" is  a a  pretty wild
  41.    experience (even if I do say so myself)...
  42.  
  43.  
  44.    GENERAL INFORMATION
  45.  
  46.    (i) Sample File Formats
  47.  
  48.         Play590  will   work  correctly   with  samples  created  using  any
  49.    sound-sampler package saved in the RAW (non IFF) format. If  your sampler
  50.    cannot  generate  RAW  files,  you  can  still use IFF 8SVX files, as you
  51.    probably won't be able to hear  the IFF  header information  as it  is so
  52.    short.  You  can  in  fact  play  any file, for example the CLI commands,
  53.    although the results are not guaranteed to be very musical!
  54.  
  55.    (ii) Mono and Stereo Samples
  56.  
  57.         Play590 will play samples in either mono or  stereo at  any speed up
  58.    to 32767Hz.  On a  hard-disk it is quite possible to play stereo samples,
  59.    at full speed, but on floppies, the maximum I've achieved successfully is
  60.    12Khz in  mono. Use  of a  good disk-optimiser  such as  B.A.D may enable
  61.    higher speeds to be achieved. To  play samples  in stereo,  you must have
  62.    the left  channel stored in one file, for example "Music.L" and the right
  63.    channel stored in another, for example "Music.R". Both  samples in stereo
  64.    are played  at the  same speed. If you want to play more than two samples
  65.    at a time, for example if you have  a four-track  recorder, then  you can
  66.    just run two copies of Play590, one for each pair of samples.
  67.  
  68.    (iii) Playing Samples from Memory
  69.  
  70.         Play590 can  be used in the same way as a conventional sample-player
  71.    such as BMP by copying the sample files you want to play into a ram disk.
  72.    This also allows you to play samples which will not fit in chip ram.
  73.  
  74.    (iv) Memory Requirements
  75.  
  76.         Because Play590  only stores  a small amount of a sample in chip ram
  77.    at one time, it is quite economical on memory, working fine on  an a 512k
  78.    Amiga. You can specify the size of the chip ram buffer which Play590 uses
  79.    for its samples, and  the  total  chip  ram  used  can  be  calculated as
  80.    follows:
  81.  
  82.                 Chip ram used = buffersize * 2 * (2 if stereo)
  83.  
  84.         In order  to keep  the sample playing perfectly smooth, Play590 uses
  85.    double-buffering techniques, so the buffersize must be multiplied  by two
  86.    to find  the total  memory used.  If you  are playing stereo samples, the
  87.    memory needed is doubled.
  88.  
  89.         Play590 defaults to a buffersize of  32Kb, thus  using 64Kb  to play
  90.    mono samples,  or 128Kb  for stereo samples. You can specify a buffersize
  91.    between 0 and 64Kb, but bear in mind that the smaller the buffersize, the
  92.    more processor  time the program uses. I have found through practice that
  93.    32Kb is a good compromise between processor and memory usage.
  94.  
  95.    (v) Audio Channel Allocation
  96.  
  97.         When playing a mono sample, Play590 uses the first audio  channel it
  98.    can find, which may be either left or right. When playing stereo samples,
  99.    or mono samples in the pseudo-stereo  mode, Play590  uses a  left & right
  100.    channel pair.  If it  cannot allocate the correct channels, an error will
  101.    be generated.
  102.  
  103.  
  104.    RUNNING PLAY590
  105.  
  106.         Play590  may  be  run  either  from  the  CLI,  Workbench,  or  in a
  107.    script-file. If you like, Play590 can open a title window so that you can
  108.    abort the playing of a sample, or  you  can  choose  to  have  no window,
  109.    making Play590 suitable for use in a demo of your own making. Play590 can
  110.    also be run as a background task allowing the CLI  or Shell  window to be
  111.    closed after running it.
  112.  
  113.  
  114.    CLI AND SCRIPT-FILE USAGE
  115.  
  116.         Play590 has  a number of special options which can be specified from
  117.    the CLI or in a script-file using options of the form "-<option>[value]".
  118.    You can  specify most  of these options anywhere in your command-line, in
  119.    any order, before or after the filenames of your samples  and options may
  120.    be in  either upper  or lower-case.  The only restriction imposed is that
  121.    the file-name  of  your  samples  must  not  begin  with  a  hyphen ("-")
  122.    character. The recommended format of the command-line is as follows:-
  123.  
  124.          Play590 <samplename1> [samplename2] [option 1] .. [option n]
  125.                                       or
  126.          Play590 [option 1] .. [option n] <samplename1> [samplename2]
  127.  
  128.         If the  file-names of  your samples  include spaces, you can enclose
  129.    the names in quotes ('"'). As I have mentioned, Play590  can also  be run
  130.    in the  background so that you can close down your CLI/Shell or terminate
  131.    your script-file. You can either use  the  Workbench  1.3  (not  1.2) RUN
  132.    command or  the RUNBACK command to run Play590 in the background. This is
  133.    shown below.
  134.  
  135.    Standard RUN command:         RUN >NIL: Play590 <samplename1> etc..
  136.    or: RUNBACK command:          RUNBACK Play590 <samplename1> etc..
  137.  
  138.         I would personally recommend using the  RUN >NIL:  command, since it
  139.    is a standard AmigaDOS command, which nobody ever seems to use!
  140.  
  141.    (i) CLI Command Line Options
  142.  
  143.    -S<speed> (1-32767)      The -S  (SPEED) option  is the most important of
  144.                             the options, being used to specify  the speed at
  145.                             which  your  samples  will  be  played back. The
  146.                             speed is specified in Hertz - If your sample was
  147.                             recorder  at  say  20KHz,  use  20000,  or if at
  148.                             1.23Khz, use 12300.  If  you  do  not  specify a
  149.                             speed option  in your  command-line, the default
  150.                             speed of 16Khz will be used.
  151.  
  152.    -W                       The -W (WINDOW) option  is used  to specify that
  153.                             you DO want Play590 to open a title window. This
  154.                             window just shows that  Play590 is  running, and
  155.                             can be used to stop a sample playing by clicking
  156.                             on the close gadget.  By  default,  Play590 does
  157.                             not open  a window  when run  from the CLI since
  158.                             this is more suitable  be script-file  usage. Be
  159.                             warned though  that if  you don't open a window,
  160.                             there is no way of aborting a sample.
  161.  
  162.    -R<repeats> (0-32767)    The -R (REPEATS) option  is used  to specify how
  163.                             many  times  Play590  will play your samples. If
  164.                             you specify a value between 1 and 32767, Play590
  165.                             will play  the samples  that number of times and
  166.                             then stop.  If  you  specify  a  value  of zero,
  167.                             Play590  will  repeat  the  samples  forever, or
  168.                             until  the  close  gadget   on  its   window  is
  169.                             activated. By default, Play590 plays the samples
  170.                             once then stops.
  171.  
  172.    -V<volume> <0-64>        The -V  (VOLUME) option  is used  to specify how
  173.                             loud  Play590  plays  your  samples. Zero (0) is
  174.                             inaudible,  and  64  is  maximum  loudness.  The
  175.                             default volume is 64.
  176.  
  177.    -F                       The -F (FILTER) option enables you to switch the
  178.                             low-pass filter  (power  light)  off  on  a post
  179.                             A1000  Amiga,  improving  the  sound  quality on
  180.                             certain types of sounds.  If you  do not specify
  181.                             this option, the filter will be left on.
  182.  
  183.    -B<buffer> <1-65535>     The -B  (BUFFER) option  specifies how much chip
  184.                             ram Play590 will  use  for  each  of  its sample
  185.                             buffers, as  discussed earlier.  You specify the
  186.                             value  in  bytes,  with  1  being  1  byte  (not
  187.                             recommended!) and  65535 being 64Kb. The default
  188.                             value is 32Kb (32768 bytes).
  189.  
  190.    -P<priority> (-128..127) The -P (PRIORITY) option  specifies the priority
  191.                             at which  the Play590 program runs, between -128
  192.                             and +127. This option  is equivalent  to running
  193.                             Play590   and   then   using  the  CHANGETASKPRI
  194.                             command. The default  priority  is  that  of the
  195.                             current CLI,  which is usually zero. If you want
  196.                             to make sure that Play590 is  never interrupted,
  197.                             you  can  set  the  priority above zero (10 is a
  198.                             good value). It  is  unadvisable  to  use values
  199.                             above  +10  or  below  -10, as this is seriously
  200.                             unfriendly to the operating system.
  201.  
  202.    -2                       The -2  (STEREO) option  lets you  play a single
  203.                             sample  as  if  it  were  a  stereo sample, like
  204.                             playing a mono cassette  on  a  stereo cassette-
  205.                             player. This  option makes Play590 use two audio
  206.                             channels - a left and right  pair, and  play the
  207.                             same  sample  on  both channels. It does however
  208.                             use more processor  time  than  playing  in true
  209.                             mono.
  210.  
  211.    <samplename1/2>          The  only  other  command-line arguments are the
  212.                             names  of  the  sample  files  themselves. Usual
  213.                             AmigaDOS file-name restrictions apply.
  214.  
  215.    (ii) Example Command Lines
  216.  
  217.    Play590 "DF0:MySample" -S28000
  218.         - Play the mono sample "DF0:MySample" once at 28KHz.
  219.  
  220.    RUN Play590 "DH1:Sample.L" "DH1:Sample.R" -s18000 -r0 -w -p10
  221.         - Open the  Play590 window  and play  the two samples specified as a
  222.         stereo pair at the speed of 18KHz. Keep repeating the  samples until
  223.         the user  closes the  Play590 window  (or the  world ends...). Boost
  224.         Play590's priority  to  +10  to  make  sure  the  samples  are never
  225.         interrupted.
  226.  
  227.    RUN Play590 "RAM:MonoSample" -S12000 -2 -F -V32
  228.         - Play the  mono sample  as if it were a stereo sample, on a pair of
  229.         left and right channels. Turn the low pass filter off to improve the
  230.         sound quality, and play the sample at half volume.
  231.  
  232.    Play590 "Sample"
  233.         - Play  the  (imaginatively  titled)  sample  "Sample" using all the
  234.         default settings.
  235.  
  236.  
  237.    WORKBENCH USAGE
  238.  
  239.         For those who go weak at the thought of entering  the untold horrors
  240.    of a CLI or Shell window, Play590 can also be run from the Workbench. You
  241.    can use of the CLI command-line options by using the Workbench INFO tool,
  242.    and can  choose the  samples you  want to play either by specifying their
  243.    names using the INFO tool again,  or by  shift-clicking with  the Play590
  244.    icon.
  245.  
  246.    (i) Specifying Sample File-Names
  247.  
  248.         In order for Play590 to run, you must specify one or two samples for
  249.    it to play. There are three ways of doing this.
  250.  
  251.    (a) Using the Workbench INFO tool
  252.  
  253.         Using the Workbench INFO tool, add a tooltype entry (select  the ADD
  254.    tool) as shown below:-
  255.  
  256.                             SAMPLE1=<samplename1>
  257.                         or: SAMPLE2=<samplename2>
  258.  
  259.  
  260.         You replace  <samplename> with  the filename  of a sample. Note that
  261.    you cannot use quote characters to enclose the  name, but  can use spaces
  262.    in the  name without  them. As  with all other tooltype options, you must
  263.    use UPPER CASE, so "SAMPLE1" will work, but "sample1" will not.
  264.  
  265.         If you are playing only a mono sample, you can use either SAMPLE1 or
  266.    SAMPLE2, it  does not make any difference which. When playing two samples
  267.    in stereo, SAMPLE1 is the left sample and SAMPLE2 the right sample.
  268.  
  269.    (b) Shift-Clicking with Sample Icons
  270.  
  271.         The second  way to  specify samples  to be  played by  Play590 is to
  272.    shift-click on  an icon  representing a sample. This method only works if
  273.    (a) your samples have an icon, and (b) the icon is of the type PROJECT.
  274.  
  275.         To play a mono sample, just click on  the sample  icon, then double-
  276.    click on the Play590 icon while holding down the <SHIFT> key.
  277.  
  278.         To  play  two  stereo  samples,  click on the left sample icon, then
  279.    click on the right sample icon while holding  down <SHIFT>,  then double-
  280.    click on the Play590 icon while still holding down <SHIFT>. Note that for
  281.    the samples to play on the correct channels, you must  click on  the left
  282.    sample first.
  283.  
  284.    (c) Setting a Sample Icon's Default Tool
  285.  
  286.         The third  way to  play a  sample with Play590 is to set the default
  287.    tool of a sample, although this method may only be used for  playing mono
  288.    samples. Again,  you must have an icon for a sample, and the icon must be
  289.    of type PROJECT.
  290.  
  291.         Using the Workbench INFO tool, change the "Default  Tool" setting of
  292.    the sample  icon to "DF0:Play590/Play590" or whatever name you have given
  293.    to the Play590 program on your floppy or hard-disk. Select  SAVE, then to
  294.    play your sample, just double-click on the sample's icon.
  295.  
  296.    (ii) Workbench Tool-Type Options
  297.  
  298.         When running  Play590 from the Workbench you can use all the options
  299.    which are available from  the CLI  command-line. This  is done  using the
  300.    Workbench INFO  tool. To specify an option, you just ADD a tooltype entry
  301.    to an icon. You can specify these tooltype options either  in the Play590
  302.    icon itself,  or in  the icon of a sample to be played. Tooltypes entered
  303.    in the Play590 icon may be  regarded as  default selections,  and will be
  304.    overridden by  tooltypes specified  in a sample icon. Here is an example,
  305.    of setting the default speed of the Play590 tool, and  the specific speed
  306.    of an individual sample.
  307.  
  308.         Click  on  the  Play590  icon,  and  select the INFO option from the
  309.    Workbench menu. Click on  the  ADD  gadget,  and  type  in "SPEED=20000".
  310.    Select the  SAVE gadget to finalize your choice. This specifies that when
  311.    Play590 is run from its icon, by default it will  use a  speed of 20000Hz
  312.    or 20KHz.
  313.  
  314.         Now  click  on  a  sample  icon,  and  repeat  the process, adding a
  315.    tooltype entry "SPEED=25000". SAVE this, and try playing this sample. You
  316.    will notice  that the  sample plays  back at  25KHz not  20KHz, since the
  317.    tooltype in the sample overrides the tooltype in the Play590 icon. If you
  318.    now delete  the tooltype from the sample icon, it will then play at 20KHz
  319.    again.
  320.  
  321.         Note that  if you  don't specify  any tooltypes,  the global Play590
  322.    default values  are used,  and these  values are included below. Remember
  323.    that you must use UPPERCASE for each option.
  324.  
  325.    SPEED=<speed> (1-32767)       Set the  sample  playback  speed:  See "-S"
  326.                                  option. Default value: 16000.
  327.  
  328.    WINDOW=<ON|OFF>               Switch  the  Play590  window on or off: See
  329.                                  "-W" option. Default value: ON.
  330.  
  331.    REPEATS=<repeats> (0-32767)   Set the number of repeats: See "-R" option.
  332.                                  Default value: 1.
  333.  
  334.    VOLUME=<volume> (0-64)        Set the  playback volume:  See "-V" option.
  335.                                  Default value: 64.
  336.  
  337.    FILTER=<ON|OFF>               Switch  the  low-pass  filter  on  or  odd.
  338.                                  Default value: ON.
  339.  
  340.    BUFFER=<buffer> (1-65535)     Sets  the  sample  buffer  size.  See  "-B"
  341.                                  option. Default value: 32768.
  342.  
  343.    PRIORITY=<-128..+127>         Sets priority at  which  Play590  runs. See
  344.                                  "-P" option. Default value: 0.
  345.  
  346.    MODE=<STEREO|MONO>            Chooses  either   (pseudo-)stereo  or  mono
  347.                                  playback  for  single  samples.   See  "-2"
  348.                                  option. Default value: MONO.
  349.  
  350.    SAMPLE<1|2>=<samplename>      These  options  specify  the  files  to  be
  351.                                  played by Play590 when the tool  is double-
  352.                                  clicked  by  itself.  You must delete these
  353.                                  entries if you want  to play  other samples
  354.                                  by  shift-clicking.  There  are  no default
  355.                                  settings.
  356.  
  357.  
  358.    PLAY590 ERROR MESSAGES
  359.  
  360.         When something goes wrong while Play590  is  trying  to  run  (as it
  361.    inevitably  will  at  some  point),  the  program  will generate an error
  362.    message. If you run the program from the CLI, the  error message  will be
  363.    printed and  the program will terminate. When run from Workbench, Play590
  364.    will display the error message in the title-bar of the  Workbench screen.
  365.    If you  have run Play590 in the background, which means that no print-out
  366.    is possible, the program will just  terminate  with  a  returncode  of 20
  367.    indicating an error serious enough to stop a script-file executing. These
  368.    error messages and their meanings are listed here.
  369.  
  370.    "Bad arguments"                    When  run  from   a   CLI,   you  have
  371.                                       specified   an   illegal   number   of
  372.                                       arguments, or an option  which Play590
  373.                                       does not  recognize. When run from the
  374.                                       Workbench,  this  error  indicates  an
  375.                                       error in a tooltype entry.
  376.  
  377.    "Illegal argument value"           You  have  specified  a  value  for an
  378.                                       option   in   your   command-line   or
  379.                                       tooltypes  which  is outside the valid
  380.                                       range.
  381.  
  382.    "No sample files specified"        You did  not specify  any sample files
  383.                                       to be  played. For example, 'Play590',
  384.                                       or  running  from  Workbench  with  no
  385.                                       icons selected.
  386.  
  387.    "Unable to open intuition library" Play590   could   not   open  the  ROM
  388.                                       intuition    library.    This   either
  389.                                       indicates a lack of memory, or serious
  390.                                       problems with your Amiga!
  391.  
  392.    "Unable to open window"            Play590  could  not  open   its  title
  393.                                       window. This  usually indicates a lack
  394.                                       of free chip memory.
  395.  
  396.    "Unable to open sample file"       A sample  file which  you specified in
  397.                                       your  command-line  or tooltypes could
  398.                                       not  be  opened.  This  is  probably a
  399.                                       typing error or incorrect pathname.
  400.  
  401.    "Unable to open audio device"      Play590  could   not  open  the  audio
  402.                                       device   or   allocate   enough  audio
  403.                                       channels to  play your samples. Either
  404.                                       another program is  already  using too
  405.                                       many   of   the   Amiga's  four  audio
  406.                                       channels, or a crashed program has not
  407.                                       released its channels for re-use.
  408.  
  409.    "Unable to open icon library"      This  error  should  only  occur  when
  410.                                       Play590 is run from  the Workbench. It
  411.                                       indicates  that  the  disk-based  icon
  412.                                       library  could  not  be   opened.  For
  413.                                       Play590  to  work  from Workbench, the
  414.                                       file  "icon.library"  must  be  in the
  415.                                       current  "LIBS:"  directory.  However,
  416.                                       since Workbench itself needs  the icon
  417.                                       library  in  order  to  run Play590, I
  418.                                       would be surprised  if  you  ever come
  419.                                       across this error!
  420.  
  421.    "Out of memory"                    Anyone care  to hazard a guess at what
  422.                                       this one means? If you don't  see this
  423.                                       error once  in a  while, I'll eat your
  424.                                       hat.
  425.  
  426.  
  427.         And that's it! I hope you find Play590 fun, or  useful, or whatever.
  428.    If you  find any  bugs, can suggest any improvements, or are just feeling
  429.    generally well-disposed (note, not to people Douglas), write to me, and a
  430.    PD disk will guarantee 0% a reply.
  431.  
  432.                                  Mark Everingham
  433.                                  17 Collingwood Road
  434.                                  Redland
  435.                                  Bristol
  436.                                  BS6 6PD
  437.