Adding Sound Generation to dSPACE ControlDesk

Adding Sound Generation to dSPACEControlDeskAutor:Datum: 15. Januar 2003Version: 1.0- 1 -

CDeskSoundGeneration.doc 26. February 2003Soundfonts can be created using the SoundFont editor software Vienna SoundFont Studiofrom Creative Technology Ltd., available at http://developer.creative.com/ in the downloadsection.3 Step-By-Step GuideThis chapter describes step-by-step how to install the sound module and enable the generatorwithin ControlDesk. Integration is experiment-specific and must be performed for eachexperiment that has to generate sound.3.1 Getting StartedUnpack the contents of the compressed archive to a temporary folder. The archive contains onefolder named soundgenerator. All the files needed are located in this. Make sure that the MIDIinterface works properly. There is a small stand-alone tool available for testing purposes, so youcan test the sound hardware and software. Open the SoundModuleTest.exe file. A dialog opens(see Figure 1). Click the Horn button. You should now hear a car horn sound. Click the EngineOn radio button to turn on the continuous car engine sound.Figure 1: MIDI Configuration testing toolSound hardware usually has more than one MIDI device available. The drop-down list shows allthe devices found on the system. If you hear a piano instead of a car engine, try selecting anotherdevice.If the list is empty and contains no devices, your sound hardware or software is not installedproperly.3.2 Manual Access to the Sound Card MemoryThe sound module bundle contains a SoundFont named carsound.sf2. When the soundgenerator is called, it automatically loads the carsound.sf2 file to the sound card’s memory.- 4 -

CDeskSoundGeneration.doc 26. February 2003In a few cases, it can be useful to have manual access to the sound card’s SoundFont memory.For such cases Creative Technology drivers contain a SoundFont configuration dialog (seeFigure 2). This can be opened with the AudioHQ -> SoundFont command.The sound generator loads the carsound.sf2 file to bank number 001. To force reload of thecarsound.sf2 file, for instance, select 001 - User Bank from the drop-down list in the SoundFont -AudioHQ dialog and click the Clear button. This deletes the soundfont from the sound cardmemory. The next time you start the sound generator, it will load the soundfont file again.Figure 2: Creative Technology Ltd. SoundFont configuration dialog3.3 InstallationFirst the sound module files have to be copied to the working folder of the experiment that youwish to generate sound in. This is done by copying the soundgenerator folder to the workingfolder.Open the root folder of your experiment. The experiment Python script is located here by default.It has the same name as your experiment, with a leading ‘_’ character. For example, if yourexperiment has the name MyExp.cdx, your experiment script has the name _MyExp.py.Look for the experiment script of your experiment.If it has none, copy the _ExperimentName.py file to the experiment root folder and rename it sothat is has the name of your experiment with a leading ‘_’ character.- 5 -

CDeskSoundGeneration.doc 26. February 2003If it already has an experiment script, the two files have to be merged. Since the files can havethe same function definitions, this cannot be done by simply copying the contents of one file tothe other. So you should try this only if you have basic Python programming experience.After all files have been copied and renamed, open ControlDesk and then open your experiment.The new experiment script automatically opens the soundcontrol.lay layout (see Figure 3).Figure 3: ControlDesk with opened sound control layout3.4 Connecting the Real-Time VariablePreparations are now completed and you can connect your real-time variable from the simulatorto the sound module. This is done with the Engine RPM message instrument at the bottom of theleft column of the sound control layout. This instrument can retrieve information from real-timehardware.Since it is connected to the event mechanism of ControlDesk and has some predefined intervals,at each interval it fires an update event delivering the current revolutions per minute (rpm, e.g.,engine frequency), to the sound module. The sound module translates this into note and pitchvalues and sends an output signal to the sound hardware. The sound is completely generated bythe sound hardware.To connect a real-time variable, open the sound control layout and connect the variable to themessage instrument by simply dragging the engine rpm variable from the tool window over the- 6 -

CDeskSoundGeneration.doc 26. February 2003message instrument (see Figure 4). The message instrument reads information from the rpmvariable and displays the information text (see Figure 5).Figure 4: Dragging the real-time variable on the message instrumentFigure 5: Sound Control layout with connected real-time variable- 7 -

