# at.atmosynth.module

> Published by [atmosynth.at](https://lexicon.garden/identity/did:plc:fzjkahpwapmoqxybwdjb6ysf)

✓ This is the authoritative definition for this NSID.

## Description

A reusable synth module: Web Audio nodes wired together, with declared audio and MIDI boundaries, exposed parameters, automation and sample slots. Each published version is its own record; records sharing a moduleId form a series.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:fzjkahpwapmoqxybwdjb6ysf/at.atmosynth.module)
- [Documentation](https://lexicon.garden/lexicon/did:plc:fzjkahpwapmoqxybwdjb6ysf/at.atmosynth.module/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:fzjkahpwapmoqxybwdjb6ysf/at.atmosynth.module/examples)

## Definitions

### `at.atmosynth.module`

**Type**: `record`

A module, held in its author's own repository.

**Key**: `tid`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes |  |
| `nodes` | `array` | Yes |  |
| `moduleId` | `string` | Yes | Stable identity shared by every published version of this module. |
| `createdAt` | `string` (datetime) | Yes |  |
| `automation` | `array` | No | Scheduled AudioParam envelopes. Web Audio has no envelope node, so these are their own structure. |
| `forkedFrom` | `ref` → `#lineage` | No |  |
| `midiInputs` | `array` | Yes | Zero or more note inputs. A note input carries note events — what is played, and when — from any note source: a sequencer's note output, or the player, which is the on-screen keys, the computer keyboard and every MIDI device at once. "MIDI" is the historical name; nothing arriving here need have come from MIDI. |
| `noteSource` | `string` | No | What this module emits notes by, where it is not made of Web Audio nodes at all. A note source has no `nodes` and no `connections`: it produces note events, and the behaviour that produces them is named here rather than described, because there is no vocabulary of nodes for a thing that makes no sound. A reader that does not know the named behaviour cannot run the module, and says so rather than guessing. |
| `parameters` | `array` | No |  |
| `versionKey` | `string` | No | The record key this version is published under, repeated in the record so a reader holding only the record knows which version it is. A patch's `moduleRef.versionKey` is this value, and it is the record key a reader fetches: a record whose `versionKey` differs from its own key is pinned by the key and misdescribed by this field. |
| `audioInputs` | `array` | Yes | Zero or more individually identified audio inputs. |
| `connections` | `array` | Yes |  |
| `description` | `string` | Yes |  |
| `noteOutputs` | `array` | No | Zero or more note outputs. A note output carries note events — what is played, and when — rather than a signal, so it is wired to another instance's note input (`midiInputs`) rather than to an audio input. A module that declares one is a source of what is played; a module that declares none is what plays it. |
| `sampleSlots` | `array` | No |  |
| `audioOutputs` | `array` | Yes |  |
| `descriptionVersion` | `integer` | Yes | Version of the module description this record follows. A reader accepts any version at or below its own. |

### `at.atmosynth.module#node`

**Type**: `object`

One Web Audio node. `kind` is drawn from a closed vocabulary; `options` are its construction-time settings, which are not AudioParams and cannot be modulated.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `kind` | `string` | Yes |  |
| `options` | `unknown` | No | The node's settings, as its kind defines them. This is an object — which is the whole of what `unknown` means here — so the data model applies inside it: a whole number is an ordinary integer, and a number that is not a whole number is carried as its decimal string, "0.5" rather than 0.5, because the ATproto data model has no floating-point type and a PDS refuses one. That is the one difference from the fields this description types as strings, which have nowhere to put an integer. |

### `at.atmosynth.module#port`

**Type**: `object`

One individually identified audio or MIDI boundary of the module.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `label` | `string` | No |  |

### `at.atmosynth.module#range`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `max` | `string` | Yes | The high bound, as its decimal form — "20000", "0.5" — because the ATproto data model has no floating-point type and a PDS refuses one. A range is numeric by definition, so a reader turns it back into a number without asking anything else. |
| `min` | `string` | Yes | The low bound, as its decimal form — "0.0001", "-1" — because the ATproto data model has no floating-point type and a PDS refuses one. A range is numeric by definition, so a reader turns it back into a number without asking anything else. |

### `at.atmosynth.module#source`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `node` | `string` | Yes |  |
| `output` | `integer` | No |  |

### `at.atmosynth.module#target`

**Type**: `object`

Exactly one of `input` or `param` is present. `param` is modulation: a node output reaching a named AudioParam.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `node` | `string` | Yes |  |
| `input` | `integer` | No |  |
| `param` | `string` | No |  |

### `at.atmosynth.module#lineage`

**Type**: `object`

The module this one was forked from, and its author.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `uri` | `string` (at-uri) | Yes |  |
| `moduleId` | `string` | No |  |
| `authorDid` | `string` (did) | Yes |  |

### `at.atmosynth.module#parameter`

**Type**: `object`

A parameter the module exposes for a patch to set. Each target reaches an AudioParam, a construction option, or one field of an automation breakpoint.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `label` | `string` | Yes |  |
| `range` | `ref` → `#range` | No |  |
| `values` | `array` | No | A closed value set, where the parameter is not numeric. |
| `default` | `string` | No | The value used where a patch sets none, always as text. A number is its decimal form — "0.5", and "2" for a whole one — because the ATproto data model has no floating-point type and a string is the only type that carries both a number and a word. Where this parameter declares a closed value set, it is one of those strings instead, and a label that looks like a number stays the label it is. |
| `targets` | `array` | Yes |  |

### `at.atmosynth.module#sampleRef`

**Type**: `object`

A sample blob and the account that holds it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `blob` | `blob` | Yes |  |
| `ownerDid` | `string` (did) | Yes |  |

### `at.atmosynth.module#automation`

**Type**: `object`

A breakpoint envelope scheduled onto an AudioParam. Breakpoints up to and including sustainAt are scheduled on note-on; those after it on note-off.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `label` | `string` | No |  |
| `target` | `ref` → `#paramTarget` | Yes |  |
| `sustainAt` | `integer` | No | Index into breakpoints where the value holds while a note is held. Absent means a one-shot. |
| `breakpoints` | `array` | Yes |  |

### `at.atmosynth.module#breakpoint`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `time` | `integer` | Yes | Milliseconds from the trigger. |
| `curve` | `string` | No | How the value travels from the previous breakpoint. |
| `value` | `string` | Yes | The param's value at this instant, as its decimal form — "0.25", "1" — because the ATproto data model has no floating-point type and a PDS refuses one. An automation is numeric by definition, so a reader turns it back into a number without asking anything else. |

### `at.atmosynth.module#connection`

**Type**: `object`

An audio connection from a node output to either an audio input or a named AudioParam.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `to` | `ref` → `#target` | Yes |  |
| `from` | `ref` → `#source` | Yes |  |

### `at.atmosynth.module#sampleSlot`

**Type**: `object`

A named slot a patch instance may fill with its own sample. `node` names a node in this graph and `property` the thing the sample feeds.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` | Yes |  |
| `node` | `string` | Yes |  |
| `label` | `string` | No |  |
| `default` | `ref` → `#sampleRef` | No |  |
| `property` | `string` | Yes |  |

### `at.atmosynth.module#paramTarget`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `node` | `string` | Yes |  |
| `param` | `string` | Yes |  |

### `at.atmosynth.module#parameterTarget`

**Type**: `object`

One of: {node, param}, {node, option}, or {automation, breakpoint, field}.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `node` | `string` | No |  |
| `field` | `string` | No |  |
| `param` | `string` | No |  |
| `option` | `string` | No |  |
| `automation` | `string` | No |  |
| `breakpoint` | `integer` | No |  |

## Raw Schema

```json
{
  "id": "at.atmosynth.module",
  "defs": {
    "main": {
      "key": "tid",
      "type": "record",
      "record": {
        "type": "object",
        "required": [
          "descriptionVersion",
          "moduleId",
          "name",
          "description",
          "audioInputs",
          "audioOutputs",
          "midiInputs",
          "nodes",
          "connections",
          "createdAt"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1
          },
          "nodes": {
            "type": "array",
            "items": {
              "ref": "#node",
              "type": "ref"
            }
          },
          "moduleId": {
            "type": "string",
            "maxLength": 128,
            "description": "Stable identity shared by every published version of this module."
          },
          "createdAt": {
            "type": "string",
            "format": "datetime"
          },
          "automation": {
            "type": "array",
            "items": {
              "ref": "#automation",
              "type": "ref"
            },
            "description": "Scheduled AudioParam envelopes. Web Audio has no envelope node, so these are their own structure."
          },
          "forkedFrom": {
            "ref": "#lineage",
            "type": "ref"
          },
          "midiInputs": {
            "type": "array",
            "items": {
              "ref": "#port",
              "type": "ref"
            },
            "description": "Zero or more note inputs. A note input carries note events — what is played, and when — from any note source: a sequencer's note output, or the player, which is the on-screen keys, the computer keyboard and every MIDI device at once. \"MIDI\" is the historical name; nothing arriving here need have come from MIDI."
          },
          "noteSource": {
            "type": "string",
            "maxLength": 64,
            "description": "What this module emits notes by, where it is not made of Web Audio nodes at all. A note source has no `nodes` and no `connections`: it produces note events, and the behaviour that produces them is named here rather than described, because there is no vocabulary of nodes for a thing that makes no sound. A reader that does not know the named behaviour cannot run the module, and says so rather than guessing.",
            "knownValues": [
              "keyboard",
              "sequencer"
            ]
          },
          "parameters": {
            "type": "array",
            "items": {
              "ref": "#parameter",
              "type": "ref"
            }
          },
          "versionKey": {
            "type": "string",
            "maxLength": 128,
            "description": "The record key this version is published under, repeated in the record so a reader holding only the record knows which version it is. A patch's `moduleRef.versionKey` is this value, and it is the record key a reader fetches: a record whose `versionKey` differs from its own key is pinned by the key and misdescribed by this field."
          },
          "audioInputs": {
            "type": "array",
            "items": {
              "ref": "#port",
              "type": "ref"
            },
            "description": "Zero or more individually identified audio inputs."
          },
          "connections": {
            "type": "array",
            "items": {
              "ref": "#connection",
              "type": "ref"
            }
          },
          "description": {
            "type": "string",
            "maxLength": 3000
          },
          "noteOutputs": {
            "type": "array",
            "items": {
              "ref": "#port",
              "type": "ref"
            },
            "description": "Zero or more note outputs. A note output carries note events — what is played, and when — rather than a signal, so it is wired to another instance's note input (`midiInputs`) rather than to an audio input. A module that declares one is a source of what is played; a module that declares none is what plays it."
          },
          "sampleSlots": {
            "type": "array",
            "items": {
              "ref": "#sampleSlot",
              "type": "ref"
            }
          },
          "audioOutputs": {
            "type": "array",
            "items": {
              "ref": "#port",
              "type": "ref"
            }
          },
          "descriptionVersion": {
            "type": "integer",
            "minimum": 1,
            "description": "Version of the module description this record follows. A reader accepts any version at or below its own."
          }
        }
      },
      "description": "A module, held in its author's own repository."
    },
    "node": {
      "type": "object",
      "required": [
        "id",
        "kind"
      ],
      "properties": {
        "id": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "kind": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "options": {
          "type": "unknown",
          "description": "The node's settings, as its kind defines them. This is an object — which is the whole of what `unknown` means here — so the data model applies inside it: a whole number is an ordinary integer, and a number that is not a whole number is carried as its decimal string, \"0.5\" rather than 0.5, because the ATproto data model has no floating-point type and a PDS refuses one. That is the one difference from the fields this description types as strings, which have nowhere to put an integer."
        }
      },
      "description": "One Web Audio node. `kind` is drawn from a closed vocabulary; `options` are its construction-time settings, which are not AudioParams and cannot be modulated."
    },
    "port": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "label": {
          "type": "string",
          "maxLength": 200
        }
      },
      "description": "One individually identified audio or MIDI boundary of the module."
    },
    "range": {
      "type": "object",
      "required": [
        "min",
        "max"
      ],
      "properties": {
        "max": {
          "type": "string",
          "maxLength": 200,
          "description": "The high bound, as its decimal form — \"20000\", \"0.5\" — because the ATproto data model has no floating-point type and a PDS refuses one. A range is numeric by definition, so a reader turns it back into a number without asking anything else."
        },
        "min": {
          "type": "string",
          "maxLength": 200,
          "description": "The low bound, as its decimal form — \"0.0001\", \"-1\" — because the ATproto data model has no floating-point type and a PDS refuses one. A range is numeric by definition, so a reader turns it back into a number without asking anything else."
        }
      }
    },
    "source": {
      "type": "object",
      "required": [
        "node"
      ],
      "properties": {
        "node": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "output": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "target": {
      "type": "object",
      "required": [
        "node"
      ],
      "properties": {
        "node": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "input": {
          "type": "integer",
          "minimum": 0
        },
        "param": {
          "type": "string",
          "maxLength": 64
        }
      },
      "description": "Exactly one of `input` or `param` is present. `param` is modulation: a node output reaching a named AudioParam."
    },
    "lineage": {
      "type": "object",
      "required": [
        "uri",
        "authorDid"
      ],
      "properties": {
        "uri": {
          "type": "string",
          "format": "at-uri"
        },
        "moduleId": {
          "type": "string",
          "maxLength": 128
        },
        "authorDid": {
          "type": "string",
          "format": "did"
        }
      },
      "description": "The module this one was forked from, and its author."
    },
    "parameter": {
      "type": "object",
      "required": [
        "id",
        "label",
        "targets"
      ],
      "properties": {
        "id": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "label": {
          "type": "string",
          "maxLength": 200,
          "minLength": 1
        },
        "range": {
          "ref": "#range",
          "type": "ref"
        },
        "values": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 200
          },
          "description": "A closed value set, where the parameter is not numeric."
        },
        "default": {
          "type": "string",
          "maxLength": 200,
          "description": "The value used where a patch sets none, always as text. A number is its decimal form — \"0.5\", and \"2\" for a whole one — because the ATproto data model has no floating-point type and a string is the only type that carries both a number and a word. Where this parameter declares a closed value set, it is one of those strings instead, and a label that looks like a number stays the label it is."
        },
        "targets": {
          "type": "array",
          "items": {
            "ref": "#parameterTarget",
            "type": "ref"
          },
          "minLength": 1
        }
      },
      "description": "A parameter the module exposes for a patch to set. Each target reaches an AudioParam, a construction option, or one field of an automation breakpoint."
    },
    "sampleRef": {
      "type": "object",
      "required": [
        "blob",
        "ownerDid"
      ],
      "properties": {
        "blob": {
          "type": "blob",
          "accept": [
            "audio/wav"
          ],
          "maxSize": 2097152
        },
        "ownerDid": {
          "type": "string",
          "format": "did"
        }
      },
      "description": "A sample blob and the account that holds it."
    },
    "automation": {
      "type": "object",
      "required": [
        "id",
        "target",
        "breakpoints"
      ],
      "properties": {
        "id": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "label": {
          "type": "string",
          "maxLength": 200
        },
        "target": {
          "ref": "#paramTarget",
          "type": "ref"
        },
        "sustainAt": {
          "type": "integer",
          "minimum": 0,
          "description": "Index into breakpoints where the value holds while a note is held. Absent means a one-shot."
        },
        "breakpoints": {
          "type": "array",
          "items": {
            "ref": "#breakpoint",
            "type": "ref"
          },
          "minLength": 1
        }
      },
      "description": "A breakpoint envelope scheduled onto an AudioParam. Breakpoints up to and including sustainAt are scheduled on note-on; those after it on note-off."
    },
    "breakpoint": {
      "type": "object",
      "required": [
        "time",
        "value"
      ],
      "properties": {
        "time": {
          "type": "integer",
          "minimum": 0,
          "description": "Milliseconds from the trigger."
        },
        "curve": {
          "type": "string",
          "description": "How the value travels from the previous breakpoint.",
          "knownValues": [
            "step",
            "linear",
            "exponential"
          ]
        },
        "value": {
          "type": "string",
          "maxLength": 200,
          "description": "The param's value at this instant, as its decimal form — \"0.25\", \"1\" — because the ATproto data model has no floating-point type and a PDS refuses one. An automation is numeric by definition, so a reader turns it back into a number without asking anything else."
        }
      }
    },
    "connection": {
      "type": "object",
      "required": [
        "from",
        "to"
      ],
      "properties": {
        "to": {
          "ref": "#target",
          "type": "ref"
        },
        "from": {
          "ref": "#source",
          "type": "ref"
        }
      },
      "description": "An audio connection from a node output to either an audio input or a named AudioParam."
    },
    "sampleSlot": {
      "type": "object",
      "required": [
        "id",
        "node",
        "property"
      ],
      "properties": {
        "id": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "node": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "label": {
          "type": "string",
          "maxLength": 200
        },
        "default": {
          "ref": "#sampleRef",
          "type": "ref"
        },
        "property": {
          "type": "string",
          "knownValues": [
            "buffer"
          ]
        }
      },
      "description": "A named slot a patch instance may fill with its own sample. `node` names a node in this graph and `property` the thing the sample feeds."
    },
    "paramTarget": {
      "type": "object",
      "required": [
        "node",
        "param"
      ],
      "properties": {
        "node": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "param": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        }
      }
    },
    "parameterTarget": {
      "type": "object",
      "properties": {
        "node": {
          "type": "string",
          "maxLength": 64
        },
        "field": {
          "type": "string",
          "knownValues": [
            "time",
            "value"
          ]
        },
        "param": {
          "type": "string",
          "maxLength": 64
        },
        "option": {
          "type": "string",
          "maxLength": 64
        },
        "automation": {
          "type": "string",
          "maxLength": 64
        },
        "breakpoint": {
          "type": "integer",
          "minimum": 0
        }
      },
      "description": "One of: {node, param}, {node, option}, or {automation, breakpoint, field}."
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "description": "A reusable synth module: Web Audio nodes wired together, with declared audio and MIDI boundaries, exposed parameters, automation and sample slots. Each published version is its own record; records sharing a moduleId form a series."
}
```