FilmStripBooleanControl
A boolean control that displays frames from a filmstrip sprite sheet, supporting the industry-standard bitmap-based control representation.
FilmStripBooleanControl is a boolean control that displays frames from a filmstrip sprite sheet. It supports the widely-used industry standard for control representation: bitmap sprite sheets (filmstrips).
While bitmap-based visualization is more constrained than SVG (no dynamic theming, fixed visual appearance), this component shares the same layout, parameter model, interaction, and accessibility as other controls (vector, raster, and control primitives); see the Raster introduction.
Typically uses 2 frames: frame 0 for false/off, frame 1 for true/on.
Note:
No Theming Support: This component does NOT support themable props (color, roundness, thickness) as visuals are entirely determined by the image content.
Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
value | boolean | — | Yes | Current value of the control |
onChange | (event: AudioControlEvent<boolean>) => void | — | No | Handler for value changes |
latch | boolean | false | No | Whether the button operates in latch (toggle) mode or momentary mode |
label | string | — | No | Label displayed below the component |
frameWidth | number | — | Yes | Width of a single frame in the filmstrip (pixels) |
frameHeight | number | — | Yes | Height of a single frame in the filmstrip (pixels) |
frameCount | number | — | Yes | Total number of frames in the filmstrip sprite sheet (typically 2 for boolean controls) |
imageHref | string | — | Yes | URL to the sprite sheet/filmstrip image |
orientation | "vertical" | "horizontal" | vertical | No | Orientation of the filmstrip (frames stacked vertically or horizontally) |
frameRotation | number | 0 | No | Optional frame rotation in degrees |
invertValue | boolean | false | No | If true, inverts the normalized value (0.0 -> 1.0 and 1.0 -> 0.0). Useful for filmstrips where frame 0 represents "on" and frame 1 represents "off" |
adaptiveSize | boolean | false | No | Whether the component stretches to fill its container |
size | "xsmall" | "small" | "normal" | "large" | "xlarge" | normal | No | Size of the component |
parameter | BooleanParameter | — | No | Audio Parameter definition (Model). If provided, overrides label/latch from ad-hoc props |
Basic Usage
FilmStripBooleanControl requires a filmstrip sprite sheet image with typically 2 frames (off and on states):
Modes of Operation
Latch Mode (Toggle)
In latch mode, the button toggles between pressed and released states:
Momentary Mode
In momentary mode, the button is only active while being pressed:
Filmstrip Configuration
Frame Dimensions
Specify the dimensions of a single frame:
Orientation
Control whether frames are stacked vertically or horizontally:
Frame Rotation
Rotate the entire filmstrip container:
Value Inversion
Invert the value mapping for filmstrips where frame 0 represents "on" and frame 1 represents "off":
Frame Mapping
The component maps boolean values to frames:
false(normalized 0.0) → Frame 0true(normalized 1.0) → Frame 1
When invertValue is true, the mapping is reversed:
false→ Frame 1true→ Frame 0
Parameter Model
Use a parameter model for integration with audio parameter systems. The following example uses ad-hoc props; with the full library you would use createBooleanParameter and the parameter prop:
Adaptive Sizing
The FilmStripBooleanControl component supports both fixed sizes and adaptive sizing. By default, the size of the component is driven by the Size System and their size attribute:
Adaptive sizing allows the component to adapt to the size of its parent container, adjusting its dimensions intelligently without causing distortion (scaleToFit display mode). The fill display mode makes the component fill the entire container, potentially distorting it.
Common Use Cases
Power Switch
Momentary Button
Metal Switch
Filmstrip Image Format
Filmstrip images should follow these conventions:
- Frame count: Typically 2 frames for boolean controls (off and on)
- Vertical orientation (default): Frames stacked top to bottom
- Horizontal orientation: Frames stacked left to right
- Frame dimensions: All frames must have identical dimensions
- Compatibility: Works with filmstrips exported from WebKnobMan and other VST development tools
Next Steps
- Explore FilmStripContinuousControl for continuous parameter control
- Learn about FilmStripDiscreteControl for discrete parameter control
- Check out the playground for interactive examples