Audio Insights

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:

1. In the main menu, select Tools > Audio Insights.

2. Confirm Monitoring is active (shows a green icon).

   1. If necessary, click Start Monitoring.

3. 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. 

1. 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.

   

   1. Alternatively, you can run Unreal Insights from the command line using:

      /Engine/Binaries/Win64/UnrealInsights.exe -DisableFramerateThrottle

      The extra flag enables Unreal Insights to run at 60fps even when not in focus.

2. 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.

   

3. In the Menu, select the Audio Insights option.

   

4. This opens an Audio Insights window that functions similarly to the window that connects to a PIE session described above.

   1. If you do not specify audio,audiomixer trace channels when you are connecting, Audio Insights asks you to enable them as the window opens.

5. Start your standalone game with the -Messaging flag and connect to it from Unreal Insights by using the Connection tab. Enter audio,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:

1. Run /Engine/Binaries/Win64/UnrealInsights.exe -DisableFramerateThrottle

2. Enter audio,audiomixer in the Initial Channels field of the Connection tab.

3. Start your game using the command MyGame.exe -messaging.

4. In Unreal Insights, click Connect.

5. Go to the Trace Store tab and double-click on the LIVE session.

6. 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,audiomixer

• Replace 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. 

1. In the Connection tab, click Start Unreal Insights:

   

2. When the timing window appears, open the Audio Insights window from the menu as before, then start your game.exe with the -messaging option. This displays audio information in Audio Insights without saving a file.

3. 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.

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 .utrace file. This mode is useful to view data for long periods of time without creating large log files. This defaults to on, shown in green, but you can turn it off if you want to stop collecting data. Editor only.
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 .utrace file. By default, snapshots are limited to 32MB in the editor and 4MB in standalone. You can access them in the Unreal Insights Trace Store. To specify a custom snapshot size (in MB) launch the editor executable with the -tracetailmb=<size> option. This works in either Monitor or Recording modes and is available in both editor and standalone versions of Audio Insights.
Bookmark	Creates an Audio Insights bookmark in the .utrace file generated by Save Snapshot or Trace at the timestamp the button was pressed. You can also place a bookmark using Ctrl+M.
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.

Event Log Data

You can select which columns to show by right-clicking on the toolbar, the tab settings, or the editor preferences.

Event Types

You can use the Add Filter menu to filter the events by type.

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 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.

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.

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.

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.

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

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

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

• Meter

• Oscilloscope

• Vectorscope

• Spectrogram

• Spectrum Analyzer

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:

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.

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.