[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
Modified:
websites/celt-codec.org/squishyball/squishyball.1
Log:
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 @@
- "CONVERSION AND DITHER:\n"
- " 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"
+
+.SH NAME
+squishyball \- perform A/B, A/B/X and X/X/Y testing on the command line
+
+.SH SYNOPSIS
+.B squishyball
+[\fIoptions\fR]
+.I fileA fileB
+
+.SH DESCRIPTION
+.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.
+
+.SH OPTIONS
+.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.
+
+.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"
+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.
+
+.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
+.IP \fBFLAC/OggFLAC
+16 and 24 bit
+.IP \fBSW
+Mono signed 16 bit little endian raw with a .sw extension
+.IP \fBOggVorbis
+all Vorbis I files
+
+.SH CONVERSION AND DITHER
+\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.
+
+.SH A/B TESTING
+
+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.
+
+.SH A/B/X TESTING
+
+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.
+
+.SH X/X/Y TESTING
+
+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.
+
+.SH AUTHORS
+Monty <monty at xiph.org>
+
+.SH "SEE ALSO"
+
+.PP
+\fBabx-comparator\fR(1), \fBogg123\fR(1), \fBoggdec\fR(1), \fBflac\fR(1)
More information about the commits
mailing list