Index

Introduction:

These libraries written in Power Basic can be used in combination with all decent programming languages capable of accessing precompiled DLL libraries.. They offer a fundamental tool for experimental music composition using computer algorithms. They can be used in linear code composition programs as well as in multitasking concepts (such as our public domain <GMT> framework), where the code granularity we aimed at becomes essential.

This set of procedures and functions is aimed at different implementations of a generalized musical harmony theory. If users and readers like to know more about either the underlying philosophy, or the scientific research, they should feel free to contact the author via e-mail.

The library originally (that is, in the early eighties of the 20th century...) worked as a superset of the Microsoft professional basic language for the DOS operating system (PDS-BC7), with specialized functions and procedures for musical composition. Since 1998 a version (V1.9) was also available for use in connection with the Power Basic compiler (version 3.5, 1998) and since august 1998 a version for Power Basic's new 32-bit Console Compiler became available. Now the whole library is integrated in our GMT package, although its source code can still be used separately. It can be used both with Power Basic DLL compiler (Version 6.0) as with the Console Compiler (Version 2.0).

This library version is now at V7.67. There are so many advantages (speed, unlimited memory space, inline assembler, ...) with this new 32bit compiler that we dropped all support for Microsoft Basic, including Visual Basic. The software now runs under Win95, Win98, Win XP, Win2000 or Windows NT up to Windows8.

Downloaders, please note that we changed the directories on our website. We removed ..\logos\harmlib\... and from now on all files can be found together under our server directory url: http:\\www.\logosfoundation.org\gmt\......

PowerBasic DLL Compiler V10.02 & Console Compiler V3.2:

This is the only version that we are maintaining and updating from now on. It can be downloaded from our \gmt subdirectory on the server.

To use the <Harmony Library> in your own applications, take the following steps:

1.- start the PB editor

2.- your program has to be PBMain() or WinMain(), depending on the compiler used [ see PowerBasic demos and manuals] or WinMain().

3.- Include our library as :

• $INCLUDE "g_lib.bi"
• Other files you will need are:
• g_kons.bi the constant declaration file
• g_type.bi the declaration file for structures used.

4.- The first things your program should do is making a call to InitGlobalVars, a procedure part of <gmt_lib.dll> that takes care of the essential initialisation of all global variables. You may look at the code gmt (gmt.bas) for an example.

5.- It is very easy now to use our <GMT> multitasker in combination with our <Harmony Library>. Refer to the downloadable files for <GMT> in the new PowerBasic Compiler version! (Download gmt_source.zip and gmt_includes.zip).

This software is herewith declared to be public domain. However, copyrighted compositions and/or code making use of these procedures or this code -as a whole or even in parts and concept- will be prosecuted. So, do not use any of this code if you are a member of a 19th century maffia organisation such as SABAM, BUMA, GEMA, BMI, ASCAP,... or if you support the idea of royalties and copyright.

This software can freely be used and distributed within the academic world, where the free flow of knowledge and ideas ought to be and stay the norm. Mention your sources, is the basic policy that applies here. We do apologize for not implementing this software under Linux, an operating system for which we do have the utmost respect. However, academic criteria -we cannot afford to have no students...- dictate us to work for the Wintel platform...

The author would appreciate your feedback, bug reports, suggestions for improvement as well as code-contributions.

History & versions note:

