MetaSound Templates Quick Start

A MetaSound Template is a USTRUCT that lives on a MetaSound asset and procedurally generates or mutates the asset's graph, interface, and properties whenever a designer edits the template's exposed fields — and again at cook time. By isolating a small set of UPROPERTY fields that drive the template's ConfigureDocument() call, a template author shields end-users from the full MetaSound graph and exposes only the knobs that matter.

Templates enable developers to templatize procedural sounds (footsteps with effects, randomized weapon fire, ambient layers), let non-audio programmers or designers tweak variations without touching the graph, automate repetitive audio setups, hide implementation details that should not be edited, and version template behavior so fixes and deprecations can roll out without touching individual assets. The existing MetaSound Preset system is now itself a template (FMetaSoundFrontendPresetTemplate) — Presets are just a more sophisticated template characterization.

Workflows

This guide offers two self-contained workflows:

Using Templates in MetaSound Editor

Audience: Sound Designers. No C++ required. Every step is an editor action.

Create a MetaSound from a Template

1. In the Content Browser, right-click and choose Audio → MetaSound Source (or MetaSound Patch).

2. When the asset is created, open it. New MetaSounds start with an unset Template.

   A Template can be registered to appear directly in the Content Browser right-click menu, and creation of a MetaSound (with that template already applied) can be done in a single step.

Apply or Switch a Template on an Existing Asset

Open the MetaSound asset and click the Template dropdown in the top-left of the toolbar. You will see up to two sections:

• Set Template: Replaces the current template with the one you select. This discards the current graph content so that the new template can regenerate the graph from scratch using its ConfigureDocument() rules. Use this when you know you want the new template's topology.

• Convert Template: Appears only when a Template is set. Clears template, preserving the underlying MetaSound in its last state as applied by the Template, preserving designer intent while exposing the underlying MetaSound for further manipulation and customization otherwise hidden by the Template settings.

  If a menu entry is greyed out or missing, the current template author has restricted which templates can be set on this asset class — see Troubleshooting.

Edit Template Properties

Once a Template is applied, you have up to three editor surfaces to interact with, depending on what the template author opted into:

• Details panel → Template category: The template's exposed UPROPERTY fields appear here by default. This is your primary edit location for most templates.

• Custom Template tab: If the template ships a custom UMG widget, a dedicated Template tab appears (alongside the graph editor if the graph has not been hidden by the template author), giving you a purpose-built UI (sliders, previews, array editors) for that template.

• Graph editor, Interfaces panel, Members panel: These traditional MetaSound panels and tabs may be hidden, read-only, or fully editable (depending on FEditorOptions flags set by the author). A template that hides the graph editor is doing so intentionally — it expects the designer to drive behavior purely through properties.

  Any edit to a template property rebuilds the underlying MetaSound graph, inputs, etc. procedurally. You do not need to hit Save to observe changes — just audition.

Worked example: the Randomizer Template

The Randomizer is a reference template. It is hidden by default.

Because this is also an Unreal Engine feature and can be compiled with code there, the "Hidden" keyword must be removed in code and the project recompiled to enable the "Randomizer". Keep in mind, this struct is only included in Unreal Engine 5.8, this example has not been tested in a production-ready environment.

1. Create a new MetaSound Source.

2. Toolbar → Template dropdown → under Set Template, pick Randomizer.

3. In the Details panel, locate the Randomizer Options category and:

   1. Toggle Is One Shot — off plays a continuous loop, on triggers a single pick per play.

   2. Expand Sounds and add USoundWave references. The Randomizer will discard anything that is not exactly a USoundWave (e.g. USoundSourceBus, derived UMetaSoundSource) the next time the template runs.

   3. Adjust Pitch — the X component is the minimum semitone offset, the Y the maximum. Defaults are -3.0 to 3.0. The template clamps to -36 / +36.  

4. Audition. Each play picks a random sound from the list and applies a random pitch offset inside your range.

Presets are Templates

The MetaSound Preset system is now fully integrated with the template system as FMetaSoundFrontendPresetTemplate. When you apply a Preset, you are applying a specialized template whose job is to inherit from a parent MetaSound and let you override a curated subset of its inputs. Everything you know about Presets still works — see the existing MetaSound Reference Guide for Preset-specific details.

Troubleshooting for designers

Authoring a Template in Code

Audience: plugin and project developers. Requires C++.

Prerequisites

• A C++ toolchain set up for your project (Visual Studio on Windows, etc.).

