ref: 7c672fe9aaaaaac4ad5d25fc904dfa0a9d12c23a
parent: ab21f2b775066b8158ac5d90c0dba6a99c7aa2e7
author: robs <robs>
date: Sun Jan 14 09:12:47 EST 2007
Display & man-page clean-ups; soxexam moved to section 7.
--- a/Makefile.am
+++ b/Makefile.am
@@ -10,18 +10,25 @@
# man pages are not considered to be sources, so need to add "dist_"
# prefix to ensure they are added to the distribution.
-dist_man_MANS = sox.1 soxexam.1 libst.3
+dist_man_MANS = sox.1 soxexam.7 libst.3 play.1 rec.1
dist_pkgdata_DATA = sox.txt soxexam.txt libst.txt
+play.1 rec.1: sox.1
+ $(RM) $@ && $(LN_S) $< $@
+
# Rule for making plain text man pages
-%.txt: %.1
+%.txt: %.[1-9]
tbl $(srcdir)/$< | nroff -man -Tascii | col -b > $@
# Rule for making PDF man pages
-%.pdf: %.1
+%.pdf: %.[1-9]
tbl $(srcdir)/$< | groff -man -Tps | ps2pdf - $@
-pdf: sox.pdf soxexam.pdf
+pdf: sox.pdf soxexam.pdf libst.pdf
+
+install-exec-hook:
+ cd $(DESTDIR)$(bindir) && $(RM) play.1 && $(LN_S) sox.1 play.1
+ cd $(DESTDIR)$(bindir) && $(RM) rec.1 && $(LN_S) sox.1 rec.1
# Automatically update libtool script if it gets out-of-date
libtool: $(LIBTOOL_DEPS)
--- a/libst.txt
+++ /dev/null
@@ -1,210 +1,0 @@
-ST(3) ST(3)
-
-
-
-NAME
- libst - Sound Tools : sound sample file and effects libraries.
-
-SYNOPSIS
- #include <st.h>
-
- ft_t st_open_input(const char *path, const st_signalinfo_t *info, const
- char *filetype);
-
- ft_t st_open_output(const char *path, const st_signalinfo_t *info,
- const char *filetype, const char *comment);
-
- st_ssize_t st_read(ft_t ft, st_sample_t *buf, st_ssize_t len);
-
- st_ssize_t st_write(ft_t ft, st_sample_t *buf, st_ssize_t len);
-
- int st_close(ft_t ft);
-
- int st_seek(ft_t ft, st_size_t offset, int whence);
-
- cc file.c -o file libst.a
-
-DESCRIPTION
- Sound Tools is a library of sound sample file format readers/writers
- and sound effects processors. It is mainly developed for use by SoX
- but is useful for any sound application.
-
- st_open_input function opens the file for reading whose name is the
- string pointed to by path and associates an ft_t with it. If info is
- non-NULL then it will be used to specify the data format of the input
- file. This is normally only needed for headerless audio files since
- the information is not stored in the file. If filetype is non-NULL
- then it will be used to specify the file type. If this is not speci-
- fied then the file type is attempted to be derived by looking at the
- file header and/or the filename extension. A special name of "-" can
- be used to read data from stdin.
-
- st_open_output function opens the file for writing whose name is the
- string pointed to by path and associates an ft_t with it. If info is
- non-NULL then it will be used to specify the data format of the output
- file. Since most file formats can write data in different data for-
- mats, this generally has to be specified. The info structure from the
- input format handler can be specified to copy data over in the same
- format. If comment is non-NULL, it will be written in the file header
- for formats that support comments. If filetype is non-NULL then it will
- be used to specify the file type. If this is not specified then the
- file type is attempted to be derived by looking at the filename exten-
- sion. A special name of "-" can be used to write data to stdout.
-
- The function st_read reads len samples in to buf using the format han-
- dler specified by ft. All data read is converted to 32-bit signed sam-
- ples before being placed in to buf. The value of len is specified in
- total samples. If its value is not evenly divisable by the number of
- channels, undefined behavior will occur.
-
- The function st_write writes len samples from buf using the format han-
- dler specified by ft. Data in buf must be 32-bit signed samples and
- will be converted during the write process. The value of len is speci-
- fied in total samples. If its value is not evenly divisable by the
- number of channels, undefined behavior will occur.
-
- The st_close function dissociates the named ft_t from its underlying
- file or set of functions. If the format handler was being used for
- output, any buffered data is written first.
-
- Sound Tools includes skeleton C files to assist you in writing new for-
- mats and effects. The full skeleton driver, skel.c, helps you write
- drivers for a new format which has data structures. The simple skele-
- ton drivers help you write a new driver for raw (headerless) formats,
- or for formats which just have a simple header followed by raw data.
-
-RETURN VALUE
- Upon successful completion st_open_input and st_open_output return a
- ft_t (which is a pointer). Otherwise, NULL is returned. TODO: Need a
- what to return reason for failures. Currently, relies on st_warn to
- print information.
-
- st_read and st_write return the number of samples successfully read or
- written. If an error occurs, or the end-of-file is reached, the return
- value is a short item count or ST_EOF. TODO: st_read does not distigu-
- ish between end-of-ifle and error. Need an feof() and ferror() concept
- to determine which occured.
-
- Upon successful completion st_close returns 0. Otherwise, ST_EOF is
- returned. In either case, any further access (including another call
- to st_close()) to the handler results in undefined behavior. TODO: Need
- a way to return reason for failures. Currently, relies on st_warn to
- print information.
-
- Upon successful completion st_seek returns 0. Otherwise, ST_EOF is
- returned. TODO Need to set a global error and implement st_tell.
-
-ERRORS
- TODO
-
-INTERNALS
- The Sound Tools formats and effects operate on an internal buffer for-
- mat of signed 32-bit longs. The data processing routines are called
- with buffers of these samples, and buffer sizes which refer to the num-
- ber of samples processed, not the number of bytes. File readers trans-
- late the input samples to signed 32-bit integers and return the number
- of samples read. For example, data in linear signed byte format is
- left-shifted 24 bits.
-
- This does cause problems in processing the data. For example:
- *obuf++ = (*ibuf++ + *ibuf++)/2;
- would not mix down left and right channels into one monophonic channel,
- because the resulting samples would overflow 32 bits. Instead, the
- ‘‘avg’’ effects must use:
- *obuf++ = *ibuf++/2 + *ibuf++/2;
-
- Stereo data is stored with the left and right speaker data in succes-
- sive samples. Quadraphonic data is stored in this order: left front,
- right front, left rear, right rear.
-
-FORMATS
- A format is responsible for translating between sound sample files and
- an internal buffer. The internal buffer is store in signed longs with
- a fixed sampling rate. The format operates from two data structures: a
- format structure, and a private structure.
-
- The format structure contains a list of control parameters for the sam-
- ple: sampling rate, data size (8, 16, or 32 bits), encoding (unsigned,
- signed, floating point, etc.), number of sound channels. It also con-
- tains other state information: whether the sample file needs to be
- byte-swapped, whether st_seek() will work, its suffix, its file stream
- pointer, its format pointer, and the private structure for the format .
-
- The private area is just a preallocated data array for the format to
- use however it wishes. It should have a defined data structure and
- cast the array to that structure. See voc.c for the use of a private
- data area. Voc.c has to track the number of samples it writes and when
- finishing, seek back to the beginning of the file and write it out.
- The private area is not very large. The ‘‘echo’’ effect has to mal-
- loc() a much larger area for its delay line buffers.
-
- A format has 6 routines:
-
- startread Set up the format parameters, or read in a data
- header, or do what needs to be done.
-
- read Given a buffer and a length: read up to that many
- samples, transform them into signed long integers,
- and copy them into the buffer. Return the number
- of samples actually read.
-
- stopread Do what needs to be done.
-
- startwrite Set up the format parameters, or write out a data
- header, or do what needs to be done.
-
- write Given a buffer and a length: copy that many samples
- out of the buffer, convert them from signed longs
- to the appropriate data, and write them to the
- file. If it can’t write out all the samples, fail.
-
- stopwrite Fix up any file header, or do what needs to be
- done.
-
-EFFECTS
- An effects loop has one input and one output stream. It has 5 rou-
- tines.
-
- getopts is called with a character string argument list for
- the effect.
-
- start is called with the signal parameters for the input
- and output streams.
-
- flow is called with input and output data buffers, and
- (by reference) the input and output data buffer
- sizes. It processes the input buffer into the out-
- put buffer, and sets the size variables to the num-
- bers of samples actually processed. It is under no
- obligation to read from the input buffer or write
- to the output buffer during the same call. If the
- call returns ST_EOF then this should be used as an
- indication that this effect will no longer read any
- data and can be used to switch to drain mode
- sooner.
-
- drain is called after there are no more input data sam-
- ples. If the effect wishes to generate more data
- samples it copies the generated data into a given
- buffer and returns the number of samples generated.
- If it fills the buffer, it will be called again,
- etc. The echo effect uses this to fade away.
-
- stop is called when there are no more input samples to
- process. 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.
-
-BUGS
- The HCOM format is not re-entrant; it can only be used once in a pro-
- gram.
-
- On errors, the effects currently invoke st_fail and rely on that call-
- ing exit(). They do not currently gracefully fail.
-
- The program/library interface is pretty weak.
-
-
-
-
- September 26 2005 ST(3)
--- a/sox.1
+++ b/sox.1
@@ -25,9 +25,11 @@
\fBsox\fR [\fIglobal-options\fR] [\fIformat-options\fR] \fIinfile1\fR
[[\fIformat-options\fR] \fIinfile2\fR] ... [\fIformat-options\fR] \fIoutfile\fR
[\fIeffect\fR [\fIeffect-options\fR]] ...
+.SP
\fBplay\fR [\fIglobal-options\fR] [\fIformat-options\fR] \fIinfile1\fR
[[\fIformat-options\fR] \fIinfile2\fR] ... [\fIformat-options\fR]
[\fIeffect\fR [\fIeffect-options\fR]] ...
+.SP
\fBrec\fR [\fIglobal-options\fR] [\fIformat-options\fR] \fIoutfile\fR
[\fIeffect\fR [\fIeffect-options\fR]] ...
.fi
@@ -269,7 +271,7 @@
.SP
More examples can found thoughout this manual and in the
separate
-.BR soxexam (1)
+.BR soxexam (7)
manual.
.SH FILE-NAMES
The following may be used in certain circumstances in place of a normal
@@ -289,9 +291,29 @@
.TP
\fB\-\-\fR
This can be used in place of an input or output file-name
-to specify that a `null' file is to be used. See
-.B null
-below for further information.
+to specify that a `null' file is to be used.
+.SP
+Using a null file to input audio is equivalent to
+using a normal audio file that contains an infinite amount
+of silence, and as such is not generally useful unless used
+with an effect that specifies a finite time length
+(such as \fBtrim\fR or \fBsynth\fR).
+.SP
+Using a null file to output audio amounts to discarding the audio
+and is useful mainly with effects that produce information about the
+audio instead of affecting it (such as \fBnoiseprof\fR or \fBstat\fR).
+.SP
+The number of channels and the sampling rate associated with a null file
+are by default 2 and 44\*d1kHz respectively, but these can be overridden
+if necessary by using appropriate command-line format options.
+.SP
+One other use of \fB\-\-\fR is to use it in conjunction with
+.B \-V
+to display information from the audio file header
+without having to read any further into the file, e.g.
+.B sox \-V *.wav \-\-
+will display header information for each `WAV' file in the current
+directory.
.TP
\fB\-e\fR
This is an alias of
@@ -583,10 +605,8 @@
compressing file formats. See the description of the file formats that
use this option for more information.
.SH FILE TYPES
-File types can be set by the file-name extension, the
+File types can be set by the file-name extension or the
.B -t
-option, or the
-.B -n
option (see above for details).
File types that can be determined
by a file-name extension are listed with their names preceded by a dot.
@@ -773,38 +793,6 @@
and look for it under the list of supported file formats as `mp3'.
.SP
.TP
-.B null
-Null file type.
-This is a special file type that can be used when normal
-file reading or writing is not needed to use a particular effect.
-It is selected by using the
-special file-name
-.B \-\-
-in place of an input or output file-name.
-.SP
-Using this file type to input audio is equivalent to
-using a normal audio file that contains an infinite amount
-of silence, and as such is not generally useful unless used
-with an effect that specifies a finite time length
-(such as \fBtrim\fR or \fBsynth\fR).
-.SP
-Using this type to output audio amounts to discarding the audio
-and is useful mainly with effects that produce information about the
-audio instead of affecting it (such as \fBnoiseprof\fR or \fBstat\fR).
-.SP
-The number of channels and the sampling rate associated with a null file
-are by default 2 and 44\*d1kHz respectively, but these can be overridden
-if necessary by using appropriate command-line format options.
-.SP
-One other use of the null file type is to use it in conjunction
-with
-.B \-V
-to display information from the audio file header
-without having to read any further into the file, e.g.
-.B sox \-V *.wav \-\-
-will display header information for each `WAV' file in the current
-directory.
-.TP
\&\fB.ogg\fR, \fB.vorbis\fR
Ogg Vorbis compressed audio.
Ogg Vorbis is a open, patent-free CODEC designed for compressing music
@@ -1780,11 +1768,10 @@
independently.
.SP
Though this effect is used to generate audio, an input file must
-still be specified. This can be used to set the synthesised audio
+still be given. This can be used to set the synthesised audio
length, the number of channels, and the sampling rate, however since the
-input file's audio is not needed, the
-.B null
-file `\fB\-\-\fR' is usually used instead (and the length specified
+input file's audio is not needed, the null
+file `\fB\-\-\fR' is usually given instead (and the length specified
as a parameter to \fBsynth\fR or by another given effect that can has an
associated length).
.SP
@@ -1811,10 +1798,9 @@
.SP
Frequencies can also specified in terms of musical semitones relative to
`middle A' (440Hz); the following could be used to help tune
-a guitar's `low E' string (on a system that supports
-\fBalsa\fR):
+a guitar's `low E' string:
.SP
- sox \-\- \-t alsa default synth sine %\-5
+ play \-\- synth sine %\-5
.SP
The following produces a chord with a pipe-organ sound:
.SP
@@ -1963,9 +1949,8 @@
Please report any bugs found in this version of SoX to the mailing list
(sox-users@lists.sourceforge.net).
.SH SEE ALSO
-.BR play (1),
-.BR rec (1),
-.BR soxexam (1)
+.BR soxexam (7),
+.BR libst (3)
.SP
The SoX web page at http://sox.sourceforge.net
.SH LICENSE
--- a/soxexam.1
+++ /dev/null
@@ -1,333 +1,0 @@
-'\" t
-'\" The line above instructs most `man' programs to invoke tbl
-'\"
-'\" Separate paragraphs; not the same as .PP which resets indent level.
-.de SP
-.if t .sp .5
-.if n .sp
-..
-'\"
-'\" Replacement em-dash for nroff (default is too short).
-.ie n .ds m " -
-.el .ds m \(em
-'\"
-'\" Placeholder macro for if longer nroff arrow is needed.
-.ds RA \(->
-'\"
-'\" Decimal point set slightly raised
-.ds d \v'-.15m'.\v'+.15m'
-'\"
-.TH SoX 1 "January 31, 2007" "soxexam" "Sound eXchange"
-.SH NAME
-soxexam\*mSoX Examples
-.SH SYNOPSIS
-.nf
-\fBsox\fR [\fIglobal-options\fR] [\fIformat-options\fR] \fIinfile1\fR
- [ [\fIformat-options\fR] \fIinfile2\fR ] ... [\fIformat-options\fR] \fIoutfile\fR
- [\fIeffect\fR [\fIeffect-options\fR] ] ...
-.SP
-\fBplay\fR [\fIgeneral-options\fR] [\fIformat-options\fR] \fIinfile1\fR
- [ [\fIformat-options\fR] \fIinfile2\fR ] ...
- [\fIeffect\fR [\fIeffect-options\fR] ] ...
-.SP
-\fBrec\fR [\fIgeneral-options\fR] [\fIformat-options\fR] \fIoutfile\fR
- [\fIeffect\fR [\fIeffect-options\fR] ] ...
-.fi
-.SH DESCRIPTION
-.SS Introduction
-The core problem is that you need some experience in using effects
-in order to say `that any old sound file sounds with effects
-absolutely hip'. There isn't any rule-based system which tell you
-the correct setting of all the parameters for every effect.
-But after some time you will become an expert in using effects.
-.SP
-Here are some examples which can be used with any music sample.
-(For a sample where only a single instrument is playing, extreme
-parameter setting may make well-known `typically' or `classical'
-sounds. Likewise, for drums, vocals or guitars.)
-.SP
-Single effects will be explained and some given parameter settings
-that can be used to understand the theory by listening to the sound file
-with the added effect.
-.SP
-Using multiple effects in parallel or in series can result either
-in a very nice sound or (mostly) in a dramatic overloading in
-variations of sounds such that your ear may follow the sound but
-you will feel unsatisfied. Hence, for the first time using effects
-try to compose them as minimally as possible. We don't regard the
-composition of effects in the examples because too many combinations
-are possible and you really need a very fast machine and a lot of
-memory to play them in real-time.
-.SP
-However, real-time playing of sounds will greatly speed up learning
-and/or tuning the parameter settings for your sounds in order to
-get that `perfect' effect.
-.SP
-Basically, we will use the `play' front-end of SoX since it is easier
-to listen sounds coming out of the speaker or earphone instead
-of looking at cryptic data in sound files.
-.SP
-For easy listening of file.xxx (`xxx' is any sound format):
-.SP
- play file.xxx effect-name effect-parameters
-.SP
-Or more SoX-like (for `dsp' output on a UNIX/Linux computer):
-.SP
- sox file.xxx \-t ossdsp \-w \-s /dev/dsp effect-name effect-parameters
-.SP
-or (for `au' output):
-.SP
- sox file.xxx \-t sunau \-w \-s /dev/audio effect-name effect-parameters
-.SP
-And for date freaks:
-.SP
- sox file.xxx file.yyy effect-name effect-parameters
-.SP
-Additional options can be used. However, in this case, for real-time
-playing you'll need a very fast machine.
-.SP
-Notes:
-.SP
-I played all examples in real-time on a Pentium 100 with 32 MB and
-Linux 2.0.30 using a self-recorded sample ( 3:15 min long in `wav'
-format with 44\*d1 kHz sample rate and stereo 16 bit ).
-The sample should not contain any of the effects. However,
-if you take any recording of a sound track from radio or tape or CD,
-and it sounds like a live concert or ten people are playing the same
-rhythm with their drums or funky-grooves, then take any other sample.
-(Typically, less then four different instruments and no synthesizer
-in the sample is suitable. Likewise, the combination vocal, drums, bass
-and guitar.)
-.SS Echo
-.SP
-An echo effect can be naturally found in the mountains, standing somewhere
-on a mountain and shouting a single word will result in one or more repetitions
-of the word (if not, turn a bit around and try again, or climb to the next
-mountain).
-.SP
-However, the time difference between shouting and repeating is the delay
-(time), its loudness is the decay. Multiple echos can have different delays and
-decays.
-.SP
-It is very popular to use echos to play an instrument with itself together,
-like some guitar players (Brain May from Queen) or vocalists are doing.
-For music samples of more than one instrument, echo can be used to add a
-second sample shortly after the original one.
-.SP
-This will sound as if you are doubling the number of instruments playing
-in the same sample:
-.SP
- play file.xxx echo 0\*d8 0\*d88 60 0\*d4
-.SP
-If the delay is very short, then it sound like a (metallic) robot playing
-music:
-.SP
- play file.xxx echo 0\*d8 0\*d88 6 0\*d4
-.SP
-Longer delay will sound like an open air concert in the mountains:
-.SP
- play file.xxx echo 0\*d8 0\*d9 1000 0\*d3
-.SP
-One mountain more, and:
-.SP
- play file.xxx echo 0\*d8 0\*d9 1000 0\*d3 1800 0\*d25
-.SS Echos
-Like the echo effect, echos stand for `ECHO in Sequel', that is the first echos
-takes the input, the second the input and the first echos, the third the input
-and the first and the second echos, ... and so on.
-Care should be taken using many echos (see introduction); a single echos
-has the same effect as a single echo.
-.SP
-The sample will be bounced twice in symmetric echos:
-.SP
- play file.xxx echos 0\*d8 0\*d7 700 0\*d25 700 0\*d3
-.SP
-The sample will be bounced twice in asymmetric echos:
-.SP
- play file.xxx echos 0\*d8 0\*d7 700 0\*d25 900 0\*d3
-.SP
-The sample will sound as if played in a garage:
-.SP
- play file.xxx echos 0\*d8 0\*d7 40 0\*d25 63 0\*d3
-.SS Chorus
-The chorus effect has its name because it will often be used to make a single
-vocal sound like a chorus. But it can be applied to other instrument samples
-too.
-.SP
-It works like the echo effect with a short delay, but the delay isn't constant.
-The delay is varied using a sinusoidal or triangular modulation. The modulation
-depth defines the range the modulated delay is played before or after the
-delay. Hence the delayed sound will sound slower or faster, that is the delayed
-sound tuned around the original one, like in a chorus where some vocals are
-a bit out of tune.
-.SP
-The typical delay is around 40ms to 60ms, the speed of the modulation is best
-near 0\*d25Hz and the modulation depth around 2ms.
-.SP
-A single delay will make the sample more overloaded:
-.SP
- play file.xxx chorus 0\*d7 0\*d9 55 0\*d4 0\*d25 2 \-t
-.SP
-Two delays of the original samples sound like this:
-.SP
- play file.xxx chorus 0\*d6 0\*d9 50 0\*d4 0\*d25 2 \-t 60 0\*d32 0\*d4 1\*d3 \-s
-.SP
-A big chorus of the sample is (three additional samples):
-.SP
- play file.xxx chorus 0\*d5 0\*d9 50 0\*d4 0\*d25 2 \-t 60 0\*d32 0\*d4 2\*d3 \-t 40 0\*d3 0\*d3 1\*d3 \-s
-.SS Flanger
-The flanger effect is like the chorus effect, but the delay varies between
-0ms and maximal 5ms. It sound like wind blowing, sometimes faster or slower
-including changes of the speed.
-.SP
-The flanger effect is widely used in funk and soul music, where the guitar
-sound varies frequently slow or a bit faster.
-.SP
-Now, let's groove the sample:
-.SP
- play file.xxx flanger
-.SP
-listen carefully between the difference of sinusoidal and triangular modulation:
-.SP
- play file.xxx flanger triangle
-.SS Reverb
-The reverb effect is often used in audience hall which are to small or contain
-too many many visitors which disturb (dampen) the reflection of sound at
-the walls. Reverb will make the sound be perceived as if it were in
-a large hall. You can try the reverb effect in your bathroom or garage or
-sport halls by shouting loud some words. You'll hear the words reflected from
-the walls.
-.SP
-The biggest problem in using the reverb effect is the correct setting of the
-(wall) delays such that the sound is realistic and doesn't sound like music
-playing in a tin can or has overloaded feedback which destroys any illusion
-of playing in a big hall.
-To help you obtain realistic reverb effects, you should decide first how
-long the reverb should take place until it is not loud enough to be registered
-by your ears. This is be done by varying the reverb time `t'. To simulate
-small halls, use 200ms. To simulate large halls, use 1000ms. Clearly,
-the walls of such a hall aren't far
-away, so you should define its setting be given every wall its delay time.
-However, if the wall is to far away for the reverb time, you won't hear the
-reverb, so the nearest wall will be best at `t/4' delay and the farthest
-at `t/2'. You can try other distances as well, but it won't sound very realistic.
-The walls shouldn't stand to close to each other and not in a multiple integer
-distance to each other ( so avoid wall like: 200 and 202, or something
-like 100 and 200 ).
-.SP
-Since audience halls do have a lot of walls, we will start designing one
-beginning with one wall:
-.SP
- play file.xxx reverb 1 600 180
-.SP
-One wall more:
-.SP
- play file.xxx reverb 1 600 180 200
-.SP
-Next two walls:
-.SP
- play file.xxx reverb 1 600 180 200 220 240
-.SP
-Now, why not a futuristic hall with six walls:
-.SP
- play file.xxx reverb 1 600 180 200 220 240 280 300
-.SP
-If you run out of machine power or memory, then stop as many applications
-as possible (every interrupt will consume a lot of CPU time which for
-bigger halls is absolutely necessary).
-.SS Phaser
-The phaser effect is like the flanger effect, but it uses a reverb instead of
-an echo and does phase shifting. You'll hear the difference in the examples
-comparing both effects.
-The delay modulation can be sinusoidal or triangular, preferable is the
-later for multiple instruments. For single instrument sounds,
-the sinusoidal phaser effect will give a sharper phasing effect.
-The decay shouldn't be to close to 1 which will cause dramatic feedback.
-A good range is about 0\*d5 to 0\*d1 for the decay.
-.SP
-We will take a parameter setting as before (gain-out is
-lower since feedback can raise the output dramatically):
-.SP
- play file.xxx phaser 0\*d8 0\*d74 3 0\*d4 0\*d5 \-t
-.SP
-The drunken loudspeaker system (now less alcohol):
-.SP
- play file.xxx phaser 0\*d9 0\*d85 4 0\*d23 1\*d3 \-s
-.SP
-A popular sound of the sample is as follows:
-.SP
- play file.xxx phaser 0\*d89 0\*d85 1 0\*d24 2 \-t
-.SP
-The sample sounds if ten springs are in your ears:
-.SP
- play file.xxx phaser 0\*d6 0\*d66 3 0\*d6 2 \-t
-.SS Compander
-The compander effect allows the dynamic range of a signal to be
-compressed or expanded.
-For most situations, the attack time (response to the music getting
-louder) should be shorter than the decay time because our ears are more
-sensitive to suddenly loud music than to suddenly soft music.
-.SP
-For example, suppose you are listening to Strauss' `Also Sprach
-Zarathustra' in a noisy environment such as a car.
-If you turn up the volume enough to hear the soft passages over the
-road noise, the loud sections will be too loud.
-You could try this:
-.SP
- play file.xxx compand 0\*d3,1 \-90,\-90,\-70,\-70,\-60,\-20,0,0 \-5 0 0\*d2
-.SP
-The transfer function (`\-90,...') says that
-.I very
-soft sounds between \-90 and \-70 decibels (\-90 is about the limit of
-16-bit encoding) will remain unchanged.
-That keeps the compander from boosting the volume on `silent' passages
-such as between movements.
-However, sounds in the range \-60 decibels to 0 decibels (maximum
-volume) will be boosted so that the 60dB dynamic range of the
-original music will be compressed 3-to-1 into a 20dB range, which is
-wide enough to enjoy the music but narrow enough to get around the
-road noise.
-The \-5 dB output gain is needed to avoid clipping (the number is
-inexact, and was derived by experimentation).
-The 0 for the initial volume will work fine for a clip that starts
-with a bit of silence, and the delay of 0\*d2 has the effect of causing
-the compander to react a bit more quickly to sudden volume changes.
-.SS Changing the Rate of Playback
-You can use stretch to change the rate of playback of an audio sample
-while preserving the pitch. For example to play at half the speed:
-.SP
- play file.wav stretch 2
-.SP
-To play a file at twice the speed:
-.SP
- play file.wav stretch 0\*d5
-.SP
-Other related options are `speed' to change the speed of play
-(and changing the pitch accordingly), and pitch, to alter the
-pitch of a sample. For example to speed a sample so it plays in
-half the time (for those Mickey Mouse voices):
-.SP
- play file.wav speed 2
-.SP
-To raise the pitch of a sample 1 while note (100 cents):
-.SP
- play file.wav pitch 100
-.SP
-.SS Reducing noise in a recording
-.SP
-First find a period of silence in your recording, such as the beginning or
-end of a piece. If the first 1\*d5 seconds of the recording are silent, do
-.SP
- sox file.wav \-n trim 0 1\*d5 noiseprof /tmp/profile
-.SP
-Next, use the noisered effect to actually reduce the noise:
-.SP
- play file.wav noisered /tmp/profile
-.SH SEE ALSO
-.BR sox (1),
-.BR play (1),
-.BR rec (1)
-.SH AUTHOR
-This manual was written by Juergen Mueller (jmueller@uia.ua.ac.be).
-Other SoX authors and contributors are listed in the AUTHORS file that
-is distributed with the source code.
--- /dev/null
+++ b/soxexam.7
@@ -1,0 +1,332 @@
+'\" t
+'\" The line above instructs most `man' programs to invoke tbl
+'\"
+'\" Separate paragraphs; not the same as PP which resets indent level.
+.de SP
+.if t .sp .5
+.if n .sp
+..
+'\"
+'\" Replacement em-dash for nroff (default is too short).
+.ie n .ds m " -
+.el .ds m \(em
+'\"
+'\" Placeholder macro for if longer nroff arrow is needed.
+.ds RA \(->
+'\"
+'\" Decimal point set slightly raised
+.ds d \v'-.15m'.\v'+.15m'
+'\"
+.TH SoX 7 "January 31, 2007" "soxexam" "Sound eXchange"
+.SH NAME
+soxexam\*mSoX Examples
+.SH SYNOPSIS
+.nf
+\fBsox\fR [\fIglobal-options\fR] [\fIformat-options\fR] \fIinfile1\fR
+ [ [\fIformat-options\fR] \fIinfile2\fR ] ... [\fIformat-options\fR] \fIoutfile\fR
+ [\fIeffect\fR [\fIeffect-options\fR] ] ...
+.SP
+\fBplay\fR [\fIgeneral-options\fR] [\fIformat-options\fR] \fIinfile1\fR
+ [ [\fIformat-options\fR] \fIinfile2\fR ] ... [\fIformat-options\fR]
+ [\fIeffect\fR [\fIeffect-options\fR] ] ...
+.SP
+\fBrec\fR [\fIgeneral-options\fR] [\fIformat-options\fR] \fIoutfile\fR
+ [\fIeffect\fR [\fIeffect-options\fR] ] ...
+.fi
+.SH DESCRIPTION
+.SS Introduction
+The core problem is that you need some experience in using effects
+in order to say `that any old sound file sounds with effects
+absolutely hip'. There isn't any rule-based system which tell you
+the correct setting of all the parameters for every effect.
+But after some time you will become an expert in using effects.
+.SP
+Here are some examples which can be used with any music sample.
+(For a sample where only a single instrument is playing, extreme
+parameter setting may make well-known `typically' or `classical'
+sounds. Likewise, for drums, vocals or guitars.)
+.SP
+Single effects will be explained and some given parameter settings
+that can be used to understand the theory by listening to the sound file
+with the added effect.
+.SP
+Using multiple effects in parallel or in series can result either
+in a very nice sound or (mostly) in a dramatic overloading in
+variations of sounds such that your ear may follow the sound but
+you will feel unsatisfied. Hence, for the first time using effects
+try to compose them as minimally as possible. We don't regard the
+composition of effects in the examples because too many combinations
+are possible and you really need a very fast machine and a lot of
+memory to play them in real-time.
+.SP
+However, real-time playing of sounds will greatly speed up learning
+and/or tuning the parameter settings for your sounds in order to
+get that `perfect' effect.
+.SP
+Basically, we will use the `play' front-end of SoX since it is easier
+to listen sounds coming out of the speaker or earphone instead
+of looking at cryptic data in sound files.
+.SP
+For easy listening of file.xxx (`xxx' is any sound format):
+.SP
+ play file.xxx effect-name effect-parameters
+.SP
+Or more SoX-like (for `dsp' output on a UNIX/Linux computer):
+.SP
+ sox file.xxx \-t ossdsp \-w \-s /dev/dsp effect-name effect-parameters
+.SP
+or (for `au' output):
+.SP
+ sox file.xxx \-t sunau \-w \-s /dev/audio effect-name effect-parameters
+.SP
+And for date freaks:
+.SP
+ sox file.xxx file.yyy effect-name effect-parameters
+.SP
+Additional options can be used. However, in this case, for real-time
+playing you'll need a very fast machine.
+.SP
+Notes:
+.SP
+I played all examples in real-time on a Pentium 100 with 32 MB and
+Linux 2.0.30 using a self-recorded sample ( 3:15 min long in `wav'
+format with 44\*d1 kHz sample rate and stereo 16 bit ).
+The sample should not contain any of the effects. However,
+if you take any recording of a sound track from radio or tape or CD,
+and it sounds like a live concert or ten people are playing the same
+rhythm with their drums or funky-grooves, then take any other sample.
+(Typically, less then four different instruments and no synthesizer
+in the sample is suitable. Likewise, the combination vocal, drums, bass
+and guitar.)
+.SS Echo
+.SP
+An echo effect can be naturally found in the mountains, standing somewhere
+on a mountain and shouting a single word will result in one or more repetitions
+of the word (if not, turn a bit around and try again, or climb to the next
+mountain).
+.SP
+However, the time difference between shouting and repeating is the delay
+(time), its loudness is the decay. Multiple echos can have different delays and
+decays.
+.SP
+It is very popular to use echos to play an instrument with itself together,
+like some guitar players (Brain May from Queen) or vocalists are doing.
+For music samples of more than one instrument, echo can be used to add a
+second sample shortly after the original one.
+.SP
+This will sound as if you are doubling the number of instruments playing
+in the same sample:
+.SP
+ play file.xxx echo 0\*d8 0\*d88 60 0\*d4
+.SP
+If the delay is very short, then it sound like a (metallic) robot playing
+music:
+.SP
+ play file.xxx echo 0\*d8 0\*d88 6 0\*d4
+.SP
+Longer delay will sound like an open air concert in the mountains:
+.SP
+ play file.xxx echo 0\*d8 0\*d9 1000 0\*d3
+.SP
+One mountain more, and:
+.SP
+ play file.xxx echo 0\*d8 0\*d9 1000 0\*d3 1800 0\*d25
+.SS Echos
+Like the echo effect, echos stand for `ECHO in Sequel', that is the first echos
+takes the input, the second the input and the first echos, the third the input
+and the first and the second echos, ... and so on.
+Care should be taken using many echos (see introduction); a single echos
+has the same effect as a single echo.
+.SP
+The sample will be bounced twice in symmetric echos:
+.SP
+ play file.xxx echos 0\*d8 0\*d7 700 0\*d25 700 0\*d3
+.SP
+The sample will be bounced twice in asymmetric echos:
+.SP
+ play file.xxx echos 0\*d8 0\*d7 700 0\*d25 900 0\*d3
+.SP
+The sample will sound as if played in a garage:
+.SP
+ play file.xxx echos 0\*d8 0\*d7 40 0\*d25 63 0\*d3
+.SS Chorus
+The chorus effect has its name because it will often be used to make a single
+vocal sound like a chorus. But it can be applied to other instrument samples
+too.
+.SP
+It works like the echo effect with a short delay, but the delay isn't constant.
+The delay is varied using a sinusoidal or triangular modulation. The modulation
+depth defines the range the modulated delay is played before or after the
+delay. Hence the delayed sound will sound slower or faster, that is the delayed
+sound tuned around the original one, like in a chorus where some vocals are
+a bit out of tune.
+.SP
+The typical delay is around 40ms to 60ms, the speed of the modulation is best
+near 0\*d25Hz and the modulation depth around 2ms.
+.SP
+A single delay will make the sample more overloaded:
+.SP
+ play file.xxx chorus 0\*d7 0\*d9 55 0\*d4 0\*d25 2 \-t
+.SP
+Two delays of the original samples sound like this:
+.SP
+ play file.xxx chorus 0\*d6 0\*d9 50 0\*d4 0\*d25 2 \-t 60 0\*d32 0\*d4 1\*d3 \-s
+.SP
+A big chorus of the sample is (three additional samples):
+.SP
+ play file.xxx chorus 0\*d5 0\*d9 50 0\*d4 0\*d25 2 \-t 60 0\*d32 0\*d4 2\*d3 \-t 40 0\*d3 0\*d3 1\*d3 \-s
+.SS Flanger
+The flanger effect is like the chorus effect, but the delay varies between
+0ms and maximal 5ms. It sound like wind blowing, sometimes faster or slower
+including changes of the speed.
+.SP
+The flanger effect is widely used in funk and soul music, where the guitar
+sound varies frequently slow or a bit faster.
+.SP
+Now, let's groove the sample:
+.SP
+ play file.xxx flanger
+.SP
+listen carefully between the difference of sinusoidal and triangular modulation:
+.SP
+ play file.xxx flanger triangle
+.SS Reverb
+The reverb effect is often used in audience hall which are to small or contain
+too many many visitors which disturb (dampen) the reflection of sound at
+the walls. Reverb will make the sound be perceived as if it were in
+a large hall. You can try the reverb effect in your bathroom or garage or
+sport halls by shouting loud some words. You'll hear the words reflected from
+the walls.
+.SP
+The biggest problem in using the reverb effect is the correct setting of the
+(wall) delays such that the sound is realistic and doesn't sound like music
+playing in a tin can or has overloaded feedback which destroys any illusion
+of playing in a big hall.
+To help you obtain realistic reverb effects, you should decide first how
+long the reverb should take place until it is not loud enough to be registered
+by your ears. This is be done by varying the reverb time `t'. To simulate
+small halls, use 200ms. To simulate large halls, use 1000ms. Clearly,
+the walls of such a hall aren't far
+away, so you should define its setting be given every wall its delay time.
+However, if the wall is to far away for the reverb time, you won't hear the
+reverb, so the nearest wall will be best at `t/4' delay and the farthest
+at `t/2'. You can try other distances as well, but it won't sound very realistic.
+The walls shouldn't stand to close to each other and not in a multiple integer
+distance to each other ( so avoid wall like: 200 and 202, or something
+like 100 and 200 ).
+.SP
+Since audience halls do have a lot of walls, we will start designing one
+beginning with one wall:
+.SP
+ play file.xxx reverb 1 600 180
+.SP
+One wall more:
+.SP
+ play file.xxx reverb 1 600 180 200
+.SP
+Next two walls:
+.SP
+ play file.xxx reverb 1 600 180 200 220 240
+.SP
+Now, why not a futuristic hall with six walls:
+.SP
+ play file.xxx reverb 1 600 180 200 220 240 280 300
+.SP
+If you run out of machine power or memory, then stop as many applications
+as possible (every interrupt will consume a lot of CPU time which for
+bigger halls is absolutely necessary).
+.SS Phaser
+The phaser effect is like the flanger effect, but it uses a reverb instead of
+an echo and does phase shifting. You'll hear the difference in the examples
+comparing both effects.
+The delay modulation can be sinusoidal or triangular, preferable is the
+later for multiple instruments. For single instrument sounds,
+the sinusoidal phaser effect will give a sharper phasing effect.
+The decay shouldn't be to close to 1 which will cause dramatic feedback.
+A good range is about 0\*d5 to 0\*d1 for the decay.
+.SP
+We will take a parameter setting as before (gain-out is
+lower since feedback can raise the output dramatically):
+.SP
+ play file.xxx phaser 0\*d8 0\*d74 3 0\*d4 0\*d5 \-t
+.SP
+The drunken loudspeaker system (now less alcohol):
+.SP
+ play file.xxx phaser 0\*d9 0\*d85 4 0\*d23 1\*d3 \-s
+.SP
+A popular sound of the sample is as follows:
+.SP
+ play file.xxx phaser 0\*d89 0\*d85 1 0\*d24 2 \-t
+.SP
+The sample sounds if ten springs are in your ears:
+.SP
+ play file.xxx phaser 0\*d6 0\*d66 3 0\*d6 2 \-t
+.SS Compander
+The compander effect allows the dynamic range of a signal to be
+compressed or expanded.
+For most situations, the attack time (response to the music getting
+louder) should be shorter than the decay time because our ears are more
+sensitive to suddenly loud music than to suddenly soft music.
+.SP
+For example, suppose you are listening to Strauss' `Also Sprach
+Zarathustra' in a noisy environment such as a car.
+If you turn up the volume enough to hear the soft passages over the
+road noise, the loud sections will be too loud.
+You could try this:
+.SP
+ play file.xxx compand 0\*d3,1 \-90,\-90,\-70,\-70,\-60,\-20,0,0 \-5 0 0\*d2
+.SP
+The transfer function (`\-90,...') says that
+.I very
+soft sounds between \-90 and \-70 decibels (\-90 is about the limit of
+16-bit encoding) will remain unchanged.
+That keeps the compander from boosting the volume on `silent' passages
+such as between movements.
+However, sounds in the range \-60 decibels to 0 decibels (maximum
+volume) will be boosted so that the 60dB dynamic range of the
+original music will be compressed 3-to-1 into a 20dB range, which is
+wide enough to enjoy the music but narrow enough to get around the
+road noise.
+The \-5 dB output gain is needed to avoid clipping (the number is
+inexact, and was derived by experimentation).
+The 0 for the initial volume will work fine for a clip that starts
+with a bit of silence, and the delay of 0\*d2 has the effect of causing
+the compander to react a bit more quickly to sudden volume changes.
+.SS Changing the Rate of Playback
+You can use stretch to change the rate of playback of an audio sample
+while preserving the pitch. For example to play at half the speed:
+.SP
+ play file.wav stretch 2
+.SP
+To play a file at twice the speed:
+.SP
+ play file.wav stretch 0\*d5
+.SP
+Other related options are `speed' to change the speed of play
+(and changing the pitch accordingly), and pitch, to alter the
+pitch of a sample. For example to speed a sample so it plays in
+half the time (for those Mickey Mouse voices):
+.SP
+ play file.wav speed 2
+.SP
+To raise the pitch of a sample 1 while note (100 cents):
+.SP
+ play file.wav pitch 100
+.SP
+.SS Reducing noise in a recording
+.SP
+First find a period of silence in your recording, such as the beginning or
+end of a piece. If the first 1\*d5 seconds of the recording are silent, do
+.SP
+ sox file.wav \-n trim 0 1\*d5 noiseprof /tmp/profile
+.SP
+Next, use the noisered effect to actually reduce the noise:
+.SP
+ play file.wav noisered /tmp/profile
+.SH SEE ALSO
+.BR sox (1),
+.BR libst (3)
+.SH AUTHOR
+This manual was written by Juergen Mueller (jmueller@uia.ua.ac.be).
+Other SoX authors and contributors are listed in the AUTHORS file that
+is distributed with the source code.
--- a/src/au.c
+++ b/src/au.c
@@ -266,7 +266,6 @@
buf[hdr_size] = '\0';
ft->comment = buf;
- st_report("Input file %s: Sun header info: %s", ft->filename, buf);}
/* Needed for seeking */
ft->length = data_size/ft->signal.size;
--- a/src/sox.c
+++ b/src/sox.c
@@ -269,7 +269,7 @@
if (doopts(fi, argc, argv)) { /* is null file? */if (fi->filetype != NULL && strcmp(fi->filetype, "null") != 0)
- st_warn("Ignoring \"-t %s\".", fi->filetype);+ st_warn("Ignoring '-t %s'.", fi->filetype);fi->filetype = "null";
fi->filename = xstrdup("--"); } else {