Skip to content


Repository files navigation

Swami - README

Copyright (C) 1999-2021 Element Green and others

Build Status

Note that this readme might be outdated

1. What is Swami?

Swami (Sampled Waveforms And Musical Instruments) is a SoundFont editor. SoundFont files are a collection of audio samples and other data that describe instruments for the purpose of composing music. SoundFont files do not describe the music itself, but rather the sounds of the instruments. These instruments can be composed of any digitally recordable or generated sound. This format provides a portable and flexible sound synthesis environment that can be supported in hardware or software.

2. What happend to the Smurf SoundFont Editor?

Nothing actually. Since I was already doing an entire re-code of Smurf I decided it would be good to change the name to give the program a fresh start and because I'm planning to make it more than just a SoundFont editor. Also the word 'Smurf' is copyrighted so I thought a change wise in this day and age of law suits. Swami does not yet completely replace Smurf in functionality, but it will.

3. License

See Copying.

4. Changes from Smurf

Most of the changes have occured in the programming architecture. Much of this work has been done in preparation for really cool features (TM) :) The SoundFont editing code is now completely abstracted from the GUI in separate shared libraries making things like: scripting support, multiple client concurrent access to SoundFont objects and SwamiJam (networked semi-realtime composition with friends) more feasible. Most importantly things are much cleaner now so I don't go insane in attempts to add functionality.

New features:

  • FluidSynth soft synth support (actually its required) which allows any OS supported sound card to be used and gives us modulators (real time effects) and routeable digital audio output for adding additional effects and for easy recording.
  • More operations work for multiple items. Including loading/saving/closing of multiple SoundFont files, loading multiple samples, and setting/viewing properties on multiple items.
  • Modulator editor for editing real time control parameters
  • Default toggle buttons for generator (effect) controls

Things missing (as of this README):

  • Undo support
  • virtual SoundFont bank support
  • OSS AWE/SB Live! wavetable backend

5. Requirements

Look at the INSTALL file for instructions on compiling and installing Swami and for more details on software requirements.

Version numbers listed are what I developed Swami on, older or newer versions of the listed software may or may not work, but give it a try! And do let me know if you encounter any problems.

Swami has the following requirements:

  • Linux, Windows and Mac OS X. Probably anywhere else GTK+ will run.
  • GTK+ v2.0
  • FluidSynth v2.0 (software wavetable synthesizer)
  • libsndfile

GTK homepage: FluidSynth homepage: libsndfile homepage: ALSA homepage: OSS homepage:

6. Supported sound cards

Any FluidSynth supported sound card (i.e. works under ALSA or OSS in Linux), since Swami uses FluidSynth which does all synthesis in software. A wavetable backend is planned for using hardware based SoundFont synthesizers like the SB AWE/Live! for those who don't want to use their precious CPU cycles :)

7. Features

Current features include:

  • Loading of multiple SoundFont 2.x files *.SF2
  • Saving of multiple SoundFont files
  • Copy Samples/Instruments/Presets between and within SoundFont objects
  • Load and export multiple audio sample files (WAV, AU, etc)
  • View/set multiple Preset, Instrument and Sample parameters
  • A GTK piano widget to play notes with computer keyboard/mouse
  • Wavetable loading of entire SoundFont
  • Piano MIDI controls (Pitch bender amount, volume etc.)

Features provided by FluidSynth:

  • Flexible driver system that supports OSS, ALSA, LADSPA, Jack, Midishare, etc
  • Real time effects via modulators and C API

8. Future plans

