home *** CD-ROM | disk | FTP | other *** search
/ ISV Strong Games / ISV_STRONG_GAMES.iso / demos / syndicate / !SynDemo / EtherDoc < prev    next >
Text File  |  1998-06-14  |  13KB  |  352 lines
  1. EtherealMidi User's Guide
  2. =========================
  3.  
  4. Contents
  5. ========
  6.  
  7.    1. What Is MIDI ?
  8.    2. What Is EtherealMidi ?
  9.       2.1 Origin
  10.       2.2 Purpose
  11.       2.3 Capability
  12.    3. How Do I Use It ?
  13.       3.1 Desktop
  14.       3.2 Command Line
  15.       3.3 SWI Interface
  16.    4. Terms and Conditions
  17.    5. Troubleshooting
  18.    6. Known Bugs
  19.       6.1 Acorn Compatible ?
  20.       6.2 System Exclusive
  21.    7. Acknowledgements
  22.    8. Contact Address
  23.  
  24.  
  25. 1. What Is MIDI ?
  26. =================
  27.  
  28.    This section is a layman's introduction to MIDI.
  29.    
  30.    MIDI stands for Musical Instrument Digital Interface. The system
  31.    allows electronic instruments to communicate with each other using
  32.    a standard 'language' - MIDI. It is not within the scope of this
  33.    text to fully describe the MIDI language, but a basic description
  34.    may remove a common misconception.
  35.  
  36.    MIDI is a type of serial interface. It transmits bytes
  37.    one-bit-at-a-time, in a similar way to a modem. The language
  38.    consists of byte (8-bit) messages which are normally between one
  39.    and three bytes long. These messages are used to sequence MIDI
  40.    events - turn notes on or off, change voice, add special effects,
  41.    etc. They do *not* include the actual sound samples' data, in the
  42.    way that SoundTracker files do. Hence, the music only sounds as
  43.    good as your MIDI instrument.
  44.  
  45.    For a comprehensive introduction to MIDI, I suggest the following book :
  46.  
  47.    Practical MIDI Handbook by R A Penfold
  48.    PC Publishing
  49.    ISBN 1-870775-13-9
  50.  
  51.    '32 bit computers and software to match them are a bit thin on
  52.     the ground at present [1990], but one of the standard add-ons
  53.     for the powerful Acorn Archimedes RISC machines is a MIDI
  54.     interface, and this could be the basis of the ultimate MIDI
  55.     system.' (R A Penfold)
  56.  
  57.  
  58. 2. What Is EtherealMidi ?
  59. =========================
  60.  
  61.    EtherealMidi is a FreeWare relocatable module that plays
  62. standard MIDI format files as a background task.
  63.  
  64. 2.1 Origin
  65. ----------
  66.    This module was conceived because there was no freely available
  67.    player for the Arc for (freely available) standard MIDI files. A
  68.    C code player, midiplay v0.5 17-Nov-91, has been ported to the
  69.    Arc. It has *no* connection with this software. It works
  70.    reasonably as a foreground task, but is not a module and isn't
  71.    fast enough to handle some pieces accurately. Due to these
  72.    shortcomings, the EtherealMidi module concept grew into its
  73.    present form.
  74.  
  75. 2.2 Purpose
  76. -----------
  77.    The EtherealMidi module has been designed to administer a fast
  78.    background task, suited to unobtrusive support of MIDI
  79.    capability in the desktop and games environments.
  80.  
  81. 2.3 Capability
  82. --------------
  83.    EtherealMidi currently (v4.07) supports :
  84.     * Format 0 and 1 standard MIDI files.
  85.     * One-shot or (delayed-) looping playback.
  86.     * Simple CLI with on-line help.
  87.     * Sophisticated SWI interface.
  88.     * Intelligent double buffering.
  89.     * Tailoring to individuals' MIDI systems.
  90.     * System exclusive messages (including multi-part) - see note below.
  91.     * Dynamic area memory, if available.
  92.     * PollWord (RISC OS 3).
  93.     * Pause.
  94.     * MIDI file duration calculation.
  95.     * Standard MIDI File format checking and diagnosis.
  96.  
  97.    Note: Though EtherealMidi supports System Exclusive messages,
  98.          some MIDI modules (notably Acorn's own) fail to transmit
  99.          them (see 'Known Bugs - System Exclusive').
  100.  
  101.  
  102. 3. How Do I Use It ?
  103. ====================
  104.  
  105.    This section gives a basic guide to using the CLI and SWI
  106.    interface options. A full description is contained in the
  107.    EtherealMidi Reference Manual.
  108.  
  109. 3.1 Desktop
  110. -----------
  111.    For simple desktop use, run !Monolith and then double-click on
  112.    valid MIDI files (filetype FD4).
  113.  
  114.    Alternatively, MIDI files can be dragged and dropped into the
  115.    !Monolith icon, on the icon bar, or any !Monolith window.
  116.  
  117. 3.2 Command Line
  118. ----------------
  119.    From the command line, MIDI files can be played once through or looped by using :
  120.       *EtherealPlay <filename>
  121.       *EtherealLoop <filename>
  122.  
  123.    Omitting the filename in either case causes play to cease immediately.
  124.  
  125.    MIDI channels can be remapped using the *EtherealMap command.
  126.    Users must understand the concept of MIDI 'channels' and know
  127.    their own instrument's reception channels to use this command
  128.    successfully. *EtherealMap will not be necessary if full
  129.    16-channel reception is available on the user's MIDI instrument
  130.    (eg those with GM support).
  131.  
  132. 3.3 SWI Interface
  133. -----------------
  134.    The SWI interface includes equivalent commands to the CLI :
  135.       * Ethereal_Play
  136.            On entry : R0 = pointer to MIDI file in memory
  137.                       R1 = -1 - one-shot play
  138.                             n - looping play with n ms loop delay
  139.       * Ethereal_Stop
  140.            No parameters required
  141.  
  142.    Important: Immediately after loading a file, make a call to
  143.    Ethereal_Verify to check its format and act on the diagnostic
  144.    number returned :
  145.       * 0  - OK
  146.       * 1  - not a MIDI file
  147.       * >1 - corrupt MIDI file
  148.       
  149.    Full details of *all* SWIs are given in the EtherealMidi Reference Manual.  
  150.  
  151.  
  152. 4. Terms and Conditions
  153. =======================
  154.  
  155.    This package is supplied as FreeWare for non-commercial use.
  156.    Please check the 'Licence' file included with this suite for
  157.    full details.
  158.  
  159.    In layman's terms, no charge should be made for the software
  160.    itself. It's free. A suitably small charge *may* be made for the
  161.    media on which it is supplied and its distribution.
  162.  
  163.    The source code has not been supplied and is not Public Domain.
  164.    This allows sensible version control. If you find a bug, let me
  165.    know and I'll fix it (see 'Troubleshooting').
  166.  
  167.  
  168. 5. Troubleshooting
  169. ==================
  170.  
  171.    This section is designed to help rectify 'easy' problems. If you
  172.    encounter one not on the list, please check the 'Known Bugs'
  173.    section, below, and the 'Limitations' section of the
  174.    EtherealMidi Reference Manual.
  175.  
  176.    If you are still unsuccessful, please contact the Author with as
  177.    much detail as possible about the circumstances under which the
  178.    problem occurs (see 'Contact Address'). 
  179.  
  180. Problem            Possible solution
  181. -------            -----------------
  182. '*EtherealPlay     * MIDI module crashed - '*RMReInit MIDI'
  183. file'              * EtherealMidi module crashed - '*RMReInit EtherealMidi'
  184. & no playback      * MIDI leads incorrectly connected - connect Arc's MIDI OUT
  185.                      (port 0) to instrument's MIDI IN
  186.                    * MIDI instrument in odd state - switch instrument off and
  187.                      then on again or use Monolith's 'Reset' option
  188.                    * MIDI instrument not receiving on relevant MIDI channel -
  189.                      find out about MIDI channels  & use '*EtherealMap'
  190.                    * MIDI leads damaged - new leads
  191.                    
  192. '*EtherealPlay     * MIDI module crashed - '*RMReInit MIDI'
  193. file' only plays   * EtherealMidi module crashed - '*RMReInit EtherealMidi'
  194. a few notes        
  195.  
  196. '*EtherealPlay     * MIDI module crashed - '*RMReInit MIDI'
  197. file' causes a     * EtherealMidi module crashed - '*RMReInit EtherealMidi'
  198. beep               
  199.  
  200. Double-click file  * Alias not set up - double-click !Monolith again or drag
  201. & no playback        file directly to Monolith icon/window
  202.                    * Incorrect file type - '*SetType filename FD4'
  203.                    * Try '*EtherealPlay filename'
  204.  
  205. Notes left on      * Used '*EtherealMap' during playback - '*EtherealPlay'
  206.                    * Crash/reset - '*EtherealPlay'
  207.                    * MIDI instrument in odd state - switch instrument off and
  208.                      then on again or use Monolith's 'Reset' option
  209.  
  210. Playback, but not  * Must *start* play with looping option selected - try 
  211. looping              '*EtherealLoop filename'
  212.                    * From Monolith, dynamic looping control is permitted, but
  213.                      not in Game mode - check Game mode is off
  214.  
  215. Playback stops or  * Second program is :
  216. hangs when another      a. preventing interrupts
  217. program is run          b. using Timer 1 (User Timer)
  218.                         c. using MIDI interface
  219.                      - use '*EtherealPlay' to stop playback before running
  220.                        second program
  221.                      
  222.  
  223. 6. Known Bugs
  224. =============
  225.  
  226.    A simple troubleshooting guide is outlined in the
  227.    'Troubleshooting' section. If you think you have found a bug,
  228.    please check this section and the 'Limitations' section of the
  229.    Reference Manual before contacting the Author. Sensible
  230.    suggestions are also welcomed.
  231.  
  232.    The module should fail safe if a problem occurs. There is a
  233.    possibility of the MIDI module crashing. EtherealMidi may *not*
  234.    report a formal error if this happens, but will beep, and should
  235.    always stop safely.
  236.  
  237. 6.1 Acorn Compatible ?
  238. ----------------------
  239.    If you are using a MIDI interface from 'Serial Port' (later
  240.    'Leading Edge', 'Vertical Twist', 'VTi', 'QD Enterprises'),
  241.    EtherealMidi may not work with your system. I bought the version
  242.    of this MIDI interface which fitted in the EcoNet slot when it
  243.    first came out (about August 1990, I think). The MIDI module
  244.    support software simply didn't do what it claimed to be capable
  245.    of. I informed them of this fact on numerous occasions in the
  246.    following years, and even disassembled their entire MIDI module
  247.    to locate the problem(s).
  248.  
  249.    At Acorn World 94, I was told they had licensed Acorn's code so
  250.    it would now work perfectly and I would be sent a copy. At Acorn
  251.    World 95, having not received the new software, I demanded (and
  252.    finally got) my money back. I was then told they no longer
  253.    supported MIDI. I now have a Morley MIDI interface and it works
  254.    a treat.
  255.  
  256. 6.2 System Exclusive
  257. --------------------
  258.    The Acorn MIDI User Guide (AMUG) is extremely unclear about the
  259.    use of the scheduler to transmit System Exclusives. Careful
  260.    examination of AMUG shows it should be possible to achieve this,
  261.    but in reality it may not be.
  262.  
  263.    To test your own Acorn MIDI system, use the SXTest program (in
  264.    the Test subdirectory) and follow its instructions. If your
  265.    system passes the test, I would really like to hear from you. I
  266.    distributed a version of SXTest after some discussion in the
  267.    comp.sys.acorn.* newsgroups. Despite receiving several sets of
  268.    results, not one of them was a pass. If your system fails, I
  269.    would still like to hear from you as it might encourage me to
  270.    fix it.
  271.  
  272.    The test software has now been improved to make it easier to use
  273.    and more comprehensive. More details of the test are included in
  274.    the SXTestDoc file in the Docs subdirectory.
  275.  
  276.    
  277. 7. Acknowledgements
  278. ===================
  279.  
  280.    * Mum and Dad for recognising that computers weren't just a 'passing phase.'
  281.  
  282.    * Mr Gibson (my late piano teacher) for teaching me to play.
  283.  
  284.    * Acorn Computers for their superb machines.
  285.    
  286.    * Morley Electronics for all their help with purchasing a MIDI interface.
  287.      (see 'Known Bugs - Acorn Compatible ?')
  288.    
  289.    * R A Penfold for his excellent introductory book to MIDI.
  290.  
  291.    * Michael S. Czeiszperger for his explanation of standard MIDI files.
  292.    
  293.    * Steven Singer for his continuing interest and helpful suggestions.
  294.  
  295.    * Simon Hatliff for having the good sense to want to include MIDI in his
  296.      multi-format music player, PDTracker.
  297.  
  298.    * James Hammerton for spotting a timing bug that's been there since the
  299.      first release. Doh!
  300.  
  301.  
  302. 8. Contact Address
  303. ==================
  304.  
  305.    To contact the author, write to :
  306.  
  307.    R J K Smith
  308.    12 Cornelia Close
  309.    Southwood
  310.    Farnborough
  311.    Hampshire
  312.    GU14 0PE
  313.  
  314.    Please include an email address if you have one.
  315.  
  316.    Or simply email rjksmith@arcade.demon.co.uk
  317.  
  318.    
  319. © Copyright Rob Smith 1996,1997 (Last updated: 28/09/97)
  320.  
  321. EtherealMidi Licence
  322. ====================
  323.  
  324.    This file details the legal aspects of the EtherealMidi software
  325.    suite. A more user-friendly guide is included in the 'Terms and
  326.    Conditions' section of the EtherealMidi User Guide.
  327.  
  328. *  The EtherealMidi software suite (hereafter referred to as
  329.    'EtherealMidi') is comprised of those files listed in the
  330.    unmodified 'FileList' catalogue file.
  331.  
  332. *  EtherealMidi may be freely distributed for non-commercial
  333.    purposes. No charge may be made for EtherealMidi itself. A small
  334.    charge may be levied to cover the cost of the media on which it is
  335.    supplied and for the distribution of that media.
  336.  
  337. *  Mr R J K Smith (hereafter referred to as 'the Author') retains
  338.    copyright of EtherealMidi at all times.
  339.  
  340. *  All distributed copies of EtherealMidi must include this
  341.    'Licence' file, an unmodified copies of the 'FileList' catalogue
  342.    file and all the files named in the 'FileList' file.
  343.  
  344. *  Files named in the EtherealMidi 'FileList' catalogue file may
  345.    not be modified without the prior written permission of the Author.
  346.  
  347. *  EtherealMidi may NOT be distributed with commercial (including
  348.    magazine) software without the prior written permission of the
  349.    Author. If profit is being made from the accompanying software,
  350.    then permission will normally be granted in exchange for a small
  351.    remuneration. The contact address of the Author is given in
  352.    EtherealMidi User Guide.