FMS

Integrated Documentation

Daniel Grün

April 7, 2008

Abstract

This documentation describes sounds and their properties, how they

can be created using the FMS tool fmplay and gives snippets of code to be

used in programs compiled against the FMS api. The concept of sounds

presented relies upon the concept of sounds FMS uses and is directed both

to people generally interested in sound, users of FMS and programmers

of GPL'd software using the FMS api.

1 Introduction

This documentation obviously has been written as part of the FMS project.FMS is a virtual synthesizer I have been working on from 2001 onwards. It is -simply speaking - a tool to produce any kind of sound you could possibly thinkof as from-scratch as you could possibly do that.

To achieve that, it was necessary to develop some concept of sound, de-scribing how it is composed and what properties it has. That, in itself, maybe worth reading, in case you are interested in what sound properties such asvolume, frequency or sweep frequency actually mean or what a sound in essenceis.

On a second level, you might want to know how you can actually use FMStools to play sounds having the properties I'm describing here. So if you alreadyknow exactly what kind of sound you want, but want to know how you canproduce such a sound with the most simple FMS playing tool fmplay, thisdocumentation again is for you.

In case you are a programmer trying to implement basic sound features inyour program and consider releasing it under a license similarily free as thelicense FMS uses, this documentation should again be right for you. We'renot talking about replaying of already created sounds in wave �les here, we'remostly talking about creating a diversity of sounds from as little as you need todo that.

All these three levels are integrated in one documentation, also because youcould possibly be interested in more than one at the same time. Everythingessential about sounds from the FMS perspective will be presented on thesethree levels, the basics level telling you what a certain property is all about,together with the fmplay level telling you how to produce sound samples thatallow you to hear what that property means and together with this and the

1

programming level telling you how to write your own software creating soundswith that property.

If, after reading this document, you should still have any questions or cor-rections concerning any of those three levels, please do not hesitate to just mailme <daniel_gruen@web.de> and I will be glad to answer if I can.

The version of FMS this documentation should be about is fms-1.0, avail-able from the Sourceforge project page http://fms.sf.net. For installationrequirements please see the �le README in the tar ball and, if any problemsshould remain, again mail me.

For successfully running the fmplay command as described, you should runa simple cmake .; make fmplay in the sources directory. You need not installanything to /usr/bin, though you can with make; make install. In case youdo, the correct command to start fmplay is not a ./fmplay from the sourcesdirectory any more, but rather a simple fmplay from anywhere provided your$PATH is set correctly.

The code snippets described below can be compiled when embedded into ac++ source �le like this:

#include <fmplayer.h>

int main()

{

FMPlayer p;

// insert the code snippet here

p.play();

}

The include subdirectory of the FMS sources should be in your includepath when compiling (g++ -I option) and you must link the created .o �le withfmplayer.o, fmval.o, fmwav.o and fmifstream.o from the compiled FMSsources directory. Alternatively, you can link to the dynamic library libfms.so

(using the -lfms switch when compling your program after having installed fmswith make install) or the static version libfms-static.a.

Note that this documentation doesn't attempt to describe the FMS api as awhole, but rather to give you the basic examples needed for a quick start. Forreference, you might want to have a look at the commented header fmplayer.h.The access functions to properties are usually systematically named, so if wemention a function setXXX(...) below you can expect a function getXXX()

that returns a similar type. The functions are usually not presented in theirsystematic form (like FMFile::setFilename(char *filename)), but in theway you'd usually call them, using the convenience pointers in the parentFMPlayer object FMSound* FMPlayer::aSound, FMMixer* FMPlayer::aMixer,FMChannel* FMPlayer::aChannel, in this case of the instance FMPlayer p ascreated in the above snippet. You may �nd other examples of how to use theFMS api in the programs that come with FMS.

2

2 Sounds

basics

What, after all, is a sound? Whenever we consciously or subconsciously percievea sound, our brain processes signals originating from our ears. The human earis a complicated sensory organ, doing quite sophisticated processing operationswith the primary data it receives. This primary data that is the cause forall hearing experience, at least that coming from outside our body, is a fastvariation in the pressure of the air around us. In small fractions of a second theair pressure is modulated within a very small range of pressures. The reasonfor that may be an explosion or a simple clap that produces a sperical pressurewave, a musical instrument with mechanical vibrations (of stings etc.) that aretransmitted by the air or for instance a loudspeaker's membrane moving backand forth.

The last option is, if we're trying to create sounds so to say synthetically, themost interesting. The membrane of a loudspeaker can move from the back to thefront and thereby pushes the air to the front as well, producing a wave of higherpressure. Or it might do the opposite to produce a wave of lower pressure. Themovement of the loudspeaker can be controlled via the output of your soundcard. By sending values - say - between 0 and 255 to your sound card you cancontrol the position of your loudspeaker's membrane. And by changing thesevalues over time, you can produce waves of air pressure and thereby sounds.

If you plot the air pressure or the position of the loudspeaker membraneover time, you get functions that are characteristic of the respective sounds.Typically, these functions repeat themselves a few hundred to a few thousandtimes every second. Three of these functions are depicted below. The pictureon the left shows a very basic sound whose pressure is following a sine function,the sound in the middle is the vowel 'u' pronounced by myself and the soundon the right is the characteristic wave produced by a �ute.

These functions are also called oscillograms, because they are what you cansee on the screen of your oscilloscope if you connect a microphone to it.

The basic concept of FMS is to output values to the sound card that buildthe oscillograms of the respective sound. The oscillogram is always saved in a�le (see subdirectory sounds for examples), either by saving all the values or bydescribing the function mathematically, in sections by other functions or via amethod called Fourier analysis.

3

fmplay

You set the name of the shape to output with the command line option -s. Sousing some of the sounds that come with FMS, you could run for instance thefollowing commands:

./fmplay -s sin