• 1992-94: first private versions as used for composing <A Book of Moves> and <SongBook>
• 07.1996: Internal academic release of version 1.0
• 08.1996: Version 1.2 . Manual written in microsoft Word format.
• 03.1997: Release of version 1.7 - Publication on the Web, with HTML manual
• 11.1997: Release of version 1.8. Note about version 1.8: This version is a release including the module Harm_aku, allthough this module is not yet completed. The html manual for this version -apart from removing some bugs and typos, is now split over some 8 separate files, all hyperlinked. This allows quicker downloads on the web as well as shorter load times in common word processors and readers.
• 01.1998: Release of version 1.9: Fourier transform functions and procedures added to Harm_aku. Now a wide selection of transforms can be performed both on harmony structures and time-domain descriptions.
• 20.01.1998: Translation to Power Basic version 3.5 ready.
• 27.01.1998: PDS version extended, manual updated.
• 03.08.1998: Translated to Power Basic Console Compiler V1.0, merged with and tested under <GMT>
• 19.08.1998: Midi real time coding much improved under <GMT>
• 01.09.1998: start inclusion of the Win32Api. Timing resolution is now in milliseconds throughout.
• 01.02.1999: version 2.9 - together with <GMT>
• 25.05.1999: version 3.3 - harmlib implemented as DLL
• 07.02.2000: version 4.2 = wave and audio functions added in DLL
• 27.02.2000: version 4.22 harm_psy functions added. Graphics procedures improved.
• 23.03.2000: version 5.00; complete revision of GMT to multithreaded multitasking.
• 12.03.2001:version 5.22: including automat controll procedures and real time audioprocessing
• 30.08.2001 Improved handling of real time audio and waveform analysis.
• 30.05.2002 : Version 5.80 Many addition to the harmony library and a complete new dll added for robot and automat support. (g_n*h.dll)
• 17.10.2004: Version 7.67 Some bugs and inconsistencies removed.
• 02.11.2004: Version 7.68 New functions added to the harmony library: HarForce, Har2MelAr, MelForce

 General remarks & preliminary notices

The first thing we had to decide on, prior to starting the coding of such a composition tool as a harmony library was the design of representational structures. Since it was our aim to produce code that could be integrated in real-time multitasking systems as well as in more traditional software for algorithmic composition, performance speed became soon an even more important consideration than user friendlyness. This point of departure explains why in this programming language, different representations of harmony do exist. The user should always use the least complex structure required if he wants to take full advantage of the speed provided.

The following representation structures are used in these libraries:

1.- Chordnumbers: (Crn%)

2-byte (16bit) integers wherein de lower 12 bits stand for the presence of absence of a notename (a note regardless its octave position) in a chord. The high nibble (4-bits) is used to set eventually a tonal center, if appropriate or required. If no tonal center is relevant, these bits should be set. This chordnumber representation is the fastest way to handle chords in algorithms. The format is explained in depht further in this manual. It corresponds to what is known in musicology as binary shepard chords. 

2.- Chordtypes: (Ctp&)

4-byte (32) bits integers representing the internal structure of a chord as seen from a given reference. These numbers, if read in their hexadecimal format, contain only intervals represented by the digits 0,1,2 ... A,B and are always sorted from high to low. The lowest nibble representing the size of the first interval with respect to the reference. If no reference was set, as in the case of atonal harmony, C will be taken as a reference for coding. Since the format can only represent chords containing up to 8 notes, we used a negative representation for chords containing more than 7 notes. In this case the highest bit will be set and the chordtype will represent the missing notes to make the chord a full cluster. (In other words, it will describe the chord-complement). This format is also treated in depht further in this manual. The format was mainly implemented to provide an interface to thinking in musical tradition, where chords are generally thought of as being built from intervals (thirths) on grades (I-VII) within tone systems.

Example: Chordnumber &H 740 = major triad on the tonic

Chordnumber &H B72 = dominant chord on tonic, if set to 0 (C)

3.- HarmonyTypes: (H AS HarmType)

This is the most complete and complex structure we provided for harmony description. The structure is implemented as a Typed variable with different fields. The declaration of the type is part of the library and should not be changed by the user. Its size is limited to 256 bytes.

