About

Control maps and manuals for the Synthux Simple Touch. The library shows what every knob, fader, switch and pad does in a firmware; the designer is where those labels are made.

The whole route

From a first line of code to a firmware anyone can read, play and host. Each step names the tool that does it and what it leaves behind. Doing it? The step-by-step guide has every step with its checks, in the best order, starting from a repository you have or from scratch.

  1. Set upVS CodeGitDaisy Toolchain

    An editor, Git, and an account on GitHub or Codeberg. The Daisy Toolchain builds and flashes libDaisy firmware; a Plugdata patch goes through Plugdata's Daisy export instead.

  2. Build or fork a firmwareVS CodeGitHub

    Start from scratch, from an official firmware or from a community one. Push it to a repository of your own.

    Leaves your firmware repository

  3. Get listed and labelled, in either order
    List it first

    Designer Directory entry… opens a pull request on the community directory. Once it is merged, the Library lists your firmware under Community and a script reads labels from your README.

    Then check what it read: Build the labels in the Designer opens them there to fix and finish.

    Manual first

    In the Designer: labels, modifiers, modes, MIDI, notes and your own look. Repository kit… writes a README with the control map, the label file and the directory entry in one .zip.

    Then Directory entry… to get listed.

    Leaves simple-touch-labels.json (and a README) in your repository, and an entry in the directory

  4. See it in the libraryLibrary

    Your labels on the drawing, in your look (the Creator theme) with your faceplate, the control table, your notes, and your whole README underneath. Preview in library in the designer shows this before you publish.

  5. Make it playablesimple-touch-webDesigner

    Split main() into a setup and a loop half and add one workflow file. Every push then builds the firmware for the browser, checks it boots and publishes it in your repository. Listen to it on the test bench; if it sounds right, paste its emulator block into Browser build and save the label file again. How

    Leaves a Play button in the library: the drawing becomes the instrument

  6. A page of your ownDesignerGitHub Pages

    Web app… gives your manual as a site of its own: the library's page for just your firmware, in your look, with Play, the control table, your notes and README. Copy the folder into docs/, switch on GitHub Pages for that folder, done; the dialog and the .zip's HOW-TO-PAGES.md walk you through it. More

    Leaves <you>.github.io/<firmware>

Three places

Community directorySynthux's list of community firmware: one small projects/<id>.json per project, with its name, author and repository.
Firmware repositoryThe creator's own GitHub or Codeberg repository: code, firmware, README, and optionally simple-touch-labels.json.
This siteReads the directory's list, then each repository, in your browser.

The directory is synthux-academy.github.io/community-instruments (source: Synthux-Academy/community-instruments). This site only reads it. The designer can write back to both: a label file for the repository, and an entry for the directory.

How the library finds labels

The official firmware (TouchBass, Touch FX, Touch String, Audrey II Touch) have labels checked by hand. For the community firmware under Community, the library tries, in this order:

  1. The creator's label file. A simple-touch-labels.json at the root of the repository's default branch, made in the designer. Shown as is, first in the creator's own look (the Creator theme), and with their faceplate if the file names one.
  2. Auto-extracted from the README. A script reads README.md, and a Markdown manual it links to, for control names (S30, P03, Switch A…) and the words next to them. These labels are a guess: they can be incomplete or shortened. The library marks them as auto-extracted and lists the line each one came from. When the README has a section per mode, the drawing shows one mode at a time, with a button for each.
  3. Nothing found. The drawing shows the Synthux names, with a link to the designer.

Controls without a label show their Synthux name, so you can still find your way around.

The README underneath

