NormalizedAmplitudeToMask

The NormalizedAmplitudeToMask node receives an array of floating-point numbers representing audio amplitude as input, with its value range constrained between 0 and 1.

The NormalizedAmplitudeToMask node is an audio-driven tool that converts normalized audio amplitude data into an image mask. This node serves as a bridge connecting audio processing and image generation, allowing users to dynamically generate or influence visual elements based on sound intensity.
Works as a bridge to the AudioScheduler nodes.

Node Functionality

This node receives an array of floating-point numbers representing audio amplitude as input, with its value range constrained between 0 and 1. Its core mechanism involves adjusting the temporal alignment of the amplitude data via an optional frame offset parameter, and then generating a corresponding mask on a user-defined canvas according to the specified shape, position, size, and color mode. It supports generating mask areas in shapes such as circle, square, triangle, or no specific shape.

Node Parameter Description - NormalizedAmplitudeToMask

Connection Inputs (Inputs)

Parameter Name	Data Type	Required	Default Value	Value Range/Options	Description
`normalized_amp`	NORMALIZED_AMPLITUDE	Yes	-	-	normalized_amp (Input Parameter): Input normalized audio amplitude data, values should be between 0 and 1. This is the core driving data for mask generation.

Control Parameters (Parameters)

Parameter Name	Data Type	Required	Default Value	Value Range/Options	Description
`shape`	COMBO	Yes	none	"none", "circle", "square", "triangle"	"circle", "square", or "triangle".
`color`	COMBO	Yes	amplitude	"white", "amplitude"	color (Input Parameter): Determines the value (color) within the mask area. Options are "white" (value of 1) or "amplitude" (uses the input normalized amplitude value as the intensity for that area).
`width`	INT	Yes	512	16 - 4096 (Step: 1)	width (Input Parameter): Sets the width of the output mask image. Value range is 16 to 4096 pixels, with a step of 1.
`height`	INT	Yes	512	16 - 4096 (Step: 1)	height (Input Parameter): Sets the height of the output mask image. Value range is 16 to 4096 pixels, with a step of 1.
`frame_offset`	INT	Yes	0	-255 - 255 (Step: 1)	frame_offset (Input Parameter): The number of frames to offset the input amplitude data in time, used to adjust audio-video synchronization. Value range is -255 to 255, with a step of 1.
`location_x`	INT	Yes	256	0 - 4096 (Step: 1)	location_x (Input Parameter): Specifies the horizontal center position (X-coordinate) of the drawn shape on the canvas. Value range is 0 to 4096, with a step of 1.
`location_y`	INT	Yes	256	0 - 4096 (Step: 1)	location_y (Input Parameter): Specifies the vertical center position (Y-coordinate) of the drawn shape on the canvas. Value range is 0 to 4096, with a step of 1.
`size`	INT	Yes	128	8 - 4096 (Step: 1)	size (Input Parameter): Controls the base size (e.g., radius or side length) of the drawn shape. Value range is 8 to 4096, with a step of 1.

Output

Parameter Name	Data Type	Description
MASK	MASK	MASK (Output Parameter): Outputs the image mask generated based on audio amplitude.

Usage Scenarios

This node is highly useful in video or animation generation workflows. For example, you can connect the rhythm (amplitude) of a piece of music to the node to generate a circular mask that changes size with the beat of the music. This mask can then be used to control the display area of another layer, thereby creating a music visualization effect. It is often used in conjunction with audio nodes like AudioScheduler.

Notes

When using this node, note that the input amplitude data must be an array already normalized to the range [0, 1]. The generated mask dimensions are limited by the user-set canvas width and height. Additionally, the shape's position and size parameters should not exceed the canvas boundaries; otherwise, parts of the mask area will not be visible.