Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

What would be a best practice to integrate FAUST-generated Plugins? #147

Open
florian-grond opened this issue Jun 5, 2017 · 27 comments
Open

What would be a best practice to integrate FAUST-generated Plugins? #147

florian-grond opened this issue Jun 5, 2017 · 27 comments

Comments

@florian-grond
Copy link
Contributor

Given that FAUST is getting ever more popular and will be a great codebase that can contribute to the SC3-plugins, how should we define best practices:

Some issues:

  1. Naming convention: FAUST plugins have Faust as a prefix
  2. How can we include or refer to the Faust sources
  3. should Faust generated SC code (the .sc representation of the UGen) be modified or not.
@florian-grond florian-grond changed the title What would be a best practice tointegrate FAUST generated Plugins? What would be a best practice to integrate FAUST-generated Plugins? Jun 5, 2017
@telephon
Copy link
Member

telephon commented Jun 5, 2017 •
edited
Loading

Is there a possibility to change anything about 1. and 3.? That is, could we propose improvements to the faust to supercollider code generation?

@LFSaw
Copy link
Member

LFSaw commented Jun 5, 2017

this is an issue emerging from #147 and #143 .

@LFSaw
Copy link
Member

LFSaw commented Jun 5, 2017

@telephon, the FAUST developers are very active and responsive, so yes, possibly so.

@telephon
Copy link
Member

telephon commented Jun 5, 2017

Should we work out a kind of optimal idea from the sc side and then suggest this to the FAUST developers?

@florian-grond
Copy link
Contributor Author

florian-grond commented Jun 6, 2017 •
edited
Loading

My experience from the ambitools implementation from Pierre Lecomte (which is complex and therefore a good example, I think) and compiling it for SC is the following:

  1. Big FAUST projects can come with their own non-standard libraries to organize code better, this is one reason why there is not necessarily a simple FAUST source -> cpp file relationship (in a sense that this source can be easily compiled without running into dependency issues)
    However if while compiling these sources get assembled at some point this is what we might want to catch as sources to be included with the plugin code. No idea if this is feasible.

  2. It would be awesome if the faust2supercollider script could also generate an SC helpfile.
    Even cooler if code comments in FAUST, e.g. for the in and out busses could be translated into this helpfile. This helpfile could then feature prominently that this UGen was compiled with FAUST with all sorts of version and author info, the later extracted from the .dsp file.
    Then the FAUST prefix for the UGen could possibly be dropped and FAUST leaves its traces.

  3. FAUST code is a bit cryptic for the beginner (and continues to be cryptic for me), the autogenerated cpp file is pretty much unreadable. But FAUST can make fantastic svg graphics of the signal flow, this would be great to include in the helpfile which would add didactic value of what this UGen is actually doing. maybe this cann all be done through the faust2supercollider script.
    I believe this would be a real incentive to use FAUST and SC in teaching contexts.

  4. In general, I'm wondering if there are mechanisms to carry over data structures from the dsp file into the SC class. To give an example, Ambisonics decoders necessarily need the info about speaker positions which is important information for generating the decoding matrix. So it would be cool to have those positions in the dsp file somewhere and then translate them into say a class variable of the SC class file so that they can be later accessed when building monitoring GUIs that visualize the speakers etc.

@telephon
Copy link
Member

telephon commented Jun 6, 2017

These are really good ideas, @florian-grond. Let's see what can be done. I certainly can offer to help thinking through of the sc-class file generation.

@florian-grond
Copy link
Contributor Author

I believe most of the ideas above need to be implemented on the FAUST side. @LFSaw, I'm sure you would have a wishlist yourself ;-)
I would suspect that FAUST developers might be inclined to put effort into this if the potential impact is beyond SC.
Defining best practices to document code in FAUST and translating this documentation into other platforms might be such a thing.

@florian-grond
Copy link
Contributor Author

florian-grond commented Jun 6, 2017 •
edited
Loading

I was just reading up on code documentation options in FAUST:
see section 9 in this doc:
http://faust.grame.fr/images/faust-quick-reference.pdf

There is plenty of stuff addressing many of the points from above.
Any thoughts on how to best translate that into SC helpfiles?

@LFSaw Just looking at the info you have compiled here:
sc3-plugins/source/DEINDUGens/faust_src/README.md

if you have a moment to read the section 9 in the link to the FAUST documentation from above, the command faust2mathdoc, in fact, addresses many of the ideas discussed here already, just that it produces a PDF and would like to have a SC helpfile.

