making contributions

[charlieroberts]

Hi Jussi,

I have some code I'd like to contribute... a Karplus-Strong implementation, a Flanger, a soft-clip etc. What's the best way to do this? Giving them to you as plug-ins would be most convenient for me... but I'm not sure how you're defining what a plugin is vs. should be included in the audiolib.js file.

Also, if you have specific requirements regarding tests or docs let me know.

• Charlie

[jussi-kalliokoski]

Hey Charlie!

Very glad to hear, those are of very much interest to the project! I'd be glad to take at least the Flanger and the soft-clip as part of the core, Karplus-Strong is probably better as a plugin. I'll try my best to guide you through this:

I've tried to keep making individual effects as simple as possible, i.e. minimal amount of boilerplate. GainController is probably the simplest example of how the effects work, all you need to provide is a constructor with a prototype that contains getMix(channel) and pushSample() functions. Then prepend the constructor function with a little documentation. The only required part is that you declare it an effect, using the @effect tag. This provides the build scripts with the necessary information to make it inherit from the Effect class, and to expose it through the namespace, with the additional functionality of making it a factory when it's called without the new keyword.

When you're done this, you can run make wrappers to update the wrappers to expose this functionality. This requires you have NodeJS installed with the following packages: "paramon" and "script-builder". I can also do this for you if you're on a system where installing node, npm, etc. would be tedious.

For plugins, here's an empty example plugin that has all the necessary boilerplate to enable the plugin functionality audiolib.js offers (audiolib.js allows you to export audiolib.js to a worker, alongside with the plugins, etc., and also to make it possible to use the plugins from NodeJS).

For the requirements of tests, so far there aren't any unit tests, nor any automated ones, and the test suite is a complete mess right now anyway, so a simple functionality test will suffice. Whether it's aural or visual is up to you, as long as it's possible to determine if stuff is working from opening it. I'm still planning on how an automated test suite could be made for this project, so maybe someday I'll just scrap the current tests and get the process smoothened a bit.

Documentation is still very much a WIP as well. The only requirement is that the actual effect is described properly, with references to possible original code and authors. As for methods, describing methods that are unique to that effect would be nice, (e.g. it's redundant to describe what getMix and pushSample do, like it's done in the GainController). The GainController is a bad example documentation-wise also because it describes a parameter inside the prototype. Effect parameters should be described in the effect descriptor using the @param tag. The tag has a lot of stuff you can put in it to make it more useful, but the automatic documentation doesn't take leverage of all of the features yet. Arguments for the constructor are described in a similar fashion using the @arg tag, with the exception that they can inherit from a @param by prepending the name with =.

Feel free to ask more!

Cheers, Jussi

[charlieroberts]

Cool. I tried to get the build system going when I first start with audioLib.js, but I think I missed the part about installing paramon and script-builder. I'll give it a go again with those installed; I already have node and npm so hopefully that will get rid of the errors I was seeing.

In the meantime, I already have Karplus-Strong in the plugin format, so I'll just cleanup the code and send a pull request. Also, if you have a chance, take a look at the live coding environment I'm working on (heavily using audioLib.js):

http://www.charlie-roberts.com/gibber http://www.charlie-roberts.com/gibber/info

The codebase is kind of a mess right now, but the functionality is finally getting locked into place, so hopefully I'll be able to refactor it sometime in the near future. - Charlie

[charlieroberts]

Also, here's a gibber script to hear the three fx I mentioned (I don't think they're in any of demo files at the moment):

p = Pluck();

a = Arp("C2m7", _16, "updown", 3).slave(p)

p.fx.add( Clip(100000) );

p.fx.add( Flanger() );

Just run it one line at a time to hear the results, you should hear sound starting with the second line. - Charlie

[jussi-kalliokoski]

Closing as inactive.