Iced Audio

Iced Audio provides specialized UI widgets designed for audio applications, such as VST3 or CLAP plugins. The library includes several widgets for parameter control:

• HSlider: Horizontal Slider
• VSlider: Vertical Slider
• Knob: A classic knob widget
• Ramp: Used to control easing between two points in time
• XYPad: An XY Pad for controlling two parameters simultaneously
• ModRangeInput: A dot used to control the range of modulation for a parameter. Some widgets (HSlider, VSlider, and Knob) support styles that provide visual feedback for the modulation range.

Most widgets in iced_audio (except XYPad) use a shared "virtual slider" input logic. A virtual slider produces a normalized float value in the range [0.0..1.0].

To convert this normalized value into meaningful audio parameters, you use mapping functions. The library provides four built-in mapping functions:

• FloatRange: A linear range of f32 values.
• IntRange: A discrete range of i32 values, causing the widget to "step" when moved.
• LogDBRange: A logarithmic range of decibel values (values near 0 dB increment slower than those further away).
• FreqRange: A logarithmic range of frequency values, where each octave in the 10-octave spectrum (20 Hz to 20480 Hz) is spaced evenly.

You can also implement custom mapping functions to drive your own custom virtual slider widgets.

If you are building audio plugins (VST3, CLAP, or standalone), iced_audio is designed to work with the following ecosystem:

• nice-plug: A complete audio plugin development framework for VST3, CLAP, and standalone targets with native support for Iced.
• clack-plugin: An easy way to create CLAP plugins in Rust.
• iced_baseview: Used to run Iced on the baseview windowing backend (typically used in conjunction with clack-plugin).

When defining dimensions for notches, borders, or arcs in a Knob stylesheet, use StyleLength to control how sizes are calculated relative to the knob's diameter.

• Scaled(f32): The length is a multiplier of the knob's diameter (e.g., 0.1 is 10% of the diameter).
• Fixed(f32): The length is an absolute value in pixels.

use iced_audio::style::knob::StyleLength;

let diameter_relative = StyleLength::Scaled(0.2);
let pixel_fixed = StyleLength::Fixed(10.0);

You can apply styles to an XYPad using the XYPad enum.

1. Default Style: Use XYPad::Default for the standard look.
2. Custom Style: Use XYPad::Custom(Box::new(your_style_sheet)) to apply a custom implementation of the StyleSheet trait.

You can easily convert any type that implements StyleSheet<Style = iced_core::Theme> into an XYPad using .into().

use iced_audio::style::xy_pad::{XYPad, StyleSheet, Appearance};
use iced_core::Theme;

struct MyStyle;

impl StyleSheet for MyStyle {
    type Style = Theme;

    fn idle(&self, _style: &Self::Style) -> Appearance {
        Appearance::default()
    }
}

// Convert MyStyle into the XYPad style enum
let my_xy_pad_style: XYPad = MyStyle.into();

To use specific widgets or integrations, you must enable the corresponding features in your Cargo.toml.

Important Requirements:

• You must enable the canvas feature in the iced crate for widgets to render properly.
• You must enable the image feature if you want to use texture styles.

Available Features:

• all (default): Enables all widgets.
• knob (default): Enables the Knob widget.
• h_slider (default): Enables the HSlider widget.
• v_slider (default): Enables the VSlider widget.
• ramp (default): Enables the Ramp widget.
• xy_pad (default): Enables the XYPad widget.
• nice-plug: Provides better integration with the nice-plug framework.

State

State tracks the internal lifecycle of a slider interaction. It manages:

• is_dragging: Whether the user is currently holding the mouse/touch down.
• is_gesturing(): A helper method to check if the widget is currently in a GestureStart, Gesturing, or GestureEnd state (returns true if not GestureEnd).

UpdateStatus

UpdateStatus is returned by the update method to signal what changed during the event processing:

• param_changed: The underlying NormalParam value was modified.
• hover_state_changed: The cursor entered or left the widget area.
• gesturing_state_changed: The gesture lifecycle transitioned (e.g., Start -> Gesturing).

Use UpdateStatus::should_redraw() to determine if the widget needs to be re-rendered based on these changes.

The iced_audio crate provides several specialized widgets for audio control, which are available as optional features. Depending on the features enabled in your Cargo.toml, you can use the following widgets:

• Knob: A rotary control widget.
• HSlider: A horizontal slider widget.
• VSlider: A vertical slider widget.
• Ramp: A widget for controlling ramps or transitions.
• XYPad: A two-dimensional control pad.
• ModRangeInput: A specialized range input widget for modulation.

To use these, ensure the corresponding feature is enabled in your dependency configuration.

# Example Cargo.toml configuration
[dependencies]
iced_audio = {
    version = "0.5.0",
    features = ["knob", "h_slider", "v_slider", "ramp", "xy_pad", "mod_range_input"]
}