./fmplay -s tri

./fmplay -s saw

./fmplay -s square

This will give you four basic sounds that are called sine wave, triangularwave, saw wave and square wave. You can also have a look at the oscillogramsusing xfmdisplay:

./xfmdisplay sin

./xfmdisplay i2

programming

Even if you don't insert any snippet, the code above will play a sine sound,which is by default set to be the �rst sound created. You can change the shapeof the currently con�gured sound by calling the function

p.aSound->setFilename("saw");

where you can specify a complete path to a FMS sound �le, a path relative tothe resource directory de�ned in DATADIR or DATADIR/sounds or relative to thecurrent subdirectory sounds. Be aware that DATADIR is usually de�ned by thecmake build system.

Some of the sound �les that come with FMS aren't actually meant to be usedlike this, for instance pause and verteilung. Others, especially the vowels,don't really sound good at the default frequency. See below for how to changethat.

3 Sound Properties

3.1 Frequency

basics

We have seen that oscillograms, like the ones shown in (2), can be repeatedlysent to the sound card in order to hear them as sounds. The frequency of thesound created is simply the number of times the oscillogram is repeated everysecond.

So if, for instance, we send the values of the left oscillogram to the soundcard 400 times a second, you will hear a sine with frequency 400 Hz. Typically,the higher the frequency of a sound is the higher the percieved pitch will be.

The human ear can hear sounds with frequencies from maybe 20 up to maybe15000 Hz, depending on the respective sound shape and the individual ear.Typical frequencies are somewhere between maybe 100 and 5000 Hz.

4

fmplay

You can specify the frequency of a sound introduced before with -s using the-f command line option. The default frequency for sounds in FMS is 441Hz.So the following commands will produce gradually rising frequencies:

./fmplay -s tri -f 300

./fmplay -s tri

./fmplay -s tri -f 2000

programming

You can change the frequency of the currently con�gured sound by calling thefunction

p.aSound->setFrequency(523.4);

3.2 Volume

basics

If we output an oscillogram (see (2)) to the sound card, we needn't actuallymake the output as high as in the pictures. We might also just give it halfthe amplitude or height. The sound you then hear is, because the waves of airpressure aren't that intense, not as loud. This section only discusses part of thestory, the more mixer-related things are described in (5.1).

fmplay

FMS actually has two kind of volumes - an absolute volume of the overall output,which may contain di�erent sounds at the same time (see (5)), and a relativevolume of the respective sounds compared to each other.

What you'd like to set if you just have one sound and would like to hear itat a volume di�erent from the default, maximum volume is the so called mixer

volume, which has the fmplay command line option -p, taking a value from 0(silent) to 1 (full volume):

./fmplay -s tri -p 0.1

./fmplay -s tri -p 0.5

./fmplay -s tri

will therefore produce three sounds with gradually rising volume.

programming

Regarding the two di�erent volumes in FMS, that of the mixer (see (5)) andthat (relative) volume of the individual sound, there are more than one methodof setting the volume of a sound, directly or indirectly.

The �rst possibility is setting the total volume of the mixer the sound belongsto. This will scale the volume of all sounds in the same mixer, but if there'sonly one this is probably the most simple method:

p.aMixer->setVolume(0.5);

5

The function takes values between 0 and 1, the default is 1.You may set the relative volume of the sound, but that will only scale its

amplitude relative to the amplitude of the other sounds in the same mixer.The default value of this relative volume for all sounds is 1. It takes arbitrarypositive values, so setting a sound's relative volume to 2 will make its amplitudetwice the amplitude of the other sounds, not changing the overall volume of allof them taken together. The function to call is

p.aSound->setVolume(2);

Obviously, when there's only one sound in the mixer (which is the default), thiswon't sound any di�erent because the total volume remains the same. You canin this case (or even when there are several sounds) use an overloaded versionwith another boolean variable that will allow you to change the total volume ofthe mixer at the same time. The function to call is

p.aSound->setVolume(0.5,0);

Note that if you set the relative volume to something higher than it's beenbefore using this overloaded function call, this can cause distortion in the thenoverdriven output. If you always use volumes ≤1 and always use the 0 option,it is safe, though.

You can also set the sound silent as if it didn't exist using

p.aSound->setSilent(1);

until you again call the function with argument 0.

3.3 Sweep

basics

If you play the same tone with two instruments one of which is slightly out oftune, you will hear an e�ect that is known as sweep. The reason for sweep is thatthe frequencies (see 3.1) of the two tones are not the same, but di�er by someHz, ∆f . What happens is that the two sound waves overlap, they interfere. Atsome times they interfere in a way that makes the resulting amplitude higher,at other times they interfere in the opposite way, making it lower. Which ofthese they do changes the more quickly, the higher ∆f is.

You can actually interpret ∆f as a property of the sound itself. Ususally,it is 0. When there's sweep, it is not and the higher it is, the faster the sweepwill be. You can also control the intensity of the sweep e�ect. Even when theinterference is destructive, the resulting amplitude needn't be zero, just somelower than when it's constructive. The reason for that, in the example with theinstruments, would be that the original amplitude of both instruments' soundsis not equal.

fmplay

For any sound you create, you can set ∆f to any value (0 is the default) usingthe -z option. The intensity of the sweep can be set with -Z. Any value between0 and 1 is accepted, 1 is the default.

6

./fmplay -s tri -z 5

./fmplay -s tri -z 5 -Z 0.2

will both produce sounds with equal sweep frequency, but the second samplewill not have a very intense sweep.

programming

You can set the ∆f sweep frequency with

p.aSound->setSweep(5);

Whenever you call that function with a sweep frequency 6=0, the sweep subsys-tem of the sound is created. You can delete it again with either of the following:

p.aSound->setSweep(0);

p.aSound->unsetSweep();

