Text Envelope

Well it turned out to be more of a challenge than anticipated, but finally it’s here.
A Nyquist plug-in that allows envelopes to be created via text entry.

This plug-in is basically complete, but requires a bit of tidying of the code.
This is a version 3 plug-in and requires Audacity 1.3.x

New features in version 0.8 beta:
Intermediate Control Points do not need to be entered in time order. As long as they are entered as valid pairs of values they will be sorted into the correct order automatically.

Help screens included (see below)

To Do:
May need some minor changes to the formatting of Help screens for compatibility with 800 x 600 screens on all platforms.
Volunteers to assist with this would be much appreciated.

Thorough testing on all platforms, particularly for sensible handling of invalid data input.

HELP (overview):

The ‘Initial Amplification’ is how much to amplify the start
of the selection. The ‘Final Amplification’ is how much to
amplify the end of the selection.

When Amplification Units are dB, silence is achieved by
entering ‘-inf’ (without quotes) or use a large negative value.
Other than ‘-inf’, all entered text must be numerical.

Intermediate points must be entered as a
‘time’ ‘amplification’ pair of values separated by a space.
Each pair of values must be separated from other pairs by
one or more spaces.

The time value for intermediate control points indicates
the distance from the start of the selection.
When time units are set to ‘%’ all Intermediate Control
Points must have time values in the range 0% to 100%.
When time units are set to seconds, milliseconds, or
minutes the number entered is the time after the start of
the selection. Decimals are allowed but should use a dot
as a decimal separator.

All fades between control points are linear.


EXAMPLES:
Fade out from full volume to silence:

For % settings:
Initial Amplification = 100
Final Amplification = 0

For dB settings:
Initial Amplification = 0
Final Amplification = -inf

Fade from silence at 0 seconds, to full volume after
2 seconds, then back to silence at the end:

For % Amplification settings / Time settings in seconds:
Initial Amplification = 0
Final Amplification = 0
Intermediate Control Points = 2 100

For dB Amplification settings / Time settings in seconds:
Initial Amplification = -inf
Final Amplification = -inf
Intermediate Control Points = 2 0

Comments, feedback, bug reports and suggestions welcome.
[Latest version available on the Audacity wiki]
TextEnvelope-8.ny (8.53 KB)

I’ll volunteer for that since I’m forced to use 800x600 on Ubuntu with the motherboard I have on that machine.

However if you use n and double carriage returns for paragraphs you’ll get too much space between the paragraphs. That makes the Quick Help overflow at larger dpi’s, even at 1024x768. I think it’s better to use a (single) carriage return only for paragraphs, and indicate a line break with n. You can always turn word wrap on temporarily in the editor to see what you are doing.

Instead of " as text in the form ‘t1 a1 t2 a2 … tn an’ " for GUI explanation of “Intermediate Control Points”, how about "pairs of time and amplitude values e.g. ‘1 40 2 20’ "?

No other comments yet, but looks exciting. Personally I think the loss of the sliders is a benefit over Fade+ (you get the dB reduction you ask for, and no confusing/space consuming “Amplification Multiplier”). Looking forward to the demo of “target amplitude” for possible use in either.


Gale

OK, done that.

I like that, except it pushes the screen a bit too wide.
How about

Intermediate Control Points as text pairs
of time and amplify e.g. ‘1 100 2 20’


version 0.81 (beta) attached (obsolete).
[Latest version at end of topic]
TextEnvelope-081.ny (8.53 KB)

If you drop “text” (I think that’s obvious after the ;info line) you can use the correct “amplification” word:

Intermediate Control Points as pairs ofntime and amplification e.g. ‘1 40 2 20’

(“40” saves a character, and is a more reasonable number for dB amplification, but whatever).

Two other things otherwise gotta go:

• The error values thrown when you enter negative values with units set to “%” aren’t correct. If you have a 30 seconds track and enter initial and final amplification of -4 and -3 respectively, then control points of 10 -40 20 2, you’ll see what I mean.
• Also with the above (dB) initial/final values and control points on a 30s tone of constant amplitude 1.0, some people may actually not be expecting clipping after 18s. They may think the 20s point is being increased from -40 dB, so that 20s is at -38 dB. It may be worth clarifying this in Quick Help.

Gale

Fits nicely

Should now be correct.

Updated first paragraph of Quick Help.

