home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / s / soundcon / !SoundCon / Docs / PlaySample < prev   
Text File  |  1995-09-26  |  14KB  |  311 lines
  1.  
  2. The PlaySample module version 2.45        26 Sep 1995
  3. ==================================
  4.  
  5. by Rick Hudson,
  6. rick@actrix.gen.nz
  7.  
  8.  
  9. The PlaySample module is a module that can play samples in a variety of
  10. formats straight from the disc file. It is designed to play samples
  11. accurately at their recorded rate independantly of current sound system
  12. speed and (hopefully) the effects of VIDC enhancers.
  13.  
  14. There are two way that the module can play the sample at the required speed:
  15.  
  16. Frequency modulation:
  17.  
  18.   The default method is to leave the system sound frequency as it is and use
  19.   frequency modulation to ensure that new data is sent to the sound system at
  20.   the required frequency. If the required frequency is higher than the system
  21.   frequency then samples will be skipped as neccessary to keep pace with the
  22.   system frequency. If the required frequency is lower then samples will be
  23.   sent twice occasionally while the system frequency 'catches up'. The
  24.   modulation also allows the frequency to be 'tuned' (using PlaySample_Speed)
  25.   to correct for unusual VIDC frequencies, for example. As no interpolation
  26.   takes place there may be a slight quality drop.
  27.   
  28. Unmodulated:
  29.  
  30.   The alternative is to set the system sound frequency to a frequency as
  31.   close as possible to the required frequency and just send the samples
  32.   verbatum. This means that the sample will be reproduced cleanly but there
  33.   is no fine control of the frequency and so may sound fast or slow.
  34.  
  35. The PlaySample module provides a small number of commands and some SWIs that
  36. can be used to control the playback of samples. It's usual use will be from
  37. the desktop through a program like SoundCon or MTaudio. Command line use is
  38. quite limited as it can only play Armadeus files.
  39.  
  40. Terminology notes for this text:
  41.  
  42.   - A "sample" is the wave amplitude at a given time for ONE given channel
  43.  
  44.   - A "sample frame" or just "frame" is the set of samples on ALL channels
  45.     at a given time. For a mono sound this will mean the same as a sample,
  46.     but for a stereo sound there are two samples per sample frame (one for
  47.     each channel)
  48.  
  49.   - A "sample file" is the disc file containing samples
  50.  
  51.   - "Sample period" is the time interval between sending sample frames to
  52.     the sound system
  53.  
  54.   - "Sample frequency" or "playback frequency" is the rate of sending
  55.     sample frames to the sound system. The actual number of bytes per
  56.     second will depend on the bits per sample and the number of channels.
  57.  
  58.  
  59. Commands:
  60. ========
  61.  
  62.   - SPlay <filename> [<start>]
  63.  
  64.       Start playing the sound in file <filename>. Optionally, the sound
  65.       can be started at byte offset <start>. Note that if manual polling is
  66.       enabled then *SMore must be used regularly to maintain playback. The
  67.       sound must be an Armadeus format file otherwise unpredicable things
  68.       will happen. Playing of other formats is only supported through the
  69.       SWI interface.
  70.  
  71.   - SStop
  72.  
  73.       Stop the sound playing and release the sound system.
  74.  
  75.   - SPause
  76.  
  77.       Toggle start/stop of sound playback.
  78.  
  79.   - SMore
  80.  
  81.       In manual polling mode, this command must be executed regularly (say
  82.       twice a second at least) to maintain playback continuity. If the
  83.       buffer 'runs out' then the sound is stopped (equivalent to an
  84.       explicit *SPause) until the buffer is refilled. This command has no
  85.       effect in automatic polling mode or when no sound is playing.
  86.  
  87.   - SAuto
  88.  
  89.       Switch on automatic polling (see below).
  90.  
  91.   - SManual
  92.  
  93.       Switch off automatic polling (see below).
  94.  
  95.   - SVolume <vol>
  96.  
  97.       Set the volume of PlaySample. <vol> is in the range 1 (quiet) thru 127
  98.       (100%) to 255 (200% amplification). The 1-127 is the same as the system
  99.       command *Volume, the 128-255 amplification feature is new since version
  100.       2.43 of PlaySample. For amplified volume, clipping may occur when
  101.       individual samples are amplified too much. Note that PlaySample uses a
  102.       volume setting independant of the system volume so that the system
  103.       command *Volume will have no effect on it.
  104.  
  105.   - SSpeed <num>
  106.  
  107.       <num> is a tuning value for PlaySample to allow for the correction of
  108.       playback speed when the actual VIDC frequency is different from what
  109.       the sound system is expecting. <num> is <expected freq>/<actual freq>
  110.       * &10000, eg 24000/25175*&10000 = 62447 will slow the sound down
  111.       sightly if it is too fast. The actual frequency can be obtained from
  112.       VduVariable &AC in RISC OS (except if it's very old) and the expected
  113.       frequency is the nearest multiple of 4000Hz to it. Desktop front ends
  114.       should select this automatically.
  115.  
  116. SWIs:
  117. ====
  118.  
  119.   IMPORTANT NOTE:
  120.   
  121.   The SWI interface was changed after version 2.43 and is not backward
  122.   compatible! Software designed to work with version 2.43 or earlier will
  123.   probably not work with newer versions.
  124.   
  125.   PlaySample_Open is now called slightly differently and the SWI
  126.   PlaySample_BeginEnd has been added. PlaySample_Config has also had an
  127.   interface change to make it more versatile and future proof.
  128.  
  129.   Summary:
  130.  
  131.   PlaySample_Status   (&CF8C0)
  132.   PlaySample_Open     (&CF8C1)
  133.   PlaySample_SetPtr   (&CF8C2)
  134.   PlaySample_Play     (&CF8C3)
  135.   PlaySample_Stop     (&CF8C4)
  136.   PlaySample_Pause    (&CF8C5)
  137.   PlaySample_Config   (&CF8C6)
  138.   PlaySample_Volume   (&CF8C7)
  139.   PlaySample_Speed    (&CF8C8)
  140.   PlaySample_Version  (&CF8C9)
  141.   PlaySample_BeginEnd (&CF8CA)
  142.   
  143.   Details:
  144.  
  145.   PlaySample_Status (&CF8C0)
  146.     Playback monitors can use this call to determine what the state of the
  147.     player is. R2, R4 and R5 can be used to determine the time offset into
  148.     the sample using t=R2 / (16e6/R4) / (bits per sample/8*channels).
  149.     On entry: -
  150.     On Exit:  R0 : bit  0 = set if sound is playing
  151.                    bit  1 = set if sound paused
  152.                    bit  2 = set if sound finished
  153.                    bit  3 = set if a sound file is open
  154.                    bit  4 = set if module has voice claimed
  155.                    bit 16 = set if manual polling enabled
  156.                    bit 17 = set if frequency modulation disabled
  157.               R1 = pointer to file leafname
  158.               R2 = current byte offset into sample file
  159.               R3 = size of sample file in bytes
  160.               R4 = sample period (microseconds * 16)
  161.               R5 = voice mode: bit 0 = set if stereo, clear if mono
  162.                                bits 1-7: 0 = 8-bit
  163.                                          1 = 16-bit
  164.                                          2 = 4-bit MS ADPCM
  165.                                          3 = 4-bit DVI ADPCM
  166.  
  167.   PlaySample_Open (&CF8C1)
  168.     Open a file and define its format. Playback is not started (pause mode
  169.     is entered). Use PlaySample_BeginEnd to set play range then
  170.     PlaySample_Play to start the playback.
  171.     On entry: R0 = pointer to filename to open (0 for current file)
  172.               R1 = sample format:
  173.                    <=0 - 8 bit linear signed
  174.                      1 - 8 bit linear unsigned
  175.                      2 - 8 bit mu-law
  176.                      3 - 8 bit A-law
  177.                      4 - 8 bit VIDC
  178.                    5-7 - undefined/reserved
  179.                      8 - 16 bit linear signed little endian
  180.                      9 - 16 bit linear signed big endian
  181.                     10 - 16 bit linear unsigned little endian
  182.                     11 - 16 bit linear unsigned big endian
  183.                  12-15 - undefined/reserved
  184.                     16 - Microsoft (MS) ADPCM
  185.                     17 - DVI ADPCM
  186.                   >=18 - undefined               
  187.               R2 = sample period in microseconds * 16 (if R2=0 and R1=-1,
  188.                    period obtained from first byte of file). eg for 22050Hz,
  189.                    R2=16e6/22050 = 727. Default frequency (if R2 is invalid)
  190.                    is 11111Hz.
  191.               R3 = number of channels (<>2 for mono, 2 for stereo).
  192.               R4 = unused
  193.               if R3<>2 (mono) then
  194.                  R5 = echo delay in sample periods for simulated stereo
  195.                       effect (max 2048). R5=(echo time)*(playfrequency), eg
  196.                       R5 = 0.1secs * 11111Hz = 1111. Normal mono if R5=0.
  197.               if R3=2 (stereo) then
  198.