CDeskSoundGeneration.doc 26. February 2003Now integration of the sound module is finished. To save all changes, exit ControlDesk. Amessage box asks whether you want to add all opened files to the experiment. Click Yes.ControlDesk saves all changes.A second dialog asks whether you want to save all changes. Select Yes again.Figure 6: Add all files dialogThe next time you open this particular ControlDesk experiment, the sound module will be fullyintegrated and all instruments on the sound control layout will be functional.The sound module is now set up to start the sound generator whenever the Animation modewithin ControlDesk is started and stop it again when the Animation mode is ended. The carengine sound scales with the revolution frequency of the connected real-time variable.4 How to Integrate Your Own SoundsThe sound module can be used to play your own sounds - for instance, to provide feedback inControlDesk when a certain condition occurs, e.g., when a simulation variable exceeds itsboundaries. Sounds can be added by modifying the distributed SoundFont file carsound.sf2.For sound output, the sound generator has a Python-based MIDI controller core component. Thiscontroller is the main interface to the sound hardware. Both configuration and output are via thePython MIDI controller module.So the integration of sounds can be divided into two steps:1. Modification of the soundfont file2. Modification of the experimentThese steps are described in detail in the following subchapters.4.1 Adding New Samples to the SoundfontBasically, there are two ways of adding new sound samples, depending on the sound output youwant to realize.1. If you want to add sounds that fade away once triggered, this can be done relativelyeasily by adding the samples to the existing soundfont. This procedure will bedescribed in this document.2. If playback of a looped engine sound is your task, keep in mind that the creation ofloopable soundfonts can be a rather time-consuming process. It also requiresthorough experience in creating soundfonts, and last but not least, a good musicalear.- 8 -

CDeskSoundGeneration.doc 26. February 2003For general information about creating soundfonts, check the site http://www.hammersound.net/.This contains some downloadable tutorials dealing with the creation of soundfonts and the usageof the Vienna SoundFont Studio. A good starting point is the tutorial “The Art of SoundFont: AStep-by-Step Guide” by Jess Skov-Nielsen.How to add sound signalsTo add new samples, start the Vienna SoundFont Studio and load the carsound.sf2 file. Importyour sample files (must be in .wav format) to the User Sample Pool.An instrument named UserInstrument for user additions is set up for convenience.In the Instrument Pool, right-click the UserInstrument node and select the New Zone…command (see Figure 7).Figure 7: Adding a key zone within an instrumentSelect your desired sample from the dialog that opens. Now the key range of the sample has tobe specified. A sound signal is a trigger-fade-off sound and can be assigned to one note key onlyso that every key in the instrument has a different sound assigned to it. Specify the one-key rangeby dragging the left border (black arrow) to the leftmost unused note key and the right border(white arrow) to the same key (see Figure 8).Figure 8: Defining a one-key zone- 9 -

CDeskSoundGeneration.doc 26. February 2003Then transpose the root note of your sample (red arrow) to the leftmost unused note key (seeFigure 9). Finally save the soundfont.Figure 9: Defining the root key of a sampleTo ensure that the new soundfont will be loaded next time you start the sound module, manuallyclear the memory of your sound card using the sound card software (see chapter 3.2). Ensure thatthe new file is copied to the experiment folder that you want to play the new sounds. Otherwise,your computer will not be able to recognize changes within the soundfont and will not reload themodified file, with the result that your new samples will not be played.4.2 The MIDI Controller APIThe sound module has a core controller component that is implemented as a Python class locatedin the MidiController.py file . It is available for common access in the common.py module. Ifyou want to pass function calls to the MIDI controller, import the common module and accessthe midiController variable. To play a car horn, for instance, use:import commoncommon.midiController.SoundHorn()The following list shows a selection of functions of the MIDI controller.FunctionDescriptionPlayUserSound( int )Plays the specified note with the userinstrument. The parameter has to be aninteger.SoundCloseWindow()Plays the sound of a window lifter closing awindow.SoundEngineOutsideEnable(int) Function to enable/disable the engine sound.Call it with argument value 1 to enable theengine, 0 to disable.SoundEngineOutsideUpdatePitch(int) Function to update the engine soundfrequency. Call it with rpm value as theargument to update the engine sound- 10 -

CDeskSoundGeneration.doc 26. February 2003SoundOpenWindow()SoundHorn()UpdateAirStream(int)UpdateSlippageLeft(int)UpdateSlippageRight(int)frequency.Plays the sound of a window lifter opening awindow.Plays a car horn sound.Updates the volume of the air stream sound.Invoke this method with the car velocity inkilometers per hour [km/h].Plays a tire squeaking sound. Pass theslippage value of both of the left side tires.The slippage has to be passed as apercentage value. Percentage of tire velocityminus car velocity (vcar – vtire)/vcarPlays a tire squeaking sound. Pass theslippage value of both of the right side tires.The slippage has to be passed as apercentage value. Percentage of tire velocityminus car velocity (vcar – vtire)/vcar4.3 ExampleSuppose you want to add an alarm sound signal to your experiment if a certain condition isfulfilled.First the output sound has to be recorded. Afterwards, add the sample to the UserInstrument asdescribed in chapter 4.1. Notice the root key number of the sample. This is the value that youhave to pass to the MIDI Controller to play the sample. In our example, let us assume this valueto be 1 (see Figure 9). The Python code fragment to play this sound would look like this:…import commonif (condition):# play the key number 1 of the UserInstrumentcommon.midiController.PlayUserSound(1)- 11 -