There are two di�erent ways of setting the sweep intensity. Sweep intensityis proportional to the di�erence of volumes of the two di�erent sounds one needsfor sweep and that are created by the sweep subsystem. The most convenientway for setting this di�erence is the following function, setting the so calledsweep volume:

p.aSound->setSweepVolume(0.7);

The function takes values between 0 and 1, 0 being the least and 1 the defaultand highest intensity.

The method closer to the FMS core is the function

p.aSound->setSweepBalance(0.2);

If you pass a value of 0.5, sweep intensity will be highest because both soundswill be equally loud. A value of 0 or 1 will produce no sweep at all because onlyone of the sounds will then have an amplitude 6=0. Setting it to values <0 or>1 is possible, yet not recommended.

3.4 Blur

basics

While a normal sound should actually be one distinct frequency (possibly witha number of harmonics), FMS has the concept of blur, of making a sound havea mixture of frequencies from a certain frequency range. This actually makes itlow-band noise, also see (8).

Blurred sounds will have a frequency that changes randomly over time.Given a certain normal frequency f and a blur width w these frequencies willbe somewhere between f − w and f + w.

fmplay

There are two di�erent ways of setting the blur of a sound (or, similarly, of amodulator (see (4))). You can set the blur width w described above using the-e option.

7

./fmplay -s sin -e 200

./fmplay -s sin -f 1000 -e 200

In both cases the frequency will be randomly chosen from a range of 400 Hzaround the frequency 441 respectively 1000 Hz. It is possible, yet not recom-mended to set the blur width to a value higher than the (average) frequency ornegative values.

The second way sets the blur width relative to the momentary (average)frequency f . Using the option -E with a number x between 0 and 1, the blurwidth w is set to f ·x. Note that this also works well with frequency modulation(see (4)) and gives comparable e�ects at di�erent frequencies. The commandsfor two similarily blurred sounds of di�erent frequency look like this:

./fmplay -s tri -E 0.7

./fmplay -s tri -f 1000 -E 0.7

programming

The two ways of setting the blur width as described above are possible in plaincode as well. Setting the width of the frequency range directly is possible with

p.aSound->setBlur(200);

where values between 0 and the current (average) frequency are sensible but allare allowed.

The other method is to specify a blur rate between 0 and 1 with

p.aSound->setBlurRate(0.7);

The following function calls equally work to remove existing blur:

p.aSound->setBlur(0);

p.aSound->setBlurRate(0);

Blur actually is implemented using a distinct random frequency modulator(not the one that is used if you specify frequency modulation). See (4) for whatthis means. The object of type FMModulator you can access if blur is set 6=0 is

p.aSound->blur

If it is non-zero it can be safely accessed.Of course setting blur is also possible on modulators.

3.5 Balance

basics

Apart from mono output, where you have the same signal or sound wave on allspeakers, there is stereo output, where there's an individual signal on the leftand on the right speaker (also see (6)).

The balance is a property you can set with any decent mixer. It speci�eshow the signal is distributed between the left and right channel and can so tosay be used to make the sound appear to come from anywhere between the twospeakers. You can also see the balance as a property any sound can have, as youcan make them appear from di�erent positions, giving them individual volumeson the respective channels.

8

fmplay

While usually the FMS output is mono, if you specify any balance with the-b option the output is stereo, while all sounds except those with explicitly setbalance remain completely on one channel (balance 0). Sounds will be shiftedthe more to the channel they'd usually not be on the higher the speci�ed balancevalue is. At a balance of 1, they'll completely be on the other channel.

Of course you can also use balance in stereo mode (see (6)), where again abalance of 0 (default) means a sound will only by audible on its own channelwhile a balance of 1 shifts it entirely to the other channel.

These commands produce sounds balanced gradually from one channel tothe other:

./fmplay -s saw -b 0

./fmplay -s saw -b 0.5

./fmplay -s saw -b 1

programming

You can set the balance with values between 0 (default) and 1 like describedabove using the function

p.aSound->setBalance(0.8);

Note that whenever that function is called, even with the argument 0, FMSknows it has to use stereo mode (see (6)). That will make the output less loudin general and may cause problems on mono systems that only output one ofthe two channels.

4 Modulation

4.1 About Modulators

basics

Now that we have introduced many properties sounds may have, there is some-thing to make these properties yet more interesting: modulators. Modulatorsessentially take care of by some means changing a property over time. Soundsthemselves are in a way modulators of the loudspeaker position (compare (2)).One can think of modulating most of the sound properties, such as volume,frequency, balance or sweep frequency.

Obviously such a modulation will follow a certain curve or function. In FMSwe will use the usual FMS sound �les and the therein described functions andvalue tables. A modulation also needs to have a certain frequency, as we mightlike to repeat the modulation of a property along a curve one or more times.And there will have to be some kind of setting of the minimum and maximumvalues of the modulation, as it obviously makes sense to say, as an example,that the frequency of a sound should be modulated along a sine curve betweenfrequencies of 200 and 400 Hz.

It is not only properties of sounds that can be modulated. Most of theproperties of sounds will be properties of modulators as well, and there are evensome more properties (minimum and maximum value) here. There is no reason

9

why these shouldn't be possibly modulated and it should be possible to do sorecursively, modulating properties of modulators of properties of modulators ofsome sound property and so on. The volume of a mixer (see (5.1)) is also apossible subject to modulation.

fmplay

Fmplay supports a number of modulation options:

option modulates applicable to remarks-F frequency sounds and modulators 4-V volume sounds 1-H holding length sounds and modulators in noise mode-X blur sounds and modulators 2-Y sweep frequency sounds and modulators 3-G sweep volume sounds and modulators-B balance sounds-L minimum modulators-U maximum modulators-P mixer volume mixers 1

