
         ------------
          ShengGuang
         ------------

--------------------
What is ShengGuang ?
--------------------

ShengGuang is a library used by MusicBox for audio control.
"Sheng Guang" means sound and light (video) in Chinese.
It contains classes supporting audio file and CD playback, OGG tag.
It uses bundles so that user can choose the external libraries to depend on, 
as what backend of GNUstep do.
The default (and only) bundle use SDL and SDL_sound.

-------
Install
-------

It needs these libraries:

 - libogg/libvorbis : Not only for suporting OGG in SDL_sound,
                      but also for TITLE/ARTIST/ALBUM tag of OGG file.
                      There is no reason not to support the open-source 
                      audio format.

 - smpeg            : For better mp3 support.
 
 - libflac          : For flac support.
 
 - speex            : For speex support.

 - SDL and SDL_sound : Decode audio file and control CD-ROM.
                       You may first want to install libvorbis for OGG,
                       SMPEG for MP3, etc. See details in SDL_sound.
                       SDL_sound 1.0 or higher is required.

All of these libraries should be included in all modern Linux distrobutions.

Here are the steps:

a. Install libvorbis/libogg 1.0 or higher (http://www.vorbis.com).

b. Install flac (http://flac.sourceforge.net/).

c. Install speex (http://www.speex.org/)

d. Install SDL 1.2.4 or higher (http://www.libsdl.org).

e. Install smpeg (http://www.lokigames.com/development/smpeg.php3)

f. You may want to install other libraries in order to support 
   as many audio formats as possible.
   Ex. smpeg for better mp3 support.
   See SDL_sound for more details.

g. Install SDL_sound 1.0 (http://icculus.org/SDL_sound/).
   You have to SDL_sound 1.0 or higher
   because it support sound seeking.
h. Test SDL_sound using playsound in SDL_sound.
   You can check how many audio formats you can use by executing:
   `playsound --decoders`.

i. Then `make install` should work.

----
Demo
----
There is one GWorkspace bundle as the demo of ShengGuang library.
SGContentViewer is a content viewer for SDL_sound supported files.
See SGContentViewer/README for more details.

---
FAQ
---

1. Why use SDL/SDL_sound ?

   SDL is designed for game development, but it also offers
   great control of CD-ROM, audio and video system. Combined with
   SDL_sound for audio format support, almost all the functions required 
   for MusicBox exist in a single library, which minimizes the problems
   of portability, installation, and audio format support.
   Otherwise, at least five libraries are required to reach the same
   functions of SDL/SDL_sound, and it is very troublesome to
   maintain the integration among these libraries.
   The video system may be used for visualization in the future.
   There are two SDL applications doing that already.
   SDL also offer OpenGL support, which is used in 3DKit.
   Actually, SDL might be able to be another backend of GNUstep.
   An addition SDL_TTF2 using FreeType 2 can be used for font drawing.
   There is a paraGUI toolkit using SDL for GUI development.

2. It complains "audio: /dev/dsp...: Device busy" ?

   That means the audio device is occupied by other application.
   For FreeBSD, read handbook about how to add the virtual audio device.
   Set environmnet variable SDL_PATH_DSP or AUDIODEV to the unused
   audio device. It should be able to avoid conflicting with gsnd.
   Since FreeBSD and Linux use the same OSS, it should work on Linux.

   This is what I do on my FreeBSD-4.5 box:

   1. Use `sysctl -a` to find out the audio device channel:
      hw.snd.pcm0.vchans: 0
   2. Either use `sysctl hw.snd.pcm0.vchans=4` or 
      add `hw.snd.pcm0.vchans=4` in /etc/sysctl.conf to
      increase the virtual device number into 4.
   3. Check the /dev/dsp*. There should be dsp0.0 - dsp0.3.
      Those are all the virtual audio device.
      If not, try `sh MAKEDEV snd0` in /dev. 
      More details in FreeBSD handbook.
   4. Normal application will use the /dev/dsp, which is 
      links to /dev/dsp0 and /dev/dsp0.0.
      Therefore, /dev/dsp0.1 - /dev/dsp0.3 are free.
   5. Set SDL_PATH_DSP or AUDIODEV to any of the free virtual device.
      Ex. `export SDL_PATH_DSP = /dev/dsp0.2` for bash.
   6. It should works now. Good Luck.

  (FreeBSD-5.x will automatically allocate the free channel via DeviceFS)

Author
------
Yen-Ju Chen <yjchenx@hotmail.com>

