shithub: sox

Download patch

ref: f7e36c194096f7048f931ad69afb681720eb9291
parent: 36cc2a77dc286bd596f59166f6737ffb4a5e2e85
author: robs <robs>
date: Sun Jan 11 04:57:44 EST 2009

doc updates; mostly tidying

--- a/AUTHORS
+++ b/AUTHORS
@@ -1,105 +1,8 @@
-This is an incomplete list of contributors to SoX. Your name could be
-here, too! I've probably lost a few, and several people fixed the same
-bugs.
+SoX is currently maintained by
 
+	Chris Bagwell		cbagwell at users.sourceforge.net
+	Rob Sykes		robs at users.sourceforge.net
+	Pascal Giard		evilynux at users.sourceforge.net
 
-Creator:
-	Lance Norskog
-
-Mantainers:
-	Chris Bagwell		cbagwell@users.sourceforge.net
-		ALSA/OSS/Sun/MacOS X play/record support, initial ADPCM,
-		bugfixes, patch collection and general maintenance.
-	Rob Sykes		robs@users.sourceforge.net
-		FORMATS: M3U, PLS, FLAC, AMR, HTK, WavPack, VOX/IMA/VOC ADPCM
-		support, 24bit support for popular formats, MP3 tags & duration
-		support, .sox native format.
-		EFFECTS: tempo, pad, bass, bend, treble, delay, new reverb, new
-		flanger, soft-knee companding, speed via resampling, filters
-		makeover inc. gnuplot & octave plotting, splice, remix, norm,
-		contrast, new rate, spectrogram, new pitch, riaa, loudness, new
-		dither/noise-shape, overdrive,
-		new effects chain with buffering and any # channels.
-		OTHERS: open input files via URL, file merge, play
-		multiple files with mixed format types, play with replay-gain,
-		building with cmake, much manual improvement and expansion,
-		soxi, improved displays with -S & -V including VU and clips,
-		libSoX examples, various fixes, enhancements and clean-ups,
-		multiple input pipes.
-
-Contributors:
-	Reuben Thomas		rrt@sc3d.org
-		Build system makeover, libsndfile and ffmpeg sound
-		format support, libao playback, Secret Rabbit Code
-		resampling; many fixes and much cleanup.
-	Juergen Mueller		jmueller@uia.ua.ac.be
-		chorus, echo, echos, flanger, phaser, and reverb
-		effects.
-	Guido Van Rossum	guido@cwi.nl
-		AU, AIFF, AUTO, HCOM, reverse, many bug fixes.
-	Jef Poskanzer		jef@well.sf.ca.us
-		original code for u-law and delay line
-	Bill Neisius
-		DOS port, 8SVX, Sounder, Soundtool formats,
-		Apollo fixes, stat with auto-picker.
-	Rick Richardson		rick@digibd.com
-		WAV and SB driver handlers, fixes.
-	David Champion		dgc3@midway.uchicago.edu
-		Amiga port.
-	Pace Willisson		pace@blitz.com
-		Fixes for ESIX.
-	Leigh Smith		leigh@psychokiller.dialix.oz.au
-		SMP and comment movement support, AIFF Loop/MIDI
-		support.
-	David Sanderson		dws@ssec.wisc.edu
-		AIX3.1 fixes.
-	Glenn Lewis		glewis@pcocd2.intel.com
-		AIFF chunking fixes.
-	Brian Campbell		brianc@quantum.qnx.com
-		QNX port and 16-bit fixes.
-	Chris Adams		gt8741@prism.gatech.edu
-		DOS port fixes.
-	John Kohl		jtkohl@kolvir.elcr.ca.us
-		BSD386 port, VOC stereo support.
-	Ken Kubo		ken@hmcvax.claremont.edu
-		VMS port, VOC stereo support.
-	Frank Gadegast          <phade@cs.tu-berlin.de>
-		Microsoft C 7.0 & C Borland 3.0 ports.
-	David Elliot		<dce@scmc.sony.com>
-		CD-R format support.
-	David Sears		<dns@essnj3.essnjay.com>
-		Linux support.
-	Tom Littlejohn          <tlit@seq1.loc.gov>
-		Raw textual data
-	Boisy G. Pitre          boisy@microware.com
-		OS9 port.
-	Sun Microsystems, Guido Van Rossum
-		CCITT G.711, G.721, G.723 implementation
-	Graeme Gill		graeme@labtam.labtam.oz.au
-		A-LAW format, Good .WAV handling, avg channel
-		expansion.
-	Allen Grider		grider@hfsi.hfsi.com
-		VOC stereo mode, WAV file handling
-	Michel Fingerhut        Michel.Fingerhut@ircam.fr
-		Upgrade 'sf' format to current IRCAM format,
-		float file support.
-	Chris Knight
-		Acorn Archimedes support.
-	Richard Caley           R.Caley@ed.ac.uk
-		Psion WVE handler.
-	Lutz Vieweg		lkv@mania.RoBIN.de
-		MAUD (Amiga) file handler
-	Tim Gardner		timg@tpi.com
-		Windows NT port for V7.
-	Jimen Ching             jiching@wiliki.eng.hawaii.edu
-		Libst porting bugs.
-	Lauren Weinstein	lauren@vortex.com
-		DOS porting, scripts, professional use.
-	Stan Brooks		stabro@megsinet.net
-		Rewrite of resample and polyphase code,
-		DSP filter effect, some test code/scripts.
-	Stuart Daines <sjd.u-net.com>
-		Patches for r/w support of gsm-encoded wav files,
-		cleanup of wav.c.
-	Matthias Nutt
-		Multiple effects from command line.
+Many people contribute new features and bug fixes to SoX.  See the
+ChangeLog file for records of all changes and contributors so far.
--- a/ChangeLog
+++ b/ChangeLog
@@ -2,7 +2,7 @@
 --------------
 
 This file contains a list of all changes starting after the release of
