README

   1
   2                   Soepkip The Next Generation
   3      ----------------------------------------------------
   4              by Eric Lammerts <eric@lammerts.org>
   5
   6
   7 Download:
   8 ---------
   9 https://github.com/eric321/soepkiptng
  10
  11
  12 Features:
  13 ---------
  14 * file format support:
  15   - MP3 (including id3/id3v2 tag reading, id3v2 tag writing)
  16   - Ogg-Vorbis (including Vorbis comment reading/writing)
  17   - flac (including Vorbis comment reading/writing)
  18   - CD/DA (reading directly from CD, using cdparanoia)
  19   - wav
  20   - raw (headerless 44.1kHz/16bit/2ch/little-endian files)
  21   - Video (everything supported by MPlayer: MPEG, AVI, ASF, WMV, Quicktime,
  22     RealMedia and more)
  23   - midi/mod (using TiMidity++)
  24   - Shorten
  25   - AC3
  26   - MP4 (AAC, ALAC)
  27   - WMA & RealAudio (all formats that are supported by your mplayer)
  28   - Musepack (SV7 only)
  29 * supports playing Shoutcast streams (MP3 / Ogg Vorbis)
  30 * supports playing back in 32-bit mode
  31 * player uses real-time scheduling and memory locking for uninterrupted music
  32   playback; zero silence period between two songs (very nice for consecutive
  33   songs of a live cd).
  34 * song information is kept in a MySQL database, but can be written back
  35   to mp3 files (using ID3v2) or ogg/flac files (using vorbis comments) too.
  36 * lyrics support; Lyrics can be entered manually or downloaded automatically
  37   from http://www.purelyrics.com and http://www.lyricsdomain.com.
  38   They can be read from and written to mp3 files using id3v2 tags.
  39 * volume correction to avoid clipping
  40 * plays from request queue; plays random songs if nothing is on the request
  41   queue
  42 * versatile web interface:
  43   - supports browsing, searching, requesting songs,
  44     killing current song, editing song information etc.
  45   - very fast (thanks to mod_perl)
  46   - configurable look (CSS style)
  47   - tested with Netscape, Mozilla, Konqueror, Opera & MSIE.
  48 * commandline interface
  49 * partial emulation of a Music Player Daemon on port 6600
  50   (http://www.musicpd.org/doc/protocol/), for use with Conky
  51   (http://conky.sourceforge.net/)
  52
  53
  54 Requirements:
  55 -------------
  56 * perl5
  57 * mysql 3.22
  58   (3.23 recommended; 3.22 cannot do case-insensitive regexps)
  59 * perl modules:
  60   - MP3::Tag
  61   - MPEG::MP3Info
  62   - CGI
  63   - DBI
  64   - DBD::mysql
  65   - Compress::Zlib
  66   - BSD::Resource (optional)
  67   - TermReadKey (optional)
  68   - CDDB_get (optional)
  69 * programs for decoding the various sound formats:
  70   - mp3: madplay >= 0.15.0 (http://www.mars.org/home/rob/proj/mpeg/)
  71   - midi/mod: TiMidity++ (http://www.goice.co.jp/member/mo/timidity/)
  72   - wav, flac, ogg, ac3, aac, alac, shorten, ape: mplayer
  73   - wav, flac, ogg, m4a: sox (optional)
  74   - CD/DA: requires cdparanoia (http://www.xiph.org/paranoia/)
  75   - Video: requires MPlayer (http://http://www.mplayerhq.hu/)
  76 * programs for tag reading/writing:
  77   - flac: metaflac
  78   - ogg: ogginfo, vorbiscomment
  79
  80 The webinterface used to run under Apache using mod_perl, but I've switched
  81 to running as a separate webserver. The Apache method may still work, but is
  82 now completely untested.
  83
  84 Perl modules can be installed directly from CPAN by starting "perl -MCPAN
  85 -e shell" (you must answer some configuration questions if you do this for
  86 the first time) and typing "install Some::Module".
  87
  88
  89 On a Debian or Ubuntu system you can install all the necessary software with
  90 apt-get.
  91
  92 Package list:
  93 - libcompress-zlib-perl
  94 - libdbd-mysql-perl
  95 - libmp3-tag-perl
  96 - libmpeg-mp3info-perl or libmp3-info-perl
  97 - libterm-readkey-perl    (optional)
  98 - mysql-server
  99 - madplay                 (for mp3 support)
 100 - mplayer
 101 - flac                    (for flac support; >= 1.04)
 102 - vorbis-tools            (for Ogg-Vorbis support)
 103 - libwww-perl
 104 - cdparanoia              (optional; for CD-DA support)
 105 - libcddb-get-perl        (optional; for CD-DA support)
 106
 107
 108 Installation:
 109 -------------
 110 * compile the helper applications:
 111   cd src; make; sudo make install
 112   The binaries will be placed in the 'bin' subdirectory.
 113 * create the database:
 114   sudo mysql -u root < soepkiptng_create.my
 115 * reload the grant tables:
 116   sudo mysqladmin reload
 117 * copy soepkiptng.conf.example to either:
 118   - /etc/soepkiptng.conf
 119   - ~/.soepkiptng.conf
 120   - any file named in $SOEPKIPTNG_CONFIGFILE
 121   (or edit soepkiptng.lib if you want a different location)
 122 * edit the config file to taste
 123 * make the directory /var/local/soepkiptng and make sure
 124   it's writable for the user that will run soepkiptngd
 125 * run soepkiptng_update to add songs to the database
 126 * run soepkiptngd -d to start playing with debugging on.
 127   If everything works alright, start it without -d to run it in the
 128   background. Debugging output is then sent to
 129   /var/local/soepkiptng/soepkiptng.err, which is automatically rotated if
 130   the size reaches 64Kbyte. Make sure file permissions in
 131   /var/local/soepkiptng are OK. If you sometimes run soepkiptngd as root and
 132   sometimes as non-root you can expect problems.
 133 * run soepkiptng_httpd -d to start the webinterface. By default it runs on
 134   port 8888.
 135   If everything works alright, start it without -d to run it in the
 136   background.
 137 * for status display through conky, put something like this in your .conkyrc:
 138     ${mpd_artist} - ${mpd_title} (${mpd_album}, \#${mpd_track}) ${mpd_elapsed}/${mpd_length}
 139   If you don't want soepkiptngd to listen on port 6600, add mpd_port=0 to
 140   the config file.
 141
 142
 143 TODO:
 144 -----
 145 * write man pages for all scripts & executables
 146 * better interface / web interface for 'see also' feature
 147 * clean up Shoutcast support (separate table, multiple urls per name with
 148   automatic fallback)
 149 * lirc support (IR remote)
 150 * play directly from urls
 151 * smb support (playing/updating directly from Windoze shares)
 152 * playlists/genres
 153 * ripping integration
 154 * multiple soepkiptng daemons & request queues
 155 * remote playing using esd (Enlightenment Sound Daemon), http streaming or
 156   similar stuff
 157 * message input that will be played using a text-to-speech program
 158 * user-level access control (limit access to database editing / song requests)
 159 * improve docs
 160 * make music format more modular; maybe support xmms plugins (well, they suck)
 161 * silence before random songs
 162 * fade-out/fade-in in pause/resume
 163 * cleanup Xing VBR info detection (it's a quick hack now)
 164 * scan VBR mp3s without Xing VBR header for length
 165 * Ogg-Vorbis embedded songinfo support (reading/writing)
 166 * cleanup resampling & mono->stereo conversion
 167 * smooth transition between 2 songs (interpolation)
 168 * synchronize update of statusfile with cdrplay
 169 * CD-DA support: don't re-enter info into db every time you click "CD-DA"
 170   maybe use persistent info and cddb disc_id?
 171
 172
 173
 174
 175 Copyright:
 176 ----------
 177 soepkiptng is (c) copyright 2000-2010 Eric Lammerts <eric@lammerts.org>
 178
 179 This program is free software; you can redistribute it and/or modify
 180 it under the terms of the GNU General Public License, version 2, as
 181 published by the Free Software Foundation.
 182
 183 This program is distributed in the hope that it will be useful,
 184 but WITHOUT ANY WARRANTY; without even the implied warranty of
 185 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 186 GNU General Public License for more details.
 187
 188 A copy of the GNU General Public License is available on the World Wide Web
 189 at `http://www.gnu.org/copyleft/gpl.html'.  You can also obtain it by
 190 writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 191 Boston, MA 02111-1307, USA.
 192