sfxr-dssi
                              =========
                   The famous sound effect generator
                          as a DSSI plugin

Introduction
============
sfxr-dssi is a simple conversion of the sfxr sound effect generator
written by DrPetter (Tomas Pattersson), from a stand-alone SDL
program to a DSSI plugin.  The conversion was done as a development
milestone for libwhy.  The original sfxr-sdl-1.1.tar.gz used in this
conversion can be found at:

    https://code.google.com/p/sfxr/

More information about the DSSI software synthesis plugin API can be
found here:

    http://dssi.sourceforge.net/

More information about the libwhy Lua/GTK+ GUI application
development library is here:

    http://smbolton.com/lua.html#libwhy

sfxr-dssi is written and copyright (c) 2012 by Sean Bolton, and
licensed under the same MIT/Expat-style license as the original
sfxr-sdl 1.1 code (which was written and copyright (c) 2007 by Tomas
Pettersson).  See the bottom of this file for the license text.

If you enjoy using this plugin, or otherwise find it useful, please
send me (Sean) any of the following:

    - an email stating where you're from and how you're using
        sfxr-dssi, sent to <sean@smbolton.com>.
    - copies of or links to music, software or other art you've
        created with sfxr-dssi.
    - suggestions for improving sfxr-dssi.
    - offers of paying work writing this sort of code!

Requirements
============
To build sfxr-dssi, you need:

    - a version of Python suitable to run the included waf build
        tool; see http://code.google.com/p/waf/ for more information.

    - DSSI version 0.9 or greater, available from the
        dssi.sourceforge.net address above.

    - the LADSPA v1.x SDK.

    - the ALSA headers (DSSI plugins use ALSA structures, but not
        the actual drivers, so you don't necessarily need the
        drivers installed.)  Users of non-Linux systems can use
        libdssialsacompat, available at:

        http://smbolton.com/linux.html

    - liblo version 0.12 or later (0.23 or later recommended), a
        library implementing the Open Sound Control (OSC) protocol,
        available at:

        http://liblo.sourceforge.net/

    - GTK+ version 2.4 or later (sfxr-dssi has not been tested with
        any GTK+ 3.x version.)

    - libwhy version 20121103 or later, which is available at:

        http://smbolton.com/lua.html#libwhy

    - pkgconfig with PKG_CONFIG_PATH set appropriately to pick up
        the above packages.

Additionally, to use sfxr-dssi you will need:

    - a working DSSI host.  sfxr-dssi has been tested with
        jack-dssi-host, available in the DSSI distribution, and with
        ghostess, available at:

        http://smbolton.com/linux.html

Installation
============
On typical POSIX-ish systems, sfxr-dssi can be installed as follows:

1. Unpack the tar file.

2. Make sure PKG_CONFIG_PATH is set correctly to locate the
    pkgconfig files for DSSI, ALSA, liblo, GTK+ and libwhy.  On many
    systems, this will be:

    $ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
    $ export PKG_CONFIG_PATH

3. 'cd' into the package directory and execute './waf configure'.
    Run './waf --help' to see the available configuration options.

5. Do './waf build'.  Hopefully it should build without warnings (or
    errors.)

6. './waf install' will install the following:

    <prefix>/lib/dssi/sfxr-dssi.so
    <prefix>/lib/dssi/sfxr-dssi/about.png
    <prefix>/lib/dssi/sfxr-dssi/about_icon.png
    <prefix>/lib/dssi/sfxr-dssi/buttons.png
    <prefix>/lib/dssi/sfxr-dssi/gui.lua
    <prefix>/lib/dssi/sfxr-dssi/panel.png
    <prefix>/lib/dssi/sfxr-dssi/sfxr-dssi_gtk
    <prefix>/lib/dssi/sfxr-dssi/slider.png

Feedback on your experiences building sfxr-dssi is appreciated.

Operation
=========
To run the sfxr-dssi plugin under the jack-dssi-host provided in
the DSSI distribution, I do the following:

1. Start JACK.

2. Start jack-dssi-host, supplying the correct plugin path
    and filename (substitute <prefix> as appropriate):

    $ DSSI_PATH=<prefix>/lib/dssi sudo jack-dssi-host sfxr-dssi.so

    jack-dssi-host should start, and moments later the sfxr-dssi
    graphic user interface should appear.

3. Use aconnect or kaconnect to connect jack-dssi-host to a MIDI
   source, such as vkeybd.

4. Begin playing sounds!  If you get no response, try clicking the
    'Play' button in the sfxr-dssi GUI. This sends a note directly
    via the host to the plugin, so if you hear sound now, look for a
    problem between the example host and your MIDI source.  If you
    still don't hear sound, I'd look for a problem between the
    example host and your output device.

sfxr-dssi is a very straightforward translation of the original
sfxr-sdl 1.1 code, except that the patch and WAV file saving
functions ahve been omitted.  Like the original sfxr-sdl, sfxr-dssi
assumes a sample rate of 44100Hz -- it will work at other sample
rates, but the sounds produced will be shifted in pitch.

What follows here is the contents of the README.txt from the
original sfxr-sdl 1.1 distribution.

-----------------------------
sfxr - sound effect generator
-----------------------------
   by DrPetter, 2007-12-14
    developed for LD48#10
-----------------------------


Basic usage:

Start the application, then hit
some of the buttons on the left
side to generate random sounds
matching the button descriptions.

Press "Export .WAV" to save the
current sound as a WAV audio file.
Click the buttons below to change
WAV format in terms of bits per
sample and sample rate.

If you find a sound that is sort
of interesting but not quite what
you want, you can drag some sliders
around until it sounds better.

The Randomize button generates
something completely random.

Mutate slightly alters the current
parameters to automatically create
a variation of the sound.



Advanced usage:

Figure out what each slider does and
use them to adjust particular aspects
of the current sound...

Press the right mouse button on a slider
to reset it to a value of zero.

Press Space or Enter to play the current sound.

The Save/Load sound buttons allow saving
and loading of program parameters to work
on a sound over several sessions.

Volume setting is saved with the sound and
exported to WAV. If you increase it too much
there's a risk of clipping.

Some parameters influence the sound during
playback (particularly when using a non-zero
repeat speed), and dragging these sliders
can cause some interesting effects.
To record this you will need to use an external
recording application, for instance Audacity.
Set the recording source in that application
to "Wave", "Stereo Mix", "Mixed Output" or similar.

Using an external sound editor to capture and edit
sound can also be used to string several sounds
together for more complex results.

Parameter description:
- The top four buttons select base waveform
- First four parameters control the volume envelope
  Attack is the beginning of the sound,
  longer attack means a smoother start.
  Sustain is how long the volume is held constant
  before fading out.
  Increase Sustain Punch to cause a popping
  effect with increased (and falling) volume
  during the sustain phase.
  Decay is the fade-out time.
- Next six are for controlling the sound pitch or
  frequency.
  Start frequency is pretty obvious. Has a large
  impact on the overall sound.
  Min frequency represents a cutoff that stops all
  sound if it's passed during a downward slide.
  Slide sets the speed at which the frequency should
  be swept (up or down).
  Delta slide is the "slide of slide", or rate of change
  in the slide speed.
  Vibrato depth/speed makes for an oscillating
  frequency effect at various strengths and rates.
- Then we have two parameters for causing an abrupt
  change in pitch after a ceratin delay.
  Amount is pitch change (up or down)
  and Speed indicates time to wait before changing
  the pitch.
- Following those are two parameters specific to the
  squarewave waveform.
  The duty cycle of a square describes its shape
  in terms of how large the positive vs negative
  sections are. It can be swept up or down by
  changing the second parameter.
- Repeat speed, when not zero, causes the frequency
  and duty parameters to be reset at regular intervals
  while the envelope and filter continue unhindered.
  This can make for some interesting pulsating effects.
- Phaser offset overlays a delayed copy of the audio
  stream on top of itself, resulting in a kind of tight
  reverb or sci-fi effect.
  This parameter can also be swept like many others.
- Finally, the bottom five sliders control two filters
  which are applied after all other effects.
  The first one is a resonant lowpass filter which has
  a sweepable cutoff frequency.
  The other is a highpass filter which can be used to
  remove undesired low frequency hum in "light" sounds.


----------------------


License
-------

Basically, I don't care what you do with it, anything goes.

To please all the troublesome folks who request a formal license,
I attach the "MIT license" as follows:

--

Copyright (c) 2007 Tomas Pettersson

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.



----------------------

http://www.drpetter.se

  drpetter@gmail.com

----------------------