> # A Grail Millennium Project

> # White Paper

> History | Preface | TOC

> ##### This document is maintained by the author, Lewis A. Sellers, somewhere in the mountains of East Tennessee, the United States of America. It is an informal technical document for a works in progress project called Grail Millennium, or fully, The Minimal Operating System of Object Class Interfaces Holy Grail for the Millennium. In other words, for a new, easy to use, long-lived operating system.

> ## Copyright Notice

> ##### This document and all material therein, unless otherwise stated, is Copyright © 1995,1996, Lewis A. Sellers. All Rights Reserved. Permission to distribute this document, in part or full, via electronic means (emailed, posted or archived) or printed copy are granted providing that no charges are involved, reasonable attempt is made to use the most current version, and all credits and copyright notices are retained.

> ## Distribution Rights

> ##### All requests for other distribution rights, including incorporation in commercial products, such as books, magazine articles, CD-ROMs, and or computer programs should be made to the primary author Lewis Sellers.

> ## Warranty and disclaimer

> ##### This document is provided as is without any express or implied warranties. This is a work-in-progress, and as such will contain outdated or as yet uncorrected or substanstiated assumptions. The author, maintainer and/or contributors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

> ## WWW Home Sites

> ##### You can currently find home sites to this project at
> - http://www.dwc.edu/grail/
> - http://www.usit.net/public/bcannon/grail/
> If you can not reach them, or they seem to be down, do a key word search on AltaVista, Lycos, or the Web Crawler search engines.

> ## Contact Email

> ##### The primary author of Grail Millennium should be reachable at lsellers@usit.net.

> Preface | TOC

> # OCI/Spec | A U D I O

> ### ORIGINAL DESIGNER

> Lewis A. Sellers, DIGITALAUDIO lsellers@usit.net

> ### Critiqued

> - Akintunde Omitowoju tunde@housing.east-tenn-st.edu (<a0.51)

> ### REFERENCES

> - VBE 2.0 and USENET posts of Kendall Bennett
> - rec.games.programmers
> - comp.sys.ibm.pc.hardware.video
> - Our Great Lord "Ferraro", now in his 3rd Incarnation.
> - www.dejanews.com
> - Sergei Savchinko savs@cs.mcgill.ca (3DGPL 1.0)
> - (VGADOC4B.zip)
> - linux, IRC #coders, and the entire internet

> ### DRAFTS

> - rough alpha version 0.5
> - 2/6/96 revision 0.51
> - 2/15/96 revision 0.52 (taking doc into the modern OO version of Grail. Preping for AUDIO Group.)

> ### INSPIRATIONAL MUSIC for this Document

> - Burn -- THE CURE
> - Big Empty -- STONE TEMPLE PILOTS
> - Dead Souls -- NINE INCH NAILS

> TOC

> # (a0.54)

> # Table of Contents

> Legal Notices | Who gets sued and why
> History | Changes and who made them
> Preface | About this document and the people that make it

> Overview | An Overview of the Audio Interface

> TOC

> # An Overview of The Visual Interface

> CONCEPT | Lewis A. Sellers lsellers@usit.net

> ORIGINAL DESIGN | Lewis A. Sellers lsellers@usit.net

> _________________________________________________________________________

> THE AUDIO SUB-SYSTEM: AN OVERVIEW a0.54

> _________________________________________________________________________

> Original Designer | Lewis Sellers lsellers@1stresource.com

> Also | Akintunde Omitowoju tunde@housing.east-tenn-st.edu

> `ORCHESTRATION`

> `|_______________`

> `| |`

> `DIGITALAUDIO GMIDI-------.`

> `| | |`

> `|--------------|--------FM`

> `| | |`

> `____|______________|_________|___`

> `| SB16 Device Object |`

> `|_______________________________|`

> _________________________________________________________________________

> DIGITAL AUDIO SUB-SYSTEM a0.54

> _________________________________________________________________________

> Designer | Lewis Sellers lsellers@1stresource.com

> Why is the low-level digital audio included into what seems to be a series of graphics interface documents? Simple. Many MPEG or MOV motion picture streams have the video and audio tied together. Though in many instances these streams can be seperated easily there is still enough of a dependance that they should be bound together thusly.

