SuperCollider 4: First Thoughts

A thousand times this. Thank you for saying so.

The example demonstrates shadowing.

Yes, in relation to making this efficient, and that some implementations are quite strange.

I’d imagined SuperCollider doing something like:

{var x; x = 0; var y = 1; x + y} => {var x; x = 0; {var y = 1; x + y}.value}

and then analysing it to know if it was safe to delete the inner function.

It seemed like quite a bit of work, and I was just curious if it was worth it.

I’m very happy to know it’s actually straightforwards!


Ps. There’s this (very old!) issue about possibly useful interpreter warnings, including shadowing.

Pps. Also (and obliquely related to Lua) the commentary at has some interesting notes about implementing Smalltalk like interpreters, ie. “Final conclusion December 2020”.

{var a = 10.rand + x; var x = 50; a}

Very nice knowledge!

Of course this looks completely normal as Haskell!

  let {a = 10 + x;x = 50} in a


The reason why it (ahem) “works” is because vars initialized to literals save the initial value in the function’s prototypeFrame, so they are available from the beginning of the function’s execution. Initializing to an expression requires evaluating the expression, which of course doesn’t happen until the interpreter reaches the expression’s bytecodes (so the result is not available at the start of the function.

Not really a parser bug – a side effect of the design of execution frames.



Thanks for the explanation! Makes sense.

I think there’s a way to make SC4 a strong reality… which seems very difficult, considering many conflicts of interest.

Here is the top ten list of most frequently answered ‘pain points’ from the most recent survey, most of them are related:

  • Documentation is missing / unclear
  • Tutorial materials are missing / unclear
  • Debugging is difficult
  • Errors messages confusing
  • sclang syntax is difficult
  • making GUI’s is difficult
  • …too many ways of doing things

…and so with so many ideas contributing to the same idea pool, it seems the language has become to an extent scattered and disorganized.

I’ve been thinking of the possibility of organizing SC’s reference source into 4/5 main sections… something like:

Client Server Guides Extensions 

…with perhaps GUI being the fifth, or perhaps as a client abstraction.

Guides would be reserved for reference material to cross boundaries, as well as introductory material.

Each one of the four, five, or six Main sections would then have a limited number of sub-sections (abstractions like Collections, Streams, Ugens, JITLib, etc.) …and each sub-section would most likely end with it’s own dedicated tutorial, and it’s class reference.

It’s just an idea… to keep everything organized would make it easier for everyone when trying to meet a specific intent, as well as for building extensions that fit in well with the rest of the language.

1 Like

There is definitely something that we can do to improve the state of SuperCollider’s documentation. I guess that it is not necessary to wait for SuperCollider 4 to start the work on this aspect. I suppose that many wouldn’t object to a refactoring, because it is slightly less political than licensing or organization. The actual documentation is really good but nowadays it feels like something that grew organically to the point of being too scaterred (I’m pretty sure that this is what happened).

I would love to spend some time improving the documentation but I don’t really understand how to collaborate and how the development team is organized. I have a lot of time to devote to this task if needed. I would be greateful if someone is available to help me and explain how to contribute (DM or mail). Although it is difficult for many to make a relevant contribution to the improvement of the audio engine or the language, I am convinced that it is possible for a large number of users to share their knowledge and skills to restructure the documentation.

One way to start would be to encourage people to contribute by providing guided steps or some sort of “first contribution tutorial”.

This might temporarily bring unstability to the structure / content of the documentation, but I am sure that it will ultimately lead to something nice, clean and more actual. It’s not clear how a transition from the classic documentation to the new documentation would take place but this is something that can be done, maybe by providing the two versions until one is visibly preferred to the other.

Anyway, I enjoy working on docs, so please contact me if you are willing to talk about this. I already refactored the Tidalcycles docs recently, and it was really a nice project to undertake!

1 Like

Alternate view: Perhaps we don’t need to remove ways of doing things, but rather start documenting best practices.

  • Current situation: Here are 8 ways to do x. 5 are terrible; 2 are ok; 1 is really good. You guess which is which.

  • Better situation: This is the best way to do x. (And here’s one alternative.)

Then refactor the docs to steer users toward best practices docs.

We like writing class documentation (which is necessary). The idea of writing mid-level documentation hasn’t gained as much traction. Max/MSP has done a great job of shipping intermediate/advanced topic-focused tutorials. We haven’t (except for the Practical Guide to Patterns, but even this in hindsight is less topic-driven than it could be), and I think this contributes to that “lost at sea” feeling. We tell you that there’s a Starbucks on the corner, but we don’t tell you how it relates to other shops on other corners and how to get there.

I think this is really the first step. Some useful topics:

  • Basic synthesis technique cookbook. (We don’t need to replicate the Computer Music Tutorial, just provide templates for basic subtractive, FM, waveshaping, etc synths).
  • Effects (how to write standard studio fx; best practices for managing fx buses and node order).
  • Time and tempo, quant factors, sequencing.
  • Cool things to do with buffers.
  • Responding to external input (basic concepts of UI callbacks that apply to GUI widgets, MIDI, OSC, and HID). Especially the idea of the callback updating a model only, and active tasks refer to the model. Everybody gets stuck on this – because the class interfaces by themselves lead users toward a weaker design, but nowhere do we suggest better designs.
    • Specifics for GUI.
    • Specifics for MIDI.
    • … for OSC etc.



I’ve been thinking about a quark that would help us contribute to the documentation…

…allowing you to edit the help source ‘in-place’… & with a simple edit | preview split view along with a drop-down menu for ‘click-to-add’ instances of schelp markdown syntax.

… and git integration under the hood (perhaps a dedicated branch for doc-only updates…) and a Submit button over the hood, and I’m sure A LOT of us would be able to contribute.

Currently there’s 2502 documents across 37 sections… with around 14-16 sections having only 5 entries or less.

There’s 6 classes or document types… one of them (Other) applies to only one document… and at a glance Tutorial Reference Overview & Guide could all easily refer to the same kind of content.

If the core reference is well organized… then there’s far more room for all of those interesting things @jamshark70 is already brainstorming… things like that are sorely missed from the current reference.

Is it possible that we could build something that would speed up a common workflow?

1 Like

That got me thinking… POC of simplified responders


Cycling74 did something clever. They acknowledged the fact that help and reference are not the same thing and they introduced two different kind of help documents. They also introduced built-in tutorials, demo patches, and many many things that are only shipped with the software because it demonstrates what good practices are.

I’m not entirely convinced, but I still agree with your plan. A first clean-up phase is really important, and I agree with @Rainer, there are too many sections and the documentation has succumbed to entropy. The actual reference is the low-level documentation, so it should be sane before building something else on the top of it.

I think that this is simply too much work to add on the devs shoulders, at least for the beginning. There is no need to wait for a system if the job can be done manually. In the near future, I guess that a simplification in the contribution workflow would be welcome, but I’m not sure how it could work because I don’t really know how the dev team would think / implement something like this.

I could have made this more clear:

The editor can be built as a script written in pure supercollider, and then run inside the scide.

There’s only four features: edit, preview, add syntax, and submit.

A very rough and quick draft, for the sake of demonstration:

  • Edit : Use Document’s robust interface.
  • Preview: use classes ScDocEntry and HelpBrowser, have a full local copy of help source for work, (use PathName & File to clone a local working directory) …have the preview update every 1-2 seconds using a SkipJack, or use Document.globalKeyDownAction_ to constantly update changes made to the in-edit copy, perhaps…
  • Add syntax: At first, a cheat sheet using copy & paste is half-way there… or good enough for pre-alpha
  • Submit: The most basic operation would be just like any normal git pull request… But ideally, you could update and submit as many times as you wanted to, and all of the updates would then be merged or managed by git somehow… The devs would be able to view all of the doc changes at once and at their convenience, and perhaps requiring a separate ‘develop-reference’ branch, if it would be sensible to do so.

Documentation seems to be a thing when reading this topic indeed.

One small addition to this from my side: there are quite some nice tutorials or learning SC especially from @elifieldsteel. What might be missing in this realm are clear instructions on the language itself. How to program in SC. What are the base principles. How to write functions, lists, arrays etc and how to use it’s syntax.


I’ve been working for a while now on a drop-in replacement for sclang called Hadron. Hadron is a complete rewrite for sclang and is designed as a JIT compiler.

I originally started it over a year ago mainly as a way to teach myself more about compilers by working on a non-trivial project. I took a long break due to personal reasons, but have recently been working on it consistently. I’ve been having a lot of fun defining the basic architecture and building (and re-building) some of the fundamental components of the compiler.

I’m not ready to accept contributions to either the design or code, but as the project has started to take shape it’s made me wonder if it could be useful to the SC community. A friend called my attention to this thread (I normally lurk on Discord and Slack and only rarely browse this forum), and I thought it might be time to say hello.

My plan is to work on Hadron independently until enough of the design is established and the test infrastructure is in place that I could invite contributions from other folks. I would estimate this will take another 6 months of work at least. If you have questions about Hadron I would first invite you to read through some of the requirements and other documentation in the docs/ directory in the Hadron repository. That’s the best place to track the development of the project as well. I have limited time to respond to online communications here so apologies in advance if there’s a long delay in responses.

My goal of communicating about Hadron now is mostly to reduce the chances of duplicate effort. If you’ve been working in secret on a JIT compiler replacement for sclang please do get in touch, perhaps we can join forces!




Love the sound of it.

1 Like

Hi Luke, this sounds amazing!

I am particularly excited about the following:

The Hadron C API will hopefully enable a wide variety of interoperability and extensibility options, while also allowing the core library to remain small, delegating many functions (such as UI and MIDI frameworks) to extensions.

One reason I’ve personally stayed away from sclang is the missing interoperability with other languages/libraries, so this would be a real game changer!

Sweet, thanks for your interest! By making SC code run faster, and by allowing some kind of bridge to C code, I’m hoping that it will allow SuperCollider users to do more with the language without having to learn C++. I’ll keep hacking away, and report back here when I have something that can do things a bit more interesting than compute the Fibonacci sequence.

1 Like

Hi all,

Just to add to what has already been said re: documentation:

In another context I (I think the Tidal Cycles forum??) someone shared this resource for thinking about documentation

I find the four-part distinction between Tutorials, How-Tos, Explanations, and Reference to be a very useful way for thinking about what to include and exclude from any documentation system. Here’s the graphic used to explain these distinctions:


Currently there are:

  • 1124 (excluding Meta) classes in the core library

  • 524 undocumented classes (…half of the library ! )

  • 2502 doc / reference pages in total

…there must be some way to streamline the process.

YEah, apropos documentation. I would love to see SC4 be documented in markdown. Makes it easy to convert to any format and also easy to maintain and then have a static site generator system create links between documents, tags, etc. automatically (and “inherit” documentation in subclasses from superclasses).