Metasounds

🧠 Brains complement: IF an unreal-engine-skills-manager tool (external MCP) exists in this session, call it with {action: "load", skill: "audio-and-metasounds"} for UE domain knowledge on this topic — correct APIs, architecture, best practices — and treat it as the rubric for any review / "best practices" question. If no such tool is available (e.g. running under Claude Code or Codex without that MCP), skip this line entirely and proceed with this skill alone — do NOT attempt the call.

MetaSound Service Skill

Use this skill to create and edit MetaSound Source assets via Python.

pythonCopy code
import unreal
ms = unreal.MetaSoundService()

Key Concepts

• MetaSound Source — a procedural audio asset (UMetaSoundSource) defined by a node graph. It replaces SoundCue for runtime-parameterisable sounds.
• Node — a DSP processing block (Sine oscillator, Gain, Delay, etc.). Nodes have named input pins and output pins with associated DataTypes.
• NodeId — a GUID string returned by add_node. Pass it to connect, remove, set_default, etc.
• Graph I/O — add_graph_input / add_graph_output expose values at the asset level (settable at runtime via Set Float Parameter, etc.).
• Standard interface — every Source created by this service comes pre-wired with:
  • On Play (Trigger output) — fires when the sound starts
  • On Finished (Trigger input) — call to stop the sound
  • Audio:0 (Audio input on the graph output node) — connect your audio signal here

Workflow

1 — Discover available nodes

pythonCopy code
# List all nodes whose class name or display name contains "Sine"
nodes = ms.list_available_nodes("Sine")
for n in nodes:
    print(n.full_class_name, "  inputs:", n.inputs, "  outputs:", n.outputs)

2 — Create a MetaSound

pythonCopy code
r = ms.create_meta_sound("/Game/Audio", "MS_SineLoop", "Mono")
asset_path = r.asset_path   # "/Game/Audio/MS_SineLoop"

3 — Find the built-in interface node IDs

pythonCopy code
all_nodes = ms.list_nodes(asset_path)
for n in all_nodes:
    print(n.node_id, n.node_title, n.inputs, n.outputs)

# IMPORTANT: A MetaSound Source has MULTIPLE nodes with title "Output" —
# one per interface pin group (e.g. "On Finished" Trigger, "Out Mono" Audio).
# You MUST filter by the node whose inputs contain an Audio-type pin.
# Pin strings are "VertexName:TypeName" — the TypeName suffix after the last colon.
audio_out_node = next(
    n for n in all_nodes
    if n.node_title == "Output" and any(p.endswith(":Audio") for p in n.inputs)
)
audio_out_id = audio_out_node.node_id
# Drop the last :TypeName suffix to get the raw vertex name for connect_nodes
audio_in_pin = ":".join(audio_out_node.inputs[0].split(":")[:-1])  # "UE.OutputFormat.Mono.Audio:0"

# Input node — filter by class_name "Input.Trigger" to avoid matching graph input nodes
# (graph inputs also appear as "Input" nodes but with class "Input.Float", "Input.Bool", etc.)
input_node = next(n for n in all_nodes if n.class_name == "Input.Trigger")
input_node_id = input_node.node_id
on_play_pin = ":".join(input_node.outputs[0].split(":")[:-1])  # "UE.Source.OnPlay"

4 — Add a node

pythonCopy code
# add_node(asset_path, namespace, name, variant="", major_version=1, pos_x=0, pos_y=0)
# Use list_available_nodes() to discover the correct namespace/name/variant for any node
r2 = ms.add_node(asset_path, "UE", "Sine", "Audio", 1, -200.0, 0.0)
sine_id = r2.node_id   # GUID string

5 — Set a node input default

pythonCopy code
# Set the Sine frequency to 880 Hz
# Use get_node_pins() to confirm exact input pin names before setting
ms.set_node_input_default(asset_path, sine_id, "Frequency", "880.0", "Float")

# Read it back (issue #460):
ms.get_node_input_default(asset_path, sine_id, "Frequency")   # -> "880.000000"
# All inputs at once: name / data_type / default_value / is_connected
for v in ms.get_node_input_values(asset_path, sine_id):
    print(v.name, v.data_type, v.default_value, v.is_connected)

6 — Connect nodes

pythonCopy code
# connect_nodes(asset_path, from_node_id, output_name, to_node_id, input_name)
# Sine output pin is "Audio"; AudioOut input pin is "UE.OutputFormat.Mono.Audio:0"
ms.connect_nodes(asset_path, sine_id, "Audio", audio_out_id, audio_in_pin)

# Read the wiring back (issue #460) — every edge touching a node, both directions:
for c in ms.get_node_connections(asset_path, sine_id):
    print(f"{c.from_node_id}.{c.from_output} -> {c.to_node_id}.{c.to_input} [{c.data_type}]")

7 — Save

pythonCopy code
ms.save_meta_sound(asset_path)