One point that I think we could discuss with the FAUST devs is how to best document in and out busses. This could potentially translate into many other platforms (PD, MaxMSP, etc.) where the function of in and outlets also needs to be documented.

@telephon
Copy link
Member

telephon commented Jun 9, 2017

@florian-grond so you mean this section?

9.4 Automatic documentation

By default, when no tag can be found in the input FAUST file, the -mdoc option automatically generates a LATEX file with four sections:

  1. ”Equations of process”, gathering all formulas needed for process,
  2. ”Block-diagram schema of process”, showing the top-level block-diagram of
    process,
  3. ”Notice of this documentation”, summing up generation and conventions
    information,
  4. ”Complete listing of the input code”, listing all needed input files (including libraries).

So the main point would be to convert that LaTeX-file into schelp?

@florian-grond
Copy link
Contributor Author

florian-grond commented Jun 10, 2017 •
edited
Loading

yes, this is the section I mean, and yes, this would be the main point: translating the LaTeX-file into schelp.
I am wondering though if we could extract from this a proper description of the audio in and out busses for the schelp file. So I thought we might want to enquire for this with the FAUST devs, how they think this should be properly documented in the FAUST file, and then find out how to translate this into the schelp file.

@telephon
Copy link
Member

yes, this sounds good. In FAUST, all arguments of a unit are single channel streams of floats, right? So the regrouping for supercollider is a thing that probably we could take care of separately. In general, all inputs that have numbers, like a1, a2 etc. should probably be grouped to an array.

@florian-grond
Copy link
Contributor Author

Yes, the regrouping we could take care of separately, we just need to find out how to properly document inputs (outputs) in FAUST. I think this should be of general interest, while less necessary for plugins with a GUI, platforms like MaxMSP and PureData also need to document their inlets and outlets. I'll enquire with the FAUST devs ...

@jamshark70
Copy link
Contributor

I'm not sure if I should mention it here as a side note, or open a separate issue for it, but -- if we're discussing FAUST integration, I'd like to suggest removing the plug-in load messages from the default verbosity level:

booting server 'localhost' on address: 127.0.0.1:57110
Faust: supercollider.cpp: sc_api_version = 2
Faust: FaustJPverbRaw numControls=11
Faust: supercollider.cpp: sc_api_version = 2
Faust: FaustGreyholeRaw numControls=7
Found 370 LADSPA plugins
JackDriver: client name is 'SuperCollider' ... etc

The four Faust lines are not necessary. During normal usage, sc_api_version and numControls are totally, 100% irrelevant to anything that users care about. They are relevant only to be sure SC is picking up the Faust definition properly.

Currently there are just two Faust plug-ins, so it's not too much output -- it is irritating but not overwhelming. But if "FAUST is getting ever more popular and will be a great codebase that can contribute to the SC3-plugins" and eventually we have more Faust-generated plug-ins, the extra output may well become a burden.

I think we could safely remove it completely. But, if some people feel it would be useful for debugging new plug-ins, then I would suggest adding a new verbosity level 1 (debug level) and print these messages only for that level.

@florian-grond
Copy link
Contributor Author

florian-grond commented Jul 19, 2017 via email

@capocasa
Copy link
Member

capocasa commented Jul 19, 2017 •
edited
Loading

@florian-grond suggest to make it conditional on NDEBUG, as are the other Faust messages that do not appear in scsynth production. If there are no objections I can do a pull request to Faust

@capocasa
Copy link
Member

capocasa commented Jul 19, 2017 •
edited
Loading

Late to the party, but I brought a keg! Well, more like six pack... a bottle for sure.

@telephon @florian-grond

Yes, 1. and 3. can absolutely be avoided. I just figured that out trying make my JPverb_supernova fix palatable to @LFSaw in #149.

  1. The prefixing can be disabled by adding #define SC_FAUST_PREFIX="" by compiler parameters- JPverb does this, but it appears to me to be broken.

  2. I suggest to generate the .cpp and commit it to the repository for stability and consistency, like JPverb is doing. If we start mass-importing Faust plugins, a script could be used to do this with the current Faust version after every SC major release, for example, in the hopes of receiving new optimizations.

  3. I suggest to write the sclang classes manually. APIs are one of those things that don't change much by design, so we can afford to give them a little careful thought and polish. Once they're released we're stuck with them, basically forever.