version 0.82 (beta) attached (obsolete).
[Latest version at end of topic]
TextEnvelope-082.ny (8.62 KB)

from discussion with Edgar on audacity-nyquist:

Edgar replied:

Please excuse, but what I do not understand:

Is there no wx-widgets function to determine the number of characters per line? Or how is this window specified in the
Audacity C/C++ code?

To write a formatting routine it needs exact specifications, not vague guesses. Everything else makes not much sense.

I certainly don’t fully understand this either. It’s something I have on a list of Nyquist matters to be investigated or improved for future.

However as far as those Nyquist “help” or error dialogues go, the OS seems to determine when to wrap the lines, for want of anything else. Linux systems seem to wrap at about 60 characters and Windows at about 70 characters. Would it work better if we just let the OS wrap the text, and only had a carriage return for a new paragraph?

I think it might, but we’d still have to watch the number of lines, so would still have to check it out on different platforms. There is no vertical scrollbar if the text is too long - it just goes off screen.

In contrast, some Widgets windows (progress dialogues and message boxes come to mind) don’t seem to wrap horizontally at all - they’re as wide as you want and just go off screen if they are too wide for the screen.


Gale

I think it probably would, but do you know what Macs do?
I presume that there can be variation depending on the default font / font size?

Another weird thing - on Linux, text layout of the help screen is different if I run the plug-in from Nyquist Workbench to if I run it as an installed plug-in.

Also, on Linux, with the OS wrapping the text, the line length changes depending on the number of lines.

Is there really no way to have screens with scroll bars? The current situation is like trying to write a manual in haiku.

Would it be worth having a forum or wiki topic about these? There are a number of limitations of the Nyquist plug-in GUI that come up repeatedly.

Audacity CVS HEAD (Mai 22, 2010)
Debian Lenny with Gnome 2.22.3
Tested screen resolutions: 1280x1024, 1024x768, 800x600, 640x480
All resolutions the same result:

47 characters horizontal max.
11 visible text lines

• 1 half-visible line

File: “src/effects/nyquist/Nyquist.cpp”
Search for “NyquistOutputDialog”, Line 1260 ff.

1. The text window is defined in pixels instead of characters and lines
2. The text font is proportional instead of fixed width

With these settings it’s not possible to write a text formatter from the Lisp level at all.

The good news is: since I’m switched from Ubuntu back to Debian I finally have sound again…

• edgar

I’ll repost the Help for Text Envelope with all text for each paragraph on one long line, after checking/fitting the number of lines on Ubuntu 800x600. Hopefully Koz or Bill can try it out on Mac (perhaps you could PM them to ask for help in case they are not following this).

Certainly on Windows, the wrap takes font/font size of message boxes into account, so that the Nyquist help screens remain properly wrapped even at ridiculously large font sizes.

I think we need a Wiki page so it will be more “visible” by developers. There wasn’t any direct urgency for this, as all changes like this were for “after 2.0”. But if you can start a “shopping list” thread on the Nyquist board of things we’d like to fix/improve, that would be useful. Anyone on the Forum could add points there, and then everything could be collated/organised onto a Wiki Proposal page.


Gale

I’ve changed my mind about this. Because the “pages” need to so small, allowing Ubuntu to handle the text wrapping produces just a few long lines on a full size screen which looks silly.

I’ve now incorporated some enhancements proposed by David Bailes:

The Intermediate Control Points may now be delimited by spaces or commas.
This allows lists such as this (which I think are a lot easier to read and check whether using a screen reader or not):
1,0 2,-6 5,-18 6,-20 8,-20
or if the user prefers:
1 0 , 2 -6 , 5 -18 , 6 -20 , 8 -20

Times may now be given relative to the start of the track (positive values), or counting back from the end of the track (negative values).
For example, to fade in and fade out of 10 seconds, the % amplification of start and end would be set to 0, and then there could be two control points: 10,100 -10,100.

Also some changes to the help screens.
Hopefully I’ve not broken anything in doing this.

[Latest version at end of topic]
TextEnvelope-083.ny (9.82 KB)

I’m considering adding support for parentheses to be used in the intermediate control point list, so that control points can be added in the form:
(time , amplification)
for example:
(1,0)(2,-6)(-2,-6)(-1,0)

Any comments?

Maybe it’s an unnecessary complication, and there are already a lot of options? You can already use extra spaces to separate values or pairs, so it should be easy enough to tell between them. Parentheses to me are quite an RSI-inducing movement.