-sox-11gamma.
+sox-11gamma, followed by a list of prior authors and features.
 
 sox-14.x.x	2009-xx-xx
 ----------
@@ -407,7 +407,6 @@
   o Added cmake build files for Win32.  (robs)
 
 
-
 sox-13.0.0	2007-02-11
 ----------
 
@@ -534,8 +533,10 @@
   o Removed the old internally invoked (but mentioned in the man page)
     copy effect.  (robs)
 
+
 sox-12.18.2	2006-09-03
 -----------
+
   o Adding in Debian's disk full fix (#313206).
   o Finally got rid of reference to cleanup() function in
     library.  Applications are now required to detect
@@ -559,6 +560,7 @@
   o Updates to nul file handler to prevent crashes during output.
     Martin Panter (1482869)
 
+
 sox-12.18.1	2006-05-07
 ------------
 
@@ -597,6 +599,7 @@
   o Added support for multiple channels in .dat files.
     (1366634) tomchristie
 
+
 sox-12.17.9	2005-12-05
 -----------
 
@@ -648,8 +651,10 @@
   o Allow aborting SoX with SIGTERM, along with previous SIGINT.
     Norman Ramsey.
 
+
 sox-12.17.8	2005-08-22
 -----------
+
   o noisered effect had compile problems with some compilers.
   o "-x" option was being ignored since 12.17.7.
   o Stuart Brady added support for reading and writing RIFX files (big
@@ -667,8 +672,10 @@
   o In AIFF files, fixed problem were short comments should cause
     AIFF handler to get confused and become misaligned.
 
+
 sox-12.17.7	2004-12-20
 -----------
+
   o Christian Weisgerber sent patches to man page fixes
     and patches for sunaudio driver on openbsd.
   o Default volume for soxmix wrongly set to 0 instead
@@ -695,8 +702,10 @@
     to determine what the noise is (like background hiss on
     cassette tapes).
 
+
 sox-12.17.6	2004-10-13
 -----------
+
   o Changed comment code to always use copies of strings to
     fix bug in WAV handlering freeing argv[] memory.
   o Use calloc() to create ft_t structures so that all
@@ -752,8 +761,10 @@
   o WAV with GSM data now always pads data to even number of bytes.
   o Added support for writing 32-bit audio to AIFF.
 
+
 sox-12.17.5	2004-08-15
 -----------
+
   o Thomas Klausner sent in patches to compile audio drivers under
     NetBSD.
   o Rahul Powar pointed out a memory leak in the WAV file handler.
@@ -791,8 +802,10 @@
   o Rearrange link order of ogg vorbis libraries so that they
     can be compiled as static. (Christian Weisgerbr)
 
+
 sox-12.17.4	2003-03-22
 -----------
+
   o Peter Nyhlen fixed a problem with reading Comments in Ogg Vorbis files.
   o Added install target to allow installing libgsm from main Makefile.
     Leigh Smith.
@@ -836,8 +849,10 @@
     Forte compiler happy.
   o Added support for ALSA 0.9 driver. Jimen Ching
 
+
 sox-12.17.3	2001-12-15
 -----------
+
   o Removed check that prevented pan from being invoked when the
     input and output channels were the same.
   o Ciaran Anscomb added a flush to sunaudio driver after changing
@@ -900,8 +915,10 @@
     support as well as able to read in VOC files using a pipe.  More
     examples added to soxexam file.
 
+
 sox-12.17.2	2001-09-15
 -----------
+
   o Daniel Culbert found and fixed a bug in the polyphase effect
     that occurs on platforms that rand() can return large values.
     The bug resulted in polyphase resampling an audio file to a
@@ -966,8 +983,10 @@
     Also have auto handler now use file extensions if it can't figure
     it out.
 
+
 sox-12.17.1	2000-11-19
 -----------
+
   o Andreas Kies fixed a bug were we were not detecting correctly
     if an output file was seekable.
   o Fixed a bug in the mask effect introduced in 12.17.  If the libc
@@ -997,8 +1016,10 @@
     man pages.  Changed effect so that it computed the time the
     same way that the fade effect does.
 
+
 sox-12.17	2000-09-08
 ---------
+
   o Sox can now read and write w98 compatible gsm .wav files,
     if compiled properly with libgsm.  Thanks go to Stuart
     Daines <sjd.u-net.com> for the gsm-wav patches.
@@ -1019,12 +1040,12 @@
     fast with floating arithmetic as the old (buggy) version
     was with 16-bit integer arithmetic.  The older version
     in sox-12.16 shifted frequencies slightly and was less
-    accurate.
-  o Extensive rewrite of polyphas.c, should be faster and use
-    less memory now.  The sox-12.16 polyphase code had some bugs.
+    accurate.  (Stan Brooks)
+  o Extensive rewrite of polyphas.c, should be faster and use less memory
+    now.  The sox-12.16 polyphase code had some bugs.  (Stan Brooks)
   o New effect 'filter' which is a high-quality DSP lowpass/
     highpass/bandpass filter using windowed sinc function
-    methods, like polyphase and resample.
+    methods, like polyphase and resample.  (Stan Brooks)
   o Jan Paul Schmidt added new low/high/bandpass and bandlimit
     filters to sox.  They have much better results then the old
     versions of low/high/bandpass.  The new effects are all
@@ -1075,6 +1096,7 @@
   o Curt Zirzow added a trim effect to trim off audio data.
   o Updated ALSA driver to support new interface. Jimen Ching
 
+
 sox-12.16	1999-07-13
 ---------
 
@@ -1122,6 +1144,7 @@
   o Fixed core dump when writting AIFF files with no comments.
     (Olaf Pueschel)
 
+
 sox-12.15	1998-10-01
 ---------
 
@@ -1160,6 +1183,7 @@
   o Added -g and -a options for new style support of GSM and ADPCM.  Added
     error checking to various formats to avoid allowing these types.
 
+
 sox-12.14	1998-05-15
 ---------
 
@@ -1203,6 +1227,7 @@
   o There is a known bug in hcom's compress() function.  It is allocating
     memory that can't be free'd under some OS's.  It causes a core dump.
 
+
 sox-11gamma-cb3	1997-03-28
 ---------------
 
@@ -1227,6 +1252,7 @@
   o  Added new sound format, cvsd (Continuously Variable Slope Delta)
      from Thomas Sailer (sailer@ife.ee.ethz.ch).
 
+
 sox-11gamma-cb2	1996-10-04
 ---------------
 
@@ -1239,7 +1265,6 @@
 thanks for Bryan Franklin for sending in a patch when I was
 to busy to even look for it.
 
-
   o  Better play support for 8-bit stereo voc files.  New support
      for outputing both 8-bit and 16-bit stereo voc files.
   o  Built-in support for playing and recording from Linux /dev/dsp.
@@ -1261,3 +1286,68 @@
      "mixer" for Linux) then you will want to edit the play and rec
      to use this.  The current support for it is only in example
      form of how it can be done.
