neulab/tldr huggingface dataset:
-w name Window: Hann (default), Hamming, Bartlett, Rectangular, Kaiser or Dolph.  The spectrogram is produced using the Discrete Fourier Transform (DFT) algorithm.  A significant parameter to this algorithm is the choice of `window function'.  By default, SoX uses the Hann window which has good all-round frequency-resolution and dynamic-range properties.  For better frequency resolution (but lower dynamic-range), select a Hamming window; for higher dynamic-range (but poorer frequency-resolution), select a Dolph window.  Kaiser, Bartlett and Rectangular windows are also available.
-W num Window adjustment parameter.  This can be used to make small adjustments to the Kaiser or Dolph window shape.  A positive number (up to ten) increases its dynamic range, a negative number decreases it.
-s     Allow slack overlapping of DFT windows.  This can, in some cases, increase image sharpness and give greater adherence to the -x value, but at the expense of a little spectral loss.
-m     Creates a monochrome spectrogram (the default is colour).
-h     Selects a high-colour palette - less visually pleasing than the default colour palette, but it may make it easier to differentiate different levels.  If this option is used in conjunction with -m, the result will be a hybrid monochrome/colour palette.
-p num Permute the colours in a colour or hybrid palette.  The num parameter, from 1 (the default) to 6, selects the permutation.
-l     Creates a `printer friendly' spectrogram with a light background (the default has a dark background).
-a     Suppress the display of the axis lines.  This is sometimes useful in helping to discern artefacts at the spectrogram edges.
-r     Raw spectrogram: suppress the display of axes and legends.
-A     Selects an alternative, fixed colour-set.  This is provided only for compatibility with spectrograms produced by another package.  It should not normally be used as it has some problems, not least, a lack of differentiation at the bottom end which results in masking of low-level artefacts.
-t text Set the image title - text to display above the spectrogram.
-c text Set (or clear) the image comment - text to display below and to the left of the spectrogram.
-o file Name of the spectrogram output PNG file, default `spectrogram.png'.  If `-' is given, the spectrogram will be sent to standard output (stdout).
Advanced Options: In order to process a smaller section of audio without affecting other effects or the output signal (unlike when the trim effect is used), the following options may be used.
-d duration This option sets the X-axis resolution such that audio with the given duration (a time specification) fits the selected (or default) X-axis width.  For example, sox input.mp3 output.wav -n spectrogram -d 1:00 stats creates a spectrogram showing the first minute of the audio, whilst the stats effect is applied to the entire audio signal.
See also -X for an alternative way of setting the X-axis resolution.
-S position(=) Start the spectrogram at the given point in the audio stream.  For example sox input.aiff output.wav spectrogram -S 1:00 creates a spectrogram showing all but the first minute of the audio (the output file, however, receives the entire audio stream).
For the ability to perform off-line processing of spectral data, see the stat effect.
speed factor[c] Adjust the audio speed (pitch and tempo together).  factor is either the ratio of the new speed to the old speed: greater than 1 speeds up, less than 1 slows down, or, if appended with the letter `c', the number of cents (i.e. 100ths of a semitone) by which the pitch (and tempo) should be adjusted: greater than 0 increases, less than 0 decreases.
Technically, the speed effect only changes the sample rate information, leaving the samples themselves untouched.  The rate effect is invoked automatically to resample to the output sample rate, using its default quality/speed.  For higher quality or higher speed resampling, in addition to the speed effect, specify the rate effect with the desired quality option.
See also the bend, pitch, and tempo effects.
splice  [-h|-t|-q] { position(=)[,excess[,leeway]] } Splice together audio sections.  This effect provides two things over simple audio concatenation: a (usually short) cross-fade is applied at the join, and a wave similarity comparison is made to help determine the best place at which to make the join.
One of the options -h, -t, or -q may be given to select the fade envelope as half-cosine wave (the default), triangular (a.k.a. linear), or quarter-cosine wave respectively.
Type   Audio          Fade level       Transitions t     correlated     constant gain    abrupt h     correlated     constant gain    smooth q     uncorrelated   constant power   smooth
To perform a splice, first use the trim effect to select the audio sections to be joined together.  As when performing a tape splice, the end of the section to be spliced onto should be trimmed with a small excess (default 0.005 seconds) of audio after the ideal joining point.  The beginning of the audio section to splice on should be trimmed with the same excess (before the ideal joining point), plus an additional leeway (default 0.005 seconds).  Any time specification may be used for these parameters.  SoX should then be invoked with the two audio sections as input files and the splice effect given with the position at which to perform the splice - this is length of the first audio section (including the excess).
The following diagram uses the tape analogy to illustrate the splice operation.  The effect simulates the diagonal cuts and joins the two pieces:
length1   excess -----------><---> _________   :   :  _________________ \  :   : :\     ` \ :   : : \     ` \:   : :  \     ` *   : :   * - - * \  : :   :\     ` \ : :   : \     ` _______________\: :   :  \_____`____ :   :   :     : <--->   <-----> excess  leeway
where * indicates the joining points.
For example, a long song begins with two verses which start (as determined e.g. by using the play command with the trim (start) effect) at times 0:30.125 and 1:03.432.  The following commands cut out the first verse: sox too-long.wav part1.wav trim 0 30.130 (5 ms excess, after the first verse starts) sox too-long.wav part2.wav trim 1:03.422 (5 ms excess plus 5 ms leeway, before the second verse starts) sox part1.wav part2.wav just-right.wav splice 30.130 For another example, the SoX command play "|sox -n -p synth 1 sin %1" "|sox -n -p synth 1 sin %3" generates and plays two notes, but there is a nasty click at the transition; the click can be removed by splicing instead of concatenating the audio, i.e. by appending splice 1 to the command. (Clicks at the beginning and end of the audio can be removed by preceding the splice effect with fade q .01 2 .01).
Provided your arithmetic is good enough, multiple splices can be performed with a single splice invocation.  For example: #!/bin/sh # Audio Copy and Paste Over # acpo infile copy-start copy-stop paste-over-start outfile # No chained time specifications allowed for the parameters # (i.e. such that contain +/-). e=0.005                      # Using default excess l=$e                         # and leeway. sox "$1" piece.wav trim $2-$e-$l =$3+$e sox "$1" part1.wav trim 0 $4+$e sox "$1" part2.wav trim $4+$3-$2-$e-$l sox part1.wav piece.wav part2.wav "$5" \ splice $4+$e +$3-$2+$e+$l+$e In the above Bourne shell script, two splices are used to `copy and paste' audio.
It is also possible to use this effect to perform general cross- fades, e.g. to join two songs.  In this case, excess would typically be an number of seconds, the -q option would typically be given (to select an `equal power' cross-fade), and leeway should be zero (which is the default if -q is given).  For example, if f1.wav and f2.wav are audio files to be cross-faded, then sox f1.wav f2.wav out.wav splice -q $(soxi -D f1.wav),3 cross-fades the files where the point of equal loudness is 3 seconds before the end of f1.wav, i.e. the total length of the cross-fade is 2 × 3 = 6 seconds (Note: the $(...) notation is POSIX shell).
stat [-s scale] [-rms] [-freq] [-v] [-d] Display time and frequency domain statistical information about the audio.  Audio is passed unmodified through the SoX processing chain.
The information is output to the `standard error' (stderr) stream and is calculated, where n is the duration of the audio in samples, c is the number of audio channels, r is the audio sample rate, and xk represents the PCM value (in the range -1 to +1 by default) of each successive sample in the audio, as follows:
Samples read        n×c Length (seconds)    n÷r Scaled by                                 See -s below. Maximum amplitude   max(xk)               The maximum sample value in the audio; usually this will be a positive number. Minimum amplitude   min(xk)               The minimum sample value in the audio; usually this will be a negative number. Midline amplitude   ½min(xk)+½max(xk) Mean norm           ¹/nΣ│xk│              The average of the absolute value of each sample in the audio. Mean amplitude      ¹/nΣxk                The average of each sample in the audio. If this figure is non-zero, then it indicates the presence of a D.C. offset (which could be removed using the dcshift effect). RMS amplitude       √(¹/nΣxk²)            The level of a D.C. signal that would have the same power as the audio's average power. Maximum delta       max(│xk-xk-1│) Minimum delta       min(│xk-xk-1│) Mean delta          ¹/n-1Σ│xk-xk-1│
RMS delta           √(¹/n-1Σ(xk-xk-1)²) Rough frequency                           In Hz. Volume Adjustment                         The parameter to the vol effect which would make the audio as loud as possible without clipping. Note: See the discussion on Clipping above for reasons why it is rarely a good idea actually to do this.
Note that the delta measurements are not applicable for multi- channel audio.
The -s option can be used to scale the input data by a given factor.  The default value of scale is 2147483647 (i.e. the maximum value of a 32-bit signed integer).  Internal effects always work with signed long PCM data and so the value should relate to this fact.
The -rms option will convert all output average values to `root mean square' format.
The -v option displays only the `Volume Adjustment' value.
The -freq option calculates the input's power spectrum (4096 point DFT) instead of the statistics listed above.  This should only be used with a single channel audio file.
The -d option displays a hex dump of the 32-bit signed PCM data audio in SoX's internal buffer.  This is mainly used to help track down endian problems that sometimes occur in cross-platform versions of SoX.
See also the stats effect.
stats [-b bits|-x bits|-s scale] [-w window-time] Display time domain statistical information about the audio channels; audio is passed unmodified through the SoX processing chain.  Statistics are calculated and displayed for each audio channel and, where applicable, an overall figure is also given.
For example, for a typical well-mastered stereo music file:
Overall     Left      Right DC offset   0.000803 -0.000391  0.000803 Min level  -0.750977 -0.750977 -0.653412 Max level   0.708801  0.708801  0.653534 Pk lev dB      -2.49     -2.49     -3.69 RMS lev dB    -19.41    -19.13    -19.71 RMS Pk dB     -13.82    -13.82    -14.38 RMS Tr dB     -85.25    -85.25    -82.66 Crest factor       -      6.79      6.32 Flat factor     0.00      0.00      0.00 Pk count           2         2         2 Bit-depth      16/16     16/16     16/16 Num samples    7.72M Length s     174.973 Scale max   1.000000 Window s       0.050
DC offset, Min level, and Max level are shown, by default, in the range ±1.  If the -b (bits) options is given, then these three measurements will be scaled to a signed integer with the given number of bits; for example, for 16 bits, the scale would be -32768 to +32767.  The -x option behaves the same way as -b except that the signed integer values are displayed in hexadecimal.  The -s option scales the three measurements by a given floating-point number.
Pk lev dB and RMS lev dB are standard peak and RMS level measured in dBFS.  RMS Pk dB and RMS Tr dB are peak and trough values for RMS level measured over a short window (default 50ms).
Crest factor is the standard ratio of peak to RMS level (note: not in dB).
Flat factor is a measure of the flatness (i.e. consecutive samples with the same value) of the signal at its peak levels (i.e. either Min level, or Max level).  Pk count is the number of occasions (not the number of samples) that the signal attained either Min level, or Max level.
The right-hand Bit-depth figure is the standard definition of bit- depth i.e. bits less significant than the given number are fixed at zero.  The left-hand figure is the number of most significant bits that are fixed at zero (or one for negative numbers) subtracted from the right-hand figure (the number subtracted is directly related to Pk lev dB).
For multi-channel audio, an overall figure for each of the above measurements is given and derived from the channel figures as follows: DC offset: maximum magnitude; Max level, Pk lev dB, RMS Pk dB, Bit-depth: maximum; Min level, RMS Tr dB: minimum; RMS lev dB, Flat factor, Pk count: average; Crest factor: not applicable.
Length s is the duration in seconds of the audio, and Num samples is equal to the sample-rate multiplied by Length.  Scale Max is the scaling applied to the first three measurements; specifically, it is the maximum value that could apply to Max level.  Window s is the length of the window used for the peak and trough RMS measurements.
See also the stat effect.
swap   Swap stereo channels.  If the input is not stereo, pairs of channels are swapped, and a possible odd last channel passed through.  E.g., for seven channels, the output order will be 2, 1, 4, 3, 6, 5, 7.
See also remix for an effect that allows arbitrary channel selection and ordering (and mixing).
stretch factor [window fade shift fading] Change the audio duration (but not its pitch).  This effect is broadly equivalent to the tempo effect with (factor inverted and) search set to zero, so in general, its results are comparatively poor; it is retained as it can sometimes out-perform tempo for small factors.
factor of stretching: >1 lengthen, <1 shorten duration.  window size is in ms.  Default is 20ms.  The fade option, can be `lin'. shift ratio, in [0 1].  Default depends on stretch factor. 1 to shorten, 0.8 to lengthen.  The fading ratio, in [0 0.5].  The amount of a fade's default depends on factor and shift.
See also the tempo effect.
synth [-j KEY] [-n] [len [off [ph [p1 [p2 [p3]]]]]] {[type] [combine] [[%]freq[k][:|+|/|-[%]freq2[k]]] [off [ph [p1 [p2 [p3]]]]]} This effect can be used to generate fixed or swept frequency audio tones with various wave shapes, or to generate wide-band noise of various `colours'.  Multiple synth effects can be cascaded to produce more complex waveforms; at each stage it is possible to choose whether the generated waveform will be mixed with, or modulated onto the output from the previous stage.  Audio for each channel in a multi-channel audio file can be synthesised independently.
Though this effect is used to generate audio, an input file must still be given, the characteristics of which will 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 normally needed, a `null file' (with the special name -n) is often given instead (and the length specified as a parameter to synth or by another given effect that has an associated length).
For example, the following produces a 3 second, 48kHz, audio file containing a sine-wave swept from 300 to 3300 Hz: sox -n output.wav synth 3 sine 300-3300 and this produces an 8 kHz version: sox -r 8000 -n output.wav synth 3 sine 300-3300 Multiple channels can be synthesised by specifying the set of parameters shown between braces multiple times; the following puts the swept tone in the left channel and adds `brown' noise in the right: sox -n output.wav synth 3 sine 300-3300 brownnoise The following example shows how two synth effects can be cascaded to create a more complex waveform: play -n synth 0.5 sine 200-500 synth 0.5 sine fmod 700-100 Frequencies can also be given in `scientific' note notation, or, by prefixing a `%' character, as a number of semitones relative to `middle A' (440 Hz).  For example, the following could be used to help tune a guitar's low `E' string: play -n synth 4 pluck %-29 or with a (Bourne shell) loop, the whole guitar: for n in E2 A2 D3 G3 B3 E4; do play -n synth 4 pluck $n repeat 2; done See the delay effect (above) and the reference to `SoX scripting examples' (below) for more synth examples.
N.B.  This effect generates audio at maximum volume (0dBFS), which means that there is a high chance of clipping when using the audio subsequently, so in many cases, you will want to follow this effect with the gain effect to prevent this from happening. (See also Clipping above.)  Note that, by default, the synth effect incorporates the functionality of gain -h (see the gain effect for details); synth's -n option may be given to disable this behaviour.
A detailed description of each synth parameter follows:
len is the length of audio to synthesise (any time specification); a value of 0 indicated to use the input length, which is also the default.
type is one of sine, square, triangle, sawtooth, trapezium, exp, [white]noise, tpdfnoise, pinknoise, brownnoise, pluck; default=sine.
combine is one of create, mix, amod (amplitude modulation), fmod (frequency modulation); default=create.
freq/freq2 are the frequencies at the beginning/end of synthesis in Hz or, if preceded with `%', semitones relative to A (440 Hz); alternatively, `scientific' note notation (e.g. E2) may be used. The default frequency is 440Hz.  By default, the tuning used with the note notations is `equal temperament'; the -j KEY option selects `just intonation', where KEY is an integer number of semitones relative to A (so for example, -9 or 3 selects the key of C), or a note in scientific notation.
If freq2 is given, then len must also have been given and the generated tone will be swept between the given frequencies.  The two given frequencies must be separated by one of the characters `:', `+', `/', or `-'.  This character is used to specify the sweep function as follows:
:      Linear: the tone will change by a fixed number of hertz per second.
+      Square: a second-order function is used to change the tone.
/      Exponential: the tone will change by a fixed number of semitones per second.
-      Exponential: as `/', but initial phase always zero, and stepped (less smooth) frequency changes.
Not used for noise.
off is the bias (DC-offset) of the signal in percent; default=0.
ph is the phase shift in percentage of 1 cycle; default=0.  Not used for noise.
p1 is the percentage of each cycle that is `on' (square), or `rising' (triangle, exp, trapezium); default=50 (square, triangle, exp), default=10 (trapezium), or sustain (pluck); default=40.
p2 (trapezium): the percentage through each cycle at which `falling' begins; default=50. exp: the amplitude in multiples of 2dB; default=50, or tone-1 (pluck); default=20.
p3 (trapezium): the percentage through each cycle at which `falling' ends; default=60, or tone-2 (pluck); default=90.
tempo [-q] [-m|-s|-l] factor [segment [search [overlap]]] Change the audio playback speed but not its pitch. This effect uses the WSOLA algorithm. The audio is chopped up into segments which are then shifted in the time domain and overlapped (cross- faded) at points where their waveforms are most similar as determined by measurement of `least squares'.
By default, linear searches are used to find the best overlapping points. If the optional -q parameter is given, tree searches are used instead. This makes the effect work more quickly, but the result may not sound as good. However, if you must improve the processing speed, this generally reduces the sound quality less than reducing the search or overlap values.
The -m option is used to optimize default values of segment, search and overlap for music processing.
The -s option is used to optimize default values of segment, search and overlap for speech processing.
The -l option is used to optimize default values of segment, search and overlap for `linear' processing that tends to cause more noticeable distortion but may be useful when factor is close to 1.
If -m, -s, or -l is specified, the default value of segment will be calculated based on factor, while default search and overlap values are based on segment. Any values you provide still override these default values.
factor gives the ratio of new tempo to the old tempo, so e.g. 1.1 speeds up the tempo by 10%, and 0.9 slows it down by 10%.
The optional segment parameter selects the algorithm's segment size in milliseconds.  If no other flags are specified, the default value is 82 and is typically suited to making small changes to the tempo of music. For larger changes (e.g. a factor of 2), 41 ms may give a better result.  The -m, -s, and -l flags will cause the segment default to be automatically adjusted based on factor.  For example using -s (for speech) with a tempo of 1.25 will calculate a default segment value of 32.
The optional search parameter gives the audio length in milliseconds over which the algorithm will search for overlapping points.  If no other flags are specified, the default value is 14.68.  Larger values use more processing time and may or may not produce better results.  A practical maximum is half the value of segment. Search can be reduced to cut processing time at the risk of degrading output quality. The -m, -s, and -l flags will cause the search default to be automatically adjusted based on segment.
The optional overlap parameter gives the segment overlap length in milliseconds.  Default value is 12, but -m, -s, or -l flags automatically adjust overlap based on segment size. Increasing overlap increases processing time and may increase quality. A practical maximum for overlap is the value of search, with overlap typically being (at least) a little smaller then search.
See also speed for an effect that changes tempo and pitch together, pitch and bend for effects that change pitch only, and stretch for an effect that changes tempo using a different algorithm.
treble gain [frequency[k] [width[s|h|k|o|q]]] Apply a treble tone-control effect.  See the description of the bass effect for details.
tremolo speed [depth] Apply a tremolo (low frequency amplitude modulation) effect to the audio.  The tremolo frequency in Hz is given by speed, and the depth as a percentage by depth (default 40).
trim {position(+)} Cuts portions out of the audio.  Any number of positions may be given; audio is not sent to the output until the first position is reached.  The effect then alternates between copying and discarding audio at each position.  Using a value of 0 for the first position parameter allows copying from the beginning of the audio.
For example, sox infile outfile trim 0 10 will copy the first ten seconds, while play infile trim 12:34 =15:00 -2:00 and play infile trim 12:34 2:26 -2:00 will both play from 12 minutes 34 seconds into the audio up to 15 minutes into the audio (i.e. 2 minutes and 26 seconds long), then resume playing two minutes before the end of audio.
upsample [factor] Upsample the signal by an integer factor: factor-1 zero-value samples are inserted between each pair of input samples.  As a result, the original spectrum is replicated into the new frequency space (imaging) and attenuated.  This attenuation can be compensated for by adding vol factor after any further processing. The upsample effect is typically used in combination with filtering effects.
For a general resampling effect with anti-imaging, see rate.  See also downsample.
vad [options] Voice Activity Detector.  Attempts to trim silence and quiet background sounds from the ends of (fairly high resolution i.e. 16-bit, 44-48kHz) recordings of speech.  The algorithm currently uses a simple cepstral power measurement to detect voice, so may be fooled by other things, especially music.  The effect can trim only from the front of the audio, so in order to trim from the back, the reverse effect must also be used.  E.g. play speech.wav norm vad to trim from the front, play speech.wav norm reverse vad reverse to trim from the back, and play speech.wav norm vad reverse vad reverse to trim from both ends.  The use of the norm effect is recommended, but remember that neither reverse nor norm is suitable for use with streamed audio.
Options: Default values are shown in parenthesis.
-t num (7) The measurement level used to trigger activity detection. This might need to be changed depending on the noise level, signal level and other charactistics of the input audio.
-T num (0.25) The time constant (in seconds) used to help ignore short bursts of sound.
-s num (1) The amount of audio (in seconds) to search for quieter/shorter bursts of audio to include prior to the detected trigger point.
-g num (0.25) Allowed gap (in seconds) between quieter/shorter bursts of audio to include prior to the detected trigger point.
-p num (0) The amount of audio (in seconds) to preserve before the trigger point and any found quieter/shorter bursts.
Advanced Options: These allow fine tuning of the algorithm's internal parameters.
-b num The algorithm (internally) uses adaptive noise estimation/reduction in order to detect the start of the wanted audio.  This option sets the time for the initial noise estimate.
-N num Time constant used by the adaptive noise estimator for when the noise level is increasing.
-n num Time constant used by the adaptive noise estimator for when the noise level is decreasing.
-r num Amount of noise reduction to use in the detection algorithm (e.g. 0, 0.5, ...).
-f num Frequency of the algorithm's processing/measurements.
-m num Measurement duration; by default, twice the measurement period; i.e.  with overlap.
-M num Time constant used to smooth spectral measurements.
-h num `Brick-wall' frequency of high-pass filter applied at the input to the detector algorithm.
-l num `Brick-wall' frequency of low-pass filter applied at the input to the detector algorithm.
-H num `Brick-wall' frequency of high-pass lifter used in the detector algorithm.
-L num `Brick-wall' frequency of low-pass lifter used in the detector algorithm.
See also the silence effect.
vol gain [type [limitergain]] Apply an amplification or an attenuation to the audio signal. Unlike the -v option (which is used for balancing multiple input files as they enter the SoX effects processing chain), vol is an effect like any other so can be applied anywhere, and several times if necessary, during the processing chain.
The amount to change the volume is given by gain which is interpreted, according to the given type, as follows: if type is amplitude (or is omitted), then gain is an amplitude (i.e. voltage or linear) ratio, if power, then a power (i.e. wattage or voltage- squared) ratio, and if dB, then a power change in dB.
When type is amplitude or power, a gain of 1 leaves the volume unchanged, less than 1 decreases it, and greater than 1 increases it; a negative gain inverts the audio signal in addition to adjusting its volume.
When type is dB, a gain of 0 leaves the volume unchanged, less than 0 decreases it, and greater than 0 increases it.
See [4] for a detailed discussion on electrical (and hence audio signal) voltage and power ratios.
Beware of Clipping when the increasing the volume.
The gain and the type parameters can be concatenated if desired, e.g.  vol 10dB.
An optional limitergain value can be specified and should be a value much less than 1 (e.g. 0.05 or 0.02) and is used only on peaks to prevent clipping.  Not specifying this parameter will cause no limiter to be used.  In verbose mode, this effect will display the percentage of the audio that needed to be limited.
See also gain for a volume-changing effect with different capabilities, and compand for a dynamic-range compression/expansion/limiting effect.
Exit status is 0 for no error, 1 if there is a problem with the command- line parameters, or 2 if an error occurs during file processing.
Please report any bugs found in this version of SoX to the mailing list (sox-users@lists.sourceforge.net).
soxi(1), soxformat(7), libsox(3) audacity(1), gnuplot(1), octave(1), wget(1) The SoX web site at http://sox.sourceforge.net SoX scripting examples at http://sox.sourceforge.net/Docs/Scripts
References [1]    R. Bristow-Johnson, Cookbook formulae for audio EQ biquad filter coefficients, http://musicdsp.org/files/Audio-EQ-Cookbook.txt
[2]    Wikipedia, Q-factor, http://en.wikipedia.org/wiki/Q_factor
[3]    Scott Lehman, Effects Explained, http://harmony- central.com/Effects/effects-explained.html
[4]    Wikipedia, Decibel, http://en.wikipedia.org/wiki/Decibel
[5]    Richard Furse, Linux Audio Developer's Simple Plugin API, http://www.ladspa.org
[6]    Richard Furse, Computer Music Toolkit, http://www.ladspa.org/cmt
[7]    Steve Harris, LADSPA plugins, http://plugin.org.uk
Copyright 1998-2013 Chris Bagwell and SoX Contributors. Copyright 1991 Lance Norskog and Sundry Contributors.
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 the Free Software Foundation; either version 2, or (at your option) any later version.
Chris Bagwell (cbagwell@users.sourceforge.net).  Other authors and contributors are listed in the ChangeLog file that is distributed with the source code.
sacct(1)                         Slurm Commands                         sacct(1)
sacct - displays accounting data for all jobs and job steps in the Slurm job accounting log or Slurm database
sacct [OPTIONS...]
Accounting information for jobs invoked with Slurm are either logged in the job accounting log file or saved to the Slurm database, as configured with the AccountingStorageType parameter.
The sacct command displays job accounting data stored in the job accounting log file or Slurm database in a variety of forms for your analysis.  The sacct command displays information on jobs, job steps, status, and exitcodes by default.  You can tailor the output with the use of the --format= option to specify the fields to be shown.
For the root user, the sacct command displays job accounting data for all users, although there are options to filter the output to report only the jobs from a specified user or group.
For the non-root user, the sacct command limits the display of job accounting data to jobs that were launched with their own user identifier (UID) by default.  Data for other users can be displayed with the --allusers, --user, or --uid options.
Elapsed time fields are presented as [days-]hours:minutes:seconds[.microseconds]. Only 'CPU' fields will ever have microseconds.
The default input file is the file named in the AccountingStorageLoc parameter in slurm.conf.
Note: If designated, the slurmdbd.conf option PrivateData may further restrict the accounting data visible to users which are not SlurmUser, root, or a user with AdminLevel=Admin. See the slurmdbd.conf man page for additional details on restricting access to accounting data.
Note: The contents of Slurm's database are maintained in lower case. This may result in some sacct output differing from that of other Slurm commands.
Note: Much of the data reported by sacct has been generated by the wait3() and getrusage() system calls. Some systems gather and report incomplete information for these calls; sacct reports values of 0 for this missing data. See your systems getrusage (3) man page for information about which data are actually available on your system.
-a, --allusers Displays all users jobs when run by user root or if PrivateData is not configured to jobs.  Otherwise display the current user's jobs
-A account_list , --accounts=account_list Displays jobs when a comma separated list of accounts are given as the argument.
-b, --brief Displays a brief listing, which includes the following data:
jobid
-c, --completion Use job completion data instead of job accounting.  The JobCompType parameter in the slurm.conf file must be defined to a non-none option.  Does not support federated cluster information (local data only).
-C constraint_list, --constraints=constraint_list Comma separated list to filter jobs based on what constraints/features the job requested.  Multiple options will be treated as 'and' not 'or', so the job would need all constraints specified to be returned not one or the other.
--delimiter=characters ASCII characters used to separate the fields when specifying the -p or -P options. The default delimiter is a '|'. This option is ignored if -p or -P options are not specified.
-D, --duplicates If Slurm job ids are reset, some job numbers will probably appear more than once in the accounting log file but refer to different jobs.  Such jobs can be distinguished by the "submit" time stamp in the data records.
When data for specific jobs are requested with the --jobs option, sacct returns the most recent job with that number. This behavior can be overridden by specifying --duplicates, in which case all records that match the selection criteria will be returned.
NOTE: Revoked federated sibling jobs are hidden unless the --duplicates option is specified.
-e, --helpformat
Print a list of fields that can be specified with the --format option.
Fields available:
Account             AdminComment        AllocCPUS           AllocNodes AllocTRES           AssocID             AveCPU              AveCPUFreq AveDiskRead         AveDiskWrite        AvePages            AveRSS AveVMSize           BlockID             Cluster             Comment Constraints         ConsumedEnergy      ConsumedEnergyRaw   CPUTime CPUTimeRAW          DBIndex             DerivedExitCode     Elapsed ElapsedRaw          Eligible            End                 ExitCode Flags               GID                 Group               JobID JobIDRaw            JobName             Layout              MaxDiskRead MaxDiskReadNode     MaxDiskReadTask     MaxDiskWrite        MaxDiskWriteNode MaxDiskWriteTask    MaxPages            MaxPagesNode        MaxPagesTask MaxRSS              MaxRSSNode          MaxRSSTask          MaxVMSize MaxVMSizeNode       MaxVMSizeTask       McsLabel            MinCPU MinCPUNode          MinCPUTask          NCPUS               NNodes NodeList            NTasks              Priority            Partition QOS                 QOSRAW              Reason              ReqCPUFreq ReqCPUFreqMin       ReqCPUFreqMax       ReqCPUFreqGov       ReqCPUS ReqMem              ReqNodes            ReqTRES             Reservation ReservationId       Reserved            ResvCPU             ResvCPURAW Start               State               Submit              Suspended SystemCPU           SystemComment       Timelimit           TimelimitRaw TotalCPU            TRESUsageInAve      TRESUsageInMax      TRESUsageInMaxNode TRESUsageInMaxTask  TRESUsageInMin      TRESUsageInMinNode  TRESUsageInMinTask TRESUsageInTot      TRESUsageOutAve     TRESUsageOutMax     TRESUsageOutMaxNode TRESUsageOutMaxTask TRESUsageOutMin     TRESUsageOutMinNode TRESUsageOutMinTask TRESUsageOutTot     UID                 User                UserCPU WCKey               WCKeyID             WorkDir
NOTE: When using with Ave[RSS|VM]Size or their values in TRESUsageIn[Ave|Tot].  They represent the average/total of the highest watermarks over all ranks in the step.  When using sstat they represent the average/total at the moment the command was run.
NOTE: TRESUsage*Min* values represent the lowest highwater mark in the step.
The section titled "Job Accounting Fields" describes these fields.
-E end_time, --endtime=end_time
Select jobs in any state before the specified time.  If states are given with the -s option return jobs in this state before this period.  See the DEFAULT TIME WINDOW for more details.
Valid time formats are: HH:MM[:SS][AM|PM] MMDD[YY][-HH:MM[:SS]] MM.DD[.YY][-HH:MM[:SS]] MM/DD[/YY][-HH:MM[:SS]] YYYY-MM-DD[THH:MM[:SS]] today, midnight, noon, fika (3 PM), teatime (4 PM) now[{+|-}count[seconds(default)|minutes|hours|days|weeks]]
--federation Show jobs from the federation if a member of one.
-f file,  --file=file Causes the sacct command to read job accounting data from the named file instead of the current Slurm job accounting log file. Only applicable when running the jobcomp/filetxt plugin.
-F flag_list,  --flags=flag_list Comma separated list to filter jobs based on what various ways the jobs were handled.  Current flags are SchedSubmit, SchedMain, SchedBackfill.  These particular options describe the scheduler that started the job.
-g gid_list, --gid=gid_list --group=group_list Displays the statistics only for the jobs started with the GID or the GROUP specified by the gid_list or the group_list operand, which is a comma-separated list.  Space characters are not allowed.  Default is no restrictions.
-h, --help Displays a general help message.
-i, --nnodes=N Return jobs which ran on this many nodes (N = min[-max])
-j job(.step) ,  --jobs=job(.step) Displays information about the specified job(.step) or list of job(.step)s.
The job(.step) parameter is a comma-separated list of jobs. Space characters are not permitted in this list.  NOTE: A step id of 'batch' will display the information about the batch step.
By default sacct shows only jobs with Eligible time, but with this option the non-eligible will be also shown.  NOTE: If --state is also specified, as non-eligible are not PD, then non-eligible jobs will not be displayed.  See the DEFAULT TIME WINDOW for details about how this option changes the default -S and -E options.
-k, --timelimit-min Only send data about jobs with this timelimit.  If used with timelimit_max this will be the minimum timelimit of the range. Default is no restriction.
-K, --timelimit-max Ignored by itself, but if timelimit_min is set this will be the maximum timelimit of the range.  Default is no restriction.
--local   Show only jobs local to this cluster. Ignore other clusters in this federation (if any). Overrides --federation.
-l, --long Equivalent to specifying:
--format=jobid,jodidraw,jobname,partition,maxvmsize,maxvmsizenode, maxvmsizetask,avevmsize,maxrss,maxrssnode,maxrsstask,averss,maxpages, maxpagesnode,maxpagestask,avepages,mincpu,mincpunode,mincputask,avecpu,ntasks, alloccpus,elapsed,state,exitcode,avecpufreq,reqcpufreqmin,reqcpufreqmax, reqcpufreqgov,reqmem,consumedenergy,maxdiskread,maxdiskreadnode,maxdiskreadtask, avediskread,maxdiskwrite,maxdiskwritenode,maxdiskwritetask,avediskwrite, reqtres,alloctres,tresusageinave,tresusageinmax, tresusageinmaxn,tresusageinmaxt,tresusageinmin,tresusageinminn,tresusageinmint, tresusageintot,tresusageoutmax,tresusageoutmaxn, tresusageoutmaxt,tresusageoutave,tresusageouttot
-L, --allclusters Display jobs ran on all clusters. By default, only jobs ran on the cluster from where sacct is called are displayed.
-M cluster_list, --clusters=cluster_list Displays the statistics only for the jobs started on the clusters specified by the cluster_list operand, which is a comma-separated list of clusters.  Space characters are not allowed in the cluster_list.  A value of 'all' will query to run on all clusters.  The default is current cluster you are executing the sacct command on or all clusters in the federation when executed on a federated cluster.  This option implicitly sets the --local option.
-n, --noheader No heading will be added to the output. The default action is to display a header.
--noconvert Don't convert units from their original type (e.g. 2048M won't be converted to 2G).
-N node_list, --nodelist=node_list Display jobs that ran on any of these node(s).  node_list can be a ranged string.
--name=jobname_list Display jobs that have any of these name(s).
-o, --format Comma separated list of fields. (use "--helpformat" for a list of available fields).
NOTE: When using the format option for listing various fields you can put a %NUMBER afterwards to specify how many characters should be printed.
e.g. format=name%30 will print 30 characters of field name right justified.  A %-30 will print 30 characters left justified.
When set, the SACCT_FORMAT environment variable will override the default format.  For example:
SACCT_FORMAT="jobid,user,account,cluster"
-p, --parsable output will be '|' delimited with a '|' at the end
-P, --parsable2 output will be '|' delimited without a '|' at the end
-q, --qos Only send data about jobs using these qos.  Default is all.
-r, --partition
Comma separated list of partitions to select jobs and job steps from. The default is all partitions.
-R reason_list,  --reason=reason_list Comma separated list to filter jobs based on what reason the job wasn't scheduled outside resources/priority.
-s state_list, --state=state_list Selects jobs based on their state during the time period given. Unless otherwise specified, the start and end time will be the current time when the --state option is specified and only currently running jobs can be displayed.  A start and/or end time must be specified to view information about jobs not currently running.  See the JOB STATE CODES section below for a list of state designators.  Multiple state names may be specified using comma separators. Either the short or long form of the state name may be used (e.g. CA or CANCELLED) and the name is case insensitive (i.e. ca and CA both work).
NOTE: Note for a job to be selected in the PENDING state it must have "EligibleTime" in the requested time interval or different from "Unknown". The "EligibleTime" is displayed by the "scontrol show job" command.  For example jobs submitted with the "--hold" option will have "EligibleTime=Unknown" as they are pending indefinitely.
NOTE: When specifying states and no start time is given the default start time is 'now'.  This is only when -j is not used. If -j is used the start time will default to 'Epoch'.  In both cases if no end time is given it will default to 'now'. See the DEFAULT TIME WINDOW for more details.
-S, --starttime Select jobs in any state after the specified time. Default is 00:00:00 of the current day, unless the '-s' or '-j' options are used. If the '-s' option is used, then the default is 'now'. If states are given with the '-s' option then only jobs in this state at this time will be returned. If the '-j' option is used, then the default time is Unix Epoch 0. See the DEFAULT TIME WINDOW for more details.
-T, --truncate Truncate time.  So if a job started before --starttime the start time would be truncated to --starttime.  The same for end time and --endtime.
-u uid_list, --uid=uid_list, --user=user_list Use this comma separated list of uids or user names to select jobs to display.  By default, the running user's uid is used.
--use-local-uid When displaying UID, sacct uses the UID stored in Slurm's accounting database by default. Use this command to make Slurm use a system call to get the UID from the username. This option may be useful in an environment with multiple clusters and one database where the UID's aren't the same on all clusters.
--units=[KMGTP] Display values in specified unit type. Takes precedence over --noconvert option.
--usage   Display a command usage summary.
-v, --verbose Primarily for debugging purposes, report the state of various variables during processing.
-V, --version Print version.
--whole-hetjob=[yes|no] When querying heterogeneous jobs, Slurm by default retrieves the information about all the components of the job if the het_job_id (leader id) is selected.  If a non-leader heterogeneous job component id is selected only that component is retrieved by default. This behavior can be changed by using this option. If set to 'yes' or no value is set, then information about all the components will be retrieved no matter which component is selected in the job filter. Otherwise, if set to 'no' then only the selected heterogeneous job components will be retrieved, even when selecting the leader.
-W wckey_list, --wckeys=wckey_list Displays the statistics only for the jobs started on the wckeys specified by the wckey_list operand, which is a comma-separated list of wckey names.  Space characters are not allowed in the wckey_list. Default is all wckeys.
-x associd_list, --associations=assoc_list Displays the statistics only for the jobs running under the association ids specified by the assoc_list operand, which is a comma-separated list of association ids.  Space characters are not allowed in the assoc_list. Default is all associations.
-X, --allocations Only show statistics relevant to the job allocation itself, not taking steps into consideration.
NOTE: Without including steps, utilization statistics for job allocation(s) will be reported as zero.
Job Accounting Fields The following describes each job accounting field:
ALL       Print all fields listed below.
AllocCPUs Count of allocated CPUs. Equivalent to NCPUS.
AllocNodes Number of nodes allocated to the job/step.  0 if the job is pending.
AllocTres Trackable resources. These are the resources allocated to the job/step after the job started running.  For pending jobs this should be blank.  For more details see AccountingStorageTRES in slurm.conf.
NOTE: When a generic resource is configured with the no_consume flag, the allocation will be printed with a zero.
Account   Account the job ran under.
AssocID   Reference to the association of user, account and cluster.
AveCPU    Average (system + user) CPU time of all tasks in job.
AveCPUFreq Average weighted CPU frequency of all tasks in job, in kHz.
AveDiskRead Average number of bytes read by all tasks in job.
AveDiskWrite Average number of bytes written by all tasks in job.
AvePages  Average number of page faults of all tasks in job.
AveRSS    Average resident set size of all tasks in job.
AveVMSize Average Virtual Memory size of all tasks in job.
Cluster   Cluster name.
Comment   The job's comment string when the AccountingStoreJobComment parameter in the slurm.conf file is set (or defaults) to YES.  The Comment string can be modified by invoking sacctmgr modify job or the specialized sjobexitmod command.
ConsumedEnergy Total energy consumed by all tasks in job, in joules. Note: Only in case of exclusive job allocation this value reflects the jobs' real energy consumption.
CPUTime   Time used (Elapsed time * CPU count) by a job or step in HH:MM:SS format.
CPUTimeRAW Time used (Elapsed time * CPU count) by a job or step in cpu-seconds.
DerivedExitCode The highest exit code returned by the job's job steps (srun invocations).  Following the colon is the signal that caused the process to terminate if it was terminated by a signal.  The DerivedExitCode can be modified by invoking sacctmgr modify job or the specialized sjobexitmod command.
Elapsed   The jobs elapsed time.
The format of this fields output is as follows: [DD-[HH:]]MM:SS
as defined by the following:
DD        days
hh        hours
mm        minutes
ss        seconds
Eligible  When the job became eligible to run in the same format as End.
End       Termination time of the job. Format output is, YYYY-MM-DDTHH:MM:SS, unless changed through the SLURM_TIME_FORMAT environment variable.
ExitCode  The exit code returned by the job script or salloc, typically as set by the exit() function.  Following the colon is the signal that caused the process to terminate if it was terminated by a signal.
GID       The group identifier of the user who ran the job.
Group     The group name of the user who ran the job.
JobID     The identification number of the job or job step.
Regular jobs are in the form:
JobID[.JobStep]
Array jobs are in the form:
ArrayJobID_ArrayTaskID
Heterogeneous jobs are in the form:
HetJobID+HetJobOffset.
JobIDRaw  The identification number of the job or job step. Prints the JobID in the form JobID[.JobStep].
JobName   The name of the job or job step. The slurm_accounting.log file is a space delimited file. Because of this if a space is used in the jobname an underscore is substituted for the space before the record is written to the accounting file. So when the jobname is displayed by sacct the jobname that had a space in it will now have an underscore in place of the space.
Layout    What the layout of a step was when it was running.  This can be used to give you an idea of which node ran which rank in your job.
MaxDiskRead Maximum number of bytes read by all tasks in job.
MaxDiskReadNode The node on which the maxdiskread occurred.
MaxDiskReadTask The task ID where the maxdiskread occurred.
MaxDiskWrite Maximum number of bytes written by all tasks in job.
MaxDiskWriteNode The node on which the maxdiskwrite occurred.