Introduction
Audio Insights provides a suite of tools to profile, debug, and monitor runtime aspects of audio in Unreal Engine (UE). Using several tabbed windows, Audio Insights provides visualizations and numerical values for current pitch, volume, and other parameter values for Sources, Audio Buses, Submixes, and more during live gameplay. It can provide information for both Play In Editor (PIE) sessions and standalone games.
The Audio Insights Plugin
Audio Insights is enabled by default in UE. If it is disabled, you can re-enable it by selecting Edit > Plugins in the main menu, then searching for and enabling the Audio Insights plugin. After re-enabling the plugin in your project, you need to restart the editor.
Using Audio Insights in the Editor
Once enabled for your project, you can open an Audio Insights window from the Tools menu.
By default, Audio Insights begins monitoring the events generated by the audio engine when you start a PIE session and presents the data in a series of tabs.
If you disabled this default behavior, you can begin monitoring using the Start Monitoring button in the upper left corner.
Audio Insights is a tabbed window; you can dock it anywhere in the editor for your convenience.
Editor trace recording summary:
In the main menu, select Tools > Audio Insights.
Confirm Monitoring is active (shows a green icon).
If necessary, click Start Monitoring.
Enter PIE mode in your project.
Saving a Trace
By default, monitoring data does not save data:
Click Start Recording to begin saving a trace:
Both of these states (monitoring and recording) show a trace stream generated in Unreal Editor. Use the Recording button's state to validate whether Audio Insights is saving the data to disk.
Using Audio Insights with Standalone Builds
You can also use Audio Insights with standalone builds, either on the same device in the case of Windows builds, or connected over the network for console builds. Using Audio Insights with a standalone build requires you to also use Unreal Insights.
In the Trace menu in the lower right side of the editor window, select Unreal Insights (Session Browser), then exit the editor after Unreal Insights starts.
Alternatively, you can run Unreal Insights from the command line using:
/Engine/Binaries/Win64/UnrealInsights.exe -DisableFramerateThrottleThe extra flag enables Unreal Insights to run at 60fps even when not in focus.
This connects to the currently-running game on the localhost. In the Trace Store, find the trace with LIVE (in red) in the Status column, then double-click it to bring up the trace session window.
In the Menu, select the Audio Insights option.
This opens an Audio Insights window that functions similarly to the window that connects to a PIE session described above.
If you do not specify
audio,audiomixertrace channels when you are connecting, Audio Insights asks you to enable them as the window opens.
Start your standalone game with the
-Messagingflag and connect to it from Unreal Insights by using the Connection tab. Enteraudio,audiomixer(with no space after the comma) in the Initial Channels field, then click Connect.
A standalone instance of Audio Insights does not have the same messaging as when you use it with PIE. The differences are documented below for each tab.
Standalone trace recording summary:
Run
/Engine/Binaries/Win64/UnrealInsights.exe -DisableFramerateThrottleEnter
audio,audiomixerin the Initial Channels field of the Connection tab.Start your game using the command
MyGame.exe -messaging.In Unreal Insights, click Connect.
Go to the Trace Store tab and double-click on the LIVE session.
In the new window's menu, select Audio Insights.
Controlling Trace Recordings in Standalone Mode
When running Audio Insights in standalone mode from Unreal Insights, you need to use the Session Frontend tab to control the recording of your trace file.
To stop or restart the recording, select the current session for your application and click the start/stop tracing button:
Using Audio Insights with a Console Build
You can use Audio Insights with a console build on another networked machine.
Set the following additional command-line arguments for the game executable:
-messaging -tracehost=192.168.1.100 -trace=audio,audiomixerReplace the Tracehost IP address with the address of the computer running Unreal Insights and the Unreal Trace Server. The image below uses an Xbox dev system as an example:
Monitor a Standalone Build Without a Trace File
You can monitor a standalone build on the local host without recording a trace file using Unreal Insights.
In the Connection tab, click Start Unreal Insights:
When the timing window appears, open the Audio Insights window from the menu as before, then start your
game.exewith the-messagingoption. This displays audio information in Audio Insights without saving a file.You can verify this by returning to the Trace Store tab on Unreal Insights and confirming there are no current traces indicated with the red LIVE text.
Monitoring a standalone game is not an option with networked console builds; you must record a trace for networked console builds.
Audio Data Detail Tabs
You can configure the visible tabs using the View menu in the Audio Insights tab:
You can reposition detailed tabs anywhere within the Audio Insights tab or pull them out as free-floating windows. Selecting Reset Layout reverts the tabs to their default positions if your layout gets too scrambled.
Top Level Controls
The top toolbar provides controls for how Audio Insights gathers and maintains data from the audio engine.
| Control | Description |
|---|---|
Start Monitoring/Monitoring | This is a direct trace from Unreal Insights and gathers data from the engine without saving anything to a
|
Start Recording/Recording | This is the live recording option from Unreal Insights, where all trace data is saved in a file, which appears in the Trace Store section of Unreal Insights. When recording, this button is red. To stop recording to a file, click either the Recording or the Monitoring button. Editor only. |
Save a Snapshot | Saves a snapshot of the most recent trace data to a |
Bookmark | Creates an Audio Insights bookmark in the
|
Only trace audio signals during PIE | Audio Insights uses the Unreal Insights tracing capabilities, which can generate a lot of data. If you are only enabling the trace for Audio Insights, clicking this checkbox reduces the data stored as you record and debug your session with Audio Insights. This helps with total system performance and memory usage. Editor only. |
World Filter | This dropdown menu gives you the option to select audio data from the currently-running worlds, including the editor. |
Logs (Editor Only)
The Logs tab is another way to filter and observe Unreal Editor logs next to any pertinent audio information you might be looking at. This data defaults to displaying all audio-specific log categories, but you can change the filters to include or exclude any other log categories and verbosities.
Event Log
The Event Log tab displays a scrollable time-stamped list of audio events as they happen. It also acts as a timeline controller for Audio Insights, in that you can select a specific event from this list and then all other tabs display the instantaneous data for that specific time.
When monitoring a live game, the event log stores data in a circular buffer cache that shows the most recent events. When the user selects an event for inspection while monitoring, the data cache continues to fill until the selected event is near the end of the cache. When using Audio Insights on a pre-recorded trace file, the event log shows all the data in that session.
Event Log User Interface
The top level UI elements of the Event Log tab are how you can control and monitor the event log cache and its contents.
| UI Element | Description |
|---|---|
Add Filter menu | Provides a way for you to select the event types shown. |
Filter text | Displays only the event entries which match the string entered. Asset, Actor, and Play Order columns are compared for this filter. |
Cache restart | When you set the cache to pause at the end, then select an event near the end of the cache, the pause button appears. Clicking it deselects the current event, moves the playhead to the current data, and restarts monitoring. |
Cache size | Shows read-only information about how much of the cache is currently filled, in terms of memory used compared to total capacity, and time duration captured. The time duration value varies depending on the complexity of the audio scenes captured. |
Clear log | Click to empty the log, so you can get a clean start when capturing a scene. |
| Settings Menu | |
Visible Columns | Gives you a way to select the data columns displayed. |
Automatically Stop Caching | Gives you a way to select the behavior of the cache when inspecting an event while monitoring. Options are:
|
Event Log Data
You can select which columns to show by right-clicking on the toolbar, the tab settings, or the editor preferences.
| Column Name | Description |
|---|---|
Cache status | Displays a warning icon if this specific event is close to getting dumped from the cache. |
ID | Shows a unique identifier for each specific event. |
Timestamp | The number of seconds since the session started. |
Play Order | The unique ID given to the audio source in the engine. When you select a specific event, events on the same Play Order (such as stop, virtualize, and similar) are lightly highlighted to indicate the relationship. |
Event | Shows the event type as listed in the Event Types section. |
Actor | The name of the world actor that owns the sound or triggered the event. |
Category | The type of sound source for this specific event. |
Event Types
You can use the Add Filter menu to filter the events by type.
| Event Type | List or Description |
|---|---|
Sound Activity | Playing, Stopped, Paused, Resume |
Virtualization | Virtualized, Realized |
Play Requests | Sound Handle, Audio Component, One Shot, Sound at Location, Play Sound 2D, Slate Sound |
Stop Requests | Stop All, Sound Handle, Audio Component, Active Sound, Sounds using resource, Concurrency (stopped for voice priority) |
Play Errors | Not Playable, Out of Range, Debug filtered, Concurrency (failed to start) |
Messages | Flush Audio Device |
Custom |
Custom Events
You can create custom events in the Editor Preferences. Under Plugins - Audio Insights, expand Custom Event Log categories, then add your custom events. You can call those events using standard trace calls in C++ or Blueprint to have them populate in the Events Log.
To create a Custom Event Log category:
Add a text string for a category.
List the text string for any events that belong to that category.
These events will be classified and filtered according to the designated category.
Any undefined user events will show up in a generic Custom category.
Event Controls
When using Audio Insights with an editor session, double clicking an event in the Events tab opens the asset editor for the event asset. You can also use the right-click context menu for both opening the editor and browsing to the asset.
The Save a Snapshot button on the top menu makes a trace file out of the Unreal Insights data at that moment. This will not be the same data as what you have in the Audio Insights data cache, it will contain other trace data and will capture less gameplay time. This is a known issue to be addressed.
The Events tab shows all the events for a given Audio Device at that time. When you stop Play in Editor (PIE), the audio device might change, which deletes the cached values for the PIE audio device.
To avoid this, in the Level Editor - Miscellaneous > Sound settings, disable Create New Audio Device for Play in Editor. This makes the editor use the same Audio Device as the PIE session, which maintains the events in the Events log after stopping PIE.
Sounds
The Sounds tab displays all the currently-playing sound assets, listed by category, with text displays of runtime data for each. It gives you a way to interact with the playing sounds to mute and solo (isolate) elements of the mix. The sounds are identified using their .uasset names and not the runtime instance name.
Sounds User Interface
The top level UI elements of the Sounds tab are how you can manipulate the sounds playing.
| UI Element | Description |
|---|---|
Mute Filtered | Mutes all currently-filtered sounds as shown by the filter text box. Which sounds are muted updates as you change the text string. Mute filtered mode is indicated by the Mute button turning green. |
Mute Selected | When you select sounds, the Mute button changes to indicate it can Mute Selected. When you click it, it toggles the mute on any sounds selected. This is a toggle control as opposed to the modal control for filtered sounds. |
Solo Filtered | Solos all sounds that are currently filtered to show by the filter text box. The sounds soloed update as you change the text string. If you filter everything, nothing plays. Solo filtered mode is indicated by the Solo button turning green. Solo takes precedence over mute - if you both mute and solo a sound, it is played. |
Solo Selected | If you selected any sounds, the Solo button changes to indicate it can Solo Selected. When you click it, it toggles soloing on any selected sounds. This is a toggle control as opposed to a modal control for filtered sounds. |
Clear All Mutes / Solos | Resets the muted and soloed sounds so that the mix is unaffected. |
Plot Selected | Sends data from the selected sounds to the Plots tab. |
Clear All Plots | Stops sending any sound data to the Plots tab. |
Filter Categories | Shows category buttons in the tab header, providing a method for quick filtering of the sounds listed. The sound filter category options are:
|
Filter Text | Filters the displayed sounds using the text string you enter in the Search window. Any sound or actor name that matches the text is displayed. |
Sounds Data
You can control the visibility of the Sounds data columns by using the right-click context menu on the Sounds toolbar or by using the Settings widget on the right. In addition to the individual columns, you can use the Select All control to select or deselect all the columns at once.
| Column Name | Description |
|---|---|
Muted | Selects and displays if this instance of the sound is muted (editor only). |
Soloed | Selects and displays if this instance of the sound is soloed (editor only). |
Plotted | Selects and displays if this instance of the sound is plotted on the Plots tab. |
Name | Displays the UAsset name of the sound, not the runtime instance name. |
Play Order | Displays the unique ID given to the audio source in the engine. This is the same value used in the Events tab. In aggregated sounds such as a Sound Cue, the underlying wave players have a unique Play Order; this column shows the parent and wave player Play Order values separated by a comma. |
Priority | Set for concurrency, a positive float value with higher numbers indicating greater priority |
Distance | Displays the positive distance from the sound renderer in map units. |
Distance/Occlusion Attenuation | Displays the value of the volume and filtering multiplier applied based on distance and occlusion of a sound, a float value from 0.0 to 1.0, with 1.0 being unattenuated. |
Amp (Peak) | Displays the value of an envelope follower tracking the sound amplitude, a float value from 0.0 to 1.0, with 1.0 being the maximum output amplitude. |
Volume | Displays the product of all volume values and modulators for this instance of the sound, excluding distance attenuation, a positive float value which is a linear amplitude multiplier. |
LPF | Displays the lowest frequency of all low-pass filter controls and modulators for this mixer source, indicating the cutoff frequency in Hertz. |
HPF | Displays the highest frequency of all high-pass filter controls and modulators for this mixer source, indicating the cutoff frequency in Hertz. |
Pitch | Displays the sum of all pitch values and modulators for this instance of the sound, a positive float value as a linear playback rate multiplier. |
Relative Render Cost | Displays a numerical value indicating how many wave-playing resources the specific sound uses. This is useful to see how expensive a Sound Cue or MetaSound is with embedded wave players. |
Actor Label | Displays either the name of the world actor that holds the Audio Component or the actor that triggered the sound. |
Category | Displays a text indication of the sound category listed above. The category icon to the left of the name column is considered part of the name, and is not controlled by this column setting. |
Aggregation
For a hierarchical object such as a Sound Cue that contains several child Sound Waves, the Sound Cue Volume and Pitch will show the top level values. However, the Sound Wave will show the aggregated value of the Sound Cue top level and any other modulations that happen to that Sound Wave within the Sound Cue.
Sounds Settings
The following settings are available when you click the Settings icon on the Sounds tab.
| Sounds Setting | Description |
|---|---|
Amp (Peak) Display Mode | Toggle between decibel (dB) and linear amplitude displays. |
View | Controls the displayed sound hierarchy. Options are:
|
Auto-Expand | Sounds are hierarchically grouped by category first, then by sound source. This controls how the nested sound assets are automatically displayed. Options are:
|
Visible Columns | Select the data columns described above under Sound Data Columns. |
Show Stopped Sounds | When enabled, sounds that recently stopped stay visible in the list grayed out for a short time, making it easier to observe short sounds. |
Recently Stopped Timeout | Determines how many seconds stopped sounds remain visible in the list after they stop. |
Sound Asset Controls
Right-clicking on a selected sound opens the sound context menu, which provides the following options:
Pin a sound to the top of the display.
Browse to the asset in the content browser.
Open up the asset editor from this window.
Plots
The Plots tab displays a line graph of value histories for the sounds selected to plot in the Sounds tab. The plot line colors match the colors displayed in the Plot column of the Sounds tab. Plots display the most recent 5 seconds of value history.
Plot Controls
Parameter selection: Use this pull down menu to select the specific sound parameters from the Sounds tab to display. All selected sounds display the same parameter, differentiated by color.
Amp (Peak)
Volume
Distance
Distance/Occlusion Attenuation
Pitch
Priority
LPF Freq (Hz)
HPF Freq (Hz)
Y Axis Range: You can choose between an automatic range scaled to fit all the data in the window or a custom range with min and max values you select.
Select Time Stamp: When you select a time stamp point on the plot, the Sounds tab displays the data at that time stamp, and the Events tab shows the nearest event to that time stamp.
Bold Sound Tab Selection: If you select a plotting sound in the Sounds tab, its plot is shown thicker than others to help identify the selection.
Virtual Loops
The Virtual Loops tab displays a list of all Active Sounds currently tracked by the renderer but not producing samples for the mixer due to concurrency or distance attenuation factors.
Virtual Loops Data
The data shown on the Virtual Loops tab. You can select which data is displayed using the Virtual Loop Controls.
| Data | Description |
|---|---|
Play Order | Shows the unique ID given to the audio source in the engine. This is the same value used in the Events tab. |
Name | Shows the .uasset name for the virtualized mixer source. |
Time (Virtualized) | Shows the time in seconds since this sound last sourced samples for the mixer. |
Time (Total) | Shows the total playing time in seconds for this sound, both virtually and not. |
Update Interval | Shows the time in seconds between position or concurrency updates that determine if this sound remains virtual. This value varies with distance from the renderer. |
Virtual Loops Controls
Browse: Click to show the selected asset in the Content Browser (editor only).
Open: Click to open the asset editor for the selected asset (editor only).
Data Filter: Right-click on the list header bar to open a context menu you can use to select which audio data values are shown for each mixer source.
Edit Asset: Double-click on a mixer source in the list display to open the asset editor with that asset (editor only).
Selection:
Single-click: Selects a virtual loop and draws a debug sphere at its location.
Shift-click: Multi-selects virtual loops and draws a debug sphere for each one selected at each location.
Control-click: Adds a virtual loop to a multi-selection and draws a debug sphere at its location.
De-selection: Control-click a selected virtual loop to de-select it and remove its debug sphere.
Debug String: In the editor, selected assets in this list show a debug string at the location of a virtualized sound.
Submixes
The Submixes tab lists all the Sound Submixes in the current project, and indicates which ones are sending active signals at the moment. You can select a set of submixes to display signal levels in the Audio Meters tab.
Submixes Data
| Data | Description |
|---|---|
Active | A dot in this column indicates an active signal on that submix. |
Select | An enabled checkbox in this column indicates the submix levels show visually on meters in the Audio Meters tab. You need to manually open the Audio Meters tab if it is not visible in your current configuration. |
Name | Shows the Sound Submix asset name. |
Submixes Controls
You can double-click a submix in the list to open the asset editor for that asset (editor only).
To reduce data storage and unnecessary computations, only submixes with enabled checkboxes send data for Audio Insights to process. When using Audio Insights with Unreal Insights to read a trace file, selecting a specific submix for the meter tab is disabled, but the enabled checkboxes do show what submixes were recorded with meterable data. If you want to inspect a specific submix in a trace file, make sure you select it to be metered when you are recording that trace.
Audio Buses
The Audio Buses tab lists all the audio buses in the current project, and indicates which ones are sending active signals at the moment. You can select a set of audio buses to display signal levels in the Audio Meters tab.
Audio Buses Data
| Data | Description |
|---|---|
Active | A dot in this column indicates an active signal on that audio bus. |
Select | An enabled checkbox in this column indicates the audio bus levels show visually on meters in the Audio Meters tab. You need to manually open the Audio Meters tab if it is not visible in your current configuration. |
Name | Shows the Audio Bus asset name. |
Audio Buses Controls
The Type Filter gives you the options to display Audio Bus assets, code-generated audio buses, or both.
You can double-click an audio bus in the list to open the asset editor for that asset (editor only).
To reduce data storage and unnecessary computations, only audio buses with enabled checkboxes send data for Audio Insights to process. When using Audio Insights with Unreal Insights to read a trace file, selecting a specific audio bus for the meter tab is disabled, but the enabled checkboxes do show what audio buses were recorded with meterable data. If you want to inspect a specific audio bus in a trace file, make sure you select it to be metered when you are recording that trace.
Audio Meters
The Audio Meters tab shows metered visualizations of both the submixes (green text) and the audio buses (blue text) selected on the respective tabs. The metered amplitude uses a logarithmic dB scale. Each channel in a bus configuration is represented with a separate meter in canonical speaker orders. The tab window scrolls to accommodate all the selected submixes and buses. There are no controls for this tab.
Analyzers
The Analyzers tab is a series of six real-time visualizations of the engine’s main audio output, some of which are only available in the editor. Select the visualizations from the options menu on the upper right of the tab. The analyzer options are:
Loudness
The Loudness analyzer is only available in the editor. It displays the main output loudness measurements in LUFS values. This is measured over three different window lengths of audio data:
Momentary: 400 ms
Short Term: 3 seconds
Long Term: Up to 60 seconds
When enabled, the Time option gives you a way to see the running window of time used for Long Term and the reset button next to it provides a way for you to restart the time.
The loudness measurements use ITU-R BS.1770 standard for perceptual weighting.
The Settings menu provides the opportunity to view each of the different Loudness measurements in either or both meter or numerical values.
Meter
The Meter displays the main output RMS amplitude in a logarithmic dB scale. The number of channels matches the channel configuration of the audio device. There are no additional controls for this analyzer.
Oscilloscope
The Oscilloscope is only available in the editor. It displays a time domain sample amplitude plot of the most recent 0.5 seconds of audio coming from the main audio output. The scale is a linear float from -1.0 to a max of 1.0. There are no additional controls for this analyzer.
Vectorscope
The Vectorscope is only available in the editor. It displays a linear time domain amplitude of the left channel on the horizontal axis against the right channel on the vertical axis. This is good for observing phase relationships and channel coherence. There are no additional controls for this analyzer.
Spectrogram
The Spectrogram is only available in the editor. It displays a frequency domain plot of the most recent audio output mixed into a mono channel. Time is on the horizontal axis and audio frequency is on the vertical. Each vertical line in the plot represents a single timed window of audio and the color of the pixel represents the power of the audio signal at that frequency. There are several controls for the plot, selected by right clicking anywhere on the analyzer:
| Spectrogram Control | Description |
|---|---|
| Analyzer Settings | |
Analyzer Type | You can choose between two options for how to represent the audio signal in the frequency domain. Options are:
|
FFT Size | Controls the number of audio samples used in each windowed transformation. A larger size gives greater frequency resolution, at the trade off of lower time resolution. |
| Display Options | |
Pixel Plot Mode | You can choose how the samples are weighted to display signal strength. You can use this to emphasize transient frequencies or not. Options are:
|
Frequency Scale | You can choose the scale to see different details in the spectrum. Options are:
|
Color Map | You can choose what color represents a greater signal strength. Options are:
|
Orientation | Choose between a horizontal orientation (pictured above) or a vertical orientation, which swaps the axes so time is vertical and frequency is horizontal. |
Spectrum Analyzer
The Spectrum Analyzer is only available in the editor. It displays an instantaneous frequency domain plot of the main output mixed into a mono channel with audio frequency on the horizontal axis and signal strength on the vertical axis. Moving the mouse to a specific frequency will display the signal strength at that band of the spectrum. There are several display options for this analyzer.
| Spectrum Analyzer Control | Description |
|---|---|
| Analyzer Settings | |
Ballistics | You can choose between Analog or Digital, which simulates the signal persistence between audio windows to have the appearance of analog or digital professional audio meters. This determines how smooth (analog) or precise (digital) the transition between frames can be. |
Analyzer Type | You can choose between two options for how to represent the audio signal in the frequency domain. Options are:
|
FFT Size | Controls the number of audio samples used in each windowed transformation. A larger size gives greater frequency resolution, at the trade off of lower time resolution. |
| Display Options | |
Tilt Spectrum | You can attenuate each frequency to flatten out the graph of a spectrum weighted on the lower frequencies. |
Pixel Plot Mode | You can choose how the samples are weighted to display signal strength. You can use this to emphasize transient frequencies or not. Options are:
|
Frequency Scale | You can choose the scale to see different details in the spectrum. Options are:
|
Display Frequency Axis Labels | When enabled, labels the horizontal graph grid lines with numerical values in Hertz. |
Display Sound Level Axis Labels | When enabled, labels the vertical graph grid lines with numerical values in decibels. |
Control Buses (Editor Only)
The Audio Modulation plugin gives you the means to create control buses that can modify pitch, volume, filter, and other values for audio sources and submixes. For Audio Modulation data to show up in Audio Insights, you must also enable the Audio Modulation Insights plugin.
The Control Bus tab displays the current numerical value for each active control bus, formatted as a float value between 0.0 and 1.0. The pitch, volume, and filter values seen on the Sources and Sounds tabs reflect the influence of the control buses displayed here.
There are no additional display or control options on this tab.
Modulation Matrix (Editor Only)
Control buses in the Audio Modulation plugin can be added together to create cumulative effects. The Modulation Matrix tab gives insight into the different buses currently active and how they are collaborating to affect audio sources.
There are no additional display or control options on this tab.