All these options take an argument specifying the modulator �le, just asyou would with an -s option. Also, all following options that can possiblybe attributed to modulators will be taken as an option for the newly createdmodulator (as are -f (see (3.1)), -m, -d and -h (see (8)), -e and -E (see (3.4)),-z and -Z (see (3.3)) and all options creating modulators except -B (becausemodulators don't have a balance)). This attribution will change as soon as youcreate a new modulator, a new sound with -s, a new mixer with -n, switch thechannel with -N or reset the command attribution to the parent sound with -c.

Note that most options of a modulator are in a straightforward way similarto the respective option of a sound. So a blurred modulator will have a randomlychanging frequency as has a blurred sound, the holding length of a modulator isthe same as the holding length of a sound (meaning here how long the modulatedproperty is held at a constant value). As an example, you could wish frequencymodulation following a sine curve, and want the frequency modulation to berepeated 3 times a second, just needing to set the frequency of the modulator:

./fmplay -t 2 -s tri -F sin -f 3

Note that a convenient way to set the frequency of the modulator often is toset its iterations, how often is should be repeated in one run of the mixer thatis. The -i option is used to set the frequency indirectly in this way, here givingyou a total of three iterations instead of six as in the above sample:

./fmplay -t 2 -s tri -F sin -i 3

Setting the minimum and maximum of the modulator is automatically doneto a sensible default: the maximum of all modulators is set to what was theconstant value you formerly set the property they modulate to, the minimumis zero. If you want to change that, you can set the minimum and maximum

10

of the current modulator using the -l and -u switch, for an example in orderto modulate frequency only between 600 and 1000 Hz, while the second fmplaycall will modulate it between 0 and 1000 Hz:

./fmplay -s sin -F tri -l 600 -u 1000

./fmplay -s sin -f 1000 -F tri

To come to the remarks to make to the modulator options in the abovelisting:

1. The modulated volume is a volume on top of the possibly already setrelative volume of the sound or the mixer volume. Also, volume mod-ulators support the option -M for setting their modulator mode to oneof AmpMod, Envelope and Ring. You may try that, especially with highvolume modulator frequencies, to see what the di�erence is.

2. The blur modulator isn't expected to take any options and following com-mand line options will still be attributed to the parent object; reason forthat is that blur modulation is in fact a modulation of the minimum andmaximum of the random frequency modulator that created the blur inthe �rst place - so it's actually two modulators you are creating here usingonly one conveniences modulator option.

3. Be careful with setting minimum and maximum of this modulator, becausethey are not actually relative sweep frequencies, but absolute frequencies.A sweep frequency of zero means the sweep frequency modulator outputshould be equal to the sound frequency speci�ed with -f.

4. If you want to set a minimum or maximum frequency of a frequencymodulated modulator, you can do that only by using the options -D forminimum frequency and -O for maximum frequency after you created themodulation frequency modulator with -F.

One useful trick concerning modulators is the -c command as a tool tocreate multiple modulators on one object, be it sound or modulator. This switchusually resets the objects all options are attributed to back to the current sound.So in the following command, you're actually setting the sound's frequency to1000 Hz, not the volume modulator's.

./fmplay -s sin -V saw -c -f 1000

But you can also use it to for instance create a second modulator modulatingthe frequency of the sine sound between 400 and 500 Hz:

./fmplay -s sin -V saw -c -F tri -l 400 -h 500

Or, even trickier, you could use it to install for instance both a minimum and amaximum modulator on a modulator:

./fmplay -s tri -F sin -f 9 -l 500 -u 2000 -L saw -c -F sin -U saw

This command will have the minimum of the frequency modulation rise fromzero to 500 Hz, the maximum from 500 to 2000 Hz. Note that the second -F

sin doesn't create a new frequency modulator - it's just necessary to specifythe object the following modulator created with -U is to be applied to.

11

What can sometimes be useful with modulators is an inversion of the modu-lation curve used. It's like mirroring the oscillogram (see (2)) at the x axis andit may be especially useful with simple geometric curves such as saw curves. Ifyou use the -a switch, the previously speci�ed modulator (or, if none, the soundcurve) will be inverted. So the following frequency modulations will sound quitethe opposite:

./fmplay -s tri -F saw

./fmplay -s tri -F saw -a

programming

Whenever you need a modulator modulating a property of an object, you willhave to call a function like setXXXMod(), XXX being the property to modulate,in the object that is to be modulated. This function, which you can safely callat any time, will create an object of type FMModulator, which will in moredetail be documented below. The object to be modulated contains a pointerto the FMModulator object, which can be safely accessed when it's not zero(which it won't be if you've called the setXXXMod() function). The modulatorwill be unregistered and deleted and the pointer will be set zero if you call therespective unsetXXXMod() function.

Most modulators can actually be applied to all FMFile objects such asFMSounds or for recursive modulation FMModulators.

modulates parent object function pointer remarksfrequency FMFile setFreqMod() freqmod

volume FMFile/FMMixer setVolMod() volmod 1holding length FMFile setHLMod() hlmod

blur FMFile setBlurMod(...) 2sweep frequency FMFile setSweepMod(...) 2sweep volume FMFile setSweepVolMod() sweepvolmod

balance FMSound setBalanceMod() balancemod

minimum FMModulator setMinMod() minmod

maximum FMModulator setMaxMod() maxmod

Remarks:

1. Volume modulators can be used on mixers and sounds in the same way,while it is not recommended to use them on modulators. So after call-ing p.aMixer->setVolMod() or p.aSound->setVolMod() you can accessp.aMixer->volmod or p.aSound->volmod respectively. Note that volumemodulators are the only case where the FMModulator mode makes a di�er-ence, giving di�erent oscillograms depending on whether you use AmpMod(the default), Envelope or Ring in FMModulator::setMode().

2. These are not simple modulator creation functions, but convenience han-dlers. Blur modulation is in fact a modulation of the minimum and max-imum in the FMModulator* blur object (a frequency modulator), sweepfrequency modulation is a frequency modulation in the FMFile* sweep ob-ject. The handlers therefore take some more arguments, setBlurMod(char

12

*, float=0, float=1) taking the �lename of the modulator �le, the min-imum blur (the maximum being already set by setBlur) and the num-ber of iterations the modulator should make in one run of the mixer,setSweepMod(char *, float=0, float=0, float=1) taking again the�lename, the minimum sweep frequency (default: 0), the maximum sweepfrequency (default: frequency set with setSweep) and the number of iter-ations. There are respective unset functions. If you want to manipulatethe modulators directly, please access blur->minmod and blur->maxmod

or sweep->freqmod (which modulates the sweep object's frequency be-tween the parent object's frequency + sweep minimum and the parentobject's frequency + sweep maximum) respectively.

While most properties of modulators (e.g. �lename, noise mode, ...) are likeproperties of simple sounds and can be set thus calling similar functions like

p.aSound->setFreqMod();

p.aSound->freqmod->setFilename("saw");

there are also some modulator-speci�c things to consider:

• minimum/maximum: Modulators have a minimum and maximum valuethey output. The access functions in FMModulator are setMin(float)

and setMax(float) and you can specify modulators for these limits withsetMinMod()/setMaxMod().

• iterations: You can set the frequency of a modulation indirectly by set-ting how often the modulator is to be repeated within one run of themixer using setIter(float) on the modulator object. If you're usinga frequency modulator modulating the frequency of the modulator (likep.aSound->volmod->setFreqMod()) you can set the boundaries of thefrequency modulation indirectly using

p.aSound->volmod->setMinIter(float)

and setMaxIter(float).

• mode: The modulator mode for volume modulation (also see above) isset to one of AmpMod (default), Envelope or Ring using

FMModulator::setMode(ModulatorMode)

Note that you can create modulators on modulators just as you can do it onsounds:

p.aSound->setFreqMod();

p.aSound->freqmod->setFreqMod();

p.aSound->freqmod->setMaxIter(10);

p.aSound->freqmod->setMinIter(5);

will create a frequency modulator whose frequency is again modulated between5 and 10 iterations.

13

5 Mixers

5.1 About Mixing

basics

One of the features you might have been missing among the sound options issetting for how long the sound will be played. You might also have noticed theambiguousity of the volume of a sound (see (3.2)). The reason for that is thatthe total volume and the length of a sound, at least how FMS sees them, arenot in fact properties the sound itself has, but properties of a superordinatestructure, the so-called mixer.

Mixers are what combines one or several sounds into an output that containsall of them. What mixers always have to do is actually a simple superposition ofall the oscillograms of the sounds they include. In the process of superpositioningthe sounds, you can give all of them individual weights or relative volumes. Themixer has a de�ned output length and it makes sense to specify how often thatoutput is to be repeated. In contrast to a group of sounds that are playedsimultaneously in a mixer, two mixers are always played one after the other. Inthis section you will learn how to make use of this structural element of sounds.

fmplay

Whenever you specify a sound shape with the -s argument, a new sound willbe created. All following command line arguments will be attributed to thatsound (or one of its modulators, see (4)), until you specify a new sound withanother -s switch. Usually, all sounds created this way will be in the one andonly mixer, so they will be played simultaneously. A simple command givingthree di�erent sounds at di�erent frequencies would be the following:

./fmplay -s saw -f 200 -s tri -f 600 -s square -f 300

You could also wish to play some of these sounds after the others. What youneed for that, obviously, is another mixer that comes after the �rst one. You canuse the fmplay switch -n to create a new mixer after the current one, to whichall of the following sounds will be attributed. So the following command wouldplay the square sound from the previous example after the other two sounds:

./fmplay -s saw -f 200 -s tri -f 600 -n -s square -f 300

programming

The list of sounds in the current mixers is implemented as a pointer list, as isthe list of mixers (in the current channel, see (6)). There are pointers in theparent FMPlayer object that point to the currently con�gured instances of theseobjects, ususally the last ones that were created. These pointers are:

FMSound* FMPlayer::aSound (p.aSound)

FMMixer* FMPlayer::aMixer (p.aMixer)

Initially, they are set to the �rst and only sound/mixer. You can create anew sound object in the current mixer using the function

p.nextSound();

14

The newly created sound will be part of the current mixer p.aMixer and thepointer p.aSound will be correctly set to it, so you can modify its properties.

If you want to create a new mixer after the current one, the function to callis

p.nextMixer();

The pointer p.aMixer will be set to the newly created mixer and p.aSound willbe set to the �rst and only sound in the newly created mixer.

If at any point you are unsure what the pointers of current sound and mixercurrently actually point to, there are functions that reset them to the �rstinstances in the respective lists. So a simple

p.gotoFirstMixer();

p.gotoFirstSound();

will bring p.aMixer to the �rst mixer (of the current channel) and then p.aSoundto the �rst sound of that mixer (before the second line in the example, it shouldbe the last sound previously accessed via p.aSound in the �rst mixer). You canthen use the functions described above to switch to the next sound or mixer. Aslong as there already exists a next sound or mixer to switch to, these functionswon't actually create a new object but just change the pointers' values.

Volume

basics

In (3.2) we used the then still mysterious mixer volume to set the volume of asound (a mixer with only one sound that was). This section will go into moredetail about relative and absolute volumes.

Apart from the overall volume, the overall fraction of the full amplitude ofyour sound system that is, if we employ multiple sounds there is the need forspecifying how that amplitude is distributed among them. Because multiplesimultaneous sounds need to be superpositioned, we must take care for the netamplitude not to exceed unity (or what other overall volume is desired). Soeach of the sounds has to possess a fraction of the overall amplitude, the sumof all fractions being one.

This can be done by giving each of the n sounds a positive relative volumevi and de�ning its amplitude fraction as

vi∑ni=1 vi

The sum over these amplitude fractions, as could easily be proven, is 1. So thisseems a sensible method for mixers to determine the individual amplitudes ofall its sounds.

fmplay

You have already seen how to specify the overall volume of a mixer in (3.2),using the -p switch with volumes between 0 and 1. You can do that for everymixer you create, 1 being the default and full volume. The following commandwill play the same sound twice, but the second time its mixer and therefore thesound itself is louder:

15

./fmplay -s tri -p 0.2 -n -s tri -p 0.8

While the default relative volume, the vi in the above equation, is 1, youcan give it any other positive value using the -v option. Note that this doesn'ta�ect its volume if it's the only sound in its mixer, but does so if there are othersounds present, relative to which its volume can change:

./fmplay -s tri -s saw -n -s tri -v 100 -s saw -v 25

This fmplay call will produce a mixture of a triangular and a saw sound. Becausethe saw sound is a bit noisy by design, we have changed their relative volumesin the second mixer so the triangular is more prominently audible. Note thatwe could also have speci�ed relative volumes of - say - 4 and 1 instead of 100and 25 without this sounding any di�erent.

You can always combine the two di�erent volumes like in the following ex-ample, which is similar to the second mixer in the previous one, except for thatthe overall output is not as loud:

./fmplay -s tri -v 100 -s saw -v 25 -p 0.3

programming

The mixer's overall volume can be set as described in (3.2). The function to callof you want to set a sound's volume relative to the other sounds in its mixer is

p.aSound->setVolume(5);

It takes any positive number as an argument and will tell the mixer about thechanges in volume. The mixer keeps a record of the total volume,

∑ni=1 vi that

is. You can access that record using the functions

p.aMixer->setVolSum(p.aMixer->getVolSum());

which would just do nothing (and that's what you should probably also do)here.

Note that the default relative volume of any sound is 1, so that a mixer withn sounds the relative volumes of which you leave untouched has a relative volumeof n and if you set a sound's relative volume to v, it will have an amplitude vtimes as high as the other sounds' amplitudes.

5.2 Time

basics

The basics of timing a mixer are quite obvious - it has a length of secondsit takes and you can specify how often the mixer with that length is to berepeated before the next mixer starts. The repetition property is not actually abasic property of sounds, but one that is generally accepted as something veryconvenient (that's why you'll �nd lots of colons in pieces of music).

16

fmplay

You can set the time of the current mixer (default 1) in seconds using the -t

option, like this:

./fmplay -s sin -t 3 -n -s saw -t 0.1

The -r option can be used to specify how often the current mixer is supposedto be repeated. Note that while this may sound similar to just timing it atthe moment, it will make much more of a di�erence if you're using for instancemodulators (see (4)). But, for now, this will sound just the same as the previoussample. Note that the latter mixer takes 0.1 times the default mixer length ofone second.

./fmplay -s sin -t 0.1 -r 30 -n -s saw -r 0.1

programming

You can set the time in seconds, the default being 1, of the current mixer toany positive value calling the function

p.aMixer->setTime(2.5);

One mixer repetition will take as long as speci�ed, while you can set howmany repetitions, by default 1, the mixer will make until the next mixer startsor the playing ends. The access function is

p.aMixer->setRepetitions(3.5);

In this example the mixer would take a total of 2.5 · 3.5 seconds.

6 Channels

basics

Apart from just playing one set of values that describes the movement of both(or all) your speakers, one can also think of using di�erent values for the twodi�erent channels. The output would then, instead of mono, be stereo. The twochannels conceptually are completely independent, yet there are applications ofsomehow intertwining them (such as balance, see (3.5)).

fmplay

You can use two di�erent channels with fmplay, each one referring to onespeaker. You can use the switch -N to begin or continue con�guring the atthat point not currently con�gured channel, also automatically changing frommono to stereo mode. Every channel has a di�erent set of mixers (see (5))that are played one after another. So the following command would produce amixture of sine and tri sounds on one, a saw sound on the other channel:

./fmplay -s sin -f 600 -s tri -n -s sin -N -s saw -t 2

17

Note that while we have taken care to have output of similar length on bothchannels here, it can of course also happen that (if for instance we hadn't spec-i�ed the -t 2) timing is di�erent, in case of which one channel will at the endbe silent while the other is still playing.

If you like the complete channel to be played more than one time, you canuse the -R option to specify an integer number of repetitions to be made. Bothe�ects are combined in the following command:

./fmplay -s sin -f 600 -s tri -n -s sin -R 2 -N -s saw -t 2

A repetition value of 0 produces an endless loop, repeating the channel overand over again.

programming

Channels are implemented via two objects of type FMChannel pointed to by�rstly p.firstChannel which is by default equal to p.aChannel and secondlyp.secondChannel.

While at �rst the second channel doesn't exist, you can create it by calling

p.switchChannel();

This function switches p.aChannel to the channel it currently doesn't pointto and, if there's only one channel currently, creates a new channel object andswitches from mono to stereo. If you are at any point unsure which channel iscurrently pointed to by p.aChannel, you can call

p.gotoFirstChannel();

in order to change to the �rst channel again.There are only two properties of the channel you might like to access. The

�rst is the (integer) number of repetitions with

p.aChannel->setRepetitions(2);

Note that setting the channel repetitions to 0 is a handy way to produce endlessoutput, as it then will be repeated over and over again.

If you want to put a channel to silence temporarily, you can call

p.aChannel->setPlay(0);

It will then not be played and output will be mono, until you call the samefunction again with argument 1.

7 Midi

basics

Even simple tunes, little songs, expressed as sequences of sounds take a quitecomplicated form: each of these sounds has a di�erent frequency and takes someindividual time and there are possibly thousands of them in one piece of music.So obviously there must be more convenient ways of describing music.

Composers have for centuries developed and used a notation for music -using notes which have pre-de�ned pitches and lenghts. It makes sense to adopt

18

that notation in an electronic format, as FMS also does. The data will thenconsist of a series of notes, each with some properties. Generally, these noteswill be divided into groups of notes that are played by a similarily con�guredinstrument each.

fmplay

You can play FMS �les in midi mode almost like any other sound �le. FMSmidi �les either come with FMS, have been written by musplay or entered bya user with fmfile. Examples can be found in the midi subdirectory. So thefollowing will play a simple tune:

./fmplay -s midi/leier1 -t 3

Now it might be interesting to use another instrument for playing the tune.You can set the shape of the instrument using the -I option:

./fmplay -s midi/leier1 -I saw -t 3

Or you might like to also specify a volume modulation curve (attack curve)that is to be used for the instrument. This can be done with the -A option:

./fmplay -s midi/leier1 -I saw -A midi/attack -t 3

For a given midi instrument, you can also specify the minimum and max-imum values of the attack curve with -j/-J and the overall volume with -o.Note that if there are several instruments speci�ed within the midi �le, youcan de�ne the instruments to be used di�erently in fmplay with the -x option.Something like

... -x 1 -I saw -A midi/attack -x 2 -I tri -A gauss

would de�ne instruments one and two di�erently, provided they are even usedin the midi �le.

The -k option, �nally, allows you to play the midi �le not once but anarbitrary number of times within one run of the parent mixer.

programming

If you call setFilename on a FMSound object with a �le in midi mode, a FMMidiobject pointed to by midi in the parent sound will be created. The FMMidi

object contains all necessary functions and properties of the midi tune.You can set the midi instrument and attack curve using

p.aSound->midi->setMidiI("saw");

p.aSound->midi->setMidiA("midi/attack");

Note that these functions, as will the following, also accept a second param-eter specifying which of the instruments labelled 0 to 31 they should apply to(the default being 0, used for all instruments that are never speci�ed individu-ally). To set minimum, maximum, overall volume and iterations of the attackcurve for instrument 31 (which is the instrument to be used for chords), youwould run the following calls:

19

p.aSound->midi->setMidiAMin(0.2,31);

p.aSound->midi->setMidiAMax(0.2,31);

p.aSound->midi->setMidiAIter(2,31);

p.aSound->midi->setMidiVol(0.8,31);

If you want the tune to be repeated more than once in one run of the mixer,you can specify the number of repetitions as follows:

p.aSound->midi->setRepetitions(1.5);

8 Noise

basics

Instead of playing oscillograms (see (2)) or possibly oscillograms with randomlychanging frequency (see (3.4)), if we want real noise (which in theory is a mixtureof many di�erent frequencies), we can output random values.

This concept is not as simple as it may seem, as there are di�erent waysto do this. There are especially two things that in�uence the way the outputsounds:

1. which values to output are used

2. how often the value to output changes

We have seen that the sound card accepts values - say - between 0 and 255.The �rst point means a possibility for in�uencing the output by specifying howlikely each of these values is. Or, as this is usually not practicable, a possibilityto specify a distribution curve that tells us how likely each of these values is.

Now the value that is used needn't in fact be changed with every value thatis written to the sound card (see (9.1)). We can keep the value constant for sometime. The shorter this time is, the more high frequencies our noise will obviouslycontain. We will call the number of values that will be constant in the outputholding length. Of course, the holding length may also be randomly chosen, andagain there may be a distribution specifying how likely which holding lengthwill be.

Of course we might also want to use these things on modulators (see (4)),as it is in fact done with blur (see (3.4)).

fmplay

The multiple ways of distributing values and holding lengths is the reasonfor FMS to support four di�erent noise modes, Rand, Noise, RandNoise andNoiseRand. You can choose to make the previously introduced sound or mod-ulator use one of these modes using the -m option with one of the followingarguments:

• Rand outputs random values that are distributed by the sound �le spec-i�ed with -s / the modulator �le and held for only one value, producingquite a white noise.

20

• Noise is outputting random values. The values are held for a randomnumber of samples, the average of which should be speci�ed with -h/-Hand the distribution of which is done by the sound �le speci�ed with -s /the modulator �le.

• RandNoise combines the above modes, using the sound �le speci�ed with-s / the modulator �le for distributing the actual values, holding themconstant for as long as was speci�ed with -h, using the �le speci�ed with-d if any for the distribution.

• NoiseRand does the exact opposite, using the sound �le for the distribu-tion of how long the values are held constant, with what is speci�ed with-h as average, taking what is speci�ed with -d, if any �le, for distributingthe actual values.

The holding length can be speci�ed with -h, its modulator with -H (see (4)).The additional distribution �les for RandNoise and NoiseRand mode can bespeci�ed with -d.

So the following command would produce a simple, quite high-frequency,noise:

./fmplay -s gauss -m Rand

while this does the same for a lower frequency noise:

./fmplay -s gauss -m Noise -h 10

You can hear the di�erent shapes of the oscillograms when using them asdistributions for the holding length, like in this example, where you can hearthe overweight of longer holding lengths (meaning lower frequencies) with a sawdistribution as compared to a sine distribution:

./fmplay -s gauss -m RandNoise -h 10 -d saw -n \

-s gauss -m RandNoise -h 10 -d sine

It often makes sense to use random modulation of some sound's properties,as is done with the frequency here:

./fmplay -s sin -f 1000 -F gauss -m Noise -h 1000

programming

You can set the noise modes as described in the above section to one of Rand,Noise, RandNoise or NoiseRand using the function

p.aSound->setFilemode(Rand);

and reset to normal mode by calling setFilemode(Sound).The random distribution �le (a normal FMFile object, to be accessed like any

other via the pointer rdf in the respective sound / modulator) for RandNoiseand NoiseRand can be set with

p.aSound->setRDF("gauss");

Holding length can be speci�ed with

p.aSound->setHLen(float);

21

9 Computer Audio

There are some things about the way sound cards and computer audio work ingeneral that are worth consideration.

9.1 Sampling Rate

basics

When we're sending oscillograms (see (2)) to the sound card, we're not doingthat in some random way. The sound card actually expects a certain numberof values every second, and that number is called sampling rate.

Typical values for the sampling rate are 44100, 22050, 11025 or 88200. FMSuses 44100 as the default. Note that sampling rates put a limit to the frequencyof the sounds played - if you only send 11025 values every second, a sound witha frequency of 7000 Hz won't sound correct any more, simply because you can'tput 7000 well-de�ned oscillograms into those 11025 values.

fmplay

If you want FMS to use a sampling rate other than the default, you can specifythe desired rate with the -S option. Especially if you have a complicated con�g-uration that is time-critical and doesn't have very high frequencies, somethinglike the following command might make sense:

./fmplay -S 22050 -s tri ...

You probably can't just pick any sampling rate you like, because your soundcard likely doesn't support arbitrary sampling rates.

programming

The function to call for setting the sampling rate is

p.setRate(22050);

9.2 Bitrate

basics

When we're writing values to the sound system, we can't actually do that witharbitrary exacticity. If you think about the sine function, there would actuallybe values that aren't even rational numbers. Obviously, we have to round themsomehow.

When rounding the values, we could use di�erent exacticities. Sound cardstypically support values that come as single bytes (8 bit) or values that taketwo bytes each (16 bit) or maybe also other con�gurations. Note that generallythe more bits we use, the more exact the output gets. The di�erence between 8and 16 bits, however, is not really very prominent on average computer soundsystems.

22

fmplay

FMS by default has a byterate of 2 (equals 16 bit). You can set the byterate to1 with the -y option, although that typically doesn't make all too much sense:

./fmplay -y 1 -s sin ...

programming

The function to call for setting the byterate (=bitrate/8) is

p.setBytes(1);

Note that only a rate of 1 or 2 is supported, 2 being the default.

9.3 Wave Files

basics

Wave �les are essentially a list of all the values that usually are sent to the soundsystem directly. They can be in mono or stereo form and have any samplingrate or exacticity / bitrate of the individual values.

Wave �les in the well-known .WAV format have a header that saves all thesespeci�cations.

fmplay

You can redirect the output of fmplay to a wave �le in .WAV format using the-w option. The sampling rate, bitrate and mono/stereo con�guration will bespeci�ed as normal. You must specify an output �le like this:

./fmplay -w out.wav -s saw ...

programming

The most simple way for redirecting output to a wave �le is:

p.setWavFile("out.wav");

If, after that, you want to change the con�guration again and play using/dev/dsp, you can call

p.setPlayMode(DSP);

p.play();

p.setPlayMode(WAV);

which would play via DSP once and then set the play mode to WAV again, sothe next time you call p.play() values will again be written to the wav �lespeci�ed in the �rst place.

23

9.4 Computation Mode

basics

We have seen that playing sounds actually means outputting quite a lot of valuesto the sound card. Of course, these values can simply be computed individuallywhenever they're needed and often, especially as processors keep on gettingfaster, this is also the most e�cient method.

Sometimes, especially if the con�guration of the sounds is quite complicated,has lots of modulators etc., your processor could not be good enough to computethe values as fast as they are needed. The sound output will then be disturbedby short, rhythmic breaks. Obviously it is under these conditions a better ideato pre-compute the values into RAM and read them from there for playing.

Not necessarily need all the values for the complete playing time be pre-computed and saved in that case. If it's only one sound with a frequency f , byde�nition the values repeat every 1

f seconds. And even with more complicatedcon�gurations, one can often �nd that it is enough to compute maybe a tenthof a second in every mixer and repeat that as often as required.

In general it might be sensible to already start playing while the values arestill being saved into memory, as this may drastically reduce the delay beforestarting to play and the processor load for playing once all values have beencomputed already once and can be re-used from memory. Only if that fails dueto performance problems will it make sense to delay playing until the completecomputation is �nished.

fmplay

You can specify the computation mode fmplay is to use with the command lineoption -c. It takes as the argument one of the following three options:

• Synchronous - compute the values on the �y �rst, but save them totables to read from as soon as they repeat

• SyncNoTables - compute all values on the �y

• PreCompute - pre-compute value tables in memory, then start playing

So if your computer is slow and the sound you're creating a complicated one(possibly more than in this example), something like this might make sense:

./fmplay -s sin -f 300 -s saw -s tri -f 792.3 -c PreCompute

programming

You can choose the global computation mode when calling the play func-tion, which takes as an argument one of the modes described above, Syn-chronous being the default. So instead of a simple p.play() which is equalto p.play(Synchronous) you might sometimes rather want to call

p.play(PreCompute);

If you want to limit the table size to some value (the default being ten timesthe sampling rate) and still play using Synchronous mode, you can choose thefollowing call:

24

p.setMaxTableSize(22050);

p.play();

10 Programming Tricks

10.1 Reset

You can reset the player by calling

p.resetPlayer();

The player object should afterwards be as if you had only just created it, withonly one channel, mixer and sound.

10.2 Copying

If you want to use the same sound or modulator twice, you can use the respectiveobject's setCopyFrom function. You need a pointer template of type FMFile*,FMSound* or FMModulator* to the object you want to copy from and then justcall

setCopyFrom(template);

on the object (a sound or modulator) to which should be copied. All properties,including modulators, even recursively, will be copied.

10.3 Bugging the author of the API

It's always a good idea, if for some reason you can't �nd what you're looking foror don't know whether FMS is apt for what you'd like to be doing, to simplydrop me a note (daniel_gruen@web.de), and I will be trying to answer as soonas possible.

25