Method Reference

Lifecycle

Node Discovery

Node Management

Connections

Graph I/O

Node Configuration

Common DataTypes

Complete Example — 880 Hz Sine Tone

pythonCopy code
import unreal
ms = unreal.MetaSoundService()

# Create asset
r = ms.create_meta_sound("/Game/Audio", "MS_Test880Hz", "Mono")
ap = r.asset_path

# Find the AudioOut node — there are multiple nodes titled "Output" (one per interface
# pin group). Filter for the one whose inputs contain an Audio-type pin.
nodes = ms.list_nodes(ap)
audio_out_node = next(
    n for n in nodes
    if n.node_title == "Output" and any(p.endswith(":Audio") for p in n.inputs)
)
audio_out_id = audio_out_node.node_id
# Pin strings are "VertexName:TypeName" — drop only the last :TypeName to get the vertex name
audio_in_pin = ":".join(audio_out_node.inputs[0].split(":")[:-1])  # "UE.OutputFormat.Mono.Audio:0"

# Add Sine oscillator (use list_available_nodes("Sine") to discover namespace/name/variant)
r2 = ms.add_node(ap, "UE", "Sine", "Audio", 1, -300.0, 0.0)
sine_id = r2.node_id

# Set frequency to 880 Hz (use get_node_pins() to confirm exact pin names)
ms.set_node_input_default(ap, sine_id, "Frequency", "880.0", "Float")

# Connect Sine "Audio" output to the AudioOut sink pin
ms.connect_nodes(ap, sine_id, "Audio", audio_out_id, audio_in_pin)

# Save
ms.save_meta_sound(ap)
print("Done:", ap)

Complete Example — One-Shot SoundWave (Gunshot)

pythonCopy code
import unreal
ms = unreal.MetaSoundService()

# Create a Mono MetaSound Source
r = ms.create_meta_sound("/Game/Audio", "MS_Gunshot", "Mono")
ap = r.asset_path

# Find interface nodes
nodes = ms.list_nodes(ap)

# Input node — has "On Play" Trigger output
input_node = next(n for n in nodes if n.node_title == "Input")
input_node_id = input_node.node_id

# Audio Output node — filter for the one with an Audio-type input
audio_out_node = next(
    n for n in nodes
    if n.node_title == "Output" and any(p.endswith(":Audio") for p in n.inputs)
)
audio_out_id = audio_out_node.node_id
audio_in_pin = ":".join(audio_out_node.inputs[0].split(":")[:-1])

# Add Wave Player (Mono) node
# Pin names (no need to call get_node_pins — see Known Node Pins below):
#   Inputs:  "Play" (Trigger), "Stop" (Trigger), "Wave Asset" (WaveAsset), "Loop" (Bool)
#   Outputs: "Out Mono" (Audio), "On Play" (Trigger), "On Finished" (Trigger)
wp = ms.add_node(ap, "UE", "Wave Player", "Mono", 1, -300.0, 0.0)
wp_id = wp.node_id

# Set the wave asset
ms.set_node_input_default(ap, wp_id, "Wave Asset", "/Game/Audio/SW_Gunshot_01", "WaveAsset")

# Wire On Play (Input) → Play (WavePlayer)
# CRITICAL: use the vertex name "UE.Source.OnPlay" — NOT the display name "On Play"
r = ms.connect_nodes(ap, input_node_id, "UE.Source.OnPlay", wp_id, "Play")
if not r.success: raise RuntimeError(f"connect On Play→Play failed: {r.message}")

# Wire Out Mono (WavePlayer) → audio sink (Output)
r = ms.connect_nodes(ap, wp_id, "Out Mono", audio_out_id, audio_in_pin)
if not r.success: raise RuntimeError(f"connect Out Mono→Output failed: {r.message}")

# Save
ms.save_meta_sound(ap)
print("Done:", ap)

Return Type Attribute Reference

Use these exact attribute names — guessing leads to AttributeError.

FMetaSoundResult — returned by most mutating methods

pythonCopy code
r = ms.connect_nodes(ap, from_id, "Audio", to_id, pin)
if not r.success:
    raise RuntimeError(r.message)
# NOT r.b_success — that attribute does not exist

FMetaSoundInfo — returned by get_meta_sound_info()

pythonCopy code
info = svc.get_meta_sound_info(asset_path)
print(info.node_count, info.output_format)
# NOT info.success, info.b_success, info.message

FMetaSoundNodeInfo — returned by list_nodes() and get_node_pins()

pythonCopy code
nodes = ms.list_nodes(asset_path)
for n in nodes:
    print(n.node_id, n.node_title, n.class_name)
    # NOT n.node_class, n.node_class_name, n.name

FMetaSoundNodeClassInfo — returned by list_available_nodes()

