Provided by: squishyball_0.1~svn19085-5build1_amd64 
NAME
squishyball - perform sample comparison testing on the command line
SYNOPSIS
squishyball [options] fileA [fileB [fileN...]] [> results.txt]
DESCRIPTION
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, squishyball prints the trial
results to stdout and exits. Results (stdout) may be redirected to a file without
affecting interactive use of the terminal.
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.
TEST TYPES
-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.
-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.
-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.
-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.
OTHER OPTIONS
-B --beep-flip
Mark transitions between samples with a short beep.
-d --device N|device
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.
-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 CONVERSION AND DITHER below for more details.
-e --end-time [[hh:]mm:]ss[.ff]
Set sample end time for playback.
-g --gabbagabbahey | --score-display
Show running score and probability figures of trials so far while testing. Can only
be used with -a, -b, or -x.
-h --help
Print usage summary to stdout and exit.
-M --mark-flip
Mark transitions between samples with a short period of silence (default).
-n --trials n
Set desired number of comparison trials (default: 20).
-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.
-r --restart-after
Set 'restart-after mode', where sample playback restarts from start point after
every trial.
-R --restart-every
Set 'restart-every mode', where sample playback restarts from start point after
'flip' as well as after every trial.
-s --start-time [[hh:]mm:]ss[.ff]
Set start time within sample for playback
-S --seamless-flip
Do not mark transitions between samples; flip with a seamless crossfade.
-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
CONVERSION AND DITHER below for more details.
-v --verbose
Produce more and more detailed progress information and warnings.
-V --version
Print version and exit.
-1 --downmix-to-mono
Downmix all multichannel samples to mono at load time.
-2 --downmix-to-stereo
Downmix all surround samples to stereo at load time.
KEYBOARD INTERACTION
a, b, x
Switch between A and B samples (A/B mode), or A, B and X samples (A/B/X mode).
A, B 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).
1, 2, 3...
Switch between first, second, third [etc] samples (X/X/Y testing mode, casual
comparison mode).
!, @, #
Indicate the 'odd sample out' as sample 1, 2, or 3 (X/X/Y testing mode).
<del>, <ins>
Undo/redo previous trial result selection.
<enter>
Choose current sample for this trial.
<-, -> Seek back/forward two seconds, +shift for ten seconds.
<up/down>
Select sample in sample list (casual mode).
<space>
Pause/resume playback.
<backspace>
Reset playback to start point.
e Set end playback point to current playback time (see also -e above).
E Reset end playback time to end of sample.
f Toggle through beep-flip/mark-flip/seamless-flip modes (see -B, -M, and -S above).
r Toggle through restart-after/restart-every/no-restart modes (see -r and -R above).
s Set start playback point to current playback time (see also -s above).
S Reset start playback time to beginning of sample.
? Print this keymap. The keymap will not be printed if the terminal has insufficient
rows to do so.
^c Abort testing early.
SUPPORTED FILE TYPES
WAV/WAVEX
8-, 16-, 24-bit linear integer PCM (format 1), 32-bit float (format 3)
AIFF/AIFF-C
8-, 16-, 24-bit linear integer PCM, 32-bit floating point
FLAC/OggFLAC
16- and 24-bit
SW Mono signed 16-bit little endian 48000Hz raw with a .sw extension
OggVorbis
all Vorbis I files
OggOpus
all Opus files
CONVERSION
squishyball '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.
NORMALIZATION
squishyball checks files for clipping at load time. By default, squishyball will
automatically normalize all float inputs by the amount needed to avoid clipping any one.
Automatic normalization can be disabled with the -N 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, squishyball
issues a warning and performs no normalization based on the integer clipping.
Downmixing samples to mono with -1 or stereo with -2 will also likely require
normalization to avoid clipping; as above, squishyball will automatically normalize all
inputs by the amount necessary to avoid clipping in any one unless -N is specified.
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.
-D overrides the default behavior and forces unconditional dithering of all 16-bit down-
conversions. Similarly, -t forces unconditional rounded truncation in all cases,
disabling dither completely.
Conversions to 24-bit are never dithered.
IMPORTANT USAGE NOTES
Playback 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,
squishyball 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.
Flip-Mode Choice
Silent Mode 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.
Mark Mode 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.
Beep Mode 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.
AUTHORS
Monty <monty@xiph.org>
SEE ALSO
abx-comparator(1), rateit(1), ogg123(1), oggdec(1), opusdec(1), flac(1)