squishyball(1)

💖 squishyball(1) 💖

okay bestie, gather round, because we're about to talk about squishyball — yes that's really its name — one of the Xiph Evaluation Tools and honestly? it's giving lab-coat-meets-group-chat. it lives on your command line and it's here to help you do serious audio comparison testing without ever leaving the terminal. slay. 🎀

---

✨ NAME ✨

squishyball — perform sample comparison testing on the command line. that's it, that's the whole job, and it does it beautifully. 💅

---

✨ SYNOPSIS ✨

squishyball [options] fileA [fileB [fileN...]] [> results.txt]

---

✨ DESCRIPTION ✨

so squishyball is a simple little command-line utility for doing double-blind A/B, A/B/X or X/X/Y testing right there in your terminal. no GUI, no drama, just vibes and science. 🔬

here's the tea: you give it two input files to compare, and then during playback you use your keyboard to flip between the randomized samples so you can do on-the-fly comparisons. real-time. live. iconic. 🎧

after a predetermined number of trials, squishyball prints the trial results to stdout and exits. and here's the best part — results (stdout) can be redirected to a file without affecting interactive use of the terminal. so you can pipe your science somewhere safe and still keep tapping keys like a main character. 👑

oh and also? squishyball can do casual, non-randomized comparisons of groups of up to ten samples. that's the default mode of operation, btw. no cap. 🦋

---

✨ 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 you (the user) select A or B as the preferred sample. then the samples get re-randomized for the next trial. 🎲

this test is useful for establishing relative or preferred quality between two samples. periodt.

💫 -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'. then a third sample 'X' is chosen randomly from either 'A' or 'B'. in each trial, you select A or B as the sample you believe is the same as X. then X gets 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. 🔍

⚠️ heads up bestie: because the A and B samples are not randomized (they're 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. don't say i didn't warn you. 💀

💫 -c, --casual

Perform casual comparison of up to ten samples (default).

casual comparison mode does not randomize the input samples and does not perform multiple trials. it just gives you a convenient way to rapidly flip back and forth within a group of up to ten samples. it's the chill one. the lowkey one. 🍓

💫 -x, --xxy

Perform randomized X/X/Y test on two input samples.

X/X/Y testing is a form of A/B/X testing where 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, you select which of sample 1, 2 or 3 you believe is 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's the stronger version of the A/B/X test that eliminates sample order bias. we love to see it. 🌈

---

✨ OTHER OPTIONS ✨

• -B, --beep-flip — mark transitions between samples with a short beep. beep boop. 🎵
• -d, --device N|device — if it's a number, output to the Nth available sound device. if it's a device name, use the 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 don't 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. (yes, there's a whole vibe section about it, keep reading. 👀)
• -e, --end-time [[hh:]mm:]ss[.ff] — set the 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. also, yes, that flag name is real. go off, king. 👑
• -h, --help — print usage summary to stdout and exit. the classic. 🫶
• -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 the start point after every trial. 🔁
• -R, --restart-every — set 'restart-every mode', where sample playback restarts from the start point after 'flip' as well as after every trial. 🔂
• -s, --start-time [[hh:]mm:]ss[.ff] — set the start time within the sample for playback. ⏱️
• -S, --seamless-flip — do not mark transitions between samples; flip with a seamless crossfade. smooth like butter. 🧈
• -t, --force-truncate — always round/truncate (never dither) when down-converting samples to 16-bit for playback on audio devices that don't 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. the yapper flag. 🗣️
• -V, --version — print version and exit. 🏷️
• -1, --downmix-to-mono — downmix all multichannel samples to mono at load time. 1️⃣
• -2, --downmix-to-stereo — downmix all surround samples to stereo at load time. 2️⃣

---

✨ KEYBOARD INTERACTION ✨

okay this is the fun part — here's your whole keymap, bestie. these keys are your instrument. learn them, love them. 🎹

• 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 the preferred sample (A/B mode), or sample A or sample B as the 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 the 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. (grow your terminal, babe. 🪟)
• ^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 ✨

so here's the magic trick: 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. fairness!! we love a level playing field. ⚖️

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. iykyk. 🧠

---

✨ 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. periodt.

---

and that's only part 1 bestie, there's more coming, so don't go anywhere 💖

💖 IMPORTANT USAGE NOTES 💖

okay bestie, this is the part where we get real. read this. fr fr.

---

🎧 Playback Depth and Rate

so here's the tea: a LOT of modern audio playback systems — think PulseAudio, or the ALSA 'default' device — literally give you no way to check whether the playback parameters you asked for are actually the ones hitting the hardware. or maybe the audio system is just being soooo helpful and quietly converting everything to some other depth/rate it feels like supporting instead. 🙈

when you're running on those systems, squishyball has no way of knowing if your 16-/24-bit playback or your sample rate is actually being honored. and automatic conversion? it can absolutely mess with audible playback quality. so be careful and verify actual system behavior yourself, bestie. don't just trust it. 💅

---

🔀 Flip-Mode Choice

this is the drama between the three flip modes. all three are valid, all three have ✨quirks✨.

Silent Mode smoothly transitions between samples. it's giving the most direct comparison between signals with zero intervening auditory distraction. but — and this is the important part — the temporary combination of different signals may cause unintended cancellation and comb-filtering effects. and those artifacts can give away the 'unknown' sample just as loudly as a 'pop' from an instantaneous transition would. 💀 so, y'know. tradeoffs.

Mark Mode quickly fades to silence before flipping to another sample, so the transition is marked. because the samples never overlap, crosslap artifacts cannot contaminate your trial results. clean. but the audible dip between samples might distract you from actually listening, which can make it slightly more difficult to detect legitimate artifacts. 🫶

Beep Mode is mark mode's louder cousin — same idea, but it adds a soft 'beep' to mark exactly where the transition occurs. it makes the transition point especially obvious. and ngl it does not crosslap the samples; one sample is faded completely before the second is mixed in, same as in mark mode. periodt. 🎀

---

👑 AUTHORS

• Monty <monty@xiph.org>

---

🌈 SEE ALSO

• abx-comparator(1)
• rateit(1)
• ogg123(1)
• oggdec(1)
• opusdec(1)
• flac(1)

---

and that's the whole page, bestie!! 🦋 brought to you by the Xiph.Org Foundation, dated 2013 November 9, and yeah — this was squishyball(1). go squish some audio, you absolute icon. 💜🌸✨