1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259
|
.\" Process this file with
.\" groff -man -Tascii squishyball.1
.\"
.TH squishyball 1 "2013 November 9" "Xiph.Org Foundation" "Xiph Evaluation Tools"
.SH NAME
squishyball \- perform sample comparison testing on the command line
.SH SYNOPSIS
.B squishyball
[\fIoptions\fR] fileA [fileB [\fIfileN...\fR]] [> results.txt]
.SH DESCRIPTION
.B squishyball
is a simple command-line utility for performing double-blind A/B,
A/B/X or X/X/Y testing on the command line. The user specifies two
input files to be compared and uses the keyboard during playback to
flip between the randomized samples to perform on-the-fly comparisons.
After a predetermined number of trials,
.B squishyball
prints the trial results to stdout and exits. Results (stdout) may be
redirected to a file without affecting interactive use of the
terminal.
.B squishyball
can also be used to perform casual, non-randomized comparisons of
groups of up to ten samples; this is the default mode of operation.
.SH TEST TYPES
.IP "\fB-a --ab"
Perform A/B test on two input samples.
A/B testing randomizes the order of two input samples and presents
them, unnamed, as sample 'A' and sample 'B'. In each trial the user
selects A or B as the preferred sample. The samples are then
re-randomized for the next trial. This test is useful for
establishing relative or preferred quality between two samples.
.IP "\fB-b --abx"
Perform A/B/X test on two input samples.
A/B/X presents two input samples, unrandomized, as sample 'A' and
sample 'B'. A third sample 'X' is chosen randomly from either 'A'
or 'B'. In each trial, the user selects A or B as the sample believed
to be the same as X. X is then re-randomized for the next trial. This
test is useful for determining if any differences are audible between
two samples and to what confidence level.
Note that because the A and B samples are not randomized (they are
presented in the order given on the command line as per standard
industry practice), an A/B/X test does not eliminate ordering bias.
A stronger version of this test that randomizes all samples is the
X/X/Y test below.
.IP "\fB-c --casual"
Perform casual comparison of up to ten samples (default).
Casual comparison mode does not randomize the input samples or perform
multiple trials. It simply provides a convenient way to rapidly flip back and
forth within a group of up to ten samples.
.IP "\fB-x --xxy"
Perform randomized X/X/Y test on two input samples.
X/X/Y testing is a form of A/B/X testing in which the order of all
samples is randomized and the position of the 'X' sample is not known
ahead of time to be in the third position. In each trial, the user
selects which of sample 1, 2 or 3 is believed to be the sample that is
different from the other two. This test is useful for determining if
any differences are audible between two samples and to what confidence
level. It is a stronger version of the A/B/X test that eliminates
sample order bias.
.SH OTHER OPTIONS
.IP "\fB-B --beep-flip"
Mark transitions between samples with a short beep.
.IP "\fB-d --device \fIN\fR|\fIdevice"
If a number, output to Nth available sound device. If a device name,
use output device matching that device name. The backend audio driver is
selected automatically based on the device name provided.
.IP "\fB-D --force-dither"
Always use dither when down-converting to 16-bit samples for playback
on audio devices that do not support 24-bit playback. By default,
uncompressed samples are always dithered, but lossy formats (such
as Vorbis and Opus) are simply rounded. See the
section \fBCONVERSION AND DITHER \fRbelow for more details.
.IP "\fB-e --end-time \fR[[\fIhh\fB:\fR]\fImm\fB:\fR]\fIss\fR[\fB.\fIff\fR]"
Set sample end time for playback.
.IP "\fB-g --gabbagabbahey \fR| \fB--score-display"
Show running score and probability figures of trials so far while
testing. Can only be used with \fB-a\fR, \fB-b\fR, or \fB-x\fR.
.IP "\fB-h --help"
Print usage summary to stdout and exit.
.IP "\fB-M --mark-flip"
Mark transitions between samples with a short period of silence (default).
.IP "\fB-n --trials \fIn"
Set desired number of comparison trials (default: 20).
.IP "\fB-N --do-not-normalize"
Do not perform autonormalization to avoid clipping when sample values
exceed the maximum playback range in floating point, lossy, and
downmixed samples.
.IP "\fB-r --restart-after"
Set 'restart-after mode', where sample playback restarts from start point
after every trial.
.IP "\fB-R --restart-every"
Set 'restart-every mode', where sample playback restarts from start point
after 'flip' as well as after every trial.
.IP "\fB-s --start-time \fR[[\fIhh\fB:\fR]\fImm\fB:\fR]\fIss\fR[\fB.\fIff\fR]"
Set start time within sample for playback
.IP "\fB-S --seamless-flip"
Do not mark transitions between samples;
flip with a seamless crossfade.
.IP "\fB-t --force-truncate"
Always round/truncate (never dither) when down-converting samples to 16-bit
for playback on audio devices that do not support 24-bit output. See the
section \fBCONVERSION AND DITHER\fR below for more details.
.IP "\fB-v --verbose"
Produce more and more detailed progress information and warnings.
.IP "\fB-V --version"
Print version and exit.
.IP "\fB-1 --downmix-to-mono"
Downmix all multichannel samples to mono at load time.
.IP "\fB-2 --downmix-to-stereo"
Downmix all surround samples to stereo at load time.
.SH KEYBOARD INTERACTION
.IP "\fBa\fR, \fBb\fR, \fBx"
Switch between A and B samples (A/B mode), or A, B and X samples (A/B/X mode).
.IP "\fBA\fR, \fBB"
Select A or B as preferred sample (A/B mode), or sample A or sample B as
match to sample X (A/B/X testing mode).
.IP "\fB1\fR, \fB2\fR, \fB3\fR..."
Switch between first, second, third [etc] samples (X/X/Y testing mode, casual comparison mode).
.IP "\fB!\fR, \fB@\fR, \fB#"
Indicate the 'odd sample out' as sample 1, 2, or 3 (X/X/Y testing mode).
.IP "\fB<del>\fR, <ins>"
Undo/redo previous trial result selection.
.IP "\fB<enter>"
Choose current sample for this trial.
.IP "\fB<-\fR, \fB->"
Seek back/forward two seconds, \fB+shift \fRfor ten seconds.
.IP "\fB<up/down>"
Select sample in sample list (casual mode).
.IP "\fB<space>"
Pause/resume playback.
.IP "\fB<backspace>"
Reset playback to start point.
.IP "\fBe"
Set end playback point to current playback time (see also -e above).
.IP "\fBE"
Reset end playback time to end of sample.
.IP "\fBf"
Toggle through beep-flip/mark-flip/seamless-flip modes (see \fB-B\fR, \fB-M\fR, and \fB-S \fRabove).
.IP "\fBr"
Toggle through restart-after/restart-every/no-restart modes (see \fB-r \fRand \fB-R \fRabove).
.IP "\fBs"
Set start playback point to current playback time (see also \fB-s \fRabove).
.IP "\fBS"
Reset start playback time to beginning of sample.
.IP "\fB?"
Print this keymap. The keymap will not be printed if the terminal has insufficient rows to do so.
.IP "\fB^c"
Abort testing early.
.SH SUPPORTED FILE TYPES
.IP \fBWAV/WAVEX
8-, 16-, 24-bit linear integer PCM (format 1), 32-bit float (format 3)
.IP \fBAIFF/AIFF-C
8-, 16-, 24-bit linear integer PCM, 32-bit floating point
.IP \fBFLAC/OggFLAC
16- and 24-bit
.IP \fBSW
Mono signed 16-bit little endian 48000Hz raw with a .sw extension
.IP \fBOggVorbis
all Vorbis I files
.IP \fBOggOpus
all Opus files
.SH CONVERSION
\fBsquishyball\fR 'reconciles' files to identical channel ordering,
length and bit-depth before playback begins so that CPU and memory
resource usage during playback should be identical for all samples.
When 24-bit playback is available and at least one sample is 24-bit or
greater (ie, 32-bit or float), all samples are converted/promoted to
24 bits. If 24-bit playback is unavailable, all samples are demoted
to 16 bits. Note that Opus and Vorbis files are both considered to be
natively float formats.
.SH NORMALIZATION
\fBsquishyball\fR checks files for clipping at load time. By default,
\fBsquishyball\fR will automatically normalize all float inputs by the
amount needed to avoid clipping any one. Automatic normalization can
be disabled with the \fB-N\fR option. Integer samples are checked for
clipping heuristically; two or more consecutive full-range values in a
channel count as clipped. Out-of-range integer values cannot be
recovered; in this case, \fBsquishyball\fR issues a warning and
performs no normalization based on the integer clipping.
Downmixing samples to mono with \fB-1\fR or stereo with \fB-2\fR will
also likely require normalization to avoid clipping; as above,
\fBsquishyball\fR will automatically normalize all inputs by the
amount necessary to avoid clipping in any one unless \fB-N\fR is
specified.
.SH DITHER
Down-conversions of uncompressed and lossless samples (WAV, AIF[C],
FLAC, SW) to 16-bit are dithered using a simple white TPDF.
Lossy-encoded samples (Vorbis and Opus) are dithered to 16-bit only if
one or more uncompressed/lossless inputs are also being dithered.
Normalization also triggers dithering of all input samples
(uncompressed, lossless and lossy) upon conversion to 16 bit.
\fB-D\fR overrides the default behavior and forces unconditional
dithering of all 16-bit down-conversions. Similarly, \fB-t\fR forces
unconditional rounded truncation in all cases, disabling dither
completely.
Conversions to 24-bit are never dithered.
.SH IMPORTANT USAGE NOTES
.IP "\fBPlayback Depth and Rate"
Many modern audio playback systems (such as PulseAudio or the
ALSA 'default' device) give no means of determining if the requested
playback paramters are actually being used by the hardware, or if the
audio system is helpfully converting everything to some other
supported depth/rate. When using these systems, \fBsquishyball\fR has
no way of knowing if 16-/24-bit playback or sample rate is being
honored. Automatic conversion can affect audible playback quality; be
careful to verify actual system behavior.
.IP "\fBFlip-Mode Choice"
\fBSilent Mode\fR smoothly transitions between samples. It allows the
most direct comparison between signals without any intervening auditory
distraction. However, the temporary combination of different signals
may cause unintended cancellation and comb-filtering effects that can
give away the 'unknown' sample just as a 'pop' from an instantaneous
transition would.
\fBMark Mode\fR quickly fades to silence before flipping to another
sample, marking the transition. Because the samples never overlap,
crosslap artifacts cannot contaminate trial results. However, the
audible dip between samples may distract from listening, potentially
making it slightly more difficult to detect legitimate artifacts.
\fBBeep Mode\fR is similar to mark mode but adds a soft 'beep' to mark
where the transition occurs. It makes the transition point especially
obvious. It does not crosslap the samples; one sample is faded
completely before the second is mixed in as in mark mode.
.SH AUTHORS
Monty <monty@xiph.org>
.SH "SEE ALSO"
.PP
\fBabx-comparator\fR(1), \fBrateit\fR(1), \fBogg123\fR(1), \fBoggdec\fR(1), \fBopusdec\fR(1), \fBflac\fR(1)
|