[Audacity-quality] Effect input validation and error messages

[Steve t. F. <ste...@gm...>]

Cc: to -devel as this also concerns design policy.

This refers specifically to "Truncate Silence" and "Bass and Treble",
both of which are currently being updated, but also applies more
generally to all built in effects.
(prompted by http://bugzilla.audacityteam.org/show_bug.cgi?id=683#c6)

Currently, user input is validated in a variety of ways. There is
little consistency.

It is often essential that user input is validated so as to avoid
errors, but there are many ways that this can be done. The
"importance" is that the plug-in code receives valid data. The
secondary issue is to help reduce user errors. Input validation does
not, in itself, prevent user errors. What validation does is to ensure
that the code does not try to process with impossible parameters.

A user error may cause an effect to produce the "wrong" result
("rubbish in, rubbish out") but that is not the concern of input
validation.
Invalid data may cause crashes, freezes, corrupting of the project,
security vulnerabilities, or any manner of error. It can be difficult
to work out exactly what problems can be caused by invalid data so it
is important that invalid data is excluded. This is the primary
purpose of validation.

Example below are taken from Audacity 2.0.5 on Windows XP.
Some of the validation approaches are:

* Invalid input is "ignored" by the code. Example: if a negative
number is entered for "repeats" in the Echo effect, the effect exits
doing nothing.
* Invalid input greys out the OK button. Example: enter a positive
number as "New Peak Amplitude" in the Amplify effect.
* Typing invalid characters is prevented (1). Example: Leveller. There
is no way to enter an invalid value.
* Typing invalid characters is prevented (2). Example: most effects
prevent typing non-numeric characters in numerical input field.
* Invalid input produces a pop-up error message on "OK". Example:
Enter a frequency of "0" in High Pass Filter.
* Invalid input produces an "in-line" warning. Example: Enter 0 as
"Minimum silence" in Truncate Silence.
* There are others.

Then there is the question of "what" is validated and the strictness
of the validation.
* Truncate silence allows any combination of numbers, comma, dot, +, -
and "e" as "valid" numbers,
* The Frequency fields in Change Pitch allow only numbers and one dot.
(comma cannot be used as the decimal separator).
* "Optional click track duration" in Click Track allows any characters
to be typed and produces an error on "OK" for invalid values.
* There are other variations.

There are pros and cons to many of these approaches, but the main
reason that we have such a variety (so little consistency) is because
we had no really good general method for input validation. That may be
about to change with the introduction of the new numerical validators
(one for integers and one for float values).
Benefits provided by the new validators include:
* Only allow actual numbers, not just numerical characters: 123.45 is
a valid floating point number. +-1.2.3.4 is not valid.
* Comma is used as the decimal separator with relevant locale.
* Range can be validated (optional). Thus if valid numbers are 0 to
100, then "-" cannot be typed and values greater than 100 cannot be
typed.
* The Integer validator does not allow the decimal separator to be typed.
* Attempting to type an invalid character produces a beep (may require
system sounds to be enabled) and the character is not typed.

Disadvantages of the new validators compared with other methods:
* In-line warnings can be "educational". If the user is unable to type
an invalid value then there is no opportunity to show the educational
message. On the other hand, if they can't type an invalid value then
there is probably not much need to "educate" the user.
* There are implementation issues that can cause accessibility
problems, but it looks like these can be overcome.
* The validators do not prevent invalid values from being pasted, but
this can be handled separately,

Overall, I think that the best policy would be to gradually roll out
the new validators across built-in effects, but not dogmatically so.
There may be some effects where the new validators are too
restrictive, or that the "educational value" of an in-line warning
outweighs the benefit of preventing user error. In most cases I think
it is better to prevent an invalid value from being typed, but I
expect there will be exceptions, for example I think that an in-line
warning could be useful in the Amplify effect rather than just greying
out the OK button.

I think that the main case for including in-line warnings is in cases
where the valid range of values may vary. For example, filters cannot
have a corner frequency greater than half the sample rate, so a low
pass filter frequency of 10 kHz is valid only as long as the sample
rate is greater than 20 kHz. Unfortunately Nyquist plug-ins cannot
currently implement an in-line message, otherwise it would be nice to
have an in-line message in High/Low Pass Filters if the frequency is >
half the sample rate.

I'd like to invite views and opinions as I am currently working on the
interfaces for Bass and Treble and Truncate Silence.

Steve