FilmStripContinuousControl
A continuous control that displays frames from a filmstrip sprite sheet, supporting the industry-standard bitmap-based control representation.
FilmStripContinuousControl is a continuous 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.
The frame displayed is determined by the normalized value (0-1 maps to frame 0 to frameCount-1).
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 | number | — | Yes | Current value of the control |
onChange | (event: AudioControlEvent<number>) => void | — | No | Handler for value changes |
min | number | — | No | Minimum value (ad-hoc mode) |
max | number | — | No | Maximum value (ad-hoc mode) |
step | number | — | No | Step size for value adjustments |
bipolar | boolean | false | No | Whether the component should operate in bipolar mode (centered at zero) |
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 |
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 the maximum value |
valueAsLabel | "labelOnly" | "valueOnly" | "interactive" | labelOnly | No | Controls how the label and value are displayed |
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 | ContinuousParameter | — | No | Audio Parameter definition (Model). If provided, overrides min/max/step/label/bipolar from ad-hoc props |
valueFormatter | (value: number, parameterDef: AudioParameter) => string | undefined | — | No | Custom renderer for the value display |
interactionMode | "drag" | "wheel" | "both" | both | No | Interaction mode |
interactionDirection | "vertical" | "horizontal" | "circular" | "both" | — | No | Direction of interaction |
interactionSensitivity | number | — | No | Sensitivity multiplier for interactions (default varies by control type) |
Basic Usage
FilmStripContinuousControl requires a filmstrip sprite sheet image and frame dimensions:
Filmstrip Configuration
Filmstrips are bitmap sprite sheets containing multiple frames stacked vertically (default) or horizontally. Each frame represents a different value state.
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 the maximum value:
Value Mapping
The component maps continuous values (0-1 normalized) to frame indices (0 to frameCount-1):
- Value 0.0 (min) → Frame 0
- Value 1.0 (max) → Frame (frameCount - 1)
- Intermediate values are linearly interpolated
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 createContinuousParameter and the parameter prop:
Adaptive Sizing
The FilmStripContinuousControl 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.
Interaction Modes
Control how users interact with the filmstrip:
Common Use Cases
VU Meter
Rotary Knob
Filmstrip Image Format
Filmstrip images should follow these conventions:
- Vertical orientation (default): Frames stacked top to bottom
- Horizontal orientation: Frames stacked left to right
- Frame dimensions: All frames must have identical dimensions
- Frame count: Total number of frames in the sprite sheet
- Compatibility: Works with filmstrips exported from WebKnobMan and other VST development tools
Next Steps
- Explore FilmStripDiscreteControl for discrete parameter control
- Learn about FilmStripBooleanControl for boolean switches
- Check out the playground for interactive examples