pythonCopy code
nodes = ms.list_available_nodes("Wave Player")
for n in nodes:
    print(n.name, n.variant, n.full_class_name)
    # NOT n.node_name, n.node_class, n.class_name

Known Node Pins

Use these instead of calling get_node_pins on freshly-added nodes (can time out).

Wave Player (UE.Wave Player.Mono)

Sine (UE.Sine.Audio)

Standard Interface Nodes

CRITICAL: Interface node pins use namespaced vertex names. The display name shown in the editor is NOT the vertex name. Always use the vertex names below in connect_nodes.

The audio output format depends on the output_format passed to create_meta_sound ("Mono" / "Stereo" / "Quad"). A Stereo source has two Output.Audio nodes (Left :0, Right :1); a Quad source has four. Mono has one.

Connecting to a Stereo (or Quad) output

A Mono asset has a single audio sink, so next(...) is fine. Stereo/Quad assets have one audio output node per channel — grab them all and feed each one, or channels will be silent.

pythonCopy code
# Collect every audio sink node (works for Mono, Stereo, and Quad)
nodes = ms.list_nodes(ap)
audio_out_nodes = [
    n for n in nodes
    if n.node_title == "Output" and any(p.endswith(":Audio") for p in n.inputs)
]
# Sort by channel index so [0]=Left, [1]=Right (the vertex name ends with ":<index>:Audio")
audio_out_nodes.sort(key=lambda n: n.inputs[0])

# Mono: one node. Stereo: two (Left, Right). Quad: four.
# Example — send a mono signal (e.g. a Mixer "Out") to BOTH stereo channels:
for out_node in audio_out_nodes:
    sink_pin = out_node.inputs[0]                 # e.g. "UE.OutputFormat.Stereo.Audio:0:Audio"
    r = ms.connect_nodes(ap, source_id, "Out", out_node.node_id, sink_pin)
    if not r.success: raise RuntimeError(r.message)

For a true stereo image, drive Left and Right from different signals (e.g. two oscillators, or a stereo Audio Mixer (Stereo, N) whose Out L / Out R feed the two sinks). To get a stereo mixer, search list_available_nodes("Mixer") for a (Stereo, …) variant — the (Mono, N) mixer has a single Out pin and only fills one channel on its own.

connect_nodes accepts the full "VertexName:TypeName" pin string (it strips the trailing :TypeName), so you can pass n.inputs[0] directly without manual splitting.

Notes

• Save after every batch of edits, not after each individual operation, to avoid excessive disk I/O.
• list_available_nodes("") returns all registered node classes (~400+). Use a filter like "Sine", "Delay", "Gain" to narrow the results.
• Node pin names for standard nodes use UE display names (e.g. "In Frequency", "Out", "Audio:0"). Use get_node_pins() to confirm exact names.
• A MetaSound Source has multiple nodes with node_title == "Output" — one per interface pin group (e.g. "On Finished" Trigger, "Out Mono" Audio). To find the audio sink node, filter for the Output node whose inputs contain an Audio-type pin: next(n for n in nodes if n.node_title == "Output" and any(p.endswith(":Audio") for p in n.inputs)). Pin strings from list_nodes are "VertexName:TypeName" — you can pass them directly to connect_nodes, which now automatically strips the trailing :TypeName suffix. Manual stripping (":".join(pin.split(":")[:-1])) still works but is no longer required.
• Node namespace/name/variant values differ from what the MetaSound editor displays. Always call list_available_nodes("keyword") to discover the correct values; do not guess.
• MetaSound Sources do not support SoundCue-style SoundNodeWavePlayer — use the WavePlayer MetaSound node instead (discover via list_available_nodes("Wave Player")).
• Graph inputs appear as Input nodes in the graph (class_name == "Input.Float", "Input.Bool", etc.). When filtering for the standard interface Input node (the one that carries On Play), always match by class_name == "Input.Trigger" — not by node_title == "Input" alone, which will also match graph input nodes.
• AudioMixer pins interleave audio and gain: Audio Mixer (Mono, 2) has pins ["In 0:Audio", "Gain 0:Float", "In 1:Audio", "Gain 1:Float"]. Never index by position — always filter for :Audio typed pins when connecting audio signals: audio_ins = [p.split(":")[0] for p in mixer_node.inputs if p.endswith(":Audio")].
• Stereo MetaSound Sources have TWO audio output sinks, one per channel. A Stereo source's audio output pins are UE.OutputFormat.Stereo.Audio:0 (Left) and UE.OutputFormat.Stereo.Audio:1 (Right) — exposed as two separate Output.Audio nodes, not one. (Quad has four: :0–:3.) You must feed both channels or one side will be silent. The single-next() audio-sink finder used for Mono only grabs one channel — for Stereo, collect every audio output node. See Connecting to a Stereo/Quad output below.

Sample scripts (run via execute_python_code)

• scripts/create_metasound.txt — create a MetaSound Source and list available node types.