Introduction

Unreal Engine version 5.1 is recommended for OMS playback, however we offer plugins for versions 4.27, 5.0, 5.1 and 5.2.

Note

This is the reference documentation for the Unreal HoloSuite Player Plugin.

For a step by step guide to setting up a HoloSuite Player in Unreal Engine, refer to the Player Configuration example document.

Overview

../_images/ue5-playback.png

The Unreal HoloSuite Player can be used to playback compressed Volumetric Video created in HoloEdit. It supports both OMS and AVV file codecs. To learn more about each codec, please check out the HoloEdit Export Output Types section. The Plugin package contains C++ classes, Blueprint functions and Material functions.

File Support

With the HoloSuite Player plugin installed, both .oms and .avv files added to your project are automatically detected as OMS and AVV files, respectively. The plugin supports both .mp4 media files and image sequences as texture input for OMS playback.

Volumetric video playback is done through the HoloSuitePlayer actor class, which leverages regular UE materials using a custom Material Function for rendering, and follows the Media Framework (External Link) for OMS texture playback.

Build Targets

The Unreal HoloSuite Player can be built for Windows 10 and Android.

Installation

The HoloSuite Player Install Directory contains all Unreal Engine plugins in the appropriate subfolder.

To Install the HoloSuite Player plugin:

  1. Locate the zip file for the desired engine version, this will be found in the plugins folder of your HoloSuite installation, found at ‘C:\Program Files (x86)\HoloSuite\HoloEdit (Version Number)\Plugins’ when following default installation.

  2. Unzip the contents of the zip file into a folder called HoloSuitePlayer.

  3. Move the HoloSuitePlayer folder into your Unreal Engine Plugins/Marketplace folder (if the Marketplace subfolder does not already exist, you can create the folder yourself).

To enable the HoloSuite Player plugin once added to the engine:

  1. Create a new project in Unreal.

  2. From the main Unreal Engine interface, click on Settings in the top menu, and select Plugins.

  3. In the Plugin editor, search for “HoloSuite” - a HoloSuite Player item will be visible.

  4. Check ‘Enabled’.

  5. For Unreal Engine 5.0 and above, you will also need to search for and enable the “Electra” video player plugin(s) if you intend to playback OMS files.

  6. Once the plugins are enabled, click the “Restart Now” button in the bottom right of the window.

When the Editor opens again, you’ll be ready to start configuring the HoloSuite Player.

If you experience any issues, see the Plugins page on the Unreal Engine Documentation (External Link) for more information on installing plugins in Unreal Engine.

Upgrading the HoloSuite Player Plugin to a Newer Version

When updating the Unreal HoloSuite Player plugin you should first delete the existing plugin from the Plugins/Marketplace folder, then copy the new plugin into the folder. Overwriting the existing plugin instead of deleting it first can result in the plugin compiling incorrectly.

Warning

HoloSuitePlayer version 4.0.0 does not have backwards compatibility, meaning you will have to recreate existing HoloSuite scene actors (previously called OMSMeshActors) with the new player tools.

With the new player actor, HoloSuitePlayer, users can now leverage both OMS and AVV codecs and enjoy several features that were previously unavailable.

Getting Started

Note

This is a step by step guide to setting up AVV and OMS playback in Unreal.

For the reference documentation for the Unreal HoloSuite Player Plugin, refer to the Player Reference Documentation.

Warning

There are specific HoloSuite player requirements when building Virtual Reality projects or using features such as HoloSuite’s retargeting or Unreal’s Sequencer.

Please refer to the HoloSuite Player Requirements for VR document to learn how to prepare a HoloSuite player for VR-projects, or checkout HoloSuite playback with retargeting and HoloSuite playback using Sequencer for non-standard setups.

OMS Playback

With the HoloSuite Player for Unreal successfully installed, you’re ready to create a player to use in your project.

