$CVSHeader: ampache/modules/ds/README,v 1.2 2003/11/24 05:53:14 vollmerk Exp $

MP3 Streaming DownSampler (mp3SDS)
Damacus Porteng (damacus@munich.com)

About MP3 Streaming DownSampler (mp3SDS)
----------------------------------------
	This program was written after @Home cut my upstream from 110K/sec to
	about 15K/sec, and I was no longer able to stream my mp3s to my work
	computer.

	The interface is intentionally minimalistic, aiming for quickness and
	pure utility.

What you need:
--------------
	- PHP 3/4
	- LAME 3.85 or newer.  (older versions are finicky)
	- Decent hardware (decode then resampling can eat CPU time..)

	My computer is a P3-550 w/ 128M RAM, and has been able to handle 4 to
	5 requests at a time with aplomb.  Read 'About mp3 settings' below for
	more information on performance.

How to install:
---------------
	- Place all of these files into a directory on your webserver.
	- Create inside of that directory a symlink to all of your mp3s. 
		(see below)
	- Edit index.php and change configuration options to your liking.
	- Hit that directory, and have fun! :)

About directories:
------------------
	This is so very configurable..  in my case, I have a single tree on my
	system where all mp3s reside.  I just do a 'ln -s
	/mnt/warehouse/s3/mp3/ songs' and put 'songs' into the config file.

	If you have mp3s in several locations, try this.
	
	-=-=-
	cd /path/to/mp3SDS
	mkdir songs
	cd songs
	ln -s /path1/has/some/tunes path1_music
	ln -s /path2/has/different/music path2_music
	-=-=- ... etc.

	Note that some people do not like this, as someone can specify
	the directory and just start leaching the full files.  To stop that,
	you can easily add an entry to your apache config file which doesn't
	allow access to that location. (as PHP handles the file accessing)

About mp3 settings:
-------------------
	The important setting for the mp3s is the bitrate.  If you're not too
	privy on about what you should set this item to, this may help.

	There are 2 mp3 options which impact the amount of users your
	computer will be able to support:
		bitrate -- determins end filesize
		stereo -- affects encoding time and sound quality.

	root@obfuscated:/mnt/warehouse/s3/mp3/work_space# ls -l test*
	-rw-r--r--   1 root     root       990289 May 30 16:32 test32_m.mp3
	-rw-r--r--   1 root     root      1971738 May 30 16:33 test64_m.mp3
	-rw-r--r--   1 root     root      1971529 May 30 16:41 test64_s.mp3   

	With these, note that 64kbit/s produces a file 1M larger than the 32
	kbit/s version.  Next note that the 64kbit/s STEREO file is SMALLER
	than the mono version.  The stereo file sounds better, but here is
	the diff:

	Encoding 44.1 kHz 64 kbps single-ch MPEG1 LayerIII (11.0x)  qval=5
		play/CPU:  5.3755  (.. 5 users will max my CPU)
	Encoding 22.1 kHz 64 kbps stereo MPEG2 LayerIII (11.0x)  qval=5
		play/CPU: 3.9793   (.. 4 users will max my CPU)

	This shows that mono encodes 35.1% faster than stereo.   (side note.. 
	the sample rate is automatically changed by lame.)

	To get an idea of how many people your computer will be able to supprt,
	take an mp3 which may be streamed, and run this command:

	lame --mp3input -m <stereo> -b <bitrate> <file.mp3> TEST.mp3
		(where stereo, bitrate and file.mp3 and what you're testing)

	Lame will show you an indicator.  You are interested in the play/CPU
	rating.  That shows you how much faster than realtime it is running.
	You can read more about sizes and performance below.

	If you don't know what bitrate to choose, you can try these values 
	based on your server connection, or the connection where you're
	located at.  Set the rate to whatever the slowest link supports.
	
	For 1 or 2 persons at a time (private):
		(rate)		- (server connection)
		32kbit/s	- modem (1 person)
		96kbit/s	- calbe modem/DSL (1 person)
		64kbit/s	- cable modem/DSL (2 persons)
		128kbit/s	- 256kbit/s upstream DSL (2 persons)

	For 3 - 5 persons at a time (private to obscure public):
		(rate)		- (server connection)
		16kbit/s	- modem (heh...)
		32kbit/s	- cable/DSL
		64kbit/s	- 256kbit/s upstream DSL

	(cable/DSL assumes 15K/sec upstream cap.. some DSL lines are a bit
	 better.)

	If the server is on a fat pipe, just pick the 1/2 person setting which 
	best suites the size of your client connection.  (ie, work machine is on
	a T1, but I want to be able to stream to friends with dialup
	 connections, so I'd set the rate to 32 kbit/s)

History:
--------

MP3 Streaming Downsampler, Release 1.0 (public)
Released May 31, 2001
	-- Changed lame command to use --mp3input, instead of decoding, then
		re-encoding.
	-- Added configuration stuff to index.php
	-- Cleaned up the mess that was security checking code.
	-- Submitted to freshmeat.  :)

MP3 Streaming Downsampler, Release 0.8 (private)
Released May 10, 2001
	-- Went to rawurlencode() instead of urlencode();
	-- fixed character handling
	-- realized that some files weren't downsampling..
		and that it was lame's fault, not mine. Yay!

MP3 Streaming Downsampler, Release 0.1 (private)
Released May 08, 2001
	-- Program conceived and written.  Fucking @Home and their 15K/sec
	   upload caps.  Ehn.
	-- about 3 - 8% of the mp3s I try to stream don't work.  BAH!

Licensing and Future Plans/Ideas
--------------------------------
	I wrote this as a means to an end, so I don't plan on making any
	drastic changes to it.  If I have time or am really bored, a 'real'
	look with colors and crap may be added.

	A useful feature would actually be the ability to search, but just
	using file functions may not be very efficient.  If I get tired of
	traversing my file trees, it'll probably be written, else, why not
	write it yourself and send it in to me? :)

	Database support is also kind've cool, though I fear that it would
	start slowing down the system, and would add a lot of complexity to
	the currently easy setup and install.

	Regardless, this code is free, I don't care what you do with it, but
	I'd appreciate an email and a copy of your changes.  I wrote this
	thing and sometimes don't have time to screw with it,

