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: MetasoundBuilderBase.h

Editor Properties: (see get_editor_property/set_editor_property)

  • class_name (MetasoundFrontendClassName): [Read-Write] deprecated: 5.5 - No longer used. ClassName should be queried from associated FrontendBuilder’s MetaSound

  • 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_graph_variable(name, data_type, default_value) → MetaSoundBuilderResult

Adds a graph variable node with the given name, DataType, and sets to default value.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

add_graph_variable_get_delayed_node(name) -> (MetaSoundNodeHandle, out_result=MetaSoundBuilderResult)

Adds a graph variable node with the given name, DataType, and sets to default value.

Parameters:

name (Name)

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

add_graph_variable_get_node(name) -> (MetaSoundNodeHandle, out_result=MetaSoundBuilderResult)

Adds a graph variable node with the given name, DataType, and sets to default value.

Parameters:

name (Name)

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

add_graph_variable_set_node(name) -> (MetaSoundNodeHandle, out_result=MetaSoundBuilderResult)

Adds a graph variable node with the given name, DataType, and sets to default value.

Parameters:

name (Name)

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

build(parent, options) → MetaSoundDocumentInterface

Build

Parameters:
Return type:

MetaSoundDocumentInterface

build_and_overwrite_meta_sound(existing_meta_sound, force_unique_class_name=False) → None

Copies a transient MetaSound with the provided builder options, copying the underlying MetaSound managed by this builder and registering it with the MetaSound Node Registry as a unique name. If ‘Force Unique Class Name’ is true, registers MetaSound as a new class in the registry, potentially invalidating existing references in other MetaSounds. Not permissible to overwrite MetaSound asset, only transient MetaSound (see EditorSubsystem for overwriting assets at edit time).

Parameters:
build_new_meta_sound(name_base) → MetaSoundDocumentInterface

Builds a transient MetaSound with the provided builder options, copying the underlying MetaSound managed by this builder and registering it with the MetaSound Node Registry as a unique class. If existing MetaSound exists with the provided NameBase, will make object with unique name with the given NameBase as prefix.

Parameters:

name_base (Name)

Return type:

MetaSoundDocumentInterface

property class_name: MetasoundFrontendClassName

[Read-Write] deprecated: 5.5 - No longer used. ClassName should be queried from associated FrontendBuilder’s MetaSound

Type:

(MetasoundFrontendClassName)

connect_named_node_output_to_graph_output(source_node, node_output_name, graph_output) → MetaSoundBuilderResult

Connects a given node’s named output to the graph output with the given handle.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

connect_named_node_output_to_named_graph_output(source_node, node_output_name, graph_output_name) → MetaSoundBuilderResult

Connects a given node’s named output to the graph output with the given name.

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_data_type=Name, node_output_handle=MetaSoundBuilderNodeOutputHandle, 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_data_type (Name):

node_output_handle (MetaSoundBuilderNodeOutputHandle):

out_result (MetaSoundBuilderResult):

Return type:

tuple

find_graph_output_node(output_name) -> (MetaSoundNodeHandle, out_data_type=Name, node_input_handle=MetaSoundBuilderNodeInputHandle, 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_data_type (Name):

node_input_handle (MetaSoundBuilderNodeInputHandle):

out_result (MetaSoundBuilderResult):

Return type:

tuple

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_graph_input_default(input_name) -> (MetasoundFrontendLiteral, out_result=MetaSoundBuilderResult)

Gets the graph input’s default literal value.

Parameters:

input_name (Name)

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

get_graph_input_names() -> (Array[Name], out_result=MetaSoundBuilderResult)

Gets names of all graph inputs.

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

get_graph_output_names() -> (Array[Name], out_result=MetaSoundBuilderResult)

Gets names of all graph outputs.

Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

get_graph_variable_default(variable_name) -> (MetasoundFrontendLiteral, out_result=MetaSoundBuilderResult)

Gets the graph variable’s default literal value.

Parameters:

variable_name (Name)

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 parent asset referenced by this preset builder. Returns nullptr if the builder is not a preset.

Return type:

Object

get_root_graph_class_name() → MetasoundFrontendClassName

Returns the MetaSound asset’s graph class name (used by the MetaSound Node Class Registry)

Return type:

MetasoundFrontendClassName

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 input from all paged graphs 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 output from all paged graphs 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_variable(name) → MetaSoundBuilderResult

Removes graph variable from the current build graph 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, remove_unused_dependencies=True) → MetaSoundBuilderResult

Removes node and any associated connections from the current build graph. (Advanced) Optionally, remove unused dependencies from the internal dependency list on successful removal of node.

Parameters:
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

remove_unused_dependencies() → None

Removes dependencies in document that are no longer referenced by nodes

set_graph_input_access_type(input_name, access_type) → MetaSoundBuilderResult

Disconnects the given graph input’s respective template nodes and sets the graph input’s AccessType should it not match the current AccessType. Result succeeds if the AccessType was successfully changed or if the provided AccessType is already the input’s current AccessType.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

set_graph_input_data_type(input_name, data_type) → MetaSoundBuilderResult

Disconnects the given graph input’s respective template nodes and sets the graph input’s DataType should it not match the current DataType. Result succeeds if the DataType was successfully changed or if the provided DataType is already the input’s current DataType.

Parameters:
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_graph_input_name(input_name, new_name) → MetaSoundBuilderResult

Sets the given graph input’s name to the new name. Result succeeds if the name was successfully changed or the new name is the same as the old name, and fails if the given input name doesn’t exist.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

set_graph_output_access_type(output_name, access_type) → MetaSoundBuilderResult

Disconnects the given graph output’s respective template nodes and sets the graph output’s AccessType should it not match the current AccessType. Result succeeds if the AccessType was successfully changed or if the provided AccessType is already the output’s current AccessType.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

set_graph_output_data_type(output_name, data_type) → MetaSoundBuilderResult

Disconnects the given graph output’s respective template nodes and sets the graph output’s DataType should it not match the current DataType. Result succeeds if the DataType was successfully changed or if the provided DataType is already the output’s current DataType.

Parameters:
Returns:

out_result (MetaSoundBuilderResult):

Return type:

MetaSoundBuilderResult

set_graph_output_name(output_name, new_name) → MetaSoundBuilderResult

Sets the given graph output’s name to the new name. Result succeeds if the name was successfully changed or the new name is the same as the old name, and fails if the given output name doesn’t exist.

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