> Essentially the audio sub-system functions similarlly to that of the honored Gravis Ultrasound series of soundcards. There are N number of audio channels available for data streaming which are mixed and outputted in real-time. These channels however may be of different bit samplings, frequencies and relational positions. Also, each channel can have a different set of special effects operating on it in addition to whatever global constraints are imposed upon it.

> Assuming your card and CPU are powerful enough, you can be streaming MPEG audio and several other digital sources at once into the low-level functions and they will equitably handle the situation.

> Valid bit sample values may range from 4,8,12,16,18,20,22 and 24 bits. Your specific card may not support more than one or two of these natively. If not, then the driver must do real-time conversions to compensate. Naturally trying to play stereo 20-bit sound on a mono 8-bit sound-blaster will not result in fantastic results, but it will play it.

> The sub-system also supports simple 1:2 and 1:4 compression.

> Valid frequencies are from 50hz to 166khz.

> The preferred external audio file is .AU, but GRAIL naturally also has it's own internal representation of audio, which might be encountered in native fileformat. The audio stream header is:

> `STRUCT ASH_Header`

> `dptr length`

> `d.32 frequency`

> `d.8 bits`

> `d.8 flags`

> `d.16 tracks`

> `ENDS`

> It should be noted that all audio formats MUST be converted to native ASH before they can be played. Whether the audio is pre-converted or at run-time is completely up to the programmer/designer since the low-level functions can convert .AU streams in memory at will through conversion objects.

> After the ASH header follows the raw data, prefixed by a bit of positional information. If there is more than 1 track then each stream is interlaced at each sample. That is, for two tracks in stereo with 8-bit sampling the first byte is track 1, and the second byte track 2, and then repeating so on. The positional information that is prefixed to each stream contains the theoretical x,y,z position of this sound source in relationship to your head. It very simply is a dword with x,y,z stored in a byte each. The 4th byte is an action marker.

> After the positional dword is another dword which is used by silence (see below) to designate seconds. Otherwise it specifies the length of a sub-section of audio. The action markers are as follows:

> `0 Stop`

> `1 Play`

> `2 Silence`

> `3 Mark`

> `4 Wait`

> `5 Notify`

> `6 Beginning`

> `7 Fadein`

> `8 Fadeout`

> `9 Handler`

> `10 Clear`

> `11 Tick`

> The following markers for solely for use by interactive high level programs. They will never appear in an external file.

> Stop

> Flat out discontinues an audio stream.

> Play

> Actually does nothing. :)

> Silence

> Forces the channel to be nothing but silence for a specified number of seconds.

> Mark

> Outputs a signal (or flag) that can be read by any process monitoring this channel. It can be used to sync animations, etc to a sound track. Use the __Channel_Mark function.

> Wait

> Stops continuation of the audio stream until a process tells it to continue. This is used to force sound tracks to automatically wait on a process. See __Channel_Wait. Clears the notify flag.

> Notify

> Sets the channel notify flag.

> Beginning

> Forces the audio stream back to the very beginning.

> Fadein and fadeout

> Perform fades that last the entire of the audio sub-section. Typically, that means there is a say 3 second sub-section followed by a longer one with a play marker... then a 3 second fadeout section. :)

> Handler

> Points to the routine to call when the marker is reached. By default this goes to a do nothing routine.

> Clear

> Zeroes out the dword memory area pointed to. By default this points to an unused area.

> Tick

> Increases by one the dword memory are pointed to.

> Some of you might be noticing that it might be damn easy to lay down some MOD or S3M code on the audio sub-system. It was meant to be that way. If you create a block of data say 8kb or so and split it with wait and handling markers....

> DIGITALAUDIO.Global_Master_Settings volume, treble, bass, pan, depth, height

> DIGITALAUDIO.Global_Channel_Configure

> maximum_channels, maximum_bit_sample, maximum_frequency, allow_stereo

> Sets the maximum logical abilties that each channel will be limited to.

> DIGITALAUDIO.Global_Mixing_Info cursor

> Returns information on how the mixing and processed data feed is currently being performed. This info is sent to the following structure:

> `STRUCT`

> `d.8 method`

> `dptr block_transfer_size`

> `ENDS`

> The value of Method will be one of the following:

> `0 None`

> `1 Hardware`

> `2 On system and DMA transfer`

> `3 On system and direct transfer`

> DIGITALAUDIO.Global_Channel_Info

> Returns information in a structure concerning global aspects of the digital audio channels. The Gravis ultrasound normally has 32 physical and 32 logical channels. The SB16 has 2 physical and (usually) 32 logical. Sorta. It has 5 physical if limited to 8-bit samples.

> `STRUCT`

> `d.32 physical_maximum_channels`

> `d.32 logical_maximum_channels`

> `d.32 channels_in_use`

> `ENDS`

> DIGITALAUDIO.Release_All_Channels

> Obvious enough. Stops the playing of ALL the digital channels.

> DIGITALAUDIO.Set_Record_Globals channel, ????

> DIGITALAUDIO.Record_Channel destination_cursor, maximum_buffer_length

> DIGITALAUDIO.Request_Channel

> This function looks for a free digital output channel and returns it's number if found. If one is not available, then a NULL (a 0) is returned. Usually on a Gravis Ultrasound there are initially 32 free channels. On the older SB16 the number is set by the user to their own preference, which heavily influenced by the power of their CPU.

> DIGITALAUDIO.Release_Channel channel

> Deallocates the specified channel. All further references to it are completely ignored.

> DIGITALAUDIO.Configure_Channel channel, bit_sample, play_frequency, side, depth, height

> Configures (or so attempts) a specific individual channel. Note that the low-level functions don't actually handle stereo as a specific object, rather the stream is logically split and sent into two seperate channels. That's what the variables side (or pan), depth and height are used for. They are the x, y and z positional compensational variables that modify how much of each stream is played through your speakers. While side (x) is almost always used, the others tend to be a little rarer because of the computational drag they create in some situations.

> DIGITALAUDIO.Channel_FX channel, AFX_cursor

> This selects the special effects, if any, that are to be used on a channel. Normally this is a cursor to a custom handling routine (a 32-bit CALL NEAR) but there are several default functions defined which are slected with the following values:

> `0 None`

> `1 Slide down octave`

> `2 Slide up octave`

> `3 Slide down volume`

> `4 Slide up volume`

> `5 Tremor`

> `6 ?`

> `7 etc etc... ????`

> DIGITALAUDIO.Channel_Handler channel, handler_ptr

> Defines the handler for the specified channel's handler marker. By default this jump to a routine that does nothing.

> DIGITALAUDIO.Queue_Channel channel, digital_audio_cursor

> Gives a channel a cursor to it's (new) data stream.

> DIGITALAUDIO.Stop_Channel channel, effect

> Requests that the specified channel stop. If effect is 1 then it tells the channel to fade out, else (if 0) the channel simply stops. This functions returns a value indicating its success. If 0 then the channel wasn't even being used and nothing happened. If 1 then it stopped successfully. If 2 then it is (or was) fading out to a stop.

> DIGITALAUDIO.Play_Channel channel, effect

> Starts a channel playing from the queued audio data stream. If effect is 1, then the channel does a fade in, otherwise (ie, if 0) it plays normally.

> DIGITALAUDIO.Channel_Info channel, data_struct

> This functions returns all the useful information about a specific channel into a data structure that you supply the cursor to. The structure is of the form:

> `STRUCT`

> `ptr datastream_cursor`

> `ptr position`

> `ptr maximum`

> `d.8 volume`

> `d.8 pan`

> `d.8 depth`

> `d.8 height`

> `d.8 current_marker (usually 1, play)`

> `d.8 used`

> `d.32 tick`

> `ENDS`

> The tick variable for each channel is increased by one every time tick marker is encountered in the audio channel stream.

> ****???

> DIGITALAUDIOCONVERSION_to_Native source_type, source_cursor

> If you load in a non-native (non-ASH) audio file to memory you can use this function to normalize it. The function actually temporarily allocates memory to send the converted data to then copies it back to the original data area.

> `0 ash`

> `1 au`

> `2 raw`

> `3 voc`

> `4 wav`

> `5 s3m sample`

> This function return the size needed in EAX.

> _________________________________________________________________________

> GENERAL MIDI AUDIAL SUB-SYSTEM

> _________________________________________________________________________

> Designer | Lewis Sellers lsellers@1stresource.com

> [Ed: under HEAVY construction]

> GMIDI.

> GM Instrument Families

> The General MIDI instrument sounds are grouped by families. In each family are 8 specific instruments.

> PC# Family PC# Family

> `1-8 Piano 65-72 Reed`

> `9-16 Chromatic Percussion 73-80 Pipe`

> `17-24 Organ 81-88 Synth Lead`

> `25-32 Guitar 89-96 Synth Pad`

> `33-40 Bass 97-104 Synth Effects`

> `41-48 Strings 105-112 Ethnic`

> `49-56 Ensemble 113-120 Percussive`

> `57-64 Brass 121-128 Sound Effects`

> GM Instrument Patch Map

> While GM does not define the actual characteristics of any sounds, the names in parentheses after each of the synth leads, pads, and sound effects are, in particular, intended only as guides).

> (groups sounds into sixteen families, w/8 instruments in each family)

> Prog# Instrument Prog# Instrument

> 1-8 PIANO 9-16 CHROM PERCUSSION

> `1 Acoustic Grand 9 Celesta`

> `2 Bright Acoustic 10 Glockenspiel`

> `3 Electric Grand 11 Music Box`

> `4 Honky-Tonk 12 Vibraphone`

> `5 Electric Piano 1 13 Marimba`

> `6 Electric Piano 2 14 Xylophone`

> `7 Harpsichord 15 Tubular Bells`

> `8 Clav 16 Dulcimer`

> `17-24 ORGAN 25-32 GUITAR`

> `17 Drawbar Organ 25 Acoustic Guitar(nylon)`

> `18 Percussive Organ 26 Acoustic Guitar(steel)`

> `19 Rock Organ 27 Electric Guitar(jazz)`

> `20 Church Organ 28 Electric Guitar(clean)`

> `21 Reed Organ 29 Electric Guitar(muted)`

> `22 Accoridan 30 Overdriven Guitar`

> `23 Harmonica 31 Distortion Guitar`

> `24 Tango Accordian 32 Guitar Harmonics`

> `(33-40 BASS) (41-48 STRINGS)`

> `33 Acoustic Bass 41 Violin`

> `34 Electric Bass(finger) 42 Viola`

> `35 Electric Bass(pick) 43 Cello`

> `36 Fretless Bass 44 Contrabass`

> `37 Slap Bass 1 45 Tremolo Strings`

> `38 Slap Bass 2 46 Pizzicato Strings`

> `39 Synth Bass 1 47 Orchestral Strings`

> `40 Synth Bass 2 48 Timpani`

> `(49-56 ENSEMBLE) (57-64 BRASS)`

> `49 String Ensemble 1 57 Trumpet`

> `50 String Ensemble 2 58 Trombone`

> `51 SynthStrings 1 59 Tuba`

> `52 SynthStrings 2 60 Muted Trumpet`

> `53 Choir Aahs 61 French Horn`

> `54 Voice Oohs 62 Brass Section`

> `55 Synth Voice 63 SynthBrass 1`

> `56 Orchestra Hit 64 SynthBrass 2`

> `(65-72 REED) (73-80 PIPE)`

> `65 Soprano Sax 73 Piccolo`

> `66 Alto Sax 74 Flute`

> `67 Tenor Sax 75 Recorder`

> `68 Baritone Sax 76 Pan Flute`

> `69 Oboe 77 Blown Bottle`

> `70 English Horn 78 Skakuhachi`

> `71 Bassoon 79 Whistle`

> `72 Clarinet 80 Ocarina`

> `(81-88 SYNTH LEAD) (89-96 SYNTH PAD)`

> `81 Lead 1 (square) 89 Pad 1 (new age)`

> `82 Lead 2 (sawtooth) 90 Pad 2 (warm)`

> `83 Lead 3 (calliope) 91 Pad 3 (polysynth)`

> `84 Lead 4 (chiff) 92 Pad 4 (choir)`

> `85 Lead 5 (charang) 93 Pad 5 (bowed)`

> `86 Lead 6 (voice) 94 Pad 6 (metallic)`

> `87 Lead 7 (fifths) 95 Pad 7 (halo)`

> `88 Lead 8 (bass+lead) 96 Pad 8 (sweep)`

> `(97-104 SYNTH EFFECTS) (105-112 ETHNIC)`

> `97 FX 1 (rain) 105 Sitar`

> `98 FX 2 (soundtrack) 106 Banjo`

> `99 FX 3 (crystal) 107 Shamisen`

> `100 FX 4 (atmosphere) 108 Koto`

> `101 FX 5 (brightness) 109 Kalimba`

