About / What is LineSpec
------------------------

  LineSpec is a library to simplify the process of getting spectrum data from
  the (default) recording device; LineSpec comes with 3 versions:

  1) Standard version processes (updates) internal spectrum data whenever
     GetSpectrum is called (assuming you call GetSpectrum regulary).

  2) Multithread version uses a seperate thread to keep spectrum data up to date
     (Use this version if GetSpectrum is not called within short time intervals,
     but spectrum data has to be up-to-date).

  3) Virtual version simply generates random values. This may come handy for
     development (e.g. with Visual Basic / Windows 9x the system). You should
     not use this version to tweak spectrum values!

The latest official version(s) can be found at http://www.ctuser.net. For
suggestions, questions, requests or bug reports, send eMail to info@ctuser.net.

Requirements
------------

  Not yet tested that much yet, but any PC capable of recording sound should do.

Copying / License / ...
-----------------------

  LineSpec and Demo applications are free software; you can redistribute them
  and/or modify them under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  Place, Suite 330, Boston, MA  02111-1307  USA

  If you have any questions, suggestions or bug reports about this product,
  contact me: info@ctuser.net; Please do not contact me about general B.A.S.I.C.
  language or A.P.I. issues.

  Files (depending on which package you downloaded, not all files may be included)
   - License.txt                  GNU General Public License
   - linespec.dll                 LineSpec library (Standard version)
   - linespec (multithread).dll   Multithread version of the LineSpec library
   - linespec (virtual).dll       Virtual version of the LineSpec library
   - LineSpec.txt                 Documentation etc.
   - Source.zip                   Source code (PureBasic) and related files;
   - LSDemo*.*                    Demo applications, source code and related
                                  files;

  Wavedata to spectrum data conversation is based on a free Visual Basic 6
  example by Ulli "Mühlenweg" <umgedv@yahoo.com>, which can be found at
  http://www.planetsourcecode.com/vb/scripts/ShowCode.asp?txtCodeId=65007&lngWId=1
  
Background
----------

  It initially started with a non-public QuickPlayer version which rendered a
  simple spectrum on about 1/5 screen height, which was ocassionally shown with
  a beamer during the "Summernight Party" 2004 in Exing (Germany) by
  Partyservice Falk (http://www.partyservica-falk.de).

  Some time later I excluded the rendering stuff to a seperate executable,
  using fmodex for recording and slightly delayed virtual playback to get the
  spectrum.

  In 2007, I helped including "sound support" for "Lights player", a Jukebox for
  external LED boards (http://www.freewebs.com/artdecojukebox), which resulted
  the LineSpec library (3.x). Due the sync problem (to keep the playback
  slightly behind recording), and invalid spectrum data after some time, I
  continued working on a example using waveIn api to "record" and displayed a
  spectrum.
  So using native waveIn APIs, there was still invalid spectrum data after some
  time; to fix this, recording totally reinitializes after each processed
  spectrum.

  Designed as standalone library, it is officially published in fall 2007,with
  version 3.10 (build 2007.09.30)

  LineSpec is open source since spring/summer? 2008, with version 3.10 (build
  2008.04.16)

API
---

  bool Startup(); // If the function succeeds, the return value is not NULL

  void Shutdown();

  void GetSpectrum(
    UINT ptrFloatArray, // pointer to an array of floats for the spectrum
    UINT ArraySize,     // Number of floats (per channel!)
    UINT Channels,      // Channels to grab: 1=left, 2=right (-> 3=stereo)
    UINT Flags.l,       // 1 = get actual spectrum; 2 = average values
    UINT ptrBoost       // pointer to a float with the boost value (required!)
    );

Usage
-----

  To use LineSpec, call Startup(). If the functions succeeds (not NULL), you can
  use GetSpectrum; When finished, call Shutdown().
  
  more documentation / remarks etc. coming soon...

Demo applications
-----------------

  The demos don't need the dll because it's compiled into (included) the binary.

  Try running the demos while latest QuickPlayer (beta 60+) is running, or
  Winamp with gen_GetTitle (or gen_ShowTitle) plugin.

  Demos will automatically use a non-primary monitor, or even the full desktop
  (e.g. the Starcraft Ghost demo will use the full desktop if all monitors are
  100% widescreen aligned, meaning having same top (=0) and height)

  Shortcuts: Ctrl+Shift+Alt+D: toggles visibility (but still fully running!)
             Ctrl+Shift+Alt+F: return to foreground-mode
             Ctrl+Shift+Alt+L: quit
             Ctrl+Shift+Alt+V: open Windows volume controls
                  Windows + M: Minimize (most) Windows (Windows shortcut)
                  Windows + D: Minimize (even more?) Windows (Windows shortcut)
                                (Windows 98+, NT?/2000?/XP+)

  TrayIcon behavior: Left click          toggles visibility (but still fully
                                         running!)
                     Left doubleclick    quit
                     Right doubleclick   opem Windows volume controls (record
                                         mode)

  For completeness, source for the released demo applications is provided, ...
  I know it's a (coding) desaster, especially all this may compiler directives.
  It's a demo application, so I didn't care a bit except speed and size of the
  final binary, and sharing code.

Tools
-----

  gen_GetTitle:  Winamp general purpose plugin that helps other applications
                 determinate current playing song
  gen_ShowTitle: Shows the title of each playing song on the screen while Winamp
                 is minimized. Also supports same functionality as gen_GetTitle.

Version history
---------------

  3.10 build 2008.04.16
   Virtual version:
    - Generates spectrum values for all channels correctly
   Demo applications:
    - Removed stuff to detect wether screensavers etc. are permitted, because
      provided information is unreliable. Quit or hide manually instead.