An additional script could use faust2supercollider to quckly install anything else (at the user's risk), maintaining the Faust prefix because that shows nicely it's not an official SC UGen. Here, a good parameter autoconverter seems like a good choice.

@capocasa
Copy link
Member

@jamshark70 The debug output issue was caused by a bug in our build system, not setting the necessary compile time flags for the supernova versions of JPverb and Greyhole- #149 fixes this as well.

@capocasa
Copy link
Member

Great news! Faust also merged my modification of the supercollider2faust script into their master-dev. Supernova is now a fully first-class citizen in the Faust world.

grame-cncm/faust#70

@florian-grond
Copy link
Contributor Author

florian-grond commented Jul 21, 2017 via email

@mossheim
Copy link
Contributor

Who has control of the supercollider2faust script?

@mossheim
Copy link
Contributor

Lessons from #146 -

  1. Don't modify the top-level CMakeLists (or provide this in a separate PR). In other words, only set properties on the targets being added in a PR. Or better yet, ask first if you're unsure.
  2. Only add the source files.
  3. Macros cannot be namespaced, so they should be as specific as possible to avoid collisions with other commonly used macros. Debugging tools like extra printing should be controlled with a precisely named macro that includes the FAUST_ prefix.

@florian-grond
Copy link
Contributor Author

I believe it is Stéphane Letz @sletz who has control over the faust2supercollider script

This is the faust2supercollider script:
https://github.com/grame-cncm/faust/blob/master-dev/tools/faust2appls/faust2supercollider
The faust2supercollider script has debug-flags but the print debug code lines always end up in the source CPP files

this is where the CPP file is generated:
https://github.com/grame-cncm/faust/blob/master-dev/tools/faust2appls/faust2supercollider#L179

it calls for the supercollider.cpp architecture file:
https://github.com/grame-cncm/faust/blob/master-dev/architecture/supercollider.cpp

These are the lines where the pesky debug prints are generated:
https://github.com/grame-cncm/faust/blob/master-dev/architecture/supercollider.cpp#L440
https://github.com/grame-cncm/faust/blob/master-dev/architecture/supercollider.cpp#L503
https://github.com/grame-cncm/faust/blob/master-dev/architecture/supercollider.cpp#L532

I believe that these debug prints served a certain purpose when developing the architecture file.
But I side with @jamshark70 that they are pointless today.

Maybe we can suggest to remove them all together or wrap them in a different macro. But this needs to be negotiated with the Faust devs. I feel less confident to argue for a solution that is serving the needs of all devs involved. If you wanna make a suggestion @brianlheim please go ahead.

Again this would make contributions through Faust much easier.

As far as the only set properties on the targets being added in a PR is concerned.
The bracket nesting issue will likely concern several future Faust-generated sources. Is there a way to set the property for folders (which contain Faust-generated CPP code) and not only for single files?

@sletz
Copy link

sletz commented Jan 31, 2018

Can you guys just submit a PR (against master-dev branch ) for the needed change?

@florian-grond
Copy link
Contributor Author

@sletz we had discussed similar matters in the past maybe you can do the changes Stéphane?

What we need for Faust contributions to the SC3plugins repository is fairly simple:
Faust generated Ugen.cpp sources without the Print statements under the NDEBUG macro.

such as those (there are 3 occurences)
#if !defined(NDEBUG) Print("Faust: %s numControls=%d\n", name.c_str(), g_numControls); #endif // NDEBUG

We would very much like to not mess with the .cpp sources after creating them (like editing them and removing these code parts) so as to fully profit from the Faust induced workflow.

If you think this debug message is still useful for future development of this architecture file, maybe you can give it a macro different from NDEBUG? that is not defined by default and needs to be defined in order to activate the printout when developing? (You might find a solution for this that is orthodox for developers)

Or modify the faust2supercollider script so that there is the option to get cpp sources (with the very useful -ks flag) that do not have this print messages?

@mossheim
Copy link
Contributor

If you wanna make a suggestion @brianlheim please go ahead.

Sorry, I will not collaborate with Stéphane given previous interactions. Someone else will have to do this.

@florian-grond
Copy link
Contributor Author

florian-grond commented Jan 31, 2018 via email

@patrickdupuis
Copy link
Contributor

Thanks for taking the lead with regards to Faust-SC. It's much appreciated :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
8 participants
@LFSaw @jamshark70 @capocasa @florian-grond @sletz @telephon @patrickdupuis @mossheim