+-------------------------------------------------------+
+	Smurf Sound Font Editor	- README		+
+	Copyright (C) 1999-2001 Josh Green		+
+	Email: jgreen@users.sourceforge.net		+
+	Smurf homepage: http://smurf.sourceforge.net	+
+-------------------------------------------------------+

*******************************************************************
* NOTE: This will be replaced by a real manual in the near future *
*******************************************************************

** New documentation for Smurf v0.52.5! **
"Troubleshooting drivers (or why does Smurf crash on startup?)"

** New documentation for Smurf v0.52! **
"Using new Wavetable and Piano interface"
"Virtual Banks"


=====================================
1. What is Smurf Sound Font Editor?
2. License
3. Requirements
4. Supported sound cards
5. Features
6. Future plans
7. Troubleshooting drivers (or why does Smurf crash on startup?)
8. Using new Wavetable and Piano interface
9. Creating Preset/Instrument zones
10. Using the sample viewer
11. Undo system
12. Virtual Banks
13. Sound font information, links and other resources
14. Thanks
15. Trademark Acknowledgement
16. Contact
=====================================

1. What is Smurf Sound Font Editor?
-------------------------------------
Smurf is a GTK based sound font editor. Sound font files are a collection of
audio samples and other data that describe instruments for the purpose of
composing music. Sound fonts 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. License
-------------------------------------
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA or point your web browser to http://www.gnu.org.


3. Requirements
-------------------------------------
Look at the INSTALL file for instructions on compiling and installing the
Smurf Sound Font Editor and for more details on software requirements.

Version numbers listed are what I developed Smurf 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.

Smurf has the following requirements:
- Linux or other *nix system that happens to work
- GTK+ v1.2
- libsndfile 0.0.5 or Audiofile 0.1.5
  (libsndfile or Audiofile 0.2.0 recommended)

Optional (required if you want to hear anything):
- AWE 32/64 or SB Live! sound card
- ALSA 0.5.11, ALSA 0.9.0beta8 or Open Sound System with
  AWE32/64 driver (comes with Linux kernel),
  ALSA is recommended (I use the latest 0.9.0beta myself)

audiofile homepage: http://www.68k.org/~michael/audiofile/
libsndfile homepage: http://www.zip.com.au/~erikd/libsndfile/
ALSA homepage: http://www.alsa-project.org
OSS homepage: http://www.4front-tech.com
GTK homepage: http://www.gtk.org


4. Supported sound cards
-------------------------------------
The AWE 32/64 and Live! are supported. The ALSA driver is recommended. It allows
multiple sequencer clients (connect MIDI sequencers to Smurf) and has several
fixes to the AWE driver that the stock AWE driver with Kernel 2.2.x doesn't
have.

My dream is of someday having direct Timidity++ support for good
software based wavetable emulation.  This may occur via ALSA patch
loading (when it is available) which would then allow Smurf to be used
with other wavetable devices (hardware or software). For now sound fonts will
have to be loaded manually with Timidity++ (rather than direct loading with
Smurf).


5. Features
-------------------------------------
Current features include:
- Loading of multiple sound font 2.x files *.SF2
- Saving of sound font files
- Loading, saving and editing of virtual bank (*.bnk) files (not complete)
- Copy Samples/Instruments/Presets between and within Sound fonts
- Multiple undo/redo tree system, allowing for multiple redo "branches"
- Load and export audio sample files (WAV, AU, etc)
- View/set Preset, Instrument and Sample parameters
- A GTK piano widget to play notes with computer keyboard/mouse
- Wavetable loading of entire sound fonts with sample caching
- Piano MIDI controls (Pitch bender amount, volume etc.)
- Flexible driver system that supports OSS and ALSA sequencers
- MIDI thru interface for external MIDI keyboard/device
- Sample cut support
- Sample waveform generation (in experimental stage)
- International language support


6. Future plans
-------------------------------------
The following are in the works or planned:
- More undo support
- Copy/Paste generator parameters
- Graphical manipulation of generator parameters
- Other wavetable device support (integration with iiwusynth)
- Other sample editing functions like pasting, normalize, etc.
- Implement SF 2.1 modulators
- Loading of sound font 1.x files via conversion utility


7. Troubleshooting drivers (or why does Smurf crash on startup?)
-------------------------------------
Some new command line switches were added to help with trouble shooting
problems with Smurf. Crashes experienced on startup of Smurf are often caused
by audio drivers.  Type "smurf --help" to get a list of usable switches.
Since Smurf, by default, tries to open the drivers on start up, a way to
disable this behavior was added. "smurf -d" will cause Smurf 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.

Smurf Sound Font Editor v0.52.5
Copyright 1999-2001 Josh Green <jgreen@users.sourceforge.net>
Distributed under the GNU General Public License
Usage: smurf [options]
Options:
-h, --help       Display this information
-d               Disable drivers (try if Smurf crashes on start up)
-c               Ignore preferences and use factory defaults


8. Using new Wavetable and Piano interface
-------------------------------------
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 sound font tree, they can be changed manually as well.
* Entire sound font loading
	Allows you to load an entire sound font. This is particularly useful
        to make a sound font available for sequencing with other programs.
* Sample caching
	Samples can now be "cached" or shared so parameter changes and other
	editing operations occur much quicker now. This currently does not work
	for sample parameter changes due to lack of support in AWE driver.
	You'll need an AWE driver that supports this feature, see NOTE below.
* Controls for changing how interface works with wavetable
	Wavetable caching
		Enable/disable sample caching. Not sure why would want to
		disable it, unless you don't have driver support.

		NOTE: Symptoms of no support for sample caching: items are
		only audible the first time they are selected, selecting
		another item and then the other again, will result in silence.

	Piano follows selection
		When enabled: virtual keyboard will "follow" the sound font
		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
		sound font, 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 sound font tree that aren't
		Presets in a loaded sound font, 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.

	Recursive bank refresh
		When enabled: all Presets in a loaded sound font will be
		updated if an Instrument in the same sound font is changed.
		In the future the same will occur for Samples, but there are
		currently some limitations in the AWE driver.

	Reset wavetable
		Clears all samples in the wavetable cache and unloads any
		loaded sound font

NOTE: You should have v0.4.4 or newer of the AWE driver in order for sample
caching to work. OSS emulation under ALSA is sufficient and the recommended
driver.

Using ALSA will also allow for multiple sequencer clients, which means that
connecting ALSA MIDI sequencer programs to Smurf is as easy as choosing the
same device.


- Loading entire sound fonts -
This can be accomplished by right clicking on a sound font and selecting
"Wavetable Load". A speaker icon will appear to the left of the sound font
tree item to indicate that it is loaded. This sound font will remain loaded
until a "Reset wavetable" action is performed, or another sound font is loaded.


- Temporary audible -
The temporary audible enables you to listen to components of a sound font 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 sound font
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.


I hope that this new interface is more flexable and at the same time not too
confusing. Let me know if you have any better ideas :)


9. 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 like the expected micro$oft way). 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.


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


11. Undo system
-------------------------------------
Smurf has a rather flexible undo system. Many actions aren't currently
undo-able, but will be implimented soon. Currently all actions
relating to new sound font items, pasted sound font 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 Smurf 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 Smurf 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.


12. Virtual Banks
-------------------------------------
Virtual banks allow you to make a sound font bank from many other sound font
files. Smurf 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
Sound Font file:Bank:Preset and its destination Bank:Preset.

** NOTE ** Make sure you set the "Virtual sound font bank search paths" field
in Preferences. It should be a colon seperated list of where to find your sound
fonts. 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) **

- Sound font files will not automatically be loaded with a virtual bank, so
  you'll have to load them by hand.
- Default sound font 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 sound font -
The default sound font sets the default Preset instruments. The Preset mappings
override the default Presets. To change the default sound font simply paste a
sound font item to the <DEFAULT> branch of the virtual bank.


13. Sound font information, links and other resources
-------------------------------------
I wrote an "Intro to Sound Fonts" and its available on the Smurf homepage
http://smurf.sourceforge.net. Its a general overview of what a SoundFont is.

More information on the SoundFont standard can be obtained from
http://www.soundfont.com, the FAQ section contains general info and
downloadable specifications. Looks like they have changed their page a bit
so you may have to do some searching around. There is a PDF Sound font
specification file somewhere.

UPDATE: I haven't been able to find this PDF file anywhere, and the license
says that it cannot be redistributed. I did find a postscript specification on
Creative Lab's FTP site, it is a somewhat older 2.0 spec (rather than the 2.1
spec) which is only missing the section on Modulators which aren't necessary in
understanding how sound fonts work.
ftp://ftp.creaf.com


14. Thanks
-------------------------------------
Thanks to the following people/projects for making Smurf possible:
- Takashi Iwai for the Linux AWE driver and awesfx utility which I borrowed
    code from (AWE driver interface and virtual bank loading)
- Glade GTK interface builder
- xmms code which I borrowed the multi selection file dialog modifications from
    although they are not active yet
- Piano to computer keyboard mapping inspired from soundtracker
- Many other GPL programs and documentation information that I found helpful or
    necessary in developing this program


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


16. Contact
-------------------------------------

Contact me (Josh Green) particularly if you are interested in helping
develop the Smurf Sound Font Editor. 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 Smurf, or have suggestions or ideas.

Email: jgreen@users.sourceforge.net
Smurf homepage: http://smurf.sourceforge.net

=====================================