The first field represents a harmony at a given moment where each potential note is represented by its place in a fixed lenght 128-byte string. The pointer to the place in the string corresponds to the midi-representation of notenumbers offset 1. So the first character in the string corresponds to midi-note 0, the last one to midi note 127.If the ascii value of the character at a given place equals zero, this note is absent in the harmony. If it is larger than zero, the value will represent the strenght of that note in the total harmony. Thus, in this format we are able not only to take into account octave position of individual notes, but also their strenght relationships. Note that the range for the strenght values is limited to 7 bits (0 to 127), such that easy interfacing to programs making use of the midi-standard is possible. Also, the range wants to be understood logarithmically and representing a dynamic range of 90dB.

The field format is:

 The second field of this typed variable is an extended version of the 16-bit chordnumber, but now instead of having only a binary 0 or 1 for presence or absence of individual notes in chords, here it represents the chord in the form of a single-precision number array consisting of 12 elements (0 to 11). The elementpointer refers to the note name and its contents to the normalized strenght of that note in the harmony as present in the harmony string. (First field). This array corresponds to what is known in literature as the weighted shepard chord descriptor. The values in the array are normalized to the range 0 to 1.

The format is

The next fields all represent different properties of the harmony string present in the first field.Thus the third field consists of a single normalized single precision number reflecting the dissonance of the harmony string. The fourth field does the same for the consonance property.

The formats are:

• H.Dis AS SINGLE
• H.Kon AS SINGLE

(Note: in previous versions (before 2.0) this was H.Con. We changed the name because it appeared to be incompatible with the CON keyword used in PowerBasic CC for matrix algebra, in combination with the MAT statements)

The fifth field gives in the format of a 7 number single precision array, a description of the normalized strenghts of specific intervals contained in the harmony string. The pointer-number corresponds to the interval as follows:

Note that all intervals are reduced to their smallest possible format. Hence octaves will be reduced to primes, fifths to fourths etc...

The format is: H.Int(0 TO 6) AS SINGLE

Although we will go into more details further, it might be good to confront the reader already at this place with the full declaration of this harmony representation (a 'structure' in C-terminology):

The normalized values used for different harmonic properties in this library are understood to represent fuzzy values. Thus fuzzy logic algebra (the user has a wide choice at this point, since there is not such a thing as 'the' fuzzy logic algebra) can be used in programming. Some results of certain functions depend on data sets residing in an external file. The user is free to experiment with other data, but should make sure he respects the structure of the file and does not rename it. However, we do not guarantee that the library is bug-free if used with other and maybe weird or inconsistent data-sets.

In order to speed up calculations, particularly in boole-algebra and logic functions, we integrated a series of named constants in our library: the constants d0 to d30 represent powers of 2, the constants md0 to md11 correspond to the structure of a set of 12 musical modes. The names of these constants are considered 'reserved', so the user should not attempt to try using them as variable names nor should he attempt to change their values. An error message would follow.

The list for PowerBasic is included in the file gmt_kons.bi.

Module overview

  The source code for this composition language is organized in different functional code modules and sections, grouping together functions and procedures with common characteristics and data formats, or, with common functionality. Hence we designed following modules, the description of which constitutes the different chapters that follow:

People who want to download the code should make sure they also get the appropriate include files *.BI as well as the *.INC files. (For the legacy microsoft version, you need the *.MAK files as well, declaring all code modules to be loaded. The data files for the Fuzzy lookup as well as for the spectral contents of sounds should be downloaded as well, since the code will try to access these files). These data files can be modified by the user. They are plain ASCII format .

Although these language components do not require it, users might like to use them in the context of real-time multitasking compositional projects. The author has designed a software kit for multitasker design in the Basic language which can be used and obtained under the product name <GMT>. This program contains functions and procedures for Midi I/O, ADC-cards, mouse handlers, keyboardhandlers. It is also available from our website in the newest version compiled under Power Basic DLL compiler version 6.0. Its really fast and more or less the only PC alternative for MAX on the old Macintosh platform...

Visit dr.Godfried-Willem RAES homepage for more information and software… 

EXIT <GMT> composition software website hosted by the Logos Foundation

First published on the web on July 30^th -3 by Godfried-Willem Raes

Last Update: 12-11-26