unreal.MetaSoundBuilderBase

class unreal.MetaSoundBuilderBase(outer: Object | None = None, name: Name | str = 'None')

Bases: Object

Base implementation of MetaSound builder

C++ Source:

  • Plugin: Metasound

  • Module: MetasoundEngine

  • File: MetasoundBuilderSubsystem.h

Editor Properties: (see get_editor_property/set_editor_property)

  • is_attached (bool): [Read-Write] deprecated: 5.4 - All source builders now operate on an underlying document source document that is also used to audition.

add_graph_input_node(name, data_type, default_value, is_constructor_input=False) -> (MetaSoundBuilderNodeOutputHandle, out_result=MetaSoundBuilderResult)

Adds a graph input node with the given name, DataType, and sets the graph input to default value. Returns the new input node’s output handle if it was successfully created, or an invalid handle if it failed.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

add_graph_output_node(name, data_type, default_value, is_constructor_output=False) -> (MetaSoundBuilderNodeInputHandle, out_result=MetaSoundBuilderResult)

Adds a graph output node with the given name, DataType, and sets output node’s input to default value. Returns the new output node’s input handle if it was successfully created, or an invalid handle if it failed.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

add_interface(interface_name) → MetaSoundBuilderResult

Adds an interface registered with the given name to the graph, adding associated input and output nodes.

Parameters:

interface_name (Name) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

add_node(node_class) -> (MetaSoundNodeHandle, out_result=MetaSoundBuilderResult)

Adds a node to the graph using the provided MetaSound asset as its defining NodeClass. Returns a node handle to the created node if successful, or an invalid handle if it failed.

Parameters:

node_class (MetaSoundDocumentInterface) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

add_node_by_class_name(class_name, major_version=1) -> (MetaSoundNodeHandle, out_result=MetaSoundBuilderResult)

Adds node referencing the highest native class version of the given class name to the document. Returns a node handle to the created node if successful, or an invalid handle if it failed.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

connect_node_input_to_graph_input(graph_input_name, node_input_handle) → MetaSoundBuilderResult

Connects a given node input to the graph input with the given name.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

connect_node_inputs_to_matching_graph_interface_inputs(node_handle) -> (Array[MetaSoundBuilderNodeOutputHandle], out_result=MetaSoundBuilderResult)

Connects a given node’s inputs to all graph inputs for shared interfaces implemented on both the node’s referenced class and the builder’s MetaSound graph. Returns outputs of connected input nodes.

Parameters:

