seal 0.1.0

data/mpg123/doc/PATENTS

@@ -0,0 +1,39 @@
+Some notes about patents and mpg123 by Thomas Orgis
+---------------------------------------------------
+
+There has been a lot of confusion over mp3 (or more generic mpeg audio) patents and licensing issues due to the patents held by Fraunhofer and marketed by Thomson.
+So, yes, there are patents held by Fraunhofer that are claimed to cover mpeg audio technology. There are also claims that they cover any similar technology (like OGG).
+You may argue if these patents are valid at all (being illegal software patents, or being preceeded by known scientific publications), but they are internationally accepted by patent authorities and if you want to use mp3 commercially you should check
+
+	http://www.mp3licensing.org
+
+for the Fraunhofer/Thomson opinion and their terms.
+
+Since mpg123 is only a mpeg audio player, a good deal of patents that describe the encoding process (the tricky part) will not apply.
+Also, statements from the patent holders up to now always allowed the non-commercial distribution of mpeg audio decoders without any fee.
+They want you to pay for a license when you want to make money by selling a decoder, though. We don't sell mpg123.
+Additionally, one should not forget the fact that the ideas are getting old; the basic (funded by government, btw.) research was somewhen back around the 80s and many patents are going to expire soon, best example in Germany:
+
+P/DE 35 06 912 Method of transmission of an audio signal using grouping of amplitude values
+
+Application was 22.02.1986 in Germany (and around Europe in the same time Jan/Feb 1986).
+German patents last 20 years... now we have 24.07.2006. Time has come...
+
+The idea of a patent is to make the inventor open the invention to the public by giving him some safe time to turn this invention into economical benefit.
+People using (and improving!) the technology freely after that time is _the_ most important aspect of that idea.
+
+Oh, I should mention the "core" mp3 patent (from http://gauss.ffii.org/PatentView/EP287578):
+
+DE 3629434 / EP287578 Digital coding process
+
+Application date in Germany was 29.08.1986 - that means that in a month from now (remember: 24.07.2006) this patent finds its natural end.
+
+Then, there are other patents listed on the Fraunhofer/Thomson website that came very late... The one about join stereo coding was aplied for in Feb 1995. Did mpg123 implement that already back then? History is a bit blurry there...
+There is a patent applied for in 1997, but probably covering encoding only. Still, even if that weren't the case - the basic decoding functionality of mpg123 didn't change that much after 1997; and they couldn't have patented existing functionality.
+In general, few patents seem to cover decoders at all. Of course, with me being no lawyer, that statement is not trustworthy...
+
+Bottom line is:
+
+While Fraunhofer/Thomson don't want to charge free software players - they said that a long time ago, the time for they being able to place such charges is expiring or has already expired. One should really think before adding mp3pro/surround support to mpg123, though, since there are for sure more recent patents for that.
+
+And don't forget: The progress bar is covered by a patent, too.

data/mpg123/doc/README.3DNOW

@@ -0,0 +1,56 @@
+************************************************************************
+* 3DNow! support by KIMURA Takuhiro   <kim@hannah.ipc.miyakyo-u.ac.jp> *
+*                                     <kim@comtec.co.jp>               *
+*                             (http://hannah.ipc.miyakyo-u.ac.jp/kim/) *
+*                   Syuuhei Kashiyama <squash@mb.kcom.ne.jp>           *
+*                             (http://user.ecc.u-tokyo.ac.jp/~g810370/)*
+************************************************************************
+
+-----------------------------
+What's new in patch for 0.59r
+-----------------------------
+- 3DNow! optimized decode routine (decode_3dnow.s,dct36_3dnow.s ;
+  these code based Syuuhei Kashiyama's 3DNow! patch for mpg123-0.59o)
+- 3DNow! optimized equalizer (equalizer_3dnow.s ; do_equalizer() only)
+- target "linux-3dnow-alsa" "linux-3dnow-esd" added (untested)
+- automatic detect 3DNow! support CPU from CPUFLAGS (getcpuflags.s)
+  (i.e. use floating-pointer decode routine if your CPU isn't support
+   3DNow! or MMX instructions)
+
+-------------
+Added options
+-------------
+"--test-3dnow"  : display result of autodetect and exit
+"--force-3dnow" : force use of 3DNow! optimized decoder
+ (it will cause SIGILL if your CPU isn't support 3DNow! or MMX
+  instructions)
+"--no-3dnow"    : force use of floating-pointer decoder
+
+-----------
+How to make
+-----------
+[1] To make 3DNow! optimized mpg123,you need binutils-2.9.1.0.15 or later.
+ You can find the most recent binutils (2.9.1.0.25 until 23.Jun.1999) at
+  - kernel.org (and mirrors) : /pub/linux/devel/gcc/
+  - http://hannah.ipc.miyakyo-u.ac.jp/kim/Linux/binutils/
+    (Takuhiro's local copy)
+ etc.
+[2] Type "make linux-3dnow" (OSS)
+      or "make linux-3dnow-alsa" (ALSA).
+[3] Enjoy!
+
+------------------
+Precompiled binary
+------------------
+You can get precompiled binary of mpg123 (with 3DNow! support) from
+ http://hannah.ipc.miyakyo-u.ac.jp/kim/Linux/mpg123/
+
+----------
+References
+----------
+Useful sources of information on optimizing 3DNow! code include:
+- AMD 3DNow! Technology Manual (Publication #21928)
+     English:  http://www.amd.com/K6/k6docs/pdf/21928d.pdf
+    (Japanese: http://www.amd.com/japan/K6/k6docs/j21928c.pdf)
+- AMD-K6-2 Processor Code Optimization Application Note (Publication #21924)
+     English:	http://www.amd.com/K6/k6docs/pdf/21924b.pdf

data/mpg123/doc/README.gain

@@ -0,0 +1,171 @@
+Thomas Orgis on RVA, Gain and Pain
+
+
+Ok, so I'm going to add RVA/ReplayGain support... the problem there is not to read these valus from ID3 or Lame, not even to do the adjustment itself.
+The problem is more to figure out how to interpret the dB values one gets there.
+
+Main players in the field of relative volume adjustment / soft gain (without modifying actual audio data):
+
+http://www1.cs.columbia.edu/~cvaill/normalize/
+	...writing RVA2 ID3v2tags for dB offset to user target amplitude, default being -12dB(FS)
+http://www.replaygain.org/
+	...store the difference to reference of 83dB(SPL) ... somewhere
+
+Both calculate some running RMS and do statistics with this - the main difference is the potentially different target level.
+Also both know two basic types of adjustment: Per track to make all tracks sound at the same sevel (track / radio) and the one with default meaning to keep the loudness relations over albums (batch / audiophile).
+
+dB can mean many things and also the raw value of a PCM sample doesn't equal directly to loudness (power of a wave != amplitude).
+
+So that says the ReplayGain about applying the adjustment:
+
+	scale=10.^(replay_gain/20);
+
+luckily, this is the same that I worked out on my own for the normalize RVA values in my mixplayer script:
+
+	return 10**($s/20);
+
+I'll take that interpretaion of dB -> linear scale factor for samples for granted, then.
+
+The replay_gain value is meant in the standard to represent the offset to 83dB(SPL - depending on your amplifier...), having in mind that actual most wanted average playback level should be 83dB(SPL) (defined by movie ppl as the loudness of a -20dB(FS) signal, leaving room for louder stuff).
+But then there is the proposal to add 6dB preamp for pop music - am I judging music types with mpg123??
+These 6dB are in fact the real world since lots of programs use 89dB(SPL...) as reference.
+Thus, lame since 3.95.1 (according to MADplay's Rob Leslie who discussed with Lame ppl, verified in 3.96 source) stores the adjustment to 89dB.
+To make that all sound the same, one should add 6bB to lame <3.95.1 ReplayGain values and use later ones verbatim - achieving 89dB everytime, whatever that may mean in reality out of my speakers (my Marantz' volume knob doesn't have a scale at all - be it dB or percent;-).
+
+A funny aspect of this 6dB issue is to tell lame 3.95.1 from lame 3.95 
+
+As for normalize... the desired playback level is essentially undefined. Ignoring that and realizing that mpg123 has no way to determine real world sound power anyway, one has to just take the provided dB values and apply with the formula above.
+The user is responsible for providing files with his desired settings... for that reason I also won't follow the ReplayGain demand/suggestion that a player should apply an average of gains of previous tracks if the current one lacks a setting.
+
+So, well. Considering that ReplayGain (at least the radio one) being stored by current lame on encoding, I suppose that if there are RVA2 values in ID3v2 tags, these were added by a conscious user act and are overriding the ReplayGain ones.
+
+I already read ReplayGain entries in Lame tag... should add ID3v2 parsing. Especially since the lame tag is ambignous because of the 6dB issue... I cannot distinguish 3.95.1 from 3.95 by reading the tag - frick!
+But wait... 6dB?
+
+[thomas@thorvas /home/thomas-data/mpg123-neu/lame-3.96.1]$ frontend/lame --cbr -T /mnt/knecht_mp3/music/covenant/2006_skyshaper/03-happy_man.mp3 ../testfiles/happy_man_lame-3.96.1.mp3
+ID3v2 found. Be aware that the ID3 tag is currently lost when transcoding.
+LAME version 3.96.1 (http://lame.sourceforge.net/)
+Using polyphase lowpass filter, transition band: 17249 Hz - 17782 Hz
+Encoding /mnt/knecht_mp3/music/covenant/2006_skyshaper/03-happy_man.mp3
+      to ../testfiles/happy_man_lame-3.96.1.mp3
+Encoding as 44.1 kHz 128 kbps j-stereo MPEG-1 Layer III (11x) qval=3
+    Frame          |  CPU time/estim | REAL time/estim | play/CPU |    ETA 
+  6371/6374  (100%)|    1:41/    1:41|    1:47/    1:47|   1.6353x|    0:00 
+average: 128.0 kbps   LR: 754 (11.83%)   MS: 5620 (88.17%)
+
+Writing LAME Tag...done
+ReplayGain: -7.4dB
+revmethod = 1
+encoder padding: 1728
+
+[thomas@thorvas /home/thomas-data/mpg123-neu/lame-3.95.1]$ frontend/lame --cbr -T /mnt/knecht_mp3/music/covenant/2006_skyshaper/03-happy_man.mp3 ../testfiles/happy_man.mp3
+ID3v2 found. Be aware that the ID3 tag is currently lost when transcoding.
+LAME version 3.95  (http://www.mp3dev.org/)
+Using polyphase lowpass  filter, transition band: 17249 Hz - 17782 Hz
+Encoding /mnt/knecht_mp3/music/covenant/2006_skyshaper/03-happy_man.mp3
+      to ../testfiles/happy_man.mp3
+Encoding as 44.1 kHz 128 kbps j-stereo MPEG-1 Layer III (11x) qval=3
+    Frame          |  CPU time/estim | REAL time/estim | play/CPU |    ETA 
+  6371/6374  (100%)|    1:36/    1:36|    1:48/    1:48|   1.7289x|    0:00 
+average: 128.0 kbps   LR: 759 (11.91%)   MS: 5615 (88.09%)
+
+Writing LAME Tag...done
+ReplayGain: -7.4dB
+
+[thomas@thorvas /home/thomas-data/mpg123-neu/lame-3.95]$ frontend/lame --cbr -T /mnt/knecht_mp3/music/covenant/2006_skyshaper/03-happy_man.mp3 ../testfiles/happy_man_lame-3.95.mp3
+ID3v2 found. Be aware that the ID3 tag is currently lost when transcoding.
+LAME version 3.95  (http://www.mp3dev.org/)
+Using polyphase lowpass  filter, transition band: 17249 Hz - 17782 Hz
+Encoding /mnt/knecht_mp3/music/covenant/2006_skyshaper/03-happy_man.mp3
+      to ../testfiles/happy_man_lame-3.95.mp3
+Encoding as 44.1 kHz 128 kbps j-stereo MPEG-1 Layer III (11x) qval=3
+    Frame          |  CPU time/estim | REAL time/estim | play/CPU |    ETA 
+  6371/6374  (100%)|    1:37/    1:37|    1:43/    1:43|   1.7041x|    0:00 
+average: 128.0 kbps   LR: 759 (11.91%)   MS: 5615 (88.09%)
+
+Writing LAME Tag...done
+ReplayGain: -13.4dB
+
+
+Together with the gain values read from tags: 
+
+3.96.1:	-1.0dB	(claimed -7.4dB)
+3.95:	-1.0dB	(claimed -7.4dB)
+3.95:	-0.6dB	(claimed -13.4dB)
+
+So, the difference of 6dB shows in the values lame prints on the command line... but the lame tags only have 0.4dB difference and are much lower anyway - do I parse them correctly?
+
+Opinion of normalize of these files: -2dB. Great. I guess the -1 is what lame really meant, then... 
+
+
+Storage places
+==============
+
+Points 1, 2 and 4 implemented to some respect.
+
+
+1. Lame/Info tag
+
+supposedly in format according to the proposed standard - but I yet have to verify if Lame really does this.
+see http://gabriel.mp3-tech.org/mp3infotag.html
+
+
+2. ID3v2 RVA2 frame(s)
+
+Normalize does that. Rare is the software reading that.
+I've never seen those frames since id3v2 -l doesn't know them.
+
+
+3. APE tags
+
+Gah, another Tag format. Foobar2000 uses this as default.
+It's getting real-hy messy folks
+
+
+4. Per convention in ID3 tags
+
+Well, I myself once used the ID3v1 comment field for storing the mix rva value (textual) ... but that is a tad too unspecific.
+I then also used user-defined ID3v2 comments like that:
+
+[thomas@thorvas /home/thomas-data/mpg123-neu/svn/trunk]$ id3v2 -l /mnt/knecht_mp3/music/underworld/second_toughest_in_the_infants/02-banstyle_sappys_curry.mp3 
+id3v1 tag info for /mnt/knecht_mp3/music/underworld/second_toughest_in_the_infants/02-banstyle_sappys_curry.mp3:
+Title  : banstyle  sappys curry          Artist: underworld                    
+Album  : second toughest in the infants  Year: 0   , Genre: Other (12)
+Comment: Created by Grip                 Track: 2
+id3v2 tag info for /mnt/knecht_mp3/music/underworld/second_toughest_in_the_infants/02-banstyle_sappys_curry.mp3:
+TYER (Year): 0
+TRCK (Track number/Position in set): 2
+COMM (Comments): (ID3v1 Comment)[XXX]: Created by Grip
+TCON (Content type): Other (12)
+TPE1 (Lead performer(s)/Soloist(s)): underworld
+TALB (Album/Movie/Show title): second toughest in the infants
+TIT2 (Title/songname/content description): banstyle  sappys curry
+COMM (Comments): (RVA)[]: 4.3291
+COMM (Comments): (RVA_ALBUM)[]: 3.666101
+
+That still doesn't look like a bad Idea to me. Not bothering with byte ordering and whatnot. Just atof(id3v2_comm_rva).
+One could still add dB, though.
+
+Another convention is (rockbox mailinglist, not checked myself) used by Foobar:
+
+TXXX (User defined text information): (replaygain_track_gain): -7.17 dB 
+TXXX (User defined text information): (replaygain_track_peak): 1.057122 
+TXXX (User defined text information): (replaygain_album_gain): -6.53 dB 
+TXXX (User defined text information): (replaygain_album_peak): 1.107456
+
+So what are custom comment fields for when there are also custom text fields? They look very similar to me.
+
+
+5. Leave the haunted music file alone and store metadata externally.
+
+That's the only sane way for stuff like album art... and it's the way I do it in my music archive. the wrapper script reads the adjustment values and then sets an adjusted volume.
+That's fine for my mixing daemon that manupulates the pcm data anyway, but it would be nice to have this functionality in the minimalist console mode. too.
+Even more since it can be done without additional cpu power during decoding (well, one-time set up of the decode tables is needed for every track) similar to the equalizer.
+I could simply start with text files with lines like
+
+RVA_MIX: 3.4dB
+RVA_ALBUM: 1.7dB
+
+Prob here is that the effort to open and parse that extra file may hinder gapless decoding between tracks...
+Well, one could parse all metadata files for a list of tracks before playback starts.
+But all this won't work for streams via stdin (hm, one could argue if the stream needs RVA at all).

data/mpg123/doc/README.remote

@@ -0,0 +1,218 @@
+Control interface to generic frontends
+
+The generic remote interface allows frontends to easily control
+mpg123 by commands through stdin/stdout. To start the generic
+remote interface, start mpg123 with parameter -R.
+
+In case of a frontend that starts mpg123 with the -s option to read the audio from stdout, the --remote-err option is automatically activated to send responses to stderr so that stdout stays clean for audio.
+
+(Still the case?)
+As an example it's used by IRMP3, a tool that allows you to
+control mpg123 with a standard infrared remote control. See
+http://www.fasta.fh-dortmund.de/users/andy/irmp3/ for more
+information.
+
+You can also specify --fifo <path> to create a named pipe at <path> and listen on that for commands instead stdin.
+That way, you can deliberately control mpg123 by echoing into the named pipe from any terminal / program.
+The command respones are still sent to standard out or standard error (depending on -s or --remote-err switches).
+
+
+COMMAND CODES
+-------------
+
+You can get this info via the control command "help".
+
+HELP/H: command listing (LONG/SHORT forms), command case insensitve
+
+LOAD/L <trackname>: load and start playing resource <trackname>
+
+LOADPAUSED/LP <trackname>: load but do not start playing resource <trackname>
+
+LOADLIST <entry> <url>: load a playlist from given <url>, and display its entries, optionally load and play one of these specificed by the integer <entry> (<0: just list, 0: play last track, >0:play track with that position in list)
+
+PAUSE/P: pause playback
+
+STOP/S: stop playback (closes file)
+
+JUMP/J <frame>|<+offset>|<-offset>|<[+|-]seconds>s: jump to mpeg frame <frame> or change position by offset, same in seconds if number followed by "s"
+
+VOLUME/V <percent>: set volume in % (0..100...); float value
+
+RVA off|(mix|radio)|(album|audiophile): set rva mode
+
+EQ/E <channel> <band> <value>: set equalizer value for frequency band 0 to 31 on channel 1 (left) or 2 (right) or 3 (both)
+
+EQFILE <filename>: load EQ settings from a file
+
+SHOWEQ: show all equalizer settings (as <channel> <band> <value> lines in a SHOWEQ block (like TAG))
+
+SEEK/K <sample>|<+offset>|<-offset>: jump to output sample position <samples> or change position by offset
+
+SCAN: scan through the file, building seek index
+
+SAMPLE: print out the sample position and total number of samples
+
+SEQ <bass> <mid> <treble>: simple eq setting...
+
+PITCH <[+|-]value>: adjust playback speed (+0.01 is 1 % faster)
+
+SILENCE: be silent during playback (meaning silence in text form)
+
+STATE: Print auxilliary state info in several lines (just try it to see what info is there).
+
+TAG/T: Print all available (ID3) tag info, for ID3v2 that gives output of all collected text fields, using the ID3v2.3/4 4-character names.
+   The output is multiple lines, begin marked by "@T {", end by "@T }".
+   ID3v1 data is like in the @I info lines (see below), just with "@T" in front.
+   An ID3v2 data field is introduced via ([ ... ] means optional):
+    @T ID3v2.<NAME>[ [lang(<LANG>)] desc(<description>)]:
+   The lines of data follow with "=" prefixed:
+    @T =<one line of content in UTF-8 encoding>
+meaning of the @S stream info:
+
+S <mpeg-version> <layer> <sampling freq> <mode(stereo/mono/...)> <mode_ext> <framesize> <stereo> <copyright> <error_protected> <emphasis> <bitrate> <extension> <vbr(0/1=yes/no)>
+The @I lines after loading a track give some ID3 info, the format:
+     @I ID3:artist  album  year  comment genretext
+    where artist,album and comment are exactly 30 characters each, year is 4 characters, genre text unspecified.
+    You will encounter "@I ID3.genre:<number>" and "@I ID3.track:<number>".
+    Then, there is an excerpt of ID3v2 info in the structure
+     @I ID3v2.title:Blabla bla Bla
+    for every line of the "title" data field. Likewise for other fields (author, album, etc).
+
+
+RESPONSE CODES
+--------------
+
+Note: mpg123 returns errors on stderr, so your frontend should
+      look not only at stdout but also at stderr for responses.
+      It is a good idea to use --remote-err and just look at stderr.
+
+@R MPG123 (ThOr) v7
+	Startup version message. Everything after MPG123 is auxilliary information about behaviour and command support, ID3v2 tag support is new in v3.
+
+@I ID3:<a><b><c>
+	Status message after loading a song (ID3 song info)
+	a = title (exactly 30 chars)
+	b = artist (exactly 30 chars)
+	c = album (exactly 30 chars)
+	d = year (exactly 4 chars)
+	e = comment (exactly 30 chars)
+	f = genre (string)
+
+@I ID3.genre:<number>
+@I ID3.track:<number>
+	Optional lines with additional ID3v1 info (if present): Genre ID and track number in set.
+
+@I ID3v2.title:<text>
+	After loading a track with ID3v2 info, such lines occur for every line of the "title" data field and likewise for other fields (author, album, etc).
+
+@I <a>
+			Status message after loading a song (no ID3 song info)
+			a = filename without path and extension
+
+@I LISTENTRY <n>: <url>
+	printout of playlists loaded with LOADLIST
+
+@S <a> <b> ...
+	Stream info at beginning of playback, meaning
+	S <mpeg-version> <layer> <sampling freq> <mode(stereo/mono/...)> <mode_ext> <framesize> <stereo> <copyright> <error_protected> <emphasis> <bitrate> <extension> <vbr(0/1=yes/no)>
+
+@S <a> <b> <c> <d> <e> <f> <g> <h> <i> <j> <k> <l>
+	Status message after loading a song (stream info)
+	a = mpeg type (string)
+	b = layer (int)
+	c = sampling frequency (int)
+	d = mode (string)
+	e = mode extension (int)
+	f = framesize (int)
+	g = stereo (int)
+	h = copyright (int)
+	i = error protection (int)
+	j = emphasis (int)
+	k = bitrate (int)
+	l = extension (int)
+
+@F <a> <b> <c> <d>
+	Status message during playing (frame info)
+	a = framecount (int)
+	b = frames left this song (int)
+	c = seconds (float)
+	d = seconds left (float)
+
+@P <a>
+	Playing status
+	a = 0: playing stopped
+	a = 1: playing paused
+	a = 2: playing unpaused
+
+@E <a>
+	An error occured
+	Errors may be also reported by mpg123 through
+	stderr (without @E)
+	a = error message (string)
+
+@J <n>
+	Jumped to frame n.
+
+@RVA <mode>
+	Switched to specified RVA mode.
+
+@V <volume>%
+	Set volume to specified value (float, percent).
+
+@<x> : <y> : <z>
+	Set equalizer value z for band y of channel x.
+
+@bass: <b> mid: <m> treble: <t>
+	Set simple equalizer control for bass, mid, treble.
+
+@T <response from TAG command>
+	The output is multiple lines, begin marked by "@T {", end by "@T }".
+	ID3v1 data is like in the @I info lines, just with "@T" in front.
+	An ID3v2 data field is introduced via ([ ... ] means optional):
+		@T ID3v2.<NAME>[ [lang(<LANG>)] desc(<description>)]:
+	The lines of data follow with "=" prefixed:
+		@T =<one line of content in UTF-8 encoding>
+
+
+EQUALIZER CONTROL (History)
+---------------------------
+
+WARNING: The interpretation of the command arguments changed. The channel is either 1 or 2 or 3 (left, right, both).
+It used to be 0 or 1 for left or right but the change slipped through during libmpg123 work and now it is a fact.
+Sorry.
+
+Cold Feet Audio Patch for MPG123
+
+10.07.2002
+
+This is a dirty little hack to enable the equalizer in mpg123's
+generic_control interface.  It works like this, there are two
+different channels on the equalizer and 32 frequencys.
+
+The hack just enables mpg123's built in equalizer to run real-time.
+We haven't built in any capability to save the eq, you're frontend
+will have to handle that part, and init the eq on the startup of
+mpg123.
+
+K, it works like this:
+
+#./mpg123 -R -  <---- This command will start mpg123 in 'frontend' mode.
+
+If you want to send it some eq values you'd send it:
+eq X Y V[ENTER]
+
+X = The channel.  It can be either 0 or 1.  I haven't put any error checking
+    in, so it probably wouldn't be a good idea to go out of bounds. (integer)
+Y = This is the frequency, it can be 0 to 31.  0 being closer to treble and
+    31 being closer to bass. (integer)
+V = The raw value of your equalizer setting.  I've found that the values work 
+    best between 0.00 and 3.00.  When mpg123 starts up, all of them are set
+    to 1.00.
+
+OK, have fun!  If you have any questions or found some bugs, please contact
+nutcase@dtmf.org
+
+Thanks,
+nut
+
+Note by Thomas Orgis: The contact appears to be dead.