| @@ -1483,34 +1483,72 @@ would typically be an number of seconds, and · 1482 unmodified lines |
| 1483 | 1483 | .I leeway |
| 1484 | 1484 | should be set to zero. |
| 1485 | 1485 | .TP |
| 1486 | | −\fBstat\fR [\fB\-s \fIn\fR] [\fB\-rms\fR] [\fB\-freq\fR] [\fB\-v\fR] [\fB\-d\fR] |
| 1487 | | −Do a statistical check on the input file, |
| 1488 | | −and print results on the standard error file. Audio is passed |
| 1489 | | −unmodified through the SoX processing chain. |
| 1486 | +\fBstat\fR [\fB\-s \fIscale\fR] [\fB\-rms\fR] [\fB\-freq\fR] [\fB\-v\fR] [\fB\-d\fR] |
| 1487 | +Display time and frequency domain statistical information about the audio. |
| 1488 | +Audio is passed unmodified through the SoX processing chain. |
| 1490 | 1489 | .SP |
| 1491 | | −The `Volume Adjustment:' field in the statistics |
| 1492 | | −gives you the parameter to the |
| 1493 | | −.B \-v |
| 1494 | | −.I number |
| 1495 | | −which will make the audio as loud as possible without clipping. |
| 1490 | +The information is output to the `standard error' (stderr) stream and is |
| 1491 | +calculated, where |
| 1492 | +.I n |
| 1493 | +is the duration of the audio in samples, |
| 1494 | +.I c |
| 1495 | +is the number of audio channels, |
| 1496 | +.I r |
| 1497 | +is the audio sample rate, and |
| 1498 | +.I x\s-2\dk\u\s0 |
| 1499 | +represents the PCM value (in the range \-1 to +1 by default) of each successive |
| 1500 | +sample in the audio, |
| 1501 | +as follows: |
| 1502 | +.TS |
| 1503 | +center; |
| 1504 | +lI l l. |
| 1505 | +Samples read \fIn\fR\^\(mu\^\fIc\fR \ |
| 1506 | +Length (seconds) \fIn\fR\^\(di\^\fIr\fR |
| 1507 | +Scaled by \ See \-s below. |
| 1508 | +Maximum amplitude max(\fIx\s-2\dk\u\s0\fR) T{ |
| 1509 | +The maximum sample value in the audio; usually this will be a positive number. |
| 1510 | +T} |
| 1511 | +Minimum amplitude min(\fIx\s-2\dk\u\s0\fR) T{ |
| 1512 | +The minimum sample value in the audio; usually this will be a negative number. |
| 1513 | +T} |
| 1514 | +Midline amplitude \(12\^min(\fIx\s-2\dk\u\s0\fR)\^+\^\(12\^max(\fIx\s-2\dk\u\s0\fR) |
| 1515 | +Mean norm \(S1/\s-2n\s+2\^\(*S\^\^\(br\^\fIx\s-2\dk\u\s0\fR\^\(br\^ T{ |
| 1516 | +The average of the absolute value of each sample in the audio. |
| 1517 | +T} |
| 1518 | +Mean amplitude \(S1/\s-2n\s+2\^\(*S\^\fIx\s-2\dk\u\s0\fR T{ |
| 1519 | +The average of each sample in the audio. If this figure is non-zero, then it indicates the |
| 1520 | +presence of a D.C. offset (which could be removed using the |
| 1521 | +.B dcshift |
| 1522 | +effect). |
| 1523 | +T} |
| 1524 | +RMS amplitude \(sr(\(S1/\s-2n\s+2\^\(*S\^\fIx\s-2\dk\u\s0\fR\(S2) T{ |
| 1525 | +The level of a D.C. signal that would have the same power |
| 1526 | +as the audio's average power. |
| 1527 | +T} |
| 1528 | +Maximum delta max(\^\(br\^\fIx\s-2\dk\u\s0\fR\^\-\^\fIx\s-2\dk\-1\u\s0\fR\^\(br\^) |
| 1529 | +Minimum delta min(\^\(br\^\fIx\s-2\dk\u\s0\fR\^\-\^\fIx\s-2\dk\-1\u\s0\fR\^\(br\^) |
| 1530 | +Mean delta \(S1/\s-2n\-1\s+2\^\(*S\^\^\(br\^\fIx\s-2\dk\u\s0\fR\^\-\^\fIx\s-2\dk\-1\u\s0\fR\^\(br\^ |
| 1531 | +RMS delta \(sr(\(S1/\s-2n\-1\s+2\^\(*S\^(\fIx\s-2\dk\u\s0\fR\^\-\^\fIx\s-2\dk\-1\u\s0\fR)\(S2) |
| 1532 | +Rough frequency \ In Hz. |
| 1533 | +Volume Adjustment \ T{ |
| 1534 | +The parameter to the |
| 1535 | +.B vol |
| 1536 | +effect which would make the audio as loud as possible without clipping. |
| 1496 | 1537 | Note: See the discussion on |
| 1497 | 1538 | .B Clipping |
| 1498 | 1539 | in |
| 1499 | 1540 | .BR sox (1) |
| 1500 | | −for reasons why it is rarely a good idea to actually do this. |
| 1501 | | −.SP |
| 1502 | | −The option |
| 1503 | | −.B \-v |
| 1504 | | −will print out the `Volume Adjustment:' field's value only and |
| 1505 | | −return. This could be of use in scripts to auto convert the |
| 1506 | | −volume. |
| 1541 | +for reasons why it is rarely a good idea actually to do this. |
| 1542 | +T} |
| 1543 | +.TE |
| 1544 | +.DT |
| 1507 | 1545 | .SP |
| 1508 | 1546 | The |
| 1509 | 1547 | .B \-s |
| 1510 | | −option is used to scale the input data by a given factor. The default value |
| 1511 | | −of |
| 1512 | | −.I n |
| 1513 | | −is the maximum value of a signed long integer (7fffffff in hexadecimal). |
| 1548 | +option can be used to scale the input data by a given factor. |
| 1549 | +The default value of |
| 1550 | +.I scale |
| 1551 | +is 2147483647 (i.e. the maximum value of a 32-bit signed integer). |
| 1514 | 1552 | Internal effects |
| 1515 | 1553 | always work with signed long PCM data and so the value should relate to this |
| 1516 | 1554 | fact. |
| @@ -1521,15 +1559,21 @@ option will convert all output average values to `root mean square' · 4 unmodified lines |
| 1521 | 1559 | format. |
| 1522 | 1560 | .SP |
| 1523 | 1561 | The |
| 1562 | +.B \-v |
| 1563 | +option displays only the `Volume Adjustment' value. |
| 1564 | +.SP |
| 1565 | +The |
| 1524 | 1566 | .B \-freq |
| 1525 | | −option calculates the input's power spectrum and prints it to standard error. |
| 1567 | +option calculates the input's power spectrum (4096 point DFT) instead of the |
| 1568 | +statistics listed above. |
| 1526 | 1569 | .SP |
| 1527 | | −There is also an optional parameter |
| 1570 | +The |
| 1528 | 1571 | .B \-d |
| 1529 | | −that will print out a hex dump of the |
| 1530 | | −audio from the internal buffer that is in 32-bit signed PCM data. |
| 1531 | | −This is mainly only of use in tracking down endian problems that |
| 1532 | | −creep in to SoX on cross-platform versions. |
| 1572 | +option |
| 1573 | +displays a hex dump of the 32-bit signed PCM data |
| 1574 | +audio in SoX's internal buffer. |
| 1575 | +This is mainly used to help track down endian problems that |
| 1576 | +sometimes occur in cross-platform versions of SoX. |
| 1533 | 1577 | .TP |
| 1534 | 1578 | \fBswap\fR [\fI1 2\fR | \fI1 2 3 4\fR] |
| 1535 | 1579 | Swap channels in multi-channel audio files. Optionally, you may |