Soepkip The Next Generation

                  Soepkip The Next Generation
     ----------------------------------------------------
             by Eric Lammerts <eric@lammerts.org>


Download:
---------
A daily cvs snapshot .tar.gz is available from
http://www.lammerts.org/software/soepkiptng/.

Direct (read-only) cvs access is also possible. Set your CVSROOT to
:pserver:anonymous@lammerts.org:/var/local/cvs, do "cvs login"
(empty password) and "cvs checkout soepkiptng".


Features:
---------
* file format support:
  - MP3 (including id3/id3v2 tag reading, id3v2 tag writing)
  - Ogg-Vorbis (including Vorbis comment reading/writing)
  - flac (including Vorbis comment reading/writing)
  - CD/DA (reading directly from CD, using cdparanoia)
  - wav
  - raw (headerless 44.1kHz/16bit/2ch/little-endian files)
  - Video (everything supported by MPlayer: MPEG, AVI, ASF, WMV, Quicktime,
    RealMedia and more)
  - midi/mod (using TiMidity++)
  - Shorten
  - lpac
  - AC3
* supports playing Shoutcast streams (MP3 / Ogg Vorbis)
* player uses real-time scheduling and memory locking for uninterrupted music
  playback; zero silence period between two songs (very nice for consecutive
  songs of a live cd).
* song information is kept in a MySQL database, but can be written back
  to mp3 files (using ID3v2) or ogg/flac files (using vorbis comments) too.
* lyrics support; Lyrics can be entered manually or downloaded automatically
  from http://www.purelyrics.com and http://www.lyricsdomain.com.
  They can be read from and written to mp3 files using id3v2 tags.
* plays from request queue; plays random songs if nothing is on the request
  queue
* versatile web interface:
  - supports browsing, searching, requesting songs,
    killing current song, editing song information etc.
  - very fast (thanks to mod_perl)
  - configurable look (CSS style)
  - tested with Netscape, Mozilla, Konqueror, Opera & MSIE.
* commandline interface


Requirements:
-------------
* perl5
* mysql 3.22
  (3.23 recommended; 3.22 cannot do case-insensitive regexps)
* apache + mod_perl
* perl modules:
  - MPEG::MP3Info
  - CGI
  - DBI
  - DBD::mysql
  - Compress::Zlib
  - Apache::DBI
  - Apache::Session
  - TermReadKey (optional)
  - FreeDB (optional)