• A module that can depend on MetasoundFrontend for the runtime portion of your template (the USTRUCT and ConfigureDocument() override).

• If you want custom editor UI, additionally:

  • A module that can depend on MetasoundEditor.

  • The Model View Viewmodel plugin enabled in your .uproject (ModelViewViewModel).

The “Minimum Viable Template”

Create a USTRUCT that inherits from FMetaSoundFrontendDocumentTemplate, declare the UPROPERTY fields you want to expose to designers, and override ConfigureDocument(). The following excerpt is adapted from the shipped Randomizer at MetasoundRandomizerTemplate.h:18-53:

// YourModule/Public/DocumentTemplates/MyProceduralTemplate.h
#pragma once
#include "DocumentTemplates/MetasoundFrontendDocumentTemplate.h"
#include "Sound/SoundWave.h"
#include "UObject/ObjectPtr.h"
#include "MyProceduralTemplate.generated.h"
USTRUCT(BlueprintType, meta = (Hidden, DisplayName = "My Procedural"))
struct FMyProceduralTemplate : public FMetaSoundFrontendDocumentTemplate
{
    GENERATED_BODY()

Implement ConfigureDocument() using the FMetaSoundFrontendDocumentBuilder API (see the MetaSound Builder API reference for the full set of operations — adding nodes, wiring inputs, setting defaults, etc.). The builder is the only way you should mutate the document: direct pointer manipulation is not supported.  

Two further virtuals you may override:

• OnAssetInitialized(TArray<UObject*> SelectedObjects, FMetaSoundFrontendDocumentBuilder&) — called once when a new MetaSound is created from this template via Content Browser drag/drop. SelectedObjects contains whatever the user had highlighted at the moment of creation, useful for seeding defaults (e.g. pre-populating Sounds from selected USoundWave assets).

• OnPropertyChanged(const FPropertyChangedEvent&, FMetaSoundFrontendDocumentBuilder&) — called before ConfigureDocument() on each property change. Use this for validation or to mutate state before the rebuild (e.g. the Randomizer uses this to strip invalid entries from Sounds via a helper RemoveInvalidSounds).

Controlling the editor UI via GetEditorOptions()

Override GetEditorOptions() to return a configured FEditorOptions that tailors the MetaSound Editor experience for your template. Defaults below come from MetasoundFrontendDocumentTemplate.h:45-89.

Return a static local FEditorOptions configured once:  

const FMetaSoundFrontendDocumentTemplate::FEditorOptions& FMyProceduralTemplate::GetEditorOptions() const
{
    static const FEditorOptions Options = []
    {
        FEditorOptions Opts;
        Opts.ToolTip = NSLOCTEXT("MyTemplates", "MyProcedural_Tip",
            "Randomly selects a sound from a list with pitch variation.");
        Opts.bGraphEditorVisible = false;  // hide the graph — designers only touch properties
        return Opts;
    }();

Topology-Manipulating Templates

For templates that do non-trivial graph manipulation, two utilities are available:

• MetasoundDocumentConfigurator.h — higher-level builder helper for common graph shapes. Start here before reaching for raw FMetaSoundFrontendDocumentBuilder calls.  

  Code for the Document Configurator is easily reflected from existing MetaSound content by selecting nodes in the MetaSound Asset Editor and using the right-click option “Copy Selected As Configurator Code to Clipboard".  

• FMetaSoundFrontendDocumentVertexTemplate (header) — extend from this instead of FMetaSoundFrontendDocumentTemplate when your template needs to attach per-vertex metadata (one payload per input or per output). It stores a TMap<FGuid, TInstancedStruct> keyed by vertex GUID and exposes OnDefaultReset / OnDefaultUpdated hooks so your template can react when a vertex's default value is modified. The shipped Preset template extends this variant.

Prefer the base FMetaSoundFrontendDocumentTemplate unless you specifically need per-vertex data — it's lighter weight and avoids the vertex-lifecycle complexity.

Custom UI via MVVM

Shipping custom in-editor UI for your template is a three-layer task: the template struct (Model), a ViewModel, and a UMG Widget. The ViewModel base bridges your template data onto a UMVVMViewModelBase so UMG's FieldNotify bindings can talk to it. The shipped Randomizer is the canonical reference implementation.

The Template struct (Model)

Use the USTRUCT from Minimum Viable Template. Every property you want bound into the UI must be a UPROPERTY.

The ViewModel

Subclass UMetaSoundTemplateViewModelBase (header). The base owns a UMetaSoundBuilderBase* reference, listens for template-change events, and exposes GetConstTemplate<T>() so you can read your template's state type-safely. It also declares a pure-virtual-style IsSupportedTemplate(const UScriptStruct&) that you must override to declare which template struct your ViewModel is for.

The Randomizer at RandomizerConfigurationViewModel.h:18-70 shows two binding patterns:

• UFUNCTION(FieldNotify)-based reads for derived values (e.g. GetPitchMin() returns Pitch.X). Widgets bind to the function and get a broadcast whenever the VM invalidates the field.

• UPROPERTY(FieldNotify, Getter=, Setter=)-based two-way for straight-through fields (e.g. the bIsOneShot bool mirrors onto a C++ getter/setter pair).

Excerpted from the Randomizer:

UCLASS(MinimalAPI, DisplayName = "MetaSound Randomizer ViewModel")
class UMetaSoundRandomizerViewModel : public UMetaSoundTemplateViewModelBase
{
    GENERATED_BODY()

public:
    UFUNCTION(BlueprintPure, FieldNotify, Category = "MetaSound|Randomizer")
    float GetPitchMin() const;

    UFUNCTION(BlueprintCallable, Category = "MetaSound|Randomizer")

In your .cpp:  

bool UMetaSoundRandomizerViewModel::IsSupportedTemplate(const UScriptStruct& InStruct) const
{
    return InStruct.IsChildOf(FMetaSoundRandomizerTemplate::StaticStruct());
}

float UMetaSoundRandomizerViewModel::GetPitchMin() const
{
    if (const FMetaSoundRandomizerTemplate* Template = GetConstTemplate<FMetaSoundRandomizerTemplate>())
    {
        return Template->Pitch.X;

The pattern: getters read from GetConstTemplate<T>(); setters write back through Builder->SetTemplateProperties<T>(…) so that the Template's ConfigureDocument() runs and the asset is marked dirty.

The Widget

Create a UUserWidget (typically an Editor Utility Widget so it can live in-editor content) and implement IMetaSoundTemplateWidgetInterface. All events are BlueprintImplementableEvent — you can implement in Blueprint or C++. The interface defines five events:

Once your widget is running, bind its inputs (sliders, spinboxes, array editors, text blocks) to the ViewModel's FieldNotify properties using UMG's standard MVVM panel. Edits flow through the VM's setters into the template, ConfigureDocument() runs, and the MetaSound rebuilds — live.

No Explicit Registration

You do not register your template, ViewModel, or widget anywhere. The editor discovers:

• Templates automatically because they are reflected USTRUCTs extending FMetaSoundFrontendDocumentTemplate.

• Widgets by scanning UClasses that implement IMetaSoundTemplateWidgetInterface.

• ViewModels by whatever class the widget returns from OnInitializingViewModel.

The single visibility gate is IsSupportedTemplate, implemented in two places: on the widget (for tab visibility) and on the ViewModel (for GetConstTemplate<T> type safety). Both should return true for the same template struct type.

Testing your Template

1. Rebuild your runtime + editor modules.

2. Open an existing or new MetaSound Source.

3. Toolbar → Template → your new entry should appear under Set Template.

4. Apply it and verify:

   1. If you shipped a widget, the Template tab opens with your UMG content.

   2. Your UPROPERTY fields appear in the Details panel under the category name you set.

5. For bring-up, drop a UE_LOG at the top of ConfigureDocument() so you can see it fire on every property edit. Remove before shipping.

6. Cook-time test: package the project with an asset that uses your template and confirm the cooked .uasset plays identically to the editor preview. A drift here means your ConfigureDocument() is nondeterministic.

Troubleshooting for Authors

Reference Appendix

Appendix 1 — Rename map

Appendix 2 — Header quick-reference

Appendix 3 — FEditorOptions full flag reference

Repeat of Controlling the Editor UI via GetEditorOptions() for quick look-up.

Debug CVar: au.MetaSound.Editor.IgnoreTemplateVisibilitySettings 1 forces all flags to true.

Appendix 4 — Further reading

• MetaSound Reference Guide — core graph/node concepts, Presets, built-in nodes.

• MetaSound Builder API — the FMetaSoundFrontendDocumentBuilder surface used inside ConfigureDocument().

• Model View Viewmodel plugin — UMG's MVVM documentation covers binding syntax, FieldNotify, and the UE_MVVM_* macros used throughout the ViewModel layer.