Below every firmware's manual, official or community, the library keeps the repository's own README.md, folded away. Open it and it is read from the default branch and drawn as GitHub draws it: headings, tables, code blocks, notes like > [!NOTE], ```mermaid flowcharts, and images and videos from where the README points. A video link on a line of its own plays in the page, and a YouTube link is embedded.

For firmware creators

The short version is below; the step-by-step guide walks through it all with checks, from your repository to the community directory.

Make your labels

  1. Open your firmware under Community in the library and follow Build the labels in the Designer. The designer opens with your name, author and repository filled in, plus anything the script found.
  2. Check and finish the labels: line 1 and line 2 per control, modifiers (P10 + knob, or a tapped mode pad), notes. If the firmware speaks MIDI, fill in the MIDI column too (e.g. CC 20 or note 36 ch 10): it becomes a column of the control table, and while someone plays the firmware here, each row shows the values that pass.
  3. Style it if you like: colours, sizes, a Google font and your own faceplate. The library shows your manual in this look first, as the Creator theme. Preview in library shows it there before you publish.
  4. Click Save file and rename the file to simple-touch-labels.json. With a faceplate of your own, Save file also downloads it, as the SVG or the image you uploaded; the label file names where it goes, img/faceplate.svg (or .png, .jpg…) unless you change it under Style.
  5. Add the label file to the root of your repository, on the default branch, and the faceplate at its path. The library shows your labels from then on.

Or everything at once

Repository kit… in the designer downloads one .zip with a README (intro, control map image, control table, your notes, install and build), simple-touch-labels.json, the directory entry and a short HOW-TO. Pick how the firmware is built (libDaisy or Plugdata) and flashed (internal flash or the Daisy bootloader) and the README suggests the matching steps. Only you know the details, so check those parts and fill in what is marked TODO. HOW-TO.txt in the .zip says where each file goes: copy it into your repository keeping its folders (docs/ is a new folder, even if you have a doc/), and commit to the default branch, usually main. The library reads only that branch, so files on another branch show once it is merged. Already have a README? Keep it at the root and copy in the parts you want; the control map's path counts from the root.

Let people play it

A libDaisy firmware can also run in the browser, built with simple-touch-web: the same code, compiled for a virtual Simple Touch with its knobs, faders, levers, pads, LED and optional OLED. The library then shows a Play button, and the drawing becomes the instrument. You decide whether that happens, and with which build:

  1. Split main() into a setup and a loop half and add the small workflow file from the simple-touch-web README. Every push then builds the firmware for the browser, checks that it boots, and publishes it on a simple-touch-web branch of your repository.
  2. Listen to the build on the test bench the run links to. Only you can say whether it sounds like your firmware.
  3. If it does, approve it in the designer: under Firmware, Find builds in the repository lists the builds, newest first; Use this build fills in Browser build. (Or copy the emulator block by hand: your repository's Actions tab › Browser build › the newest run › its summary.) Then save the file and add it to your repository as above. "embed": "allowed" lets the library play that build; "link-only" with a "url" only links to your own page. Add "oled": true if the firmware drives the optional OLED.

The block pins the build by its hash: the library refuses any other file, so a later build only plays here once you approve it. The build has to come from your own repository (its raw files or your Pages site). The library feeds it loops from simple-touch-web or the visitor's mic or own sound file.

Visitors then drag the knobs and faders on the drawing, flip the levers and press the pads (higher up on a pad is harder; a right-click keeps one held, for combos), or play the pads from the computer keyboard. Web MIDI connects a keyboard to the firmware's USB MIDI and its output to a device; with a MIDI column in your labels, each row of the control table shows the values passing. On a phone, Full screen turns the drawing into the whole instrument.

Your own web app

Web app… in the designer packs your manual as a site for GitHub Pages: one page with the drawing in your look, the control table, your notes, your README and, with an approved browser build, Play. It runs on the same code as the library, copied into the .zip, so it keeps working whatever happens to this site. Preview ↗ in the dialog shows it first, following your edits.

  1. Put simple-touch-labels.json (and your faceplate) at the root of your repository, as above.
  2. Copy everything in the .zip's folder into a docs folder in your repository, and push.
  3. On GitHub: Settings › Pages, Source Deploy from a branch, your default branch, folder /docs, Save. A minute later it is at https://<you>.github.io/<repository>/.

Online, the page reads the label file from the root of your repository, so a build you approve later shows there without a new export. On your own computer (python -m http.server in the folder) it shows the copy beside it, so you can try changes before you push. Already using Pages for something else? Any subfolder works, e.g. docs/play/.

Not in the directory yet?

In the designer, fill in Repository and Author link under Firmware, then click Directory entry…. It builds your projects/<id>.json, checks it the way the directory does, and opens a pull request on GitHub with the file filled in. Listing is not endorsement: Synthux does not review or test listed projects.

A README the script can read

If you'd rather keep everything in your README, write the controls as a table or a list, one control per line, using the Synthux names:

## Controls

| Control | Function |
|---|---|
| S30 | **Cutoff** |
| S36 | **Level** |
| P03 | **Kick** |

- **P10 + S30** · Resonance
- **Switch A** · Mode: notes / drone / off

What is read and stored