In order for players to work in standalone builds, Unreal requires a subfolder named ‘Movies’ for all .mp4 files. Create a Movies folder in the project window and import your MP4 file(s) into it. Create another folder, this time with any valid name you choose, and import your OMS file(s) into it.

../_images/hsp-4.0.0-ue5-holosuiteplayer-place-actor.png

After adding your OMS and MP4 files, you’ll be able to create a HoloSuitePlayer actor in your scene. The quick and easy way to do this is by simply dragging and dropping the imported OMS asset into the scene. This will automatically create a HoloSuitePlayer instance and assign the OMS file as its source. You can select the actor instance in the “World Outliner” and configure it in the “Details” tab. Assign the texture source of the actor and the remaining source parameters will be automatically populated for you.

If you wish to configure an actor from scratch, you can still do so manually. Use the search bar in the “Place Actors” tab to locate HoloSuitePlayer actor and click and drag it into your scene to create a new HoloSuitePlayer instance. Once you create the new HoloSuitePlayer instance, select it in the “World Outliner” and assign the source OMS and texture files.

Your HoloSuite player needs a Mesh Material, which requires a specific node, ArcturusOMS or ArcturusAVV (see Material Functions for further details), to drive the OMS playback and allow any custom shading you need for your project. You can right-click on any of your imported OMS files and choose to create a lit or unlit Mesh Material from it. Alternatively, you can search for the default HoloSuite materials that come with the plugin.

If you’re configuring the player manually, you will also need to create additional assets, namely:

  • A Media Player Asset: This asset takes the provided MP4 textures and allows for playback of the texture and mesh animation.

  • A Media Texture Asset: This asset provides the Media Player with the MP4 or texture sequence required to provide texture and OMS playback.

  • A Media Player Material: You will need to create a material that uses the ‘Texture Sample’ node to playback the information provided by the Media Player Asset in order to apply the textures to your OMS’s meshes.

Go ahead and create the assets:

  1. Media Player: Double-click on this asset after creating it, and ensure that ‘Play on Open’ and ‘Loop’ are enabled.

  2. Media Texture: Double-click on this asset after creating it, and set the Media Player parameter to the new MediaPlayer asset that you just created above.

  3. Media Player Material: Create a regular Material, open in the Material Editor, add a Texture Sample node and from it:

  • Connect the RGBA output into the Emissive input of the TextureMaterial Result Node.

  • In the Texture Sample details, this node’s Texture should be set to the Media Texture you created above.

../_images/hsp-4.0.0-ue5-holosuiteplayer-oms-properties-configured.png

Assign these 3 new assets to the corresponding parameters of your HoloSuitePlayer actor. Save and compile changes to complete your configuration. To preview the OMS playback select ‘Play’ from the Viewport toolbar.

AVV Playback

AVV playback is similar to OMS. First of all, you need to import your AVV files into any folder inside the “Content” directory. The UE Editor will automatically detect a new supported file has been added to the project and you can import the file then, similar to OMS. As the AVV codec encodes texture data in it, there’s no need for a “Movies” folder or any separate texture source files.

To create a HoloSuitePlayer actor in your scene, you may use the automatic approach of dragging and dropping the imported AVV asset into the scene, which will automatically create a HoloSuitePlayer instance and assign the AVV file as its source. You can select the actor instance in the “World Outliner” and configure it in the “Details” panel. You’ll notice that a Mesh Material will have already been assigned for you, but you may wish to create a custom one yourself. This time, the Mesh Material requires a different node, ArcturusAVV, to drive the AVV playback and allow any custom shading you need for your project. Alternatively, you can search for the default HoloSuite materials that come with the plugin. Configuring a HoloSuitePlayer actor from scratch for AVV playback is also possible, following similar steps to the manual configuration for OMS playback.

../_images/hsp-4.0.0-ue5-holosuiteplayer-avv-properties-configured.png

Save and compile changes to complete your configuration. To preview the AVV playback select ‘Play’ from the Viewport toolbar.