Patchbook – A Markup Language for Modular Synth Patches

Spektro Audio’s Icaro Ferre has introduced an open-source markup language, Patchbook. 

Patchbook is designed to be a human-readable and system-parseable standard for documenting modular synth patches.

“My goal for Patchbook is to create a standard that can help users write down patches in a way that could also be potentially used by different websites, educational tools, applications and services,” explains Ferre. “I hope Patchbook can be used to help the modular synth community grow and become even more knowledgeable.”

Here’s an example of a patch written using the Patchbook markup language:

– Metropolis (Pitch) p> Braids (1v/oct)
– Metropolis (Gate) g> Function (Trigger)
– Braids (Out) -> Optomix (Ch1 Signal)
– Function (+ Out) >> Optomix (Ch1 CV)
– Function (- Out) >> Braids (Timbre CV)

* Metropolis:
| BPM = 124
| Swing = 0
| Root = F
| Scale = Minor
| Mode = F. Forward
| Stages = 16

* Braids:
| Mode = Fold
| Timbre = 30%
| Timbre CV = -20%
| Color = 0%

* Function: Rise = 50% | Fall = 50% | Curve = 30%
* Optomix: Damp = 0% | Control = 100%

An official parser (a simple python program) and documentation are available via Github.

Check it out and let us know what you think of Patchbook in the comments!

21 thoughts on “Patchbook – A Markup Language for Modular Synth Patches

  1. A format based on XML or JSON would perhaps be a better choice since it exists a lot of open source tools that can parse these standards.

    1. The goal is to be human readable and easily writable, as well as computer parseable. This is plain text markup in the style of Markdown. All you need is a decent text editor to document your setup, no need for additional tools for writing well formed XML or JSON.

    2. Nope 🙂
      Only the parser is open source, the “standard” is what it is … a format / a convention to abide by … Pascal is right that XML or JSON would have been better, no need to invent a new markup language for storing patches.
      The claim that patchbook is a “markup language” is also completely false, it is just a specialized text file format which is perfectly ok, but using an existing markup and proposing a standard based on a schema for that language would have allowed more adhesion.
      Ok, sorry I’m just geeking …

    3. Per the github readme, the python parser will generate a JSON file.

      Why in the world would anyone prefer to write these sorts of setups out as JSON instead of this? It’s like wanting to write a regular blog post in SGML instead of Markdown. Let the machine turn it into a machine language while you have a cocktail.

      1. The reason to use JSON for saving and exchanging files is because JSON has very small file sizes and is easily readable from almost all modern programming languages. The point is not that you as a human would be typing raw JSON into a text file, but rather that the program would translate your human-readable input into machine-readable JSON for ease and reliability in programming tools and exchanging files.

        1. I get the value of JSON. So does the spec author: “Per the github readme, the python parser will generate a JSON file. “

    4. If you read the GitHub page you will see that the PatchBook parser does output JSON. I think he’s done a great job with the markup language and the Graphiz integration looks fantastic.

  2. I’m not sure why this is described as a markup language when in fact it seems more like a different way to describe a patch. Could this be used to create a graphical version of the text so I could see how to recreate a certain patch? Maybe there’s a way of writing up a patch in HTML that refers to a CSS file that contains all the functions of each module that would generate a graphical diagram when viewed in a browser?

    1. It’s described as a markup language because the markup can be parsed by something like that python script (which could then generate the HTML/CSS you’re asking about).

  3. Considering the madness that can be modular patching, that markup language is almost magically terse.

    Hopefully he turns it into a web app. Most people aren’t going to run python scripts on the command line.

  4. Heh. Two seconds later I find the web app. @synthhead, think this would be useful to add to the body of the post:

    From the github readme: “Non-programmers have the option to use the Patchbook to GraphViz Online Converter to create flowcharts without having to install Python and use the parser.”

  5. If you want to make a new markup language it needs to be compatible with preexisting parsers, whether that is xml, yaml, or json. Do not create some new syntax without a compelling justification. Thanks.

    PS that means “thumbs down” in case it wasn’t clear.

    1. What the actual complaining fuck? “If you want to make a new markup language it needs to be compatible with preexisting parsers”?? Tell that to Tim Berners Lee.

      The “compelling justification” for the syntax is that it’s easy to read and write by non-nerds (and nerds) and it can be used to semantically express complex interconnections between devices. Without worrying about missing colons or quotes or brace nesting problems or…

      Also, it’s some guys personal project that he’s shared for free. He doesn’t need to justify anything.

  6. For those of you who like the idea to write patches in JSON, we started an open source project called COSMO-Patcher. It is based on Csound as a sound engine (open-source as well) and allows to map controllers (MIDI and Raspberry Pi MCP3008) to sound processing modules. At the same time this creates the patch and is very simple to write. (

Leave a Reply