The following are in the works or planned:

  • Undo support (just haven't written a front end for it really)
  • Copy/Paste generator parameters
  • Graphical manipulation of generator parameters

Was part of Smurf, not yet added:

  • Loading, saving and editing of virtual bank (*.bnk) files
  • Multiple undo/redo tree system, allowing for multiple redo "branches"
  • Sample cut support
  • Sample waveform generation
  • International language support (currently disabled until there are some updated translations, contact me if interested)

9. Troubleshooting drivers (or why does Swami crash on startup?)

[Some of these switches haven't been enabled yet!]

Some new command line switches were added to help with trouble shooting problems with Swami. Crashes experienced on startup of Swami are often caused by audio drivers. Type "swami --help" to get a list of usable switches. Since Swami, by default, tries to open the drivers on start up, a way to disable this behavior was added. "swami -d" will cause Swami to start, but drivers will not automatically be opened. Once started you can change your driver preferences (set certain ones to NONE) to try to determine which driver is crashing. Then issue a Control->"Restart Drivers" to cause the drivers to be re-opened.

Swami v0.9.0pre1 Copyright 1999-2002 Josh Green Distributed under the GNU General Public License Usage: swami [options] Options: -h, --help Display this information -d Disable drivers (try if Swami crashes on start up) -c Ignore preferences and use factory defaults

10. Using Virtual Keyboard interface

[Most of this is true, although some things haven't been implemented yet]

The wavetable and piano interface have been changed in Smurf v0.52. Some of the new features include:

  • MIDI channel control (on toolbar, titled "Chan") Sets what MIDI channel the piano plays on. All other MIDI controls (bank, preset and MIDI controls on pop up menu) are remembered for each channel.

  • MIDI bank and preset controls (also on toolbar) Sets the current bank and preset for the selected MIDI channel. These are often changed automatically by the user interface when selecting items in the SoundFont tree, they can be changed manually as well.

  • Entire SoundFont loading Allows you to load an entire SoundFont. This is particularly useful to make a SoundFont available for sequencing with other programs.

  • Controls for changing how interface works with wavetable

    • Piano follows selection

      When enabled: virtual keyboard will "follow" the SoundFont tree selection. This will cause the selected item to be the one heard on the piano. If selected item is a Preset in a loaded SoundFont, then the piano will select the Bank:Preset of that item. Otherwise it is set to the Temporary Audible Bank:Preset (configurable from preferences, defaults to 127:127). By disabling this feature you can have more control over what is being played by the virtual keyboard.

    • Auto load temp audible

      When enabled: selected items in the SoundFont tree that aren't Presets in a loaded SoundFont, are automatically loaded into the wavetable device. They are mapped to a temporary Bank:Preset which is configurable from Preferences. Disabling this allows for faster editing, if one does not care to hear items.

  • Temporary audible - The temporary audible enables you to listen to components of a SoundFont that aren't directly mapped to a MIDI Bank:Preset. This is done by designating a Bank:Preset for temporary use. It defaults to 127:127 but can be changed in Preferences. When a non-Preset or a Preset that isn't in a loaded SoundFont is loaded (either from the "Auto load temp audible" option or manually from the "Wavetable Load" item on the right click menus), it is mapped to this temporary bank and preset number.

11. Creating Preset/Instrument zones

To add zones to an Instrument hold down the CTRL key and select the samples you want to be added (SHIFT works too for selecting a range of items). Then "Right Click" the Instrument you want to add the samples to. Select "Paste" from the pop up menu. A zone will be created for each Sample (or Instrument zone) you selected. This same procedure can be applied to Presets using Instruments as zones. To create a "Global Zone", "Right Click" on the Preset or Instrument you want to create the zone under. Select "Global Zone" from the pop up menu. Global Zones are used to set "Default" generator (and modulator) parameters that the other zones don't already have set.

12. Using the sample viewer

The sample viewer is used to change loop points for samples and instrument zones.

Some things have changed in the sample viewer and probably will be changing again. The sample zoom/unzoom is now performed with the SHIFT key held down. Regular left mouse clicks are now used for sample selections for audio editing functions (currently only "cut").

Tips to using the sample viewer:

Zooming IN/OUT Hold down SHIFT on the computer keyboard and click and hold the LEFT mouse button in the sample window, a white line will appear to mark your click, move the mouse to the left or the right to zoom into the sample. The distance you move the mouse from the original point of your click determines the speed in which the view zooms. If you then move the mouse to the other side of the line the view will unzoom. The RIGHT mouse button does the same thing, except the first direction you move the mouse unzooms the view.

Selecting audio data Left click and drag to mark an area. An existing selection can be changed by holding down CTRL and Left or Right clicking to change the left or right ends of the selection respectively.

13. Undo system

Not enabled yet!

Swami has a rather flexible undo system. Many actions aren't currently undo-able, but will be implimented soon. Currently all actions relating to new SoundFont items, pasted SoundFont items, and deleted items are undo-able. The undo system is based on a tree rather than queue or list. This means that multiple changes can be easily tested.

A traditional undo system is oriented as a list. Here is an example to help understand the Swami undo tree system compared with the traditional one.

  1. You change some parameters related to the Modulation Envelope of an instrument
  2. You don't quite like the changes, so you undo them
  3. You try some other values for the same Modulation Envelope

Lets say now you want to try the parameters in Step 1 again to compare to the settings in Step 3. In a traditional undo system you would not be able to do this because Step 3 would cause the "redo" information from Step 2 to be lost. Using a tree, multiple branches of "state" information can be stored. So rather than Step 3 "over writing" the redo info from Step 2, it would simply create another "branch" in the tree.

Note: This was just an example of usage, but Swami doesn't support undo-ing of parameter changes yet.

When just using the Undo/Redo menu items the undo system acts as a traditional list oriented undo system. The "Undo History" item on the Edit menu will bring up a dialog that lists previous actions. The dialog buttons available are Undo, Redo, Jump, Back, Forward, < (left arrow), > (right arrow). The current location in the state history is indicated by 2 greater than symbols ">>" in the left most column.

Undo and Redo act just like the menu items, undo-ing (moving up the undo history) and redo-ing (moving down the undo history) the next/previous action from the current location. The "Jump" button will jump to the desired position in the undo history, causing actions to be undone/redone as necessary to realize the desired state. The Back and Forward buttons act like the traditional web browser function. Currently the last 10 positions in the undo history are remembered. This makes testing different settings easier. This isn't really useful yet as the currently undo-able actions aren't really ones you would wan't to test different settings with. But in the future when generator parameters are tracked in the undo history, this will be useful. The < (left arrow) and > (right arrow) are the second and third column headers of the history list. These columns are used to indicate other branches in the tree. Items that have other "sibling" branches will have a number in brackets (example: [ 1]) listed in the < (left arrow) and/or > (right arrow) column(s). The left arrow switches to older branches the right arrow to newer ones. Numbers in these columns indicate how many alternate older or newer branches (left arrow or right arrow respectively) are available.

To switch to an alternate branch, select an item that has a number in one of the arrow columns. Click the corresponding arrow button at the top of the list. The selected item and all items below will be changed to reflect the new branch.

14. Virtual Banks

Not implemented yet in Swami!

Virtual banks allow you to make a SoundFont bank from many other SoundFont files. Swami currently supports loading and saving of the AWE .bnk format. This is a simple text file format listing each Preset and where it can be found SoundFont file:Bank:Preset and its destination Bank:Preset.

NOTE: Make sure you set the "Virtual SoundFont bank search paths" field in Preferences. It should be a colon seperated list of where to find your SoundFont files. Example: "/home/josh/sbks/:/tmp/sbks". Adding a '/' to the end of a path will cause that directory to be recursively scanned (all sub directories under it).

Current limitations (will be fixed in future)

SoundFont files will not automatically be loaded with a virtual bank, so you'll have to load them by hand. Default SoundFont bank can't be cleared Can't edit virtual bank mappings

Adding a Preset to a virtual bank

Simply select and paste Preset items into the Mapping section of the virtual bank.

Setting default SoundFont

The default SoundFont sets the default Preset instruments. The Preset mappings override the default Presets. To change the default SoundFont simply paste a SoundFont item to the branch of the virtual bank.

15. SoundFont information, links and other resources

I wrote an "Intro to SoundFonts" and its available on the Swami homepage Its a general overview of what a SoundFont is.

More information on the SoundFont standard can be obtained from There is a PDF of the SoundFont technical specification at If you find that it has moved then look under the Resources section off of the home page (although it looks like you have to get a login to go there).

Thanks to Frank Johnson at EMU for clarifying this.

16. Thanks

Thanks to the following projects for making Swami possible:

  • FluidSynth (its what makes the instruments sound :)
  • gstreamer for gobject2gtk code and helpful examples of using GObject
  • Glade GTK interface builder
  • Gimp for graphics editing
  • Blender for render of campfire in desert Splash image
  • xmms code which I borrowed the multi selection file dialog modifications from
  • Piano to computer keyboard mapping inspired from soundtracker

17. Trademark Acknowledgement

SoundFont is a registered trademark of E-mu Systems, Inc. Sound Blaster Live! and Sound Blaster AWE 32/64 are registered trademarks of Creative Labs Inc. All other trademarks are property of their respective holders.

18. Contact

Contact me (Element Green) particularly if you are interested in helping develop Swami. Programming, web page design, and documentation are all things that are lacking, so if you have an interest, do contact me. Also contact me if you find any bugs, have trouble compiling on a platform you think should be supported, want to tell me how much you like Swami, or have suggestions or ideas.


Swami homepage: