gstreamer/gst/synaesthesia/README-syna

SYNAESTHESIA v2.0

Introduction
============

This is a program for representing sounds visually from a CD or line
input or piped from another program. It goes beyond the usual oscilliscope
style program by combining an FFT and stereo positioning information to
give a two dimensional display. Some of the shapes I have observed are:
  * Drums: clouds of color, fairly high
  * Clean guitar: several horizontal lines, low down
  * Rough guitar: a cloud, low down
  * Trumpet: Lots of horizontal lines everywhere
  * Flute: A single horizontal line, low down
  * Voice: A vertical line with some internal structure
  * Synthesizer: All kinds of weird shapes!

Synaesthesia can run in a window in X or full screen using SVGAlib.

The display represents frequency as vertical position on screen, 
left-right position as left-right position on screen. It can also
understand surround sound encoded music, and shows ambient noise 
in orange.

X-Windows support was added in version 1.3, as well as a major redesign
of the interface. You can use Synaesthesia as a fully functional
CD player, suitable for use while working.

There is command line support for play lists and piping from another
program (such as an mp3 player).

Usage
=====

Synaesthesia should work on Linux and BSD systems. (Note: I don't
have access to a BSD system myself, I have to rely on patches -- if it
doesn't work, please tell me!) LinuxPPC users may have to use the pipe
mode rather than taking sound input from the CD player, as I believe
sound recording is not yet implemented.

Compile Synaesthesia by typing

  make
  
then install it by typing

  make install

This will create three versions of Synaesthesia:

  synaesthesia    - full screen SVGAlib version (Linux only)
  xsynaesthesia   - Version that runs as a window in X
  sdlsynaesthesia - Version that uses the SDL graphics library

If you want to use the SDL version, you need to get SDL from
http://www.devolution.com/~slouken/SDL.

You will need to run Synaesthesia as root to run it full screen
with SVGAlib. Other varieties can be run by any user providing you 
provide permissions on /dev/dsp, /dev/cdrom, and /dev/mixer.

Synaesthesia creates a configuration file, named ~/.synaesthesia,
to store settings such as brightness, color, and window size, as
well as which devices to use to control sound input.

BSD users will have to edit this file to set the CD-ROM device name
before using Synaesthesia in order to control the CD.

Run Synaesthesia with no parameters for further information on how to 
use it.

Notes for code rippers
======================

This program contains code that you may wish to use in your own projects.
If you want to, please do. (For example, you might want to add some
snazzy visual effects to your favourite MP3 or CD player)

The actual code to do the mapping from sound to visual display is
all in core.cpp, it should be fairly easy to disentangle from other
parts of the program. It does make reference to some globals defined
in syna.h, namely the #defines m (log2 of the sample size for each
frame) and brightness, data (which stores the sound input), outputBmp,
lastOutputBmp and lastLastOutputBmp (which hold the output), outWidth
and outHeight (size of the bitmaps), and fadeMode, brightnessTwiddler,
starSize and pointsAreDiamonds (various parameters affecting the display).

The normal way to use it would be:

  Call coreInit() to set up some look-up tables
  Call setStarSize(starSize) to set up some more look-up tables
  Loop
    Put data into the data array
    Call fade() to apply the fade/wave/heat effect to the output
    Call coreGo() to add the next fragment of sound input to the output
    Display contents of outputBmp to screen

There is a simple anti-aliased polygon drawing engine in the file
polygon.h. sound.cpp contains code for driving the CD. xlib.c and
xlibwrap.cpp contain code for setting up a window under X (originally
ripped from the Xaos fractal viewer program :-) ).

Authors
=======

This program is free. If you like it, or have any suggestions, please
send me (Paul Harrison) an email (pfh@yoyo.cc.monash.edu.au).

Thanks to Asger Alstrup Nielsen for many great suggestions, and for 
writing optimized 32 bit loops for fading and drawing to screen.

Thanks to Roger Knobbe for porting Synaesthesia to FreeBSD. 

Thanks to Ben Gertzfield and Martin Mitchell for some small fixes to the
CD controlling code. 

Thanks to Simon Budig for an improvement to the X code.

Changes
=======

1.1 - Added surround sound decoding.
1.2 - Fixed a bug in the ioctl calls to /dev/dsp.
1.3 - Asger Alstrup Nielsen's optimizations added.
      Added X-Windows support.
      More options, redesigned interface.
1.4 - Bug fixes, including a great reduction in
      "Sound: Recording overrun" warnings.
      New command line options: play lists and piping.
      Support for SDL.
2.0 - Bug fixes: Fixed problem in xlib.c that caused occasional segfaults,
        several endianness problems fixed.
      New effects: Wave, heat, diamond shaped points.
      Piping sound now longer requires the twiddle factor.
      Yet another interface redesign.
      Partial support for LinuxPPC (pipe mode only)