* programs for decoding the various sound formats:
  - mp3: requires madplay (http://www.mars.org/home/rob/proj/mpeg/
    version >= 0.15.0 required)
  - wav: requires sox (http://sox.sourceforge.net/)
  - lpac:
    LPAC is a non-free lossless compression algorithm. You can get a linux
    binary from http://www-ft.ee.tu-berlin.de/~liebchen/lpac.html at no cost.
    The source is not available :-(.
  - flac (>= 1.04 required):
    Flac is a free lossless compression algorithm, available from
    flac.sourceforge.net. It does not compress as well as lpac, but the
    difference is marginal.
  - Ogg-Vorbis
    Get the libraries from http://www.xiph.org.
  - CD/DA: requires cdparanoia (http://www.xiph.org/paranoia/)
  - midi/mod: requires TiMidity++ (http://www.goice.co.jp/member/mo/timidity/)
  - AC3: requires a52dec (http://liba52.sourceforge.net/)
  - Video: requires MPlayer (http://http://www.mplayerhq.hu/)
  - Shorten: requires shorten (http://www.etree.org/shnutils/shorten/) 
    and shntool (http://www.etree.org/shnutils/shntool/)

Perl modules can be installed directly from CPAN by starting "perl -MCPAN
-e shell" (you must answer some configuration questions if you do this for
the first time) and typing "install Some::Module".


On a Debian system you can install all the necessary software with apt-get.
You may have to use the unstable branch ("sid") in order to get the right
versions.

Package list:
- flac                    (optional; for flac support; >= 1.04 required)
- libcompress-zlib-perl
- libdbd-mysql-perl
- libmpeg-mp3info-perl or libmp3-info-perl
- libterm-readkey-perl    (optional)
- libvorbis-dev           (for Ogg-Vorbis support)
- madplay                 (for mp3 support)
- mysql-server
- sox                     (optional; for wav support)
- apache                  (optional; for apache/mod_perl-based web interface)
- libapache-dbi-perl      (optional; for apache/mod_perl-based web interface)
- libapache-mod-perl      (optional; for apache/mod_perl-based web interface)
- libwww-perl             (optional; for standalone web interface)
- cdparanoia              (optional; for CD-DA support)
- libfreedb-perl          (optional; for CD-DA support)
- a52dec                  (optional; for AC3 support)

Installation:
-------------
* compile the helper applications:
  cd src; make; sudo make install
  The binaries will be placed in the 'bin' subdirectory.
* create the database:
  sudo mysql -u root < soepkiptng_create.my
* reload the grant tables:
  sudo mysqladmin reload
* copy soepkiptng.conf.example to either:
  - /etc/soepkiptng.conf
  - ~/.soepkiptng.conf
  - any file named in $SOEPKIPTNG_CONFIGFILE
  (or edit soepkiptng.lib if you want a different location)
* edit the config file to taste
* make the directory /var/local/soepkiptng and make sure
  it's writable for the user that will run soepkiptngd
* Add something like the following to /etc/apache/httpd.conf:

  Alias /soepkiptng /usr/local/soepkiptng/web

  <Directory /usr/local/soepkiptng/web>
    Options +ExecCGI
    DirectoryIndex index.cgi
    AddHandler perl-script .cgi
    PerlHandler Apache::Registry
    PerlRequire /usr/local/soepkiptng/modperl.pl
    PerlSendHeader On
  </Directory>

* run soepkiptng_update to add songs to the database
* run soepkiptngd -d to start playing with debugging on.
  If everything works alright, start it without -d to run it in the
  background. Debugging output is then sent to
  /var/local/soepkiptng/soepkiptng.err, which is automatically
  rotated if the size reaches 64Kbyte. Make sure file permissions
  in /var/local/soepkiptng are OK. If you sometimes run soepkiptngd as root
  and sometimes as non-root you can expect problems.
 

TODO:
-----
* better interface / web interface for 'see also' feature
* clean up Shoutcast support (separate table, multiple urls per name with
  automatic fallback)
* lirc support (IR remote)
* play directly from urls
* smb support (playing/updating directly from Windoze shares)
* playlists/genres
* ripping integration
* multiple soepkiptng daemons & request queues
* remote playing using esd (Enlightenment Sound Daemon), http streaming or
  similar stuff
* message input that will be played using a text-to-speech program
* user-level access control (limit access to database editing / song requests)
* improve docs
* make music format more modular; maybe support xmms plugins (well, they suck)
* silence before random songs
* fade-out/fade-in in pause/resume
* cleanup Xing VBR info detection (it's a quick hack now)
* scan VBR mp3s without Xing VBR header for length
* Ogg-Vorbis embedded songinfo support (reading/writing)
* cleanup resampling & mono->stereo conversion
* smooth transition between 2 songs (interpolation)
* synchronize update of statusfile with cdrplay
* CD-DA support: don't re-enter info into db every time you click "CD-DA"
  maybe use persistent info and cddb disc_id?

$Id: README,v 1.39 2003/10/06 23:29:11 eric Exp $



Copyright:
----------
soepkiptng is (c) copyright 2000 Eric Lammerts <eric@lammerts.org>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2, as 
published by the Free Software Foundation.

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.

A copy of the GNU General Public License is available on the World Wide Web
at `http://www.gnu.org/copyleft/gpl.html'.  You can also obtain it by
writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.