nymph/README.md

# nymph

A [Nim] library for writing audio and MIDI plugins conforming to the [LV2] standard


## Examples

Build the `amp.lv2` example plugin:

    nimble build_ex amp

Check the `amp.lv2` plugin bundle with `lv2lint`:

    nimble lv2lint amp

Run the `lv2bm` benchmark with the `amp.lv2` plugin:

    nimble lv2bm amp

Install the `amp.lv2` example plugin:

    cp -a examples/amp.lv2 ~/.lv2


## How To

* Install this library:

    nimble install https://git.0x20.eu/chris/nymph

* Copy `examples/amp.lv2` and `examples/amp.nim` into your project and rename
  them as you like (also renane`amp.lv2/amp.ttl`). I'll use `myplugin` as the
  base bname in the examples below.

* Edit `myplugin.lv2/manifest.ttl` and change the plugin URI and change the
  plugin's shared library name defined with `lv2:binary` to `libmyplugin.so`.

* Edit `myplugin.lv2/myplugin.ttl`:
    * Change the plugin URI.
    * Define audio, control and atom ports as needed.

* Edit `myplugin.nim`:
    * Change the `PluginUri` constant at the top.
    * Change the `PluginPort` enum and list the ports in the order defined in
      `myplugin.ttl`.
    * Change the definition of the `AmpPlugin` object type and define its
      members with the appropriate data type for the plugin port they will be
      connected to. Update the type name in `instantiate`, `deactivate`,
      `connectPorts` and `run` procs.
    * Update and extend the `case` statement in `connectPort` to connect ports
      to your plugin object instance members.
    * Implement your DSP code in the `run` proc.

* Compile the plugin shared library object with:

        nim c --app:lib --noMain:on --mm:arc \
            --out:myplugin.lv2/libmyplugin.so myplugin.nim

    See the definition of the `build_ex` task in the
    [nymph.nimble](./nymph.nimble#L43) file on how to create a nimble task
    to siplify compilation.


## Dependencies

Required:

* [Nim] >= 2.0

Optional:

* [lv2bm] - For benchmarking and stress-testing plugins
* [lv2lint] - For checking conformity of plugin bundles


[LV2]: https://lv2plug.in/
[lv2bm]: https://github.com/moddevices/lv2bm
[lv2lint]: https://git.open-music-kontrollers.ch/~hp/lv2lint
[Nim]: https://nim-lang.org/