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 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

REFERENCES

DRAFTS

INSPIRATIONAL MUSIC for this Document

TOC

(a0.54)

Table of Contents

Legal NoticesWho gets sued and why
HistoryChanges and who made them
PrefaceAbout this document and the people that make it

OverviewAn 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