223230/cyma

Composable views for nih-plug UIs made using VIZIA

Cyma

Documentation | Book | Examples | Contributing

Composable views and associated data structures for nih-plug UIs made using VIZIA.

---

✨ Overview

Cyma is a collection of flexible, composable views that you can use to make rich plug-in user interfaces with ease. It uses various custom data structures for real-time visualizers, allowing you to easily build beautiful, performant plug-in UIs.

Here's a demo:

cyma.0420.mp4

_{Excuse the poor frame rate, my PC is slow at media encoding :(}

Wanna see the code behind this? It's this example!

🧰 What's included

Check out this project to see what views will eventually be added. Do you think something's missing? File a feature request so it can be added!

📊 Visualizers

General/Utility

• Grid backdrop
• Unit ruler

Peak/Waveform Analysis

• Meter
• Graph
• Oscilloscope
• Static waveform

Stereo imaging

• Lissajous

Spectral analysis

• Spectrum Analyzer

❓ Example

Here's how to create a basic oscilloscope with a grid background.

Oscilloscope::new(
    cx,
    Data::oscilloscope_buffer,
    (-1.2, 1.2),
    ValueScaling::Linear,
)
.background_color(Color::rgba(120, 120, 120));

Here, Data::oscilloscope_buffer is an Arc<Mutex<WaveformBuffer>>, a buffer that allows for your audio to be sent to the Oscilloscope in a much smaller package, while retaining peak information. Here, it's configured to be 512 samples long, and it represents 10 seconds of audio at 44.1 kHz.

It's very plug-and-play, you only need to call enqueue_buffer() in your plugin's process function to use it!

Check out the book, or the examples to learn how to work with these buffers.

🍔 Composing views

A core feature of Cyma is composability.

For example, by combining views such as the Grid, UnitRuler, and PeakGraph, you can make this real-time peak analyzer.

fn peak_graph(cx: &mut Context) {
    HStack::new(cx, |cx| {
        ZStack::new(cx, |cx| {
            Grid::new(
                cx,
                ValueScaling::Linear,
                (-32., 8.),
                vec![6.0, 0.0, -6.0, -12.0, -18.0, -24.0, -30.0],
                Orientation::Horizontal,
            )
            .color(Color::rgb(60, 60, 60));

            Graph::new(cx, Data::peak_buffer, (-32.0, 8.0), ValueScaling::Decibels)
                .color(Color::rgba(255, 255, 255, 160))
                .background_color(Color::rgba(255, 255, 255, 60));
        })
        .background_color(Color::rgb(16, 16, 16));

        UnitRuler::new(
            cx,
            (-32.0, 8.0),
            ValueScaling::Linear,
            vec![
                (6.0, "6db"),
                (0.0, "0db"),
                (-6.0, "-6db"),
                (-12.0, "-12db"),
                (-18.0, "-18db"),
                (-24.0, "-24db"),
                (-30.0, "-30db"),
            ],
            Orientation::Vertical,
        )
        .font_size(12.)
        .color(Color::rgb(160, 160, 160))
        .width(Pixels(32.));
    })
    .col_between(Pixels(8.));
}

🙋 Contributing

If you have questions about Cyma, need help with something, or want to show off what you built using it, head over to the Discussions tab.

If you want to contribute through issues and code contributions, read the Contributing Guidelines first

📃 License

This project is licensed under the MPL.

cyma's Issues

Provide `element` names for styling

Document Views

• Visualizers
• Utils

Allow for PeakGraph and Oscilloscope line colors

Knob

XY-Pad

Slider

Switch

Further examples

Allow resizing of `PeakBuffer` and `WaveformBuffer` without clearing

Ceptral / Spectral Envelope

Allow gradual decrease in opacity for lissajous points

Toggle Button

Allow seperately enqueueing left / right channel data in `PeakBuffer` and `WaveformBuffer`

Envelope Editor

Prelude

Implement Lissajous

Implement Spectrogram

set_range() for Graph, Grid, Meter, etc.

Just like PeakBuffer and MinimaBuffer have set_duration() to set the scale in one direction, the views that include a range should have a set_range() to set the scale in the other direction.

Revise grid drawing system

Button

Implement Peak Meter

Dropdown Menu

LoudnessBuffer for Meter, Graph, etc.

This buffer will need to compute the loudness of incoming audio in large overlapping blocks by pre-filtering each channel, taking their respective mean square values, summing them, gating the result, and averaging it. Making this work will involve adding (likely 2nd order IIR) filters to Cyma, either through an external crate, or a new internal filter struct.

This PDF explains the process in great detail.

Allow for oscilloscope db scaling

Cyma Book / Tutorials / Docs

Filter Display / Editor

Add units for grid surfaces (-3db, -6db, -12db etc for PeakBuffers) etc etc.

Feature request: gain reduction meter

As a reminder of our conversation on Discord:

For dynamics processors, it would be great to have a gain reduction meter.
A gain change meter, that can go up as well as down, would be even better.
This is since upward compressors and expanders dynamically add gain instead of reducing it.

I imagine it will be a line at 0dB, and an area when it goes above or below that.
Does that make sense?

Thanks again for this wonderful library!

Implement Oscilloscope

Universal `Meter` and `Graph`

Currently, "*Graph" and "*Meter" views are planned for:

• Peak volume
• Loudness
• Gain reduction

...and more may come in the future. The issue is that implementing these as seperate views will lead to a lot of code duplication as the logic behind different types of meters and graphs is largely identical - aside from the scaling of values.

So, maybe an abstract solution that is a bit more flexible would be better. Something like a universal Graph and Meter that can display peak volume, gain reduction, and anything else you throw at it, depending on the context. In the same vein, the scaling (linear/dB/freq/etc) should probably be handled using some ubiquitous scaling Enum that all visualizers can go on to use.

It's worth thinking about this as soon as possible as it would involve a major breaking change, especially as more views get added.

Graph drawing error

Description:
When a graph is used with .fill_from(0.0), and the value is also 0.0, the graph-outline of the left most part of the graph does not get drawn:

Screenshots:

Desktop (please complete the following information):

• OS: Linux 6.6.25
• VST Host / DAW (if applicable): Jack standalone

Allow setting a value range in Oscilloscope (analogous to PeakGraph)

Use modifiers where applicable

Modifiers should be used in place of those parameters that are often left untouched or frequently set to a default. For example:

• ValueScaling
• Inversion (f.e. of peak graph, etc)
• Orientation

Implement PeakGraph