gst/synaesthesia/README

   1 This is a visualization based on on synaesthesia. (see the synaesthesia
   2 README below)
   3
   4 This implementation is taken from alsaplayer: http://www.alsaplayer.org/ It
   5 is based on synaesthesia version 1.3 (or maybe 1.4, I'm not entirely
   6 certain), with some modifications by Richard Boulton to try and ensure that
   7 something interesting is displayed for both very quiet and very loud music.
   8
   9 Note: only one instance of this plugin may be created at a time: it has a
  10 lot of static data.  This should be fixed (and it shouldn't be hard to do
  11 so, either).
  12
  13 ----------------------------------------------------------------------------
  14
  15 SYNAESTHESIA v2.0
  16
  17 Introduction
  18 ============
  19
  20 This is a program for representing sounds visually from a CD or line
  21 input or piped from another program. It goes beyond the usual oscilliscope
  22 style program by combining an FFT and stereo positioning information to
  23 give a two dimensional display. Some of the shapes I have observed are:
  24   * Drums: clouds of color, fairly high
  25   * Clean guitar: several horizontal lines, low down
  26   * Rough guitar: a cloud, low down
  27   * Trumpet: Lots of horizontal lines everywhere
  28   * Flute: A single horizontal line, low down
  29   * Voice: A vertical line with some internal structure
  30   * Synthesizer: All kinds of weird shapes!
  31
  32 Synaesthesia can run in a window in X or full screen using SVGAlib.
  33
  34 The display represents frequency as vertical position on screen,
  35 left-right position as left-right position on screen. It can also
  36 understand surround sound encoded music, and shows ambient noise
  37 in orange.
  38
  39 X-Windows support was added in version 1.3, as well as a major redesign
  40 of the interface. You can use Synaesthesia as a fully functional
  41 CD player, suitable for use while working.
  42
  43 There is command line support for play lists and piping from another
  44 program (such as an mp3 player).
  45
  46 Usage
  47 =====
  48
  49 Synaesthesia should work on Linux and BSD systems. (Note: I don't
  50 have access to a BSD system myself, I have to rely on patches -- if it
  51 doesn't work, please tell me!) LinuxPPC users may have to use the pipe
  52 mode rather than taking sound input from the CD player, as I believe
  53 sound recording is not yet implemented.
  54
  55 Compile Synaesthesia by typing
  56
  57   make
  58
  59 then install it by typing
  60
  61   make install
  62
  63 This will create three versions of Synaesthesia:
  64
  65   synaesthesia    - full screen SVGAlib version (Linux only)
  66   xsynaesthesia   - Version that runs as a window in X
  67   sdlsynaesthesia - Version that uses the SDL graphics library
  68
  69 If you want to use the SDL version, you need to get SDL from
  70 http://www.devolution.com/~slouken/SDL.
  71
  72 You will need to run Synaesthesia as root to run it full screen
  73 with SVGAlib. Other varieties can be run by any user providing you
  74 provide permissions on /dev/dsp, /dev/cdrom, and /dev/mixer.
  75
  76 Synaesthesia creates a configuration file, named ~/.synaesthesia,
  77 to store settings such as brightness, color, and window size, as
  78 well as which devices to use to control sound input.
  79
  80 BSD users will have to edit this file to set the CD-ROM device name
  81 before using Synaesthesia in order to control the CD.
  82
  83 Run Synaesthesia with no parameters for further information on how to
  84 use it.
  85
  86 Notes for code rippers
  87 ======================
  88
  89 This program contains code that you may wish to use in your own projects.
  90 If you want to, please do. (For example, you might want to add some
  91 snazzy visual effects to your favourite MP3 or CD player)
  92
  93 The actual code to do the mapping from sound to visual display is
  94 all in core.cpp, it should be fairly easy to disentangle from other
  95 parts of the program. It does make reference to some globals defined
  96 in syna.h, namely the #defines m (log2 of the sample size for each
  97 frame) and brightness, data (which stores the sound input), outputBmp,
  98 lastOutputBmp and lastLastOutputBmp (which hold the output), outWidth
  99 and outHeight (size of the bitmaps), and fadeMode, brightnessTwiddler,
 100 starSize and pointsAreDiamonds (various parameters affecting the display).
 101
 102 The normal way to use it would be:
 103
 104   Call coreInit() to set up some look-up tables
 105   Call setStarSize(starSize) to set up some more look-up tables
 106   Loop
 107     Put data into the data array
 108     Call fade() to apply the fade/wave/heat effect to the output
 109     Call coreGo() to add the next fragment of sound input to the output
 110     Display contents of outputBmp to screen
 111
 112 There is a simple anti-aliased polygon drawing engine in the file
 113 polygon.h. sound.cpp contains code for driving the CD. xlib.c and
 114 xlibwrap.cpp contain code for setting up a window under X (originally
 115 ripped from the Xaos fractal viewer program :-) ).
 116
 117 Authors
 118 =======
 119
 120 This program is free. If you like it, or have any suggestions, please
 121 send me (Paul Harrison) an email (pfh@yoyo.cc.monash.edu.au).
 122
 123 Thanks to Asger Alstrup Nielsen for many great suggestions, and for
 124 writing optimized 32 bit loops for fading and drawing to screen.
 125
 126 Thanks to Roger Knobbe for porting Synaesthesia to FreeBSD.
 127
 128 Thanks to Ben Gertzfield and Martin Mitchell for some small fixes to the
 129 CD controlling code.
 130
 131 Thanks to Simon Budig for an improvement to the X code.
 132
 133 Changes
 134 =======
 135
 136 1.1 - Added surround sound decoding.
 137 1.2 - Fixed a bug in the ioctl calls to /dev/dsp.
 138 1.3 - Asger Alstrup Nielsen's optimizations added.
 139       Added X-Windows support.
 140       More options, redesigned interface.
 141 1.4 - Bug fixes, including a great reduction in
 142       "Sound: Recording overrun" warnings.
 143       New command line options: play lists and piping.
 144       Support for SDL.
 145 2.0 - Bug fixes: Fixed problem in xlib.c that caused occasional segfaults,
 146         several endianness problems fixed.
 147       New effects: Wave, heat, diamond shaped points.
 148       Piping sound now longer requires the twiddle factor.
 149       Yet another interface redesign.
 150       Partial support for LinuxPPC (pipe mode only)
 151