new help files

[porres]

hi, opening a new issue here instead of carrying it on in the other thread #15

here's my take on "drown~". I'm using the "fftease/" prefix as usual in the Pd documentation. The other format people normally use (like in Purr Data, just open any cyclone object for instance and you'll see) folles the pddp project, with a text description of what all objects take and arguments. What you had as a model for me was more in the line of Pd Vanilla's (and miller's) style. With all right there. I added information on the arguments that was missing, and I'm fine with whatever, so if you want something like this instead of pddp. I can also check Max's files for reference as well.

[porres]

Well, here's the patch and my final version. I have a "header" abstraction, that I plan to call on all help files. It can then be easily changed to affect all, when you have a new version, for instance, just make it "3.1"

drown~-model.zip

[ericlyon]

Thanks. This helpfile design model works for relatively few messages of drown~, but may need subpatches when there are more options (like pvtuner~). I like the "Gain DSP" abstraction. One issue I had is that the "fftease/" prefix did not work for me. The object only loaded when I removed the prefix. I understand the need to disambiguate 3rd party objects against possible name clashes. In the Max distro, there's a "fftz." prefix for all FFTease objects, and an "el." prefix for all LyonPotpourri objects. I'm fine with the convention proposed here ("fftease/" prefix) as long as it works. Any ideas why it didn't work for me?

One other detail - the overlap factor is not an absolute number of samples but rather a division factor. In order to get a hop size of 128, the correct overlap factor to use here would be 8 (1024/8 = 128).

[ericlyon]

For a hop size of 256 and FFT size of 2048, 8 would also be the overlap factor.

[porres]

Thanks. This helpfile design model works for relatively few messages of drown~, but may need subpatches when there are more options (like pvtuner~).

yup, I'm aware, and you made that remark on your general notes, so it's fine, I'm also very good at organzing things in subpatches :)

I'm fine with the convention proposed here ("fftease/" prefix) as long as it works. Any ideas why it didn't work for me?

for a while now there's a convention that we use ~/documents/pd/externals as the place to put externals. And that folder is one that Pd automatically searches on. So if you have the 'fftease' folder there, the prefix works. But anyway, this convention is old and dates back to Pd Extended days, where it'd obviously also have the external folders in the search path.

[porres]

For a hop size of 256 and FFT size of 2048, 8 would also be the overlap factor.

yeah, I'm just confused about this and was about to open a report for this. I thought the argument was hop size, not overlap. I guess I just got it wrong and need to fix it.

[porres]

yeah, I'm just confused about this and was about to open a report for this. I thought the argument was hop size, not overlap. I guess I just got it wrong and need to fix it.

here it is. Anyway, next time I'll just take a better look into the code and ask before if I have questions :)

latest revision:

help-model.zip

[ericlyon]

The directory update worked. I guess that should be mentioned in the new installation instructions, which will need to be updated in any case. That being said, please continue with the help file model you proposed, and let me know if any questions arise. Thanks!

[porres]

ok, I'll keep this open so I can eventually ask questions and in the end I'll send a Pull Request

[porres]

Here we go. Still about [drown~]. It says "In adaptive mode, the threshold is determined relative to each FFT frame peak.". Ok, but what about non-adaptive mode? What happens then?

[porres]

And now... [thresher~]. It has a "synthresh" message, what is it for?

I also don't get what "oscbank" does and what is the unit of the "transpose" parameter.

For last, why does [drown~] have a "fftinfo" method, but not [thresher~]?

[ericlyon]

Here we go. Still about [drown~]. It says "In adaptive mode, the threshold is determined relative to each FFT frame peak.". Ok, but what about non-adaptive mode? What happens then?

In that case, the threshold is absolute - any bin values that fall below the threshold are multiplied by the drown factor.

[ericlyon]

And now... [thresher~]. It has a "synthresh" message, what is it for?

Generally, that would be the threshold for synthesis. I guess bins that fall below that threshold don't get synthesized. But I'll have to check the code to be sure.

I also don't get what "oscbank" does and what is the unit of the "transpose" parameter.

"oscbank" engages an algorithm that makes "instantaneous" frequency measurements per-bin, after which each bin is resynthesized with its own cosine oscillator. (Ordinarily, synthesis is done with an inverse FFT.)

The "transpose" factor is a unit-less scalar that multiplies all of the frequencies in the spectrum. So if the scalar is 0.5, the pitch goes down an octave, without affecting the speed. A factor of 2 takes the pitch up an octave.

For last, why does [drown~] have a "fftinfo" method, but not [thresher~]?

Probably laziness. It's fine to copy the method into thresher~.

[porres]

Cool, I get it all now.

Generally, that would be the threshold for synthesis. I guess bins that fall below that threshold don't get synthesized. But I'll have to check the code to be sure.

sounds like it, and I see it only works for the 'oscbank' mode

[ericlyon]

For last, why does [drown~] have a "fftinfo" method, but not [thresher~]?

I just updated thresher~ with the "fftinfo" method.

[porres]

So, a modest version of what I wanna do is available at #35

but let's keep this issue opened as I still wanna do a deeper revision

[ericlyon]

Thank you @porres - these look great! I have one question though, about the extra copy of the object at the top of each help file. It's a nice look, but wouldn't that incur additional computation by having two copies of the object in the help file? Some of the FFTease objects can be costly in CPU even when there's no signal input. Maybe an inline GIF would be better, though that might be work for a future edition. In any case, thanks for the great work here!

[ericlyon]

Further to this, I noticed that the bare mindwarp~ object in the help file sends an annoying stream of error messages since its warp factor is zero, unless controlled by an input float or signal. I'll post an update to mindwarp~ that fixes this issue, but we should try all of the new help files with the DACs turned on, to make sure that other similar issues are not revealed.

There's definitely some CPU overhead from the extra object. It's not a lot, since the FFT algorithm uses much less CPU with a zero input signal. I think we can defer this issue to a future release.

[Lucarda]

but we should try all of the new help files with the DACs turned on, to make sure that other similar issues are not revealed.

With the lib built on Win64 as of 7682c35 I get this in the Pd console opening the help patches with DSP on:

<[ FFTease 3.0 ]>   |   ( burrow~ )
<[ FFTease 3.0 ]>   |   ( cavoc27~ )
<[ FFTease 3.0 ]>   |   ( cavoc~ )
<[ FFTease 3.0 ]>   |   ( centerring~ )
<[ FFTease 3.0 ]>   |   ( codepend~ )
incorrect FFT size specified, using 1024
incorrect FFT size specified, using 1024

<[ FFTease 3.0 ]>   |   ( cross~ )
<[ FFTease 3.0 ]>   |   ( dentist~ )
<[ FFTease 3.0 ]>   |   ( disarrain~ )
<[ FFTease 3.0 ]>   |   ( disarray~ )
<[ FFTease 3.0 ]>   |   ( drown~ )
<[ FFTease 3.0 ]>   |   ( enrich~ )
player~: buf: no such array

<[ FFTease 3.0 ]>   |   ( ether~ )
<[ FFTease 3.0 ]>   |   ( leaker~ )
<[ FFTease 3.0 ]>   |   ( mindwarp~ )
<[ FFTease 3.0 ]>   |   ( pvoc~ )
mindwarp~: zero warp factor is illegal

<[ FFTease 3.0 ]>   |   ( morphine~ )
<[ FFTease 3.0 ]>   |   ( multyq~ )
<[ FFTease 3.0 ]>   |   ( pileup~ )
<[ FFTease 3.0 ]>   |   ( pvcompand~ )
<[ FFTease 3.0 ]>   |   ( pvgrain~ )
<[ FFTease 3.0 ]>   |   ( pvharm~ )
<[ FFTease 3.0 ]>   |   ( pvtuner~ )
<[ FFTease 3.0 ]>   |   ( pvwarpb~ )
player~: buf: no such array

<[ FFTease 3.0 ]>   |   ( pvwarp~ )
<[ FFTease 3.0 ]>   |   ( reanimator~ )
<[ FFTease 3.0 ]>   |   ( resent~ )
<[ FFTease 3.0 ]>   |   ( residency_buffer~ )
player~: buf: no such array

<[ FFTease 3.0 ]>   |   ( residency~ )
<[ FFTease 3.0 ]>   |   ( schmear~ )
<[ FFTease 3.0 ]>   |   ( scrape~ )
<[ FFTease 3.0 ]>   |   ( shapee~ )
<[ FFTease 3.0 ]>   |   ( swinger~ )
<[ FFTease 3.0 ]>   |   ( taint~ )
<[ FFTease 3.0 ]>   |   ( bthresher~ )
<[ FFTease 3.0 ]>   |   ( thresher~ )
<[ FFTease 3.0 ]>   |   ( vacancy~ )
<[ FFTease 3.0 ]>   |   ( xsyn~ )

[ericlyon]

The codepend~ warning catches a typo in the help file - 1028 is an illegal FFT size. It should be 1024.

[ericlyon]

The mindwarp~ warning should be gone in the most recent version of the code as of 57667df.

[ericlyon]

pvwarpb~ - in the help file, bare object at top, replace "buf" with "pvwarpb-array."

[ericlyon]

enrich~ - in bare object at top, replace "buf" with "enrich-buffer."

[ericlyon]

Similar solutions for pvwarpb~ and residency_buffer~

[Lucarda]

I'm building the latest 7682c35 and the "mindwarp~: zero warp factor is illegal" error is still there on the console while DSP is on.

[porres]

Thank you @porres - these look great!

you're welcome :)

I have one question though, about the extra copy of the object at the top of each help file. It's a nice look, but wouldn't that incur additional computation by having two copies of the object in the help file?

Yes it would. I'm not married to that and I don't really use that in my help files of cyclone and ELSE, but it's a common standard that I was just trying to replcate.

Some of the FFTease objects can be costly in CPU even when there's no signal input. Maybe an inline GIF would be better, though that might be work for a future edition. In any case, thanks for the great work here!

Yeah, I'm up for a different design for the future. We can pass the name of the object as an argument to the [icon] abstraction. I made a couple of tests.

[ericlyon]

@porres - the new proposed model is great! I have a slight preference for the "bthresher~" design.

[porres]

but both designs are the same :) I'm just passing the name of the object as an argument. I tested with residency_buffer~ because that's the longest object name, to see if it fits. All the others will seem justified to the left.

[porres]

Oh, I guess I know what you mean, about the positioning, right?

[ericlyon]

Correct. The bthresher~ positioning style looks the best.

[ericlyon]

@Lucarda - I could not reproduce the mindwarp~ message with the most recent version. That error message literally no longer exists in the code. Is it possible you're loading an older version of the external?

[porres]

Oh, I guess I know what you mean, about the positioning, right?

So, sometimes that will depend on how the window is filled, if it has too much text or information, I will have the tendency to fit things together in a way that doesn't waste any of the window's real state :)

But I can force that standard

[ericlyon]

@porres I leave it to your aesthetic judgement. Thanks!

[porres]

I'm fixing the documentation issues...

[porres]

this will be a separate issue, but I think you should allow all objects to be created without any arguments. Some objects here have mandatory arguments and then you can't create the object. In Max, that doesn't prevent you from opening the help file so you know what you have to do, but in Pd you can't do it and I don't think it's a good idea.

[Lucarda]

@Lucarda - I could not reproduce the mindwarp~ message with the most recent version. That error message literally no longer exists in the code. Is it possible you're loading an older version of the external?

Yes my bad. I was opening the newer help patches but had and older "documents/Pd/externals/fftease" laying around that got loaded.