+
+
+List of earlier SoX Contributors
+--------------------------------
+Covering the time from its creation (Jul '91) until sox-11gamma (Feb '95):
+
+  o Lance Norskog		thinman at netcom.com
+	Creator & maintenance
+  o Guido Van Rossum		guido at cwi.nl
+	AU, AIFF, AUTO, HCOM, reverse, many bug fixes
+  o Jef Poskanzer		jef at well.sf.ca.us
+	original code for u-law and delay line
+  o Bill Neisius		bill%solaria at hac2arpa.hac.com 
+	DOS port, 8SVX, Sounder, Soundtool formats
+	Apollo fixes, stat with auto-picker
+  o Rick Richardson		rick at digibd.com
+	WAV and SB driver handlers, fixes
+  o David Champion		dgc3 at midway.uchicago.edu
+	Amiga port 
+  o Pace Willisson		pace at blitz.com
+	Fixes for ESIX
+  o Leigh Smith			leigh at psychok.dialix.oz.au
+	SMP and comment movement support.
+  o David Sanderson		dws at ssec.wisc.edu
+	AIX3.1 fixes
+  o Glenn Lewis			glewis at pcocd2.intel.com
+	AIFF chunking fixes
+  o Brian Campbell		brianc at quantum.qnx.com
+	QNX port and 16-bit fixes
+  o Chris Adams			gt8741 at prism.gatech.edu
+	DOS port fixes
+  o John Kohl			jtkohl at kolvir.elcr.ca.us
+	BSD386 port, VOC stereo support
+  o Ken Kubo			ken at hmcvax.claremont.edu
+	VMS port, VOC stereo support
+  o Frank Gadegast 		phade at cs.tu-berlin.de
+	Microsoft C 7.0 & C Borland 3.0 ports
+  o David Elliot		dce at scmc.sony.com
+	CD-R format support
+  o David Sears			dns at essnj3.essnjay.com
+	Linux support
+  o Tom Littlejohn		tlit at seq1.loc.gov
+	Raw textual data
+  o Boisy G. Pitre 		boisy at microware.com
+	OS9 port
+  o Sun Microsystems, Guido Van Rossum
+	CCITT G.711, G.721, G.723 implementation
+  o Graeme Gill			graeme at labtam.labtam.oz.au
+	A-LAW format, Good .WAV handling, avg channel expansion
+  o Allen Grider		grider at hfsi.hfsi.com
+	VOC stereo mode, WAV file handling
+  o Michel Fingerhut 		Michel.Fingerhut at ircam.fr
+	Upgrade 'sf' format to current IRCAM format.  Float file support.
+  o Chris Knight
+	Achimedes Acorn support
+  o Richard Caley 		R.Caley at ed.ac.uk
+	Psion WVE handler
+  o Lutz Vieweg			lkv at mania.RoBIN.de
+	MAUD (Amiga) file handler
+  o Tim Gardner			timg at tpi.com
+	Windows NT port for V7
+  o Jimen Ching 		jiching at wiliki.eng.hawaii.edu
+	Libst porting bugs
+  o Lauren Weinstein		lauren at vortex.com
+	DOS porting, scripts, professional use
--- a/libsox.3
+++ b/libsox.3
@@ -284,8 +284,30 @@
 stopwrite
 Fix up any file header, or do what needs to be done.
 .SH EFFECTS
