README

   1 SYNAESTHESIA v2.4                  http://logarithmic.net/pfh/Synaesthesia
   2
   3 Introduction
   4 ============
   5
   6 Synaesthesia is a program for representing sounds visually.  It goes
   7 beyond the usual oscilliscope style program by combining an FFT and
   8 stereo positioning information to give a two dimensional display. Some
   9 of the shapes I have observed are:
  10   * Drums: clouds of color, fairly high
  11   * Clean guitar: several horizontal lines, low down
  12   * Rough guitar: a cloud, low down
  13   * Trumpet: Lots of horizontal lines everywhere
  14   * Flute: A single horizontal line, low down
  15   * Voice: A vertical line with some internal structure
  16   * Synthesizer: All kinds of weird shapes!
  17
  18 Synaesthesia represents frequency as the vertical position on screen,
  19 and stereo position as the horizontal position. It can also understand
  20 surround sound encoded music, and shows ambient noise in a different
  21 color.
  22
  23 Synaesthesia can run in a window in X, or full screen using SVGAlib,
  24 or either using Simple DirectMedia Layer (SDL). Use of the SDL is
  25 recommended.
  26
  27 It can take input from a CD, line input, EsounD, or piped from another
  28 program. As of version 2.2, EsounD support is much improved. For example,
  29 Synaesthesia works well with XMMS if both use EsounD.
  30
  31
  32 Usage
  33 =====
  34
  35 Synaesthesia should work on Linux and BSD systems. (Note: I don't have
  36 access to a BSD system myself, I have to rely on patches -- if it doesn't
  37 work, please tell me!)
  38
  39 For best results, first make sure you have installed the libraries and
  40 the header files for these: (on most systems, this means installing the
  41 appropriate "dev" packages)
  42
  43   * Simple DirectMedia Layer (SDL)
  44   * EsounD (ESD)
  45
  46 Compile Synaesthesia by typing
  47
  48   ./configure
  49   make
  50
  51 then install it by typing
  52
  53   make install
  54
  55 then you should be able to type
  56
  57   synaesthesia
  58
  59 to run the program.
  60
  61 You will need to run Synaesthesia as root to run it full screen
  62 with SVGAlib. Other varieties can be run by any user providing you
  63 provide permissions on /dev/dsp, /dev/cdrom, and /dev/mixer.
  64
  65 Synaesthesia creates a configuration file named ~/.synaesthesia
  66 to store settings such as brightness, color, and window size, as
  67 well as which devices to use to control sound input.
  68
  69 BSD users will have to edit this file to set the CD-ROM device name
  70 before using Synaesthesia in order to control the CD.
  71
  72 Run Synaesthesia with no parameters for further information on how to
  73 use it.
  74
  75
  76 Notes for code rippers
  77 ======================
  78
  79 This program contains code that you may wish to use in your own projects.
  80 If you want to, please do. (For example, you might want to add some
  81 snazzy visual effects to your favourite MP3 or CD player)
  82
  83 The actual code to do the mapping from sound to visual display is
  84 all in core.cc, it should be fairly easy to disentangle from other
  85 parts of the program. It does make reference to some globals defined
  86 in syna.h, namely the #defines LogSize (log2 of the sample size for each
  87 frame) and Brightness, data (which stores the sound input), outputBmp,
  88 lastOutputBmp and lastLastOutputBmp (which hold the output), outWidth
  89 and outHeight (size of the bitmaps), and fadeMode, brightnessTwiddler,
  90 starSize and pointsAreDiamonds (various parameters affecting the display).
  91
  92 The normal way to use it would be:
  93
  94   Call coreInit() to set up some look-up tables
  95   Call setStarSize(starSize) to set up some more look-up tables
  96   Loop
  97     Put data into the data array
  98     Call fade() to apply the fade/wave/heat effect to the output
  99     Call coreGo() to add the next fragment of sound input to the output
 100     Display contents of outputBmp to screen
 101
 102 There is a simple anti-aliased polygon drawing engine in the file
 103 polygon.h. sound.cc contains code for driving the CD. xlib.c and
 104 xlibwrap.cc contain code for setting up a window under X (originally
 105 ripped from the Xaos fractal viewer program :-) ).
 106
 107
 108 Authors
 109 =======
 110
 111 Feel free to email me me (Paul Harrison) at pfh@logarithmic.net with any
 112 suggestions, bug-reports, or better yet, patches.
 113
 114 A number of other people have contributed to Synaesthesia:
 115
 116   Thanks to Asger Alstrup Nielsen for many great suggestions, and for
 117   writing optimized 32 bit loops for fading and drawing to screen.
 118
 119   Thanks to Roger Knobbe for porting Synaesthesia to FreeBSD.
 120
 121   Thanks to Ben Gertzfield and Martin Mitchell for some small fixes to the
 122   CD controlling code.
 123
 124   Thanks to Simon Budig for an improvement to the X code.
 125
 126   Thanks to Devin Carraway for fixing Synaesthesia to work with non-32-bit
 127   word machines.
 128
 129 Synaesthesia is distributed under the GPL.
 130
 131 Changes
 132 =======
 133
 134 1.1 - Added surround sound decoding.
 135 1.2 - Fixed a bug in the ioctl calls to /dev/dsp.
 136 1.3 - Asger Alstrup Nielsen's optimizations added.
 137       Added X-Windows support.
 138       More options, redesigned interface.
 139 1.4 - Bug fixes, including a great reduction in
 140       "Sound: Recording overrun" warnings.
 141       New command line options: play lists and piping.
 142       Support for SDL.
 143 2.0 - Bug fixes: Fixed problem in xlib.c that caused occasional segfaults,
 144         several endianness problems fixed.
 145       New effects: Wave, heat, diamond shaped points.
 146       Piping sound now longer requires the twiddle factor.
 147       Yet another interface redesign.
 148       Partial support for LinuxPPC (pipe mode only)
 149 2.1 - Autoconf support.
 150       Esd support.
 151       Some code cleanup, now only makes one binary.
 152       SDL version now sets title.
 153       Bug fixes: Old versions of gcc can't cope with some of the stuff
 154       I was doing with templates.
 155 2.2 - Works on machines with non-32-bit words (patch by Devin Carraway)
 156       Pipe and ESD modes greatly improved: it now syncs properly to the music
 157         with ESD
 158       Resizable window with SDL
 159       Fixes to autoconf of SDL
 160       Clicking on window toggles full screen in SDL
 161       Automatic brightness compensation
 162 2.3 - Compiles with g++ 3.4
 163       Tweaked sound code, should now work on fast computers
 164 2.4 - Applied a patch by Aurelien Jarno that fixes some FreeBSD problems
 165