| @@ -1,7 +1,7 @@ |
| 1 | '\" t | 1 | '\" t |
| 2 | '\" The line above instructs most `man' programs to invoke tbl | 2 | '\" The line above instructs most `man' programs to invoke tbl |
| 3 | '\" | 3 | '\" |
| 4 | '\" Separate paragraphs; not the same as .PP which resets indent level. | 4 | '\" Separate paragraphs; not the same as PP which resets indent level. |
| 5 | .de SP | 5 | .de SP |
| 6 | .if t .sp .5 | 6 | .if t .sp .5 |
| 7 | .if n .sp | 7 | .if n .sp |
| @@ -271,10 +271,9 @@ More examples can found thoughout this manual and in the · 263 unmodified lines |
| 271 | separate | 271 | separate |
| 272 | .BR soxexam (1) | 272 | .BR soxexam (1) |
| 273 | manual. | 273 | manual. |
| 274 | .SH OPTIONS | 274 | .SH FILE-NAMES |
| 275 | .SS Special File-name Options | 275 | The following may be used in certain circumstances in place of a normal |
| 276 | Each of these options is used in certain circumstances in place of a normal | 276 | file-name on the command line: |
| 277 | file-name on the command line. | | |
| 278 | .TP | 277 | .TP |
| 279 | \fB\-\fR | 278 | \fB\-\fR |
| 280 | SoX can be used in pipeline operations by using the special | 279 | 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 |
| 288 | .B \-t | 287 | .B \-t |
| 289 | below) must also be given. | 288 | below) must also be given. |
| 290 | .TP | 289 | .TP |
| 291 | \fB\-n\fR | 290 | \fB\-\-\fR |
| 292 | This can be used in place of an input or output file-name | 291 | 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 |
| 294 | .B null | 293 | .B null |
| 295 | below for further information. | 294 | below for further information. |
| 296 | .TP | 295 | .TP |
| 297 | \fB\-e\fR | 296 | \fB\-e\fR |
| 298 | This is an alias of | 297 | This is an alias of |
| 299 | .B \-n | 298 | .B \-\- |
| 300 | and is retained for backwards compatibility only. | 299 | 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 |
| 301 | .SS Global Options | 308 | .SS Global Options |
| 302 | These options can be specified on the command line at any point | 309 | These options can be specified on the command line at any point |
| 303 | before the first effect name. | 310 | before the first effect name. |
| @@ -340,11 +347,11 @@ the left and right channels of the stereo file. · 36 unmodified lines |
| 340 | Run in a mode that can be used, in conjunction with the GNU | 347 | Run in a mode that can be used, in conjunction with the GNU |
| 341 | Octave program, to assist with the selection and configuration | 348 | Octave program, to assist with the selection and configuration |
| 342 | of many of the filtering effects. For the first given effect | 349 | 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 |
| 344 | commands to plot the effect's transfer function, and then exit | 351 | commands to plot the effect's transfer function, and then exit |
| 345 | without actually processing any audio. E.g. | 352 | without actually processing any audio. E.g. |
| 346 | .SP | 353 | .SP |
| 347 | sox \-o input-file \-n highpass 1320 > plot.m | 354 | sox \-\-octave input-file \-\- highpass 1320 > plot.m |
| 348 | .br | 355 | .br |
| 349 | octave plot.m | 356 | octave plot.m |
| 350 | .TP | 357 | .TP |
| @@ -766,7 +773,7 @@ This is a special file type that can be used when normal · 415 unmodified lines |
| 766 | file reading or writing is not needed to use a particular effect. | 773 | file reading or writing is not needed to use a particular effect. |
| 767 | It is selected by using the | 774 | It is selected by using the |
| 768 | special file-name | 775 | special file-name |
| 769 | .B \-n | 776 | .B \-\- |
| 770 | in place of an input or output file-name. | 777 | in place of an input or output file-name. |
| 771 | .SP | 778 | .SP |
| 772 | Using this file type to input audio is equivalent to | 779 | Using this file type to input audio is equivalent to |
| @@ -788,7 +795,7 @@ with · 15 unmodified lines |
| 788 | .B \-V | 795 | .B \-V |
| 789 | to display information from the audio file header | 796 | to display information from the audio file header |
| 790 | without having to read any further into the file, e.g. | 797 | without having to read any further into the file, e.g. |
| 791 | .B sox \-V *.wav \-n | 798 | .B sox \-V *.wav \-\- |
| 792 | will display header information for each `WAV' file in the current | 799 | will display header information for each `WAV' file in the current |
| 793 | directory. | 800 | directory. |
| 794 | .TP | 801 | .TP |
| @@ -1052,7 +1059,7 @@ i.e. peaking at the · 257 unmodified lines |
| 1052 | .I center | 1059 | .I center |
| 1053 | frequency and settling around it. | 1060 | frequency and settling around it. |
| 1054 | .SP | 1061 | .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). |
| 1056 | .SP | 1063 | .SP |
| 1057 | See also \fBfilter\fR for a bandpass filter with steeper shoulders. | 1064 | See also \fBfilter\fR for a bandpass filter with steeper shoulders. |
| 1058 | .TP | 1065 | .TP |
| @@ -1063,7 +1070,7 @@ and bandwidth (in Hz, and as determined by the 3dB points) · 4 unmodified lines |
| 1063 | \fIbandwidth\fR. | 1070 | \fIbandwidth\fR. |
| 1064 | The filter rolls off at 6dB per octave (20dB per decade). | 1071 | The filter rolls off at 6dB per octave (20dB per decade). |
| 1065 | .SP | 1072 | .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). |
| 1067 | .TP | 1074 | .TP |
| 1068 | \fBbandreject \fIfrequency bandwidth\fR | 1075 | \fBbandreject \fIfrequency bandwidth\fR |
| 1069 | Apply a band-reject filter. | 1076 | Apply a band-reject filter. |
| @@ -1072,8 +1079,8 @@ See the description of the \fBbandpass\fR effect for details. · 2 unmodified lines |
| 1072 | \fBbass\fR\^|\^\fBtreble \fIgain\fR [\fIfrequency\fR] [\fIslope\fR] | 1079 | \fBbass\fR\^|\^\fBtreble \fIgain\fR [\fIfrequency\fR] [\fIslope\fR] |
| 1073 | Boost or cut the bass (lower) or treble (upper) frequencies of the audio | 1080 | Boost or cut the bass (lower) or treble (upper) frequencies of the audio |
| 1074 | using a two-pole shelving filter with a response similar to that | 1081 | 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 | 1082 | of a standard hi-fi's (Baxandall) tone-controls. This is also |
| 1076 | known as shelving equalisation or EQ. | 1083 | known as shelving equalisation (EQ). |
| 1077 | .SP | 1084 | .SP |
| 1078 | \fIgain\fR gives the dB gain at 0Hz (for \fBbass\fR), or whichever is | 1085 | \fIgain\fR gives the dB gain at 0Hz (for \fBbass\fR), or whichever is |
| 1079 | the lower of \(ap22kHz and the Nyquist frequency (for \fBtreble\fR). Its | 1086 | 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 |
| 1096 | about 0\*d3 (for a gentle slope) to 1 (for a steep slope). The | 1103 | about 0\*d3 (for a gentle slope) to 1 (for a steep slope). The |
| 1097 | default value is 0\*d5. | 1104 | default value is 0\*d5. |
| 1098 | .SP | 1105 | .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). |
| 1100 | .SP | 1107 | .SP |
| 1101 | See also \fBequalizer\fR for a peaking equalisation effect. | 1108 | See also \fBequalizer\fR for a peaking equalisation effect. |
| 1102 | .TP | 1109 | .TP |
| @@ -1169,7 +1176,7 @@ audio-CD format. The frequency response of pre-emphasized · 66 unmodified lines |
| 1169 | recordings is rectified. The filtering is defined in the | 1176 | recordings is rectified. The filtering is defined in the |
| 1170 | standard document ISO 908. | 1177 | standard document ISO 908. |
| 1171 | .SP | 1178 | .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). |
| 1173 | .SP | 1180 | .SP |
| 1174 | .TP | 1181 | .TP |
| 1175 | \fBdither\fR [\fIdepth\fR] | 1182 | \fBdither\fR [\fIdepth\fR] |
| @@ -1210,16 +1217,16 @@ pair gives the delay in milliseconds · 34 unmodified lines |
| 1210 | and the decay (relative to gain-in) of that echo. | 1217 | and the decay (relative to gain-in) of that echo. |
| 1211 | Gain-out is the volume of the output. | 1218 | Gain-out is the volume of the output. |
| 1212 | .TP | 1219 | .TP |
| 1213 | \fBequalizer \fIcentral-frequency Q gain\fR | 1220 | \fBequalizer \fIfrequency Q gain\fR |
| 1214 | Apply a two-pole peaking equalisation (EQ) filter. | 1221 | Apply a two-pole peaking equalisation (EQ) filter. |
| 1215 | This allows modification (\fIgain\fR) of the signal level at and | 1222 | With this filter, the signal-level at and around a selected frequency |
| 1216 | around (\fIQ\fR) a central frequency (\fIcentral-frequency\fR), | 1223 | can be increased or decreased, whilst (unlike band-pass and band-reject |
| 1217 | leaving all other frequencies untouched (unlike | 1224 | filters) that at all other frequencies is unchanged. |
| 1218 | bandpass/bandreject filters). | 1225 | .SP |
| 1219 | .SP | 1226 | \fIfrequency\fR gives the filter's central frequency in Hz, \fIQ\fR its |
| 1220 | \fIcentral-frequency\fR is the filter's central frequency in Hz, \fIQ\fR | 1227 | band-width specified as a `Q-factor' (see |
| 1221 | its `Q-factor' (see http://en.wikipedia.org/wiki/Q_factor), and | 1228 | http://en.wikipedia.org/wiki/Q_factor), and \fIgain\fR the required gain |
| 1222 | \fIgain\fR is the gain or attenuation in dB. | 1229 | or attenuation in dB. |
| 1223 | Beware of | 1230 | Beware of |
| 1224 | .B Clipping | 1231 | .B Clipping |
| 1225 | when using a positive \fIgain\fR. | 1232 | when using a positive \fIgain\fR. |
| @@ -1227,7 +1234,7 @@ when using a positive \fIgain\fR. · 1 unmodified line |
| 1227 | In order to produce complex equalisation curves, this effect | 1234 | In order to produce complex equalisation curves, this effect |
| 1228 | can be given several times, each with a different central frequency. | 1235 | can be given several times, each with a different central frequency. |
| 1229 | .SP | 1236 | .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). |
| 1231 | .SP | 1238 | .SP |
| 1232 | See also \fBbass\fR and \fBtreble\fR for shelving equalisation effects. | 1239 | See also \fBbass\fR and \fBtreble\fR for shelving equalisation effects. |
| 1233 | .TP | 1240 | .TP |
| @@ -1310,7 +1317,7 @@ Apply a single-pole recursive high-pass or low-pass filter with · 76 unmodified lines |
| 1310 | 3dB point \fIfrequency\fR. | 1317 | 3dB point \fIfrequency\fR. |
| 1311 | The filters roll off at 6dB per octave (20dB per decade). | 1318 | The filters roll off at 6dB per octave (20dB per decade). |
| 1312 | .SP | 1319 | .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). |
| 1314 | .SP | 1321 | .SP |
| 1315 | See also \fBfilter\fR for filters with a sharper cutoff. | 1322 | See also \fBfilter\fR for filters with a sharper cutoff. |
| 1316 | .TP | 1323 | .TP |
| @@ -1319,7 +1326,7 @@ Apply a two-pole Butterworth high-pass or low-pass filter with · 2 unmodified lines |
| 1319 | 3dB point \fIfrequency\fR. | 1326 | 3dB point \fIfrequency\fR. |
| 1320 | The filters roll off at 12dB per octave (40dB per decade). | 1327 | The filters roll off at 12dB per octave (40dB per decade). |
| 1321 | .SP | 1328 | .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). |
| 1323 | .TP | 1330 | .TP |
| 1324 | \fBlowp \fIfrequency\fR | 1331 | \fBlowp \fIfrequency\fR |
| 1325 | Apply a low-pass filter. | 1332 | Apply a low-pass filter. |
| @@ -1771,45 +1778,49 @@ still be specified. This can be used to set the synthesised audio · 445 unmodified lines |
| 1771 | length, the number of channels, and the sampling rate, however since the | 1778 | length, the number of channels, and the sampling rate, however since the |
| 1772 | input file's audio is not needed, the | 1779 | input file's audio is not needed, the |
| 1773 | .B null | 1780 | .B null |
| 1774 | file `\fB\-n\fR' is usually used instead (and the length specified | 1781 | file `\fB\-\-\fR' is usually used instead (and the length specified |
| 1775 | as a parameter to \fBsynth\fR). | 1782 | as a parameter to \fBsynth\fR or by another given effect that can has an |
| | 1783 | associated length). |
| 1776 | .SP | 1784 | .SP |
| 1777 | For example, the following produces a 3 second, 44\*d1kHz, | 1785 | For example, the following produces a 3 second, 44\*d1kHz, |
| 1778 | stereo audio file containing a sine-wave swept from 300 to 3300Hz. | 1786 | stereo audio file containing a sine-wave swept from 300 to 3300Hz. |
| 1779 | .SP | 1787 | .SP |
| 1780 | sox \-n output.au synth 3 sine 300\-3300 | 1788 | sox \-\- output.au synth 3 sine 300\-3300 |
| 1781 | .SP | 1789 | .SP |
| 1782 | This produces an 8kHz mono version: | 1790 | This produces an 8kHz mono version: |
| 1783 | .SP | 1791 | .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 |
| 1785 | .SP | 1793 | .SP |
| 1786 | Multiple channels can be synthesised by specifying the set of | 1794 | Multiple channels can be synthesised by specifying the set of |
| 1787 | parameters shown between braces multiple times; | 1795 | parameters shown between braces multiple times; |
| 1788 | the following puts the swept tone in the left channel and adds `brown' | 1796 | the following puts the swept tone in the left channel and adds `brown' |
| 1789 | noise in the right: | 1797 | noise in the right: |
| 1790 | .SP | 1798 | .SP |
| 1791 | sox \-n output.au synth 3 sine 300\-3300 brownnoise | 1799 | sox \-\- output.au synth 3 sine 300\-3300 brownnoise |
| 1792 | .SP | 1800 | .SP |
| 1793 | The following example shows how two synth effects can be cascaded | 1801 | The following example shows how two synth effects can be cascaded |
| 1794 | to create a more complex waveform: | 1802 | to create a more complex waveform: |
| 1795 | .SP | 1803 | .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 |
| 1797 | .SP | 1805 | .SP |
| 1798 | Frequencies can also specified in terms of musical semitones relative to | 1806 | Frequencies can also specified in terms of musical semitones relative to |
| 1799 | `middle A' (440Hz); the following could be used to help tune | 1807 | `middle A' (440Hz); the following could be used to help tune |
| 1800 | a guitar's `low E' string (on a system that supports | 1808 | a guitar's `low E' string (on a system that supports |
| 1801 | \fBalsa\fR): | 1809 | \fBalsa\fR): |
| 1802 | .SP | 1810 | .SP |
| 1803 | sox \-n \-t alsa default synth sine %\-5 | 1811 | sox \-\- \-t alsa default synth sine %\-5 |
| 1804 | .SP | 1812 | .SP |
| 1805 | The following produces a chord with a pipe-organ sound: | 1813 | The following produces a chord with a pipe-organ sound: |
| 1806 | .SP | 1814 | .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 |
| 1808 | .SP | 1816 | .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 |
| 1810 | is a high chance of clipping when using the audio subsequently, so | 1819 | is a high chance of clipping when using the audio subsequently, so |
| 1811 | in most cases, you will want to follow this effect with the \fBvol\fR | 1820 | 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.) |
| 1813 | .SP | 1824 | .SP |
| 1814 | A detailed description of each | 1825 | A detailed description of each |
| 1815 | .B synth | 1826 | .B synth |
| @@ -1831,7 +1842,12 @@ for specifying sample counts is the number of samples with the letter · 15 unmodified lines |
| 1831 | .SP | 1842 | .SP |
| 1832 | \fIfreq\fR/\fIfreq2\fR are the frequencies at the beginning/end of | 1843 | \fIfreq\fR/\fIfreq2\fR are the frequencies at the beginning/end of |
| 1833 | synthesis in Hz or, if preceded with `%', semitones relative to A | 1844 | 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. |
| 1835 | .SP | 1851 | .SP |
| 1836 | \fIoff\fR is the bias (DC-offset) of the signal in percent; default=0. | 1852 | \fIoff\fR is the bias (DC-offset) of the signal in percent; default=0. |
| 1837 | .SP | 1853 | .SP |
| @@ -1849,7 +1865,7 @@ begins; default=50. exp: the amplitude in percent; default=100. · 11 unmodified lines |
| 1849 | ends; default=60. | 1865 | ends; default=60. |
| 1850 | .TP | 1866 | .TP |
| 1851 | \fBtreble \fIgain\fR [\fIfrequency\fR] [\fIslope\fR] | 1867 | \fBtreble \fIgain\fR [\fIfrequency\fR] [\fIslope\fR] |
| 1852 | Apply a treble tone control effect. | 1868 | Apply a treble tone-control effect. |
| 1853 | See the description of the \fBbass\fR effect for details. | 1869 | See the description of the \fBbass\fR effect for details. |
| 1854 | .TP | 1870 | .TP |
| 1855 | \fBtrim \fIstart\fR [\fIlength\fR] | 1871 | \fBtrim \fIstart\fR [\fIlength\fR] |