node_handle (MetaSoundNodeHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

connect_node_output_to_graph_output(graph_output_name, node_output_handle) → MetaSoundBuilderResult

Connects a given node output to the graph output with the given name.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

connect_node_outputs_to_matching_graph_interface_outputs(node_handle) -> (Array[MetaSoundBuilderNodeInputHandle], out_result=MetaSoundBuilderResult)

Connects a given node’s outputs to all graph outputs for shared interfaces implemented on both the node’s referenced class and the builder’s MetaSound graph. Returns inputs of connected output nodes.

Parameters:

node_handle (MetaSoundNodeHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

connect_nodes(node_output_handle, node_input_handle) → MetaSoundBuilderResult

Connects node output to a node input. Does NOT provide loop detection for performance reasons. Loop detection is checked on class registration when built or played. Returns succeeded if connection made, failed if connection already exists with input, the data types do not match, or the connection is not supported due to access type incompatibility (ex. constructor input to non-constructor input).

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

connect_nodes_by_interface_bindings(from_node_handle, to_node_handle) → MetaSoundBuilderResult

Connects two nodes using defined MetaSound Interface Bindings registered with the MetaSound Interface registry.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

contains_node(node) → bool

Returns whether node exists.

Parameters:

node (MetaSoundNodeHandle) –

Return type:

bool

contains_node_input(input) → bool

Returns whether node input exists.

Parameters:

input (MetaSoundBuilderNodeInputHandle) –

Return type:

bool

contains_node_output(output) → bool

Returns whether node output exists.

Parameters:

output (MetaSoundBuilderNodeOutputHandle) –

Return type:

bool

convert_from_preset() → MetaSoundBuilderResult

Converts this preset to a fully accessible MetaSound; sets result to succeeded if it was converted successfully and failed if it was not.

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

convert_to_preset(referenced_node_class) → MetaSoundBuilderResult

Convert this builder to a MetaSound source preset with the given referenced source builder

Parameters:

referenced_node_class (MetaSoundDocumentInterface) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

disconnect_node_input(node_input_handle) → MetaSoundBuilderResult

Removes connection to a given node input. Returns success if connection was removed, failed if not.

Parameters:

node_input_handle (MetaSoundBuilderNodeInputHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

disconnect_node_output(node_output_handle) → MetaSoundBuilderResult

Removes all connections from a given node output. Returns success if all connections were removed, failed if not.

Parameters:

node_output_handle (MetaSoundBuilderNodeOutputHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

disconnect_nodes(node_output_handle, node_input_handle) → MetaSoundBuilderResult

Disconnects node output to a node input. Returns success if connection was removed, failed if not.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

disconnect_nodes_by_interface_bindings(from_node_handle, to_node_handle) → MetaSoundBuilderResult

Disconnects two nodes using defined MetaSound Interface Bindings registered with the MetaSound Interface registry. Returns success if all connections were found and removed, failed if any connections were not.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_graph_input_node(input_name) -> (MetaSoundNodeHandle, out_result=MetaSoundBuilderResult)

Returns graph input node by the given name if it exists, or an invalid handle if not found.

Parameters:

input_name (Name) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_graph_output_node(output_name) -> (MetaSoundNodeHandle, out_result=MetaSoundBuilderResult)

Returns graph output node by the given name if it exists, or an invalid handle if not found.

Parameters:

output_name (Name) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_interface_input_nodes(interface_name) -> (Array[MetaSoundNodeHandle], out_result=MetaSoundBuilderResult)

Returns input nodes associated with a given interface.

Parameters:

interface_name (Name) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_interface_output_nodes(interface_name) -> (Array[MetaSoundNodeHandle], out_result=MetaSoundBuilderResult)

Returns output nodes associated with a given interface.

Parameters:

interface_name (Name) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_node_class_version(node_handle) -> (MetasoundFrontendVersion, out_result=MetaSoundBuilderResult)

Returns output’s parent node if the input is valid, otherwise returns invalid node handle.

Parameters:

node_handle (MetaSoundNodeHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_node_input_by_name(node_handle, input_name) -> (MetaSoundBuilderNodeInputHandle, out_result=MetaSoundBuilderResult)

Returns node input by the given name if it exists, or an invalid handle if not found.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_node_input_parent(input_handle) -> (MetaSoundNodeHandle, out_result=MetaSoundBuilderResult)

Returns input’s parent node if the input is valid, otherwise returns invalid node handle.

Parameters:

input_handle (MetaSoundBuilderNodeInputHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_node_inputs(node_handle) -> (Array[MetaSoundBuilderNodeInputHandle], out_result=MetaSoundBuilderResult)

Returns all node inputs.

Parameters:

node_handle (MetaSoundNodeHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_node_inputs_by_data_type(node_handle, data_type) -> (Array[MetaSoundBuilderNodeInputHandle], out_result=MetaSoundBuilderResult)

Returns node inputs by the given DataType (ex. “Audio”, “Trigger”, “String”, “Bool”, “Float”, “Int32”, etc.).

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_node_output_by_name(node_handle, output_name) -> (MetaSoundBuilderNodeOutputHandle, out_result=MetaSoundBuilderResult)

Returns node output by the given name.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_node_output_parent(output_handle) -> (MetaSoundNodeHandle, out_result=MetaSoundBuilderResult)

Returns output’s parent node if the input is valid, otherwise returns invalid node handle.

Parameters:

output_handle (MetaSoundBuilderNodeOutputHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_node_outputs(node_handle) -> (Array[MetaSoundBuilderNodeOutputHandle], out_result=MetaSoundBuilderResult)

Returns all node outputs.

Parameters:

node_handle (MetaSoundNodeHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

find_node_outputs_by_data_type(node_handle, data_type) -> (Array[MetaSoundBuilderNodeOutputHandle], out_result=MetaSoundBuilderResult)

Returns node outputs by the given DataType (ex. “Audio”, “Trigger”, “String”, “Bool”, “Float”, “Int32”, etc.).

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

get_node_input_class_default(input_handle) -> (MetasoundFrontendLiteral, out_result=MetaSoundBuilderResult)

Returns node input’s class literal value if set, otherwise fails and returns default literal.

Parameters:

input_handle (MetaSoundBuilderNodeInputHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

get_node_input_data(input_handle) -> (name=Name, data_type=Name, out_result=MetaSoundBuilderResult)

Returns node input’s data if valid (including things like name and datatype).

Parameters:

input_handle (MetaSoundBuilderNodeInputHandle) –

Returns:

name (Name):

data_type (Name):

out_result (MetaSoundBuilderResult):

Return type:

tuple

get_node_input_default(input_handle) -> (MetasoundFrontendLiteral, out_result=MetaSoundBuilderResult)

Returns node input’s literal value if set on graph, otherwise fails and returns default literal.

Parameters:

input_handle (MetaSoundBuilderNodeInputHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

get_node_input_is_constructor_pin(input_handle) → bool

Returns whether the given node input is a constructor pin

Parameters:

input_handle (MetaSoundBuilderNodeInputHandle) –

Return type:

bool

get_node_output_data(output_handle) -> (name=Name, data_type=Name, out_result=MetaSoundBuilderResult)

Returns node output’s data if valid (including things like name and datatype).

Parameters:

output_handle (MetaSoundBuilderNodeOutputHandle) –

Returns:

name (Name):

data_type (Name):

out_result (MetaSoundBuilderResult):

Return type:

tuple

get_node_output_is_constructor_pin(output_handle) → bool

Returns whether the given node output is a constructor pin

Parameters:

output_handle (MetaSoundBuilderNodeOutputHandle) –

Return type:

bool

get_referenced_preset_asset() → Object

Return the asset referenced by this preset builder. Returns nullptr if the builder is not a preset.

Return type:

Object

interface_is_declared(interface_name) → bool

Returns if a given interface is declared.

Parameters:

interface_name (Name) –

Return type:

bool

property is_attached: bool

[Read-Write] deprecated: 5.4 - All source builders now operate on an underlying document source document that is also used to audition.

Type:

(bool)

is_preset() → bool

Returns whether this is a preset.

Return type:

bool

node_input_is_connected(input_handle) → bool

Returns if a given node input has connections.

Parameters:

input_handle (MetaSoundBuilderNodeInputHandle) –

Return type:

bool

node_output_is_connected(output_handle) → bool

Returns if a given node output is connected.

Parameters:

output_handle (MetaSoundBuilderNodeOutputHandle) –

Return type:

bool

nodes_are_connected(output_handle, input_handle) → bool

Returns if a given node output and node input are connected.

Parameters:
Return type:

bool

remove_graph_input(name) → MetaSoundBuilderResult

Removes graph input if it exists; sets result to succeeded if it was removed and failed if it was not.

Parameters:

name (Name) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

remove_graph_output(name) → MetaSoundBuilderResult

Removes graph output if it exists; sets result to succeeded if it was removed and failed if it was not.

Parameters:

name (Name) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

remove_interface(interface_name) → MetaSoundBuilderResult

Removes the interface with the given name from the builder’s MetaSound. Removes any graph inputs and outputs associated with the given interface and their respective connections (if any).

Parameters:

interface_name (Name) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

remove_node(node_handle) → MetaSoundBuilderResult

Removes node and any associated connections from the builder’s MetaSound.

Parameters:

node_handle (MetaSoundNodeHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

remove_node_input_default(input_handle) → MetaSoundBuilderResult

Removes node input literal default if set, reverting the value to be whatever the node class defaults the value to. Returns success if value was removed, false if not removed (i.e. wasn’t set to begin with).

Parameters:

input_handle (MetaSoundBuilderNodeInputHandle) –

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

set_graph_input_default(input_name, literal) → MetaSoundBuilderResult

Sets the input node’s default value, overriding the default provided by the referenced graph if the graph is a preset.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

set_node_input_default(node_input_handle, literal) → MetaSoundBuilderResult

Sets the node’s input default value (used if no connection to the given node input is present)

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult