History

Replaced -n with --; it's much better visually, -n was all too easily lost in a sea of other parameters.

robs committed 19 years ago

Commit e4b349b1 parent 7cefbde6 files · +84 −65Browse files

Unified · Split

6 files
  1. ChangeLog +1 −1
  2. scripts/audiogen +3 −3
  3. sox.1 +58 −42
  4. src/sox.c +19 −17
  5. src/st_i.h +1 −0
  6. src/tests.sh +2 −2
ChangeLog+1−1
@@ -60,7 +60,7 @@ sox-12.18.3 · 59 unmodified lines
6060 for backwards compatibility by "resample".
6161 o Preview mode now removed, as all it did was use rate rather than
6262 resample, and rate has been removed.
63− o Improved synth usage (by introducing -n option) and improved synth
63+ o Improved synth usage (by introducing --) and improved the synth
6464 entry in the man-page. (robs)
6565 o Documented the butterworth filter effects. (robs)
6666 o Added command line options for specifying the output file
scripts/audiogen+3−3
@@ -2,8 +2,8 @@ · 1 unmodified line
22 #
33 # usage:audiogen <rate> <channels> <filename> <length> <audio generator options>
44 #
5−# Example of using the "nul" file handler along with "synth" effect
6−# to generate audio data. Nul file handler pipes a stream of null
5+# Example of using the "null" file handler along with "synth" effect
6+# to generate audio data. Null file handler pipes a stream of null
77 # data non-stop. Synth effect overrides it with its own data and
88 # stops based on length parameter.
99
@@ -21,4 +21,4 @@ shift · 11 unmodified lines
2121 filename=$1
2222 shift
2323
24−sox -s -w -t nul -r $rate -c $channels /dev/null $filename synth $*
24+sox -s -w -r $rate -c $channels -- $filename synth $*
sox.1+58−42
@@ -1,7 +1,7 @@
11 '\" t
22 '\" The line above instructs most `man' programs to invoke tbl
33 '\"
4−'\" Separate paragraphs; not the same as .PP which resets indent level.
4+'\" Separate paragraphs; not the same as PP which resets indent level.
55 .de SP
66 .if t .sp .5
77 .if n .sp
@@ -271,10 +271,9 @@ More examples can found thoughout this manual and in the · 263 unmodified lines
271271 separate
272272 .BR soxexam (1)
273273 manual.
274−.SH OPTIONS
275−.SS Special File-name Options
276−Each of these options is used in certain circumstances in place of a normal
277−file-name on the command line.
274+.SH FILE-NAMES
275+The following may be used in certain circumstances in place of a normal
276+file-name on the command line:
278277 .TP
279278 \fB\-\fR
280279 SoX can be used in pipeline operations by using the special
@@ -288,16 +287,24 @@ Note that when using this option, the file-type (see · 7 unmodified lines
288287 .B \-t
289288 below) must also be given.
290289 .TP
291−\fB\-n\fR
290+\fB\-\-\fR
292291 This can be used in place of an input or output file-name
293−to specify that the `null' file type should be used. See
292+to specify that a `null' file is to be used. See
294293 .B null
295294 below for further information.
296295 .TP
297296 \fB\-e\fR
298297 This is an alias of
299−.B \-n
298+.B \-\-
300299 and is retained for backwards compatibility only.
300+.PP
301+.B N.B.
302+Giving SoX an input or output file-name that is the same as a SoX
303+effect-name will not work since SoX will treat it as an effect
304+specification. The only work-around to this is to avoid such
305+file-names; however, this is generally not difficult since most audio
306+file-names have a file-name `extension', whilst effect-names do not.
307+.SH OPTIONS
301308 .SS Global Options
302309 These options can be specified on the command line at any point
303310 before the first effect name.
@@ -340,11 +347,11 @@ the left and right channels of the stereo file. · 36 unmodified lines
340347 Run in a mode that can be used, in conjunction with the GNU
341348 Octave program, to assist with the selection and configuration
342349 of many of the filtering effects. For the first given effect
343−that supports the \fB\-o\fR option, SoX will output Octave
350+that supports the \fB\-\-octave\fR option, SoX will output Octave
344351 commands to plot the effect's transfer function, and then exit
345352 without actually processing any audio. E.g.
346353 .SP
347− sox \-o input-file \-n highpass 1320 > plot.m
354+ sox \-\-octave input-file \-\- highpass 1320 > plot.m
348355 .br
349356 octave plot.m
350357 .TP
@@ -766,7 +773,7 @@ This is a special file type that can be used when normal · 415 unmodified lines
766773 file reading or writing is not needed to use a particular effect.
767774 It is selected by using the
768775 special file-name
769−.B \-n
776+.B \-\-
770777 in place of an input or output file-name.
771778 .SP
772779 Using this file type to input audio is equivalent to
@@ -788,7 +795,7 @@ with · 15 unmodified lines
788795 .B \-V
789796 to display information from the audio file header
790797 without having to read any further into the file, e.g.
791−.B sox \-V *.wav \-n
798+.B sox \-V *.wav \-\-
792799 will display header information for each `WAV' file in the current
793800 directory.
794801 .TP
@@ -1052,7 +1059,7 @@ i.e. peaking at the · 257 unmodified lines
10521059 .I center
10531060 frequency and settling around it.
10541061 .SP
1055−This effect supports the \fB\-o\fR global option (see above).
1062+This effect supports the \fB\-\-octave\fR global option (see above).
10561063 .SP
10571064 See also \fBfilter\fR for a bandpass filter with steeper shoulders.
10581065 .TP
@@ -1063,7 +1070,7 @@ and bandwidth (in Hz, and as determined by the 3dB points) · 4 unmodified lines
10631070 \fIbandwidth\fR.
10641071 The filter rolls off at 6dB per octave (20dB per decade).
10651072 .SP
1066−These effects support the \fB\-o\fR global option (see above).
1073+These effects support the \fB\-\-octave\fR global option (see above).
10671074 .TP
10681075 \fBbandreject \fIfrequency bandwidth\fR
10691076 Apply a band-reject filter.
@@ -1072,8 +1079,8 @@ See the description of the \fBbandpass\fR effect for details. · 2 unmodified lines
10721079 \fBbass\fR\^|\^\fBtreble \fIgain\fR [\fIfrequency\fR] [\fIslope\fR]
10731080 Boost or cut the bass (lower) or treble (upper) frequencies of the audio
10741081 using a two-pole shelving filter with a response similar to that
1075−of a standard hi-fi's (Baxandall) tone controls. This is also
1076−known as shelving equalisation or EQ.
1082+of a standard hi-fi's (Baxandall) tone-controls. This is also
1083+known as shelving equalisation (EQ).
10771084 .SP
10781085 \fIgain\fR gives the dB gain at 0Hz (for \fBbass\fR), or whichever is
10791086 the lower of \(ap22kHz and the Nyquist frequency (for \fBtreble\fR). Its
@@ -1096,7 +1103,7 @@ steep the filter's shelf transition is. Its useful range is · 16 unmodified lines
10961103 about 0\*d3 (for a gentle slope) to 1 (for a steep slope). The
10971104 default value is 0\*d5.
10981105 .SP
1099−These effects support the \fB\-o\fR global option (see above).
1106+These effects support the \fB\-\-octave\fR global option (see above).
11001107 .SP
11011108 See also \fBequalizer\fR for a peaking equalisation effect.
11021109 .TP
@@ -1169,7 +1176,7 @@ audio-CD format. The frequency response of pre-emphasized · 66 unmodified lines
11691176 recordings is rectified. The filtering is defined in the
11701177 standard document ISO 908.
11711178 .SP
1172−This effect supports the \fB\-o\fR global option (see above).
1179+This effect supports the \fB\-\-octave\fR global option (see above).
11731180 .SP
11741181 .TP
11751182 \fBdither\fR [\fIdepth\fR]
@@ -1210,16 +1217,16 @@ pair gives the delay in milliseconds · 34 unmodified lines
12101217 and the decay (relative to gain-in) of that echo.
12111218 Gain-out is the volume of the output.
12121219 .TP
1213−\fBequalizer \fIcentral-frequency Q gain\fR
1220+\fBequalizer \fIfrequency Q gain\fR
12141221 Apply a two-pole peaking equalisation (EQ) filter.
1215−This allows modification (\fIgain\fR) of the signal level at and
1216−around (\fIQ\fR) a central frequency (\fIcentral-frequency\fR),
1217−leaving all other frequencies untouched (unlike
1218−bandpass/bandreject filters).
1219−.SP
1220−\fIcentral-frequency\fR is the filter's central frequency in Hz, \fIQ\fR
1221−its `Q-factor' (see http://en.wikipedia.org/wiki/Q_factor), and
1222−\fIgain\fR is the gain or attenuation in dB.
1222+With this filter, the signal-level at and around a selected frequency
1223+can be increased or decreased, whilst (unlike band-pass and band-reject
1224+filters) that at all other frequencies is unchanged.
1225+.SP
1226+\fIfrequency\fR gives the filter's central frequency in Hz, \fIQ\fR its
1227+band-width specified as a `Q-factor' (see
1228+http://en.wikipedia.org/wiki/Q_factor), and \fIgain\fR the required gain
1229+or attenuation in dB.
12231230 Beware of
12241231 .B Clipping
12251232 when using a positive \fIgain\fR.
@@ -1227,7 +1234,7 @@ when using a positive \fIgain\fR. · 1 unmodified line
12271234 In order to produce complex equalisation curves, this effect
12281235 can be given several times, each with a different central frequency.
12291236 .SP
1230−This effect supports the \fB\-o\fR global option (see above).
1237+This effect supports the \fB\-\-octave\fR global option (see above).
12311238 .SP
12321239 See also \fBbass\fR and \fBtreble\fR for shelving equalisation effects.
12331240 .TP
@@ -1310,7 +1317,7 @@ Apply a single-pole recursive high-pass or low-pass filter with · 76 unmodified lines
13101317 3dB point \fIfrequency\fR.
13111318 The filters roll off at 6dB per octave (20dB per decade).
13121319 .SP
1313−These effects support the \fB\-o\fR global option (see above).
1320+These effects support the \fB\-\-octave\fR global option (see above).
13141321 .SP
13151322 See also \fBfilter\fR for filters with a sharper cutoff.
13161323 .TP
@@ -1319,7 +1326,7 @@ Apply a two-pole Butterworth high-pass or low-pass filter with · 2 unmodified lines
13191326 3dB point \fIfrequency\fR.
13201327 The filters roll off at 12dB per octave (40dB per decade).
13211328 .SP
1322−These effects support the \fB\-o\fR global option (see above).
1329+These effects support the \fB\-\-octave\fR global option (see above).
13231330 .TP
13241331 \fBlowp \fIfrequency\fR
13251332 Apply a low-pass filter.
@@ -1771,45 +1778,49 @@ still be specified. This can be used to set the synthesised audio · 445 unmodified lines
17711778 length, the number of channels, and the sampling rate, however since the
17721779 input file's audio is not needed, the
17731780 .B null
1774−file `\fB\-n\fR' is usually used instead (and the length specified
1775−as a parameter to \fBsynth\fR).
1781+file `\fB\-\-\fR' is usually used instead (and the length specified
1782+as a parameter to \fBsynth\fR or by another given effect that can has an
1783+associated length).
17761784 .SP
17771785 For example, the following produces a 3 second, 44\*d1kHz,
17781786 stereo audio file containing a sine-wave swept from 300 to 3300Hz.
17791787 .SP
1780− sox \-n output.au synth 3 sine 300\-3300
1788+ sox \-\- output.au synth 3 sine 300\-3300
17811789 .SP
17821790 This produces an 8kHz mono version:
17831791 .SP
1784− sox \-r 8000 \-c 1 \-n output.au synth 3 sine 300\-3300
1792+ sox \-r 8000 \-c 1 \-\- output.au synth 3 sine 300\-3300
17851793 .SP
17861794 Multiple channels can be synthesised by specifying the set of
17871795 parameters shown between braces multiple times;
17881796 the following puts the swept tone in the left channel and adds `brown'
17891797 noise in the right:
17901798 .SP
1791− sox \-n output.au synth 3 sine 300\-3300 brownnoise
1799+ sox \-\- output.au synth 3 sine 300\-3300 brownnoise
17921800 .SP
17931801 The following example shows how two synth effects can be cascaded
17941802 to create a more complex waveform:
17951803 .SP
1796− sox \-n output.au synth 0\*d5 sine 200\-500 synth 0\*d5 sine fmod 700\-100
1804+ sox \-\- output.au synth 0\*d5 sine 200\-500 synth 0\*d5 sine fmod 700\-100
17971805 .SP
17981806 Frequencies can also specified in terms of musical semitones relative to
17991807 `middle A' (440Hz); the following could be used to help tune
18001808 a guitar's `low E' string (on a system that supports
18011809 \fBalsa\fR):
18021810 .SP
1803− sox \-n \-t alsa default synth sine %\-5
1811+ sox \-\- \-t alsa default synth sine %\-5
18041812 .SP
18051813 The following produces a chord with a pipe-organ sound:
18061814 .SP
1807− sox \-c4 \-n \-c1 Am7.au synth sin %0 sin %3 sin %7 sin %10 avg fade q 0\*d1 1 0\*d1
1815+ sox \-c4 \-\- \-c1 Am7.au synth sin %0 sin %3 sin %7 sin %10 avg fade q 0\*d1 1 0\*d1
18081816 .SP
1809−N.B. This effect generates audio at maximum volume, which means that there
1817+.B N.B.
1818+This effect generates audio at maximum volume, which means that there
18101819 is a high chance of clipping when using the audio subsequently, so
18111820 in most cases, you will want to follow this effect with the \fBvol\fR
1812−effect to select a suitable attenuation.
1821+effect to prevent this from happening. (See also
1822+.B Clipping
1823+above.)
18131824 .SP
18141825 A detailed description of each
18151826 .B synth
@@ -1831,7 +1842,12 @@ for specifying sample counts is the number of samples with the letter · 15 unmodified lines
18311842 .SP
18321843 \fIfreq\fR/\fIfreq2\fR are the frequencies at the beginning/end of
18331844 synthesis in Hz or, if preceded with `%', semitones relative to A
1834−(440Hz); for both, default=%0. Not used for noise.
1845+(440Hz); for both, default=%0. If
1846+.I freq2
1847+is given, then
1848+.I len
1849+must also have been given.
1850+Not used for noise.
18351851 .SP
18361852 \fIoff\fR is the bias (DC-offset) of the signal in percent; default=0.
18371853 .SP
@@ -1849,7 +1865,7 @@ begins; default=50. exp: the amplitude in percent; default=100. · 11 unmodified lines
18491865 ends; default=60.
18501866 .TP
18511867 \fBtreble \fIgain\fR [\fIfrequency\fR] [\fIslope\fR]
1852−Apply a treble tone control effect.
1868+Apply a treble tone-control effect.
18531869 See the description of the \fBbass\fR effect for details.
18541870 .TP
18551871 \fBtrim \fIstart\fR [\fIlength\fR]
src/sox.c+19−17
@@ -260,15 +260,13 @@ int main(int argc, char **argv) · 259 unmodified lines
260260 * found. */
261261 while (optind < argc && !is_effect_name(argv[optind])) {
262262 file_info_t fi = make_file_info();
263− struct file_info fi_none;
263+ struct file_info fi_none = *fi;
264264
265265 if (file_count >= MAX_FILES) {
266266 st_fail("Too many filenames; maximum is %d input files and 1 output file", MAX_INPUT_FILES);
267267 exit(1);
268268 }
269269
270− fi_none = *fi;
271−
272270 if (doopts(fi, argc, argv)) { /* is null file? */
273271 if (fi->filetype != NULL && strcmp(fi->filetype, "null") != 0)
274272 st_warn("Ignoring \"-t %s\".", fi->filetype);
@@ -416,7 +414,7 @@ static char * read_comment_file(char const * const filename) · 141 unmodified lines
416414 return result;
417415 }
418416
419−static char *getoptstr = "+abc:defghilmnoqr:st:uv:wxABC:DLMNRSUV::X12348";
417+static char *getoptstr = "+abc:defghilmoqr:st:uv:wxABC:DLMNRSUV::X12348";
420418
421419 static struct option long_options[] =
422420 {
@@ -447,15 +445,20 @@ static struct option long_options[] = · 24 unmodified lines
447445
448446 static bool doopts(file_info_t fi, int argc, char **argv)
449447 {
450− bool isnull = false;
451− int option_index, c;
452−
453− while ((c = getopt_long(argc, argv, getoptstr, long_options, &option_index)) != -1) {
448+ while (true) {
449+ int option_index;
454450 int i; /* Needed since scanf %u allows negative numbers :( */
455451 char dummy; /* To check for extraneous chars in optarg. */
456452
457− switch (c) {
458− case 0: /* Long options with no short equivalent. */
453+ if (strcmp(argv[optind], "--") == 0) {
454+ ++optind;
455+ return true; /* I.e. is null file. */
456+ }
457+ switch (getopt_long(argc, argv, getoptstr, long_options, &option_index)) {
458+ case -1: /* @ one of: file-name, effect name, or end of arg-list. */
459+ return false; /* I.e. not null file. */
460+
461+ case 0: /* Long options with no short equivalent. */
459462 switch (option_index) {
460463 case 0:
461464 fi->comment = read_comment_file(optarg);
@@ -509,8 +512,8 @@ static bool doopts(file_info_t fi, int argc, char **argv) · 47 unmodified lines
509512 repeatable_random = true;
510513 break;
511514
512− case 'e': case 'n':
513− isnull = true; /* Is null file. */
515+ case 'e': /* Deprecated in favour of -- */
516+ return true; /* I.e. is null file. */
514517 break;
515518
516519 case 'h': case '?':
@@ -624,8 +627,6 @@ static bool doopts(file_info_t fi, int argc, char **argv) · 107 unmodified lines
624627 break;
625628 }
626629 }
627−
628− return isnull;
629630 }
630631
631632 static int compare_input(ft_t ft1, ft_t ft2)
@@ -1623,13 +1624,13 @@ static void usage(char const * message) · 991 unmodified lines
16231624 printf("Version %s\n\n", st_version());
16241625 if (message)
16251626 fprintf(stderr, "Failed: %s\n\n", message);
1626− printf("Usage: [gopts] [fopts] %s outfile [effect [effopts]...]\n\n",
1627+ printf("Usage summary: [gopts] [fopts] %s outfile [effect [effopts]...]\n\n",
16271628 combine_method == SOX_MIX ? "infile1 [fopts] infile2 [fopts]" : "infile [fopts]");
16281629 printf(
16291630 "Special filenames:\n"
16301631 "\n"
16311632 "- stdin (infile) or stdout (outfile)\n"
1632− "-n, -e use the null file handler; for use with e.g. synth & stat\n"
1633+ "-- use the null file handler; for use with e.g. synth & stat\n"
16331634 "\n"
16341635 "Global options (gopts) (can be specified at any point before the first effect):\n"
16351636 "\n"
@@ -1639,7 +1640,7 @@ static void usage(char const * message) · 3 unmodified lines
16391640 " display usage of specified effect. use 'all' to display all\n"
16401641 "-m, --mix mix multiple input files (instead of concatenating)\n"
16411642 "-M, --merge merge multiple input files (instead of concatenating)\n"
1642− "-o generate Octave commands to plot response of filter effect\n"
1643+ "--octave generate Octave commands to plot response of filter effect\n"
16431644 "--play output to the default sound device; set if SoX run as `play'\n"
16441645 "-q run in quiet mode; opposite of -S\n"
16451646 "--rec input from the default sound device; set if SoX run as `rec'\n"
@@ -1670,6 +1671,7 @@ static void usage(char const * message) · 24 unmodified lines
16701671 "-B/-L force endian type to big/little\n"
16711672 "-s/-u/-U/-A/ sample encoding: signed/unsigned/u-law/A-law\n"
16721673 " -a/-i/-g/-f ADPCM/IMA_ADPCM/GSM/floating point\n"
1674+
16731675 "-1/-2/-3/-4/-8 sample size in bytes\n"
16741676 "-b/-w/-l/-d aliases for -1/-2/-4/-8 (byte, word, long, double-long)\n"
16751677 "-v volume input file volume adjustment factor (real number)\n"
src/st_i.h+1−0
@@ -193,6 +193,7 @@ extern const st_format_t *st_flac_format_fn(void); · 192 unmodified lines
193193 #endif
194194 extern const st_format_t *st_gsm_format_fn(void);
195195 extern const st_format_t *st_hcom_format_fn(void);
196+extern const st_format_t *st_ima_format_fn(void);
196197 extern const st_format_t *st_maud_format_fn(void);
197198 extern const st_format_t *st_mp3_format_fn(void);
198199 extern const st_format_t *st_nul_format_fn(void);
src/tests.sh+2−2
@@ -34,7 +34,7 @@ convertToAndFrom () { · 33 unmodified lines
3434 if [ "${format1_skip}x" = "x" -a "${from_skip}x" = "x" ] ; then
3535 getFormat ${format1}; format1Text=$formatText; format1Flags=$formatFlags
3636 getFormat $1; format2Text=$formatText; format2Flags=$formatFlags
37− ./sox -c $channels -r $rate -n $format1Flags input.$format1 synth $samples's' sin 300-3300 noise trapezium
37+ ./sox -c $channels -r $rate -- $format1Flags input.$format1 synth $samples's' sin 300-3300 noise trapezium
3838 ./sox $verbose -r $rate -c $channels $format1Flags input.$format1 $format2Flags intermediate.$1
3939 ./sox $verbose -r $rate -c $channels $format2Flags intermediate.$1 $format1Flags output.$format1
4040
@@ -115,7 +115,7 @@ do_multichannel_formats · 74 unmodified lines
115115 do_twochannel_formats
116116 do_singlechannel_formats
117117
118−./sox -c 1 -n output.ub synth .01 vol .5
118+./sox -c 1 -- output.ub synth .01 vol .5
119119 if [ `wc -c <output.ub` = 441 ]; then
120120 echo "ok synth size"
121121 else

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t