Another Nyquist Feature Request I might have is for centre-valigned dot separators in text boxes (a bit like you see typing IP addresses into boxes). I suppose since they would have to allow for four character spacing so wouldn’t be space-efficient.

I don’t know if the help could be clearer that you don’t need to add + to intermediate control points if you only want them to count from selection start.

Where the help says decimals must use a dot as a separator, how does this work in locales that use , (comma) as separator? I think Nyquist normally interprets commas as decimal separators there?


I’ll try and double check the Help screens on Ubuntu later if no-one beats me to it.



Gale

I think parentheses make it a lot easier to read the pairs of values, but I quite agree about RSI

As providing choice of which characters are used as delimiters does not require the user to specify/select the option, and it is very easy to add other characters as valid separators, perhaps I could include parentheses as an undocumented ‘Easter Egg’. Then if anyone asks for it, it’s already there and can just be added to the documentation.

but I don’t think that spaces are read by screen readers, which I presume is why David Bailes requested an option of commas or semi-colons.

I think that;
1 -6 3 -12 9 -3
would be read as:
one minus six three minus twelve nine minus three

whereas;
1 -6 , 3 -12 , 9 -3
would be read as:
one minus six comma three minus twelve comma nine minus three
in which it is considerably easier to identify the pairs.

Similarly for sighted user
(1 , -6) (3 , -12) (9 , -3)
is very easy to read, and possibly what I would prefer to use if using a lot of control points in the envelope.

I’m not sure how/if that would work with this effect as there is no set number of value pairs, though it may be useful with other effects?

There’s now a second page of examples (“More Tips”) and no sign of a “+” anywhere, so I think it’s reasonably obvious that “+” signs are not required.
If a user does type ‘+3’ instead of just ‘3’, then it still works and does not break anything. On balance I think it is sufficiently clear without the Help screens becoming more verbose.

I did think about that, and was hoping that you might have a definitive answer to that question

Is it just the language selection (Preferences > Interface > Language) that affect this, or do any system settings make a difference?

I’ve tested the effect with the Audacity language set to Nederlands and the decimal separator needs to be a dot. Commas do not work in this effect or in other Nyquist effects, though commas do work in some (not all) non-Nyquist effects.

I happen to find parentheses very tiring to look at (as well as to type), but we certainly needed more than spaces to act as delimiter. If you are going to add parentheses as a bonus, why not add semi-colon as well? 1,-2; 6,2; 7,3 would work well for me visually and no doubt others would have other preferences from entering pairs a particular way in other applications.

I was thinking of the user that read the overview without going further into help - I would definitely read the overview in isolation that + was required for time after start. I also completely misread it to mean that - or + modifiers only worked with the % choice. So I would put the “start/end selection” blurb as the first thing to say about Control Points. “Time values are read from the start of the selection; put a minus sign before the value to read from the selection end.”? Three more words, and being able to use + is another bonus.

From the discussions before about this, I think at the very least you have to change the system language, and really the only way to test it for sure on Windows is to install the OS in that language. On Linux, setting LC_ALL or LANG and restarting might be enough. If entering “2.5” gives you 2.5, you haven’t changed enough to test it.

So I suspect “Decimals must use the normal decimal separator for your locale, such as a dot.” would be more accurate.




Gale

I’ve just added the following options:
(){};:,

Ah - there could be a reason for that . When I first added the ‘-’ modifier, it was only for % time, but after trying it I found it was also useful for ‘absolute’ time.

OK, I changed the system language on my VirtualBox Ubuntu Studio 10.04
Audacity automatically selects Dutch (Nederlands)
I can generate a tone with amplitude 0,5
but if I type 0,5 into the Nyquist Prompt box and click on debug, I get “error: unbound function - COMMA”
Generate > pluck > length=2.5 seconds produces 2.5 seconds, but
Generate > pluck > length=2,5 seconds produces 2.0 seconds

Perhaps I’ve not made Audacity Dutch enough, but as far as I can tell Nyquist is not accepting a comma as a decimal separator.
I can’t peruse this further because I can’t read Dutch and it’s really confusing trying to work out what the heck is going on.

Multi language support for Nyquist plug-ins is a non-starter anyway, because all of the GUI text is in English.

The choice are:

1. I disallow using a comma as a separator for list values for all users.
2. I allow using a comma as a separator, but I include a comment in the code that explains how to remove the option of a comma as a list separator.

