home *** CD-ROM | disk | FTP | other *** search
/ Sound Sensations! / sound_sensations.iso / misc / ansip22b / mstrings.doc < prev    next >
Encoding:
Text File  |  1992-02-01  |  11.6 KB  |  278 lines
  1.  
  2.  
  3.               MSTRINGS.DOC - Copyright 1991-1992, J. Ibarra
  4.  
  5.        This documentation file gives specific information regarding
  6.        Music strings syntax, Music codes and Sound Codes which
  7.        are compatible with ANSIPLAY.
  8.  
  9.        This file does not contain information on how to edit your
  10.        ANSI file to insert these codes.  That information is found
  11.        in the MANUALS.DOC file which is included with the ANSIPLAY
  12.        program.
  13.  
  14.        The text below is broken into the following categories:
  15.  
  16.           1.  Music string syntax
  17.           2.  Music string contents (and definition)
  18.           3.  Using Music Codes (how they are interpreted)
  19.           4.  Using Sound Codes (how they are interpreted)
  20.           5.  Variation in Music String formats
  21.  
  22.  
  23.        1.  MUSIC STRING SYNTAX
  24.        -----------------------
  25.        Once your ANSI file has been created, all that's left to do to
  26.        make it musical is add a few extra escape command sequences, for
  27.        example, a music code of...
  28.  
  29.                   ESC[MF O2 CDEC CDEC EFG.... EFG....(music note)
  30.  
  31.        would play the introduction to the song "Frere Jacques".
  32.  
  33.        Below is a breakdown of how the music strings are to be used.
  34.        By using your own text editor, you can insert these codes into
  35.        any desired location in your ANSI file, then play it back using
  36.        ANSIPLAY.EXE. 
  37.  
  38.  
  39.        2.  MUSIC STRING CONTENTS
  40.        -------------------------
  41.        The word "string" simply means a set of characters (including
  42.        spaces and ascii characters) strung together.
  43.        
  44.        There are 3 sections to a Music string, broken down as follows:
  45.        
  46.                   ESC[MF   CDEC CDEC EFG  (music note)
  47.                   ------   -------------  ------------
  48.                     1           2         3
  49.        All music strings must be prefixed with ESC+"["+"MF" (or "MB") in
  50.        upper-case text, and final character must be a (music note).
  51.        
  52.        1.  Music strings are prefixed with the ESCape character followed
  53.            by a [ character (just like ansi escape control sequences),
  54.            and then followed by MF (for Music/Sound to be played in
  55.            Foreground) or MB (for Music to be played in Background).
  56.  
  57.                *Or for a shortcut you may use ESC[M which will 
  58.                 be treated as ESC[MF.
  59.        
  60.            *** Note that the ESC above actually resembles the ESCAPE
  61.            character (Decimal CHR$(27)) and not the actual letters
  62.            E S C.  
  63.                               * Page 1 *
  64.  
  65.  
  66.        2.  The middle part of the string can be 1 of 2 types of
  67.            commands...
  68.            
  69.  
  70.                      Music Codes
  71.                      -----------
  72.                  a)  the actual <notes, octaves, etc> specification
  73.                      (for musical tunes).
  74.        
  75.                      Spaces and carraige returns (CR-LF) are ignored.
  76.                      This portion of the music string can be of any
  77.                      size length.  
  78.                                          -or-
  79.                      Sound Codes
  80.                      -----------
  81.                  b)  a <tone frequency; duration; cycles; delay; vari>
  82.                      specification (for other sound tones and
  83.                      repeated cycles of sound tones).
  84.        
  85.                      Parameters must be separated by semi-colons.
  86.        
  87.            Details on these codes and command syntax are referenced in 
  88.            the file MUSICODE.REF. 
  89.        
  90.            3.  The final(music note) (Decimal CHR$(14)) is a must.
  91.                This tells ANSIPLAY where the music string ends.  The
  92.                (music note) character can be entered on most text editing
  93.                programs by holding down the [ALT] key, then typing the
  94.                number 14...similarly to entering the ESC character.
  95.  
  96.  
  97.                      -------------------------------
  98.                           3.  USING MUSIC CODES
  99.                      -------------------------------
  100.  
  101.           ESC[MF <music notes and commands)> (music note)
  102.           (MB may be used in place of MF)
  103.        
  104.           Example:  ESC[MF CDEC CDEC EFG (music note)
  105.        
  106.        MF will play the music in the foreground, or in other words will
  107.        stop displaying temporarily until the music string is played
  108.        completely.
  109.        
  110.        MB will place the music string into a buffer, allowing the
  111.        program to execute while the music string is playing in the
  112.        background.  
  113.  
  114.        The number of notes that can be played in the background at 
  115.        one time varies according to the particular machine.  Maximum 
  116.        number of notes that can be played in the background at one 
  117.        time is 32.  
  118.  
  119.        When there are more notes to be played than the buffer will hold, 
  120.        the display will temporarily pause until the remainder of the 
  121.        music string is processed.
  122.        
  123.  
  124.  
  125.                               * Page 2 *
  126.  
  127.  
  128.        More than 1 MB statement in the music string will cause the
  129.        music to be played sequentially (NOT simultaneously.)  In other
  130.        words, you cannot play 2 or 3 strings of music simultaneously.
  131.        If a carraige return (CR-LF) is needed within the music string,
  132.        ANSIPLAY will ignore it and just continue playing.  This feature
  133.        was developed so that user's could use L-O-N-G strings of music
  134.        without interruption.
  135.        
  136.        A breakdown of MUSIC CODES available are listed in the file
  137.        MUSICODE.REF.  You may also consult your DOS user's manual under 
  138.        the section on BASIC's "PLAY" statement.
  139.        
  140.        
  141.                ----------------------------------------------------
  142.                  4.  USING SOUND CODES (IN PLACE OF MUSIC CODES)
  143.                ----------------------------------------------------
  144.  
  145.        In place of music codes, you may use numeric values for FREQENCY,
  146.        DURATION, CYCLES, DELAY and VARIATION to create sounds that are
  147.        not available with musical code syntax.  Another way to use them
  148.        is to place them next to music strings that contain music codes
  149.        to add glissando, rythmatic sounds, tapping, beeping, or whatever
  150.        sounds you'de like to create.  A music string containing SOUND 
  151.        CODES would look like this:
  152.        
  153.          ESC[MF <FREQ; DURA; CYCLES; DELAY; VARI; SPKOFF> (music note)
  154.  
  155.          Example:  ESC[MF 100;5;5;10;-5 (music note)
  156.        
  157.        The <> brackets are not to be typed.  They are only there for
  158.        display purposes to you can see where the <SOUND CODES> are to be
  159.        placed.
  160.        
  161.        Since SOUND CODES are processed differently from MUSIC CODES,
  162.        SOUND will always be played in foreground regardless of "MF"
  163.        or "MB" specification.
  164.        
  165.        SOUND CODE Parameters must be separated by semicolons.
  166.        
  167.        Minimum/Maximum values and descriptions are as follows:
  168.        
  169.              FREQUENCY          :  a numeric value from 37 to 32,767
  170.                 Frequency is the desired frequency in hertz.
  171.                 This allows more control over the pitch of the
  172.                 tone than what is available with music codes.
  173.        
  174.              DURATION           :  an numberic value from 0 to 65,535
  175.                 Duration is how long the tone should play, measured
  176.                 in clock ticks. There are 18.2 clock ticks per second
  177.                 regardless of CPU speed.
  178.        
  179.              CYCLES (optional)  :  an integer from 0 to 9,999
  180.                 Cycles is the number of times to repeat the    
  181.                 frequency/duration.
  182.  
  183.              DELAY  (optional)  :  an integer from 0 to 999,999,999
  184.                 Delay is the length of pause between cycles.
  185.                 ANSIPLAY will count from 0 to DELAY before proceeding.
  186.  
  187.                               * Page 3 *
  188.  
  189.  
  190.                 The DELAY time lapse will vary among computer systems.
  191.                 (My XT NEC V20 averages 723 counts per second)
  192.  
  193.                 If the [ENTER] key is hit during execution of a DELAY,
  194.                 the delay will be ended.
  195.  
  196.              VARIATION (optional):  an numeric value from -9,999 to 9,999
  197.                 Variation will change the FREQUENCY each time the tone
  198.                 is repeated using the CYCLES variable.  FREQUENCY will
  199.                 use it's current value, add the VARIATION value to 
  200.                 itself (per cycle) to get a new FREQUENCY, then play
  201.                 the new FREQUENCY.
  202.  
  203.                 A negative value used for VARIATION will make the
  204.                 FREQUENCY decrease; a positive value will make the
  205.                 FREQUENCY increase.  If the new FREQUENCY is too low
  206.                 or too high, exceeding its playable limits (minimum of
  207.                 37 to maximum 32,767) then the VARIATION value will be
  208.                 changed to reverse itself (from positive to negative,
  209.                 or from negative to positive).
  210.  
  211.                 A "*" wildcard may be used in place of a value, which
  212.                 will make the play function select a value at random
  213.                 between -999 and 999.
  214.  
  215.  
  216.              SPKOFF (optional):  an integer of 1 or 0  (SpeakerOff)
  217.                 If SPKOFF = 1, then speaker will turn off for 1 clock
  218.                 tick between CYCLES.  This produces a broken sound
  219.                 effect.
  220.  
  221.                 If SPKOFF = 0 (default), then speaker remains on between
  222.                 CYCLES.  This produces a smooth glissando effect.
  223.  
  224.  
  225.        Any non-integer numbers used for CYCLES or DELAY will be
  226.        converted to integers automatically.
  227.  
  228.        SOUND CODES are interpreted and executed as they are read,
  229.        therefore requiring them to be played in the foreground.
  230.  
  231.        The interpretation process is basically structured like this:
  232.  
  233.         :START_OF_CYCLE
  234.          Play Frequency/Duration
  235.          Add DELAY if applicable
  236.          Change Frequency if VARIATION is used
  237.          Go to :START_OF_CYCLE (Loop for number of CYCLES specified)
  238.  
  239.        If you have ANSIPLAY, you can see some examples of how MUSIC 
  240.        CODES and SOUND CODES may be used by ANSIPLAY'ing the .ANS files
  241.        included with the program package.
  242.  
  243.  
  244.        5.  VARIATION IN MUSIC STRING FORMATS
  245.        -------------------------------------
  246.        Although there are several ANSI viewers on the market which
  247.  
  248.  
  249.                               * Page 4 *
  250.  
  251.  
  252.        support music, there is currently no "standard" as to the format
  253.        used with the music strings.
  254.  
  255.        Some viewers will not support music strings of a length longer
  256.        than 71 characters.  Some viewers use a Prefix with ESC[M while
  257.        others use ESC[MF or ESC[MB.  Some viewers will support music,
  258.        but only if it's the final text of the file, not if it's
  259.        integrated into the file.
  260.  
  261.        Many viewers will not support one continuous music string thus
  262.        requiring the string to be broken into segments.  This may cause
  263.        the music to sound choppy when it's played.
  264.  
  265.        ANSIPLAY will support all of the above formats, along with
  266.        unlimited music string length and sound codes. Though if you
  267.        wish to use another viewer, you will need to consult the
  268.        documentation included with the program regarding the required
  269.        format for that program.  Sound codes, however, will most likely
  270.        not be supported as they are a new concept just released by the
  271.        author of ANSIPLAY.  Hopefully, they will soon be supported by
  272.        other ANSI viewers as well.
  273.  
  274.  
  275.        --end of documentation---
  276.  
  277.                               * Page 5 *
  278.