-An effects loop has one input and one output stream.
-It has 5 routines.
+Each effect runs with one input and one output stream.
+An effect's implementation comprises six functions that may be called
+to the follow flow diagram:
+.EX
+LOOP (invocations with different parameters)
+  getopts
+  LOOP (invocations with the same parameters)
+    LOOP (channels)
+      start
+    LOOP (whilst there is input audio to process)
+      LOOP (channels)
+        flow
+    LOOP (whilst there is output audio to generate)
+      LOOP (channels)
+        drain
+    LOOP (channels)
+      stop
+  kill
+.EE
+Notes: For some effects, some of the functions may not be needed and can
+be NULL.  An effect that is marked `MCHAN' does not use the LOOP
+(channels) lines and must therefore perform multiple channel processing
+inside the affected functions.  Multiple effect instances may be
+processed (according to the above flow diagram) in parallel.
 .TP 20
 getopts
 is called with a character string argument list for the effect.
@@ -315,19 +337,26 @@
 The echo effect uses this to fade away.
 .TP 20
 stop
-is called when there are no more input samples to process.
-.I stop
-may generate output samples on its own.
-See echo.c for how to do this, 
-and see that what it does is absolutely bogus.
+is called when there are no more input samples and no more output
+samples to process.
+It is typically used to release or close resources (e.g. allocated
+memory or temporary files) that were set-up in
+.IR start .
+See echo.c for an example.
+.TP 20
+kill
+is called to allow resources allocated by
+.I getopts
+to be released.
+See pad.c for an example.
 .SH LINKING
-The method of linking against libsox and libsfx depends on how SoX was
+The method of linking against libsox depends on how SoX was
 built on your system. For a static build, just link against the
 libraries as normal. For a dynamic build, you should use libtool to
 link with the correct linker flags. See the libtool manual for
 details; basically, you use it as:
 .SP
-	libtool --mode=link gcc -o prog /path/to/libsox.la /path/to/libsfx.la
+	libtool --mode=link gcc -o prog /path/to/libsox.la
 .SP
 .SH BUGS
 This manual page is both incomplete and out of date.
@@ -337,8 +366,9 @@
 .SP
 example*.c in the SoX source distribution.
 .SH LICENSE
+Copyright 1998\-2009 by Chris Bagwell and SoX Contributors.
+.br
 Copyright 1991 Lance Norskog and Sundry Contributors.
-Copyright 1998\-2007 by Chris Bagwell and SoX Contributors.
 .SP
 This library is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as published by
@@ -351,5 +381,5 @@
 GNU Lesser General Public License for more details.
 .SH AUTHORS
 Chris Bagwell (cbagwell@users.sourceforge.net).
-Other authors and contributors are listed in the AUTHORS file that
+Other authors and contributors are listed in the ChangeLog file that
 is distributed with the source code.
--- a/sox.1
+++ b/sox.1
@@ -3295,9 +3295,9 @@
 .IR "LADSPA plugins" ,
 http://plugin.org.uk
 .SH LICENSE
-Copyright 1991 Lance Norskog and Sundry Contributors.
+Copyright 1998\-2009 Chris Bagwell and SoX Contributors.
 .br
-Copyright 1998\-2008 Chris Bagwell and SoX Contributors.
+Copyright 1991 Lance Norskog and Sundry Contributors.
 .SP
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -3310,5 +3310,5 @@
 GNU General Public License for more details.
 .SH AUTHORS
 Chris Bagwell (cbagwell@users.sourceforge.net).
-Other authors and contributors are listed in the AUTHORS file that
+Other authors and contributors are listed in the ChangeLog file that
 is distributed with the source code.
--- a/soxformat.7
+++ b/soxformat.7
@@ -658,7 +658,11 @@
 Wikipedia,
 .IR "PLS" ,
 http://en.wikipedia.org/wiki/PLS_(file_format)
+.SH LICENSE
+Copyright 1998\-2009 Chris Bagwell and SoX Contributors.
+.br
+Copyright 1991 Lance Norskog and Sundry Contributors.
 .SH AUTHORS
 Chris Bagwell (cbagwell@users.sourceforge.net).
-Other authors and contributors are listed in the AUTHORS file that
+Other authors and contributors are listed in the ChangeLog file that
 is distributed with the source code.
--- a/soxi.1
+++ b/soxi.1
@@ -103,7 +103,7 @@
 .SP
 The SoX web site at http://sox.sourceforge.net
 .SH LICENSE
-Copyright 2008 by Chris Bagwell and SoX Contributors.
+Copyright 2008-9 by Chris Bagwell and SoX Contributors.
 .SP
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -116,5 +116,5 @@
 GNU General Public License for more details.
 .SH AUTHORS
 Chris Bagwell (cbagwell@users.sourceforge.net).
-Other authors and contributors are listed in the AUTHORS file that
+Other authors and contributors are listed in the ChangeLog file that
 is distributed with the source code.