Question - comma-separated values (CSV) is one of the most common text formats for a database tables. How do people cope with that in countries that use commas as decimal separators?

I had a look at the Help. The Quick Help “overview” had the OK/Cancel buttons almost hidden on my Ubuntu system which I’ve corrected.

I corrected a “Conrol” typo and clarified in the overview that negative values can be used with any Time Unit, and you don’t need to add “+” for positive values. That meant we don’t need that in “tips” as well so I replaced that with a “tip” about the different meaning of “0” in Amplification Units. Also made consistency changes e.g “original” volume instead of “full” in “Examples”. That made the ;info line look a bit incongruous so I ended up changing that as well (now one line less). Anyway, just change anything you really don’t like except that the Overview is about at the limit for text. To be honest, do we need any ;info line text? Some would argue that with a Help file we could make inline text minimal to be like the inbuilt plug-ins…

As for dots for decimal separators, I could install Win7 in German on a partition, but perhaps Edgar could take a look if you asked him?



Gale

[Latest version at end of topic]
TextEnvelope-084.ny (9.93 KB)

I’ve had a definitive reply from Edgar regarding this and it is as I suspected.
Nyquist (like nearly all programming languages in international context) always uses a dot (period) as the decimal separator.

The comma-to-dot translation with floating point numbers is managed by wx-widgets inside the Audacity Nyquist interface BEFORE the user input is given to the Nyquist interpreter, and this only applies to floating point numbers entered in the “slider widgets”. (this is currently broken in Audacity 1.3.12 and 1.3.13 but not relevant to this plug-in).

In the case of this plug-in, the data is entered in a “text input widget” as a string. The string is then converted within Nyquist into a list of values. This means that the comma-to-dot translation by wx-widgets in Audacity is bypassed. Full story here: http://audacity.238276.n2.nabble.com/Commas-and-dots-with-numbers-and-strings-tp5198891p5198891.html

For now I intend to complete a version that uses a dot as the decimal separator (and make that as clear as is practical in both the main interface and the help screen).

If there is sufficient demand I could include an extra control to select whether to use a dot or comma as the decimal separator, but of course if the user chose to use a comma, then a comma could not be used as a separator for the list of variables.

I think as Edgar pointed out in his follow-up post, it is potentially confusing for there to be intended comma > dot translation in appropriate locales for text boxes associated with sliders, but not for “free-form” text boxes (for want of another phrase). This irritation has come up before in connection with some of David Sky’s proposed plug-ins. I’m inclined to think a better approach is to let the user type what is the recognised decimal separator for them in all user-level input boxes, then standardise the variables separator to something that’s never used as a decimal separator.

Unless we get into distributing “translated” versions of Nyquist plug-ins, I can’t see any case for having a control for the decimal separator. It would just confuse. I’d rather use that space to have un-enigmatic separate boxes for each value pair (which means Nyquist has to support more than one box per line); or solve it some other way by Nyquist permitting a physical separator inside the box. OK this limits the number of values, but inventive types should be able to run the effect in two passes to get what they want.


Gale

I think that would would cause as much irritation for users with other locales.
As Nyquist is unaware of the locale, in order to allow the use of commas as decimal separators, conversion of commas into dots must be coded into the Nyquist script. That means that ALL commas will be converted to dots. So if an English/American/Australian/Swiss/Israeli/Japanese/Korean/Malaysian/… user forgets that comma separated variables are not allowed they will get very odd errors.

A possible compromise - I could include something like this near the top of the file:



;nyquist plug-in
;version 3
;type process
;name “…”
;action “…”
;info “…TO ALLOW THE USE OF DECIMAL COMMAS, OPEN THE .NY FILE IN A TEXT EDITORnAND FOLLOW THE INSTRUCTIONS FOR EUROPEAN USERS…”

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; INSTRUCTIONS FOR EUROPEAN USERS
;;
;; To enable use of a comma as the decimal separator
;; change the next line to (setq decimal 1)

(setq decimal 0)

;; *** IMPORTANT ***
;; IF YOU SET THE DECIMAL SEPARATOR TO A COMMA
;; YOU CANNOT ALSO USE IT AS A LIST SEPARATOR.
;; End Of Instructions.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;


Alternatively, I could code in this option and make both versions available for download.
Having used this effect, for my own use I would definitely prefer to be able to use commas as list separators.