# Table of Contents

1.  [Modmark](#org0b1d179)
    1.  [Current Status and Goals](#orgd73848c)
    2.  [Purpose](#orgb91e197)
    3.  [Syntax](#org899a6d3)
        1.  [A Module File](#org1c23079)
        2.  [A Patch](#orgd896ed4)


<a id="org0b1d179"></a>

# Modmark

This repo encapsulates an attempt to develop a markup language for describing modular synth patches.

In future, this scope may be expanded to make available a language for describing arbitrary audio and
data routing across a wide array of devices.


<a id="orgd73848c"></a>

## Current Status and Goals

This software is currently a prototype. Right now the "compiler" is a Perl script that translates a
`.modmark` file into a flowchart via Graphviz.

A rough road map looks something like:

-   [X] Prototype compiler in Perl
-   [ ] Test and stabilize syntax/grammar
-   [ ] Implement modmark as a source-to-source compiler in Racket ( "Real" implementation )
-   [ ] Develop libraries for as many modules as possible


<a id="orgb91e197"></a>

## Purpose

In the past I've found it difficult to discuss discrete details of modular patches on the internet. This
arises, I believe, from the large amount of effort and time it takes to describe the intricacies of a modular
patch in long form plain English. This prototype language is an attempt to address that problem.

By specifying a concise syntax that favors brevity over absolute human-readability, the hope is to get more
modular synth users to document their patches and enable more knowledge sharing across the community.

I know of one other attempt to solve this problem: <https://github.com/SpektroAudio/Patchbook>

My problem with Patchbook is that it still requires a lot of "boilerplate", in that you have to specify
modules yourself. Modmark aims to offload this task by having the community describe modules in a Library format
(`.module` files) that can then be imported. In this way, we can specify a module *once* and then not have
to do that work again the next time we'd like to use it in a patch.


<a id="org899a6d3"></a>

## Syntax


<a id="org1c23079"></a>

### A Module File

    # A module spec
    Manufacturer: MakeNoise
    Module: Maths
    Revision: null
    - Input: Slew1
    - Input: Slew2
    - Input: Trig1
    - Input: Trig2
    - Input: Attenuveter1
    -- Position: [1-12]
    - Input: Attenuveter2
    -- Position: [1-12]
    - Input: Attenuveter3
    -- Position: [1-12]
    - Input: Attenuveter4
    -- Position: [1-12]
    - Input: Rise1
    -- Position: [1-12]
    - Input: Rise2
    -- Position: [1-12]
    - Input: Both1
    - Input: Both2
    - Input: Fall1
    -- Position: [1-12]
    - Input: Fall2
    -- Position: [1-12]
    - Input: Cycle1
    - Input: Cycle2
    - Knob: LogExp
    -- Position: [1-12]
    - Button: Cycle1
    - Button: Cycle2
    - Output: 1f
    - Output: 1
    - Output: 2
    - Output: 3
    - Output: 4
    - Output: 4f
    - Output: Or
    - Output: Sum
    - Output: Inv
    -- Position: [1-3]


<a id="orgd896ed4"></a>

### A Patch

See the below example of a "Hello World" type patch:

    # A comment
    
    # The title of the patch
    Title: Foo
    
    # The directory to look for module files
    ModuleDir "/home/swatson/Repos/modmark/"
    
    # Modules to use in this patch
    import Module::Foobar::FooMod
    import Module::MakeNoise::Maths
    
    # Sets. These are used to indicate setting
    # particular module attriubtes in accordance with
    # the module definition
    set Maths.Cycle1 = on
    set Maths.Rise1.position = 7
    set Maths.Fall1.position = 1
    set Maths.LogExp.position = 5
    
    # Connects. These are used to indicate data flow.
    # Connects are always defined left to right. The
    # below line connects the Function1 output of Maths
    # to a FooInput on FooModule, as imported above
    connect Maths.1f FooMod.FooInput