Nallely MIDI Experimental Virtual Devices: How to Enable and Use Them

Enable nallely's experimental virtual devices by passing the --experimental flag to the CLI or setting include_experimental=True in the Python API, which imports all VirtualDevice subclasses from the nallely.experimental package.

The nallely-midi framework ships with a collection of experimental virtual devices that extend its modular synthesis capabilities beyond the default built-in MIDI devices. These advanced components—including chaotic generators, fractal renderers, and specialized routers—live in the nallely.experimental package and require explicit activation to load. Understanding how to enable these experimental virtual devices unlocks generative music workflows using mathematical attractors and non-standard signal processors.

What Are Experimental Virtual Devices?

Experimental virtual devices in nallely are specialized subclasses of VirtualDevice that reside in the nallely.experimental package. Unlike the core built-in devices (such as Korg Minilogue or NTS-1 implementations), these components are not loaded by default to maintain stability and predictable resource usage.

When activated via the --experimental flag or include_experimental=True parameter, the framework performs a dynamic import of all classes in the experimental package. This occurs in nallely/trevor/trevor_bus.py at lines 828-831, where the boolean flag triggers an import * operation that registers every discovered VirtualDevice subclass with the device registry.

Available Experimental Virtual Devices

The nallely/experimental directory contains four primary categories of devices, each serving distinct synthesis and routing functions.

Routers

The routing layer provides specialized memory and distribution devices:

• BroadcastRAM8 (nallely/experimental/routers.py): An 8-slot RAM buffer that broadcasts written values immediately to all connected outputs, useful for synchronized parameter distribution across multiple downstream devices.

Random Patchers

These devices enable generative patching and randomization workflows:

• InstanceCreator (nallely/experimental/random_patchers.py): Dynamically instantiates a random number of other virtual devices at runtime, creating emergent patch configurations.
• RandomPatcher (nallely/experimental/random_patchers.py): Automatically establishes random parameter connections between existing devices in the current session, generating unpredictable modulation routings.

Maths: Chaotic and Fractal Generators

The mathematics module (nallely/experimental/maths.py) contains the largest collection of experimental devices, implementing strange attractors and fractal algorithms as signal generators:

Chaotic Attractors:

• HenonProjector: Implements the Hénon map, a two-dimensional discrete-time dynamical system producing chaotic sequences.
• LorenzProjector: Simulates the Lorenz attractor with normalized X/Y/Z axes output, translating meteorological chaos theory into modulation sources.
• RosslerProjector: Generates signals from the Rössler attractor, known for its simpler chaotic behavior compared to the Lorenz system.
• LorenzAttractor: An alternative implementation of the Lorenz system with different parameter defaults for varied chaotic characteristics.

Fractal Renderers:

• BarnsleyProjector: Iterates the Barnsley fern fractal algorithm, outputting coordinate values suitable for panning or timbre modulation.
• BuddhabrotProjector: Performs high-resolution trajectory tracing for Buddhabrot rendering, outputting density values from Mandelbrot set orbits.
• MandelbrotProjector: Classic Mandelbrot set generator that outputs iteration counts as control signals.

Signal Processing and Utilities:

• Morton: Interleaves X and Y bits to produce Morton codes (Z-order curves), useful for spatial hashing and non-linear sequencing.
• UniversalSlopeGenerator: Produces configurable slope waveforms with adjustable rise and fall characteristics.
• SmoothSteppedGenerator: Generates smooth stepped envelopes that interpolate between discrete values.
• Integrator: A simple numerical integrator for cumulative signal processing.
• Inverter: Implements signal inversion using the formula 1 - x, flipping modulation polarity.
• Laplace: Applies a Laplace filter for edge detection and high-frequency emphasis in control signals.
• KineticShaper: A non-linear waveshaper optimized for kinetic-type curves and physical modeling applications.
• Transistor: A simple transistor-style gain stage that introduces non-linear saturation characteristics.

Delays

The delay category provides time-based effects:

• Delay (nallely/experimental/delays.py): A classic digital delay line with configurable feedback and time parameters.
• ConveyorLine (nallely/experimental/delays.py): A multi-tap conveyor-belt style delay that shifts samples through a moving buffer, creating rhythmic delay patterns.

How to Enable Experimental Virtual Devices

You can activate experimental devices through the command line interface or programmatically via the Python API.

CLI Activation

The command line parser defines the --experimental flag in nallely/cli.py (lines 45-48). When passed to nallely run, the flag forwards include_experimental=True to the runtime initialization (lines 96-103).

Run a Trevor session with the web UI and experimental devices enabled:

nallely run --with-trevor --serve-ui --experimental

Launch a standalone script that utilizes experimental devices:

nallely run --init my_patch.nly --experimental

API Activation

When embedding nallely in Python applications, pass the boolean parameter directly to the startup function:

from nallely.trevor import start_trevor

start_trevor(
    builtin_devices=False,
    include_experimental=True,  # Activates experimental virtual devices

    loaded_paths=[],            # Optional additional library paths

)

Without this flag, nallely only loads the stable built-in MIDI devices and core virtual devices defined in nallely/core.

Manual Import for Testing and Development

For unit testing or granular control, import experimental devices directly without enabling the full experimental suite:

from nallely.experimental.maths import HenonProjector

device = HenonProjector(freq=2.0)
device.start()

This approach bypasses the automatic registration system while allowing access to specific chaotic generators or fractal projectors defined in the experimental modules.

Summary

• Experimental virtual devices reside in nallely/experimental and extend VirtualDevice, including chaotic generators like LorenzProjector and routers like BroadcastRAM8.
• Activation requires the --experimental CLI flag or include_experimental=True API argument, which triggers dynamic importing in nallely/trevor/trevor_bus.py.
• Categories include routers, random patchers, mathematical attractors/fractals, and specialized delay lines.
• Direct import works for individual testing: from nallely.experimental.maths import HenonProjector.
• Default behavior excludes these devices to ensure system stability; they must be explicitly enabled per session.

Frequently Asked Questions

What is the difference between built-in devices and experimental virtual devices in nallely?

Built-in devices include stable MIDI implementations for hardware like the Korg Minilogue and NTS-1, plus core virtual devices in nallely/core. Experimental virtual devices are advanced modules—such as strange attractor generators and random patchers—that reside in nallely/experimental and require explicit activation via the --experimental flag because they may consume additional resources or implement unstable mathematical algorithms.

How does the --experimental flag technically enable devices?

When detected in nallely/cli.py, the flag passes include_experimental=True to start_trevor or launch_standalone_script. Inside nallely/trevor/trevor_bus.py (lines 828-831), this boolean triggers from nallely.experimental import *, which executes the package's __init__.py and registers all VirtualDevice subclasses found in modules like maths.py, routers.py, and delays.py.

Can I use experimental devices without the Trevor bus or CLI?

Yes. Individual experimental devices can be imported directly from their source modules for testing or custom implementations. For example, from nallely.experimental.delays import Delay allows instantiation outside the standard device discovery system, though you must manually manage the device's lifecycle with .start() and parameter connections.

Are experimental virtual devices stable for production use?

Experimental devices are marked as such because they implement cutting-edge algorithms—such as high-resolution Buddhabrot rendering or chaotic Lorenz attractors—that may have higher CPU requirements or less predictable output ranges than core devices. While functional, they lack the stability guarantees of built-in MIDI devices and should be tested thoroughly in your specific signal chain before deployment in critical performance environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}