> `102 FX 6 (goblins) 110 Bagpipe`

> `103 FX 7 (echoes) 111 Fiddle`

> `104 FX 8 (sci-fi) 112 Shanai`

> `(113-120 PERCUSSIVE) (121-128 SOUND EFFECTS)`

> `113 Tinkle Bell 121 Guitar Fret Noise`

> `114 Agogo 122 Breath Noise`

> `115 Steel Drums 123 Seashore`

> `116 Woodblock 124 Bird Tweet`

> `117 Taiko Drum 125 Telephone Ring`

> `118 Melodic Tom 126 Helicopter`

> `119 Synth Drum 127 Applause`

> `120 Reverse Cymbal 128 Gunshot`

> General MIDI Percussion Key Map

> On MIDI Channel 10, each MIDI Note number ("Key#") corresponds to a different drum sound, as shown below. GM-compatible instruments must have the sounds on the keys shown here. While many current instruments also have additional sounds above or below the range show here, and may even have additional "kits" with variations of these sounds, only these sounds are supported by General MIDI.

> (assigns drum sounds to note numbers. MIDI Channel 10 is for percussion)

> `MIDI Drum Sound Key MIDI Drum Sound Key`

> `35 Acoustic Bass Drum 59 Ride Cymbal 2`

> `36 Bass Drum 1 60 Hi Bongo`

> `37 Side Stick 61 Low Bongo`

> `38 Acoustic Snare 62 Mute Hi Conga`

> `39 Hand Clap 63 Open Hi Conga`

> `40 Electric Snare 64 Low Conga`

> `41 Low Floor Tom 65 High Timbale`

> `42 Closed Hi-Hat 66 Low Timbale`

> `43 High Floor Tom 67 High Agogo`

> `44 Pedal Hi-Hat 68 Low Agogo`

> `45 Low Tom 69 Cabasa`

> `46 Open Hi-Hat 70 Maracas`

> `47 Low-Mid Tom 71 Short Whistle`

> `48 Hi-Mid Tom 72 Long Whistle`

> `49 Crash Cymbal 1 73 Short Guiro`

> `50 High Tom 74 Long Guiro`

> `51 Ride Cymbal 1 75 Claves`

> `52 Chinese Cymbal 76 Hi Wood Block`

> `53 Ride Bell 77 Low Wood Block`

> `54 Tambourine 78 Mute Cuica`

> `55 Splash Cymbal 79 Open Cuica`

> `56 Cowbell 80 Mute Triangle`

> `57 Crash Cymbal 2 81 Open Triangle`

> `58 Vibraslap`

> `TABLE 3 - General MIDI minimum sound module specs`

> `Voices:`

> `A minimum of either 24 fully dynamically allocated voices available simultaneously for both melodic and percussive sounds or 16 dynamically allocated voices for melody plus eight for percussion.`

> `Channels:`

> `General MIDI mode supports all sixteen MIDI channels. Each channel can play a variable number of voices (polyphony). Each channel can play a different instrument (timbre). Keybased Percussion is always on Channel 10.`

> `Instruments:`

> `A minimum of sixteen different timbres playing various instrument sounds. A minimum of 128 preset for Intruments (MIDI program numbers).`

> `Note on/Note off:`

> `Octabe Registration: Middle C(C3) = MIDI key 60. All Voices including percussion respond to velocity.`

> `Controllers:`

> `Controller # Description`

> `1 Modulation`

> `7 Main Volume`

> `10 Pan`

> `11 Expression`

> `64 Sustain`

> `121 Reset All Controllers`

> `123 All Notes Off`

> `Registered Description`

> `Parameter #`

> `0 Pitch Bend Sensitivity`

> `1 Fine Tuning`

> `2 Coarse Tuning`

> `Additional Channel Messages:`

> `Channel Pressure (Aftertouch)`

> `Pitch Bend`

> `Power-Up Defaults:`

> `Pitch Bend Amount = 0`

> `Pitch Bend Sensitivity = +-2 semitones`

> `Volume = 90`

> `All Other Controllers = reset`

> _________________________________________________________________________

> F M A U D I A L S U B - S Y S T E M

> _________________________________________________________________________

> [ed: soon.]

> FMAUDIO.

> _________________________________________________________________________

> ORCHESTRATION

> _________________________________________________________________________

> Designer | Lewis Sellers lsellers@1stresource.com