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.
  However, I've already encounter a computer with good hardware where playback
  (using QuickPlayer) began stuttering when LineSpec demo applications ran.

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 the 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;
   - *.lib & *.exp                Additional include files you may need for some
                                  compilers

  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.
  Also 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

  UINT Shutdown(); // Always returns NULL

  UINT GetSpectrum(
    UINT ptrFloatArray, // pointer to an array of floats for the spectrum
    UINT ArraySize,     // Number of floats (per channel!)
    UINT Channels,      // Channels to grab: 0=mixed, 1=left, 2=right, 3=stereo
    UINT Flags.l,       // 1 = get previous spectrum; 2 = average values
    UINT ptrBoost       // pointer to a float with the boost value, or NULL
    ); // returns the GetTickCount() windows api value from the last finished
       // spectrum data, or NULL / 0
Usage
-----

  To use LineSpec, call Startup(). If the functions succeeds (not NULL), you can
  use GetSpectrum; When finished, call Shutdown();
  
Remarks
-------

  - If Startup() has failed, do not call GetSpectrum() or Shutdown().
  - If Startup() has failed or after using Shutdown(), you may try Startup()
    again.
  - GetSpectrum always delivers the last used / latest available spectrum data,
    and the return value is the GetTickCount() windows api value when the
    affected spectrum data has finished.
    If no spectrum data is ready after Startup() yet, it delivers zero floats,
    and the return value is NULL / 0.
  - The boost value is applied internally whenever a new spectrum data is to be
    used; Calling GetSpectrum() with flag 1, the ptrBoost parameter is currently
    ignored; If ptrBoost is NULL, a value of 1 (no boost) will be used. For
    backwards compatibility, ptrBoost should not be NULL!

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 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.11 build 2008.06.20
   General changes:
    - GetSpectrum() returns GetTickCount() windows api value of the affected
      spectrum data, or NULL / 0
    - ptrBoost parameter for GetSpectrum() may be NULL
    - Using channel 0 in GetSpectrum() delivers mixed left/right channel data
   Multithread version:
    - Thread always stoppes recording properly now on Shutdown()
   Virtual version:
    - Flags and Channels parameters processed (correctly)
   Demo applications:
    - Recording thread always stoppes recording properly when quitting
    - New demo: LSDemo - Wallpaper - LaFee
    - Animation when title changes

  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.