[xiph-commits] r17634 - websites/celt-codec.org/squishyball

xiphmont at svn.xiph.org xiphmont at svn.xiph.org
Thu Nov 18 22:53:06 PST 2010

Author: xiphmont
Date: 2010-11-18 22:53:05 -0800 (Thu, 18 Nov 2010)
New Revision: 17634

Fill in the prospective manpage

Modified: websites/celt-codec.org/squishyball/squishyball.1
--- websites/celt-codec.org/squishyball/squishyball.1	2010-11-19 04:56:13 UTC (rev 17633)
+++ websites/celt-codec.org/squishyball/squishyball.1	2010-11-19 06:53:05 UTC (rev 17634)
@@ -1,20 +1,165 @@
-          "  All integer PCM file types are loaded at native bit depth.\n"
-          "  Floating point file types (WAV format 3 and Ogg Vorbis)\n"
-          "  are decoded to 24 integer precision.\n\n"
-          "  If files A and B have different bit-depths, the lower-depth\n"
-          "  file is promoted to the higher-depth prior to playback.\n"
-          "  Similarly if the files have different channel orderings, the\n"
-          "  channels are permuted to matching orderings before playback.\n"
-          "  The files will thus have identical formatting in memory during\n"
-          "  playback in an effort to exert identical hardware load.\n\n"
-          "  If file playback would require 24 bit depth and the selected\n"
-          "  output device supports only 16 bit depth, samples are down-\n"
-          "  converted to 16 bit.  Any samples that were originally 24 bit\n"
-          "  (or 32 bit float) will be dithered during conversion; the\n"
-          "  exception is Ogg Vorbis files.  As most Vorbis files are\n"
-          "  made from 16 bit sources, they will not be dithered during\n"
-          "  down-conversion by default.  This behavior is overridden by\n"
-          "  -d, which forces dithering for Vorbis files as well.  Down-\n"
-          "  conversion dithering can be disabled for all input types\n"
-          "  with -n.\n\n"
+.\" Process this file with
+.\" groff -man -Tascii squishyball.1
+.TH squishyball 1 "2010 November 18" "Xiph.Org Foundation" "Xiph Evaluation Tools"
+squishyball \- perform A/B, A/B/X and X/X/Y testing on the command line
+.B squishyball 
+.I fileA fileB
+.B squishyball
+is a simple command-line application used to perform 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 on the command line and uses the keyboard to flip 
+between the randomized samples on-the-fly during playback 
+to perform comparisons.  After a predetermined number of trials, 
+.B squishyball 
+prints the trial results to the terminal and exits.
+.IP "\fB-a --ab"
+Perform randomized A/B test.
+.IP "\fB-b --abx"
+Perform randomized A/B/X test (default).
+.IP "\fB-c --card \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 sample 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) 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-h --help"
+Print usage summary to stdout and exit.
+.IP "\fB-n --comparisons \fIn"
+Set desired number of comparison trials (default: 10).
+.IP "\fB-r --restart-after"
+Set 'restart-after mode', where sample playback restarts from start point
+after every test selection.
+.IP "\fB-R --restart-every"
+Set 'restart-every mode', where sample playback restarts from start point
+after 'flip' as well as every test selection.
+.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-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-x --xxy"
+Perform randomized X/X/Y test.
+.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"
+Switch between first second and third samples (X/X/Y testing mode)
+.IP "\fB!\fR, \fB@\R, \fB#"
+Indicate the 'odd sample out' as sample 1, 2, or 3 (X/X/Y testing mode)
+.IP "\fB<-\fR, \fB->"
+Seek back/forward one second, \fB+shift \fRfor five seconds,
+\fB+control \fRfor 15 seconds, \fB+meta \fRfor one minute.
+.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 "\fBr"
+Toggle through restart-after/restart-every mode (see -r and -R above).
+.IP "\fBs"
+Set start playback point to current playback time (see also -s above).
+.IP "\fBS"
+Reset start playback time to beginning of sample.
+.IP "\fB?"
+Print this keymap.
+.IP "\fB^c"
+Abort testing early.
+8, 16, 24 bit linear integer PCM (format 1), 32 bit float (format 3)
+8, 16, 24 bit linear integer PCM
+16 and 24 bit
+.IP \fBSW 
+Mono signed 16 bit little endian raw with a .sw extension
+.IP \fBOggVorbis
+all Vorbis I files
+\fBsquishyball \fRloads all linear PCM file types at native bit depth. 
+Uncompressed floating point files (eg, 32 bit floating point WAV) are
+converted to 24-bit integer PCM.  Lossy-encoded files (eg, Ogg Vorbis)
+are also decoded to 24 bit by default, unless being tested against a
+16 bit file, in which case decode is to 16 bit.
+Files are 'reconciled' to identical channel ordering, length and
+bit-depth before playback begins so that CPU and memory resources used
+during playback should be identical for both samples.  When 24-bit
+playback is available and one sample is 24-bit, the other sample is
+promoted to 24 bits. If 24-bit playback is unavailable, 24-bit samples
+are demoted to 16 bits.
+Floating point samples (32-bit) are not dithered when converting to 24
+bit, as 24 bit PCM has an equivalent bit depth.  24 bit
+and floating point (32 bit) samples are dithered using a TPDF when
+it's necessary to down-convert to 16 bit.  Lossy-encoded samples (eg
+OggVorbis) are an exception; they are not dithered by default during
+down-conversion to 16 bit. This behavior can be overridden by \fB-d\fR, 
+which forces dithering for lossy files as well.  Down-conversion
+dithering can be disabled for all input types with \fB-t\fR.
+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.
+A/B/X testing randomizes the order of two input samples and presents
+them, unnamed, as sample 'A' and sample 'B'.  A third sample 'X' is
+also chosen randomly from either either 'A' or 'B'.  In each trial, the
+user selects A or B as the sample believed to be the same as X. All
+samples are 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.
+X/X/Y testing is a form of A/B/X testing in which 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.
+Monty <monty at xiph.org>
+\fBabx-comparator\fR(1), \fBogg123\fR(1), \fBoggdec\fR(1), \fBflac\fR(1)

More information about the commits mailing list