setup-guide.md

Setup Guide

Through this guide, you will be introduced to the basic steps for setting up the playback.

Import Package

First, extract the SDK from the .zip file, copy the HISPlayer folder and paste into the Plugins/ directory in your project’s root (If that directory doesn’t exist, create one).

Then, go into the HISPlayer directory and open the HISPlayer.uplugin file. You need to check that the Engine Version in this file matches the Unreal Engine version of your project.

⚠ Don’t worry about the full version number. The Engine Version field only cares about the major and minor version numbers. Ignore the patch number.

Example:

1. Suppose your project uses Unreal Engine 5.5.4.
2. Open HISPlayer.uplugin.
3. Locate the field "Engine Version".
4. Enter only the major and minor numbers: 5.5.0.
   • ✅ Correct: 5.5.0
   • ❌ Incorrect: 5.5.4 (the patch number .4 will be ignored anyway)

This ensures that HISPlayer is recognized as compatible with your Unreal Engine project.

If you are unsure, always use X.Y.0 where X is the major version and Y is the minor version of your Unreal Engine.

Open your project and go into Edit > Plugins, look for the HISPlayer plugin and if it’s disabled, enable it and restart the project.

Set Default Build Settings Version

It is preferable to use the HISPlayer SDK in a C++ project, rather than in an only blueprint one. To create a C++ project from an only blueprint project, go to Tools > New C++ Class and follow the indications to create a new one. Any kind of C++ parent class will work.

Make sure that the YourProjectName.Target.cs and YourProjectNameEditor.Target.cs scripts located in the Source directory have the following setup:

public class HISPlayerSampleTarget : TargetRules
{
	public HISPlayerSampleTarget(TargetInfo Target) : base(Target)
	{
#if UE_5_7_OR_LATER
		Type = TargetType.Game;
		DefaultBuildSettings = BuildSettingsVersion.V6;
		IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_7;
		ExtraModuleNames.Add("HISPlayerSample");
#elif UE_5_4_OR_LATER
		Type = TargetType.Game;
		DefaultBuildSettings = BuildSettingsVersion.V5;
		IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_4;
		ExtraModuleNames.Add("HISPlayerSample");
#else
		Type = TargetType.Game;
        DefaultBuildSettings = BuildSettingsVersion.V2;
        ExtraModuleNames.AddRange(new string[] { "HISPlayerSample" });
#endif
    }
}

public class HISPlayerSampleEditorTarget : TargetRules
{
	public HISPlayerSampleEditorTarget(TargetInfo Target) : base(Target)
	{
#if UE_5_7_OR_LATER
		Type = TargetType.Editor;
		DefaultBuildSettings = BuildSettingsVersion.V6;
		IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_7;
		ExtraModuleNames.Add("HISPlayerSample");
#elif UE_5_4_OR_LATER
		Type = TargetType.Editor;
		DefaultBuildSettings = BuildSettingsVersion.V5;
		IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_4;
		ExtraModuleNames.Add("HISPlayerSample");
#else
		Type = TargetType.Editor;
        DefaultBuildSettings = BuildSettingsVersion.V2;
        ExtraModuleNames.AddRange(new string[] { "HISPlayerSample" });
#endif
    }
}

Import BP_HISPlayer

To use HISPlayer’s functionalities in your Level, you need to add the BP_HISPlayer. The is located inside Content Browser > HISPlayer Content > Blueprint.

If you can’t find the HISPlayer Content directory in the Content Browser, check “Show Plugin Content” in “View Options”.

Add the BP_HISPlayer.

To render the content, you need to set an actor with M_HISPlayerMat as Material.

Configure HISPlayer multistream properties

Set the player’s parameters as desired in your BP_HISPlayer actor for single stream and multistream. It is possible to add more than one stream using one instance of the BP_HISPlayer, by adding more elements to the Stream URL and Target Actors arrays.

You can modify the behavior of the BP_HISPlayer as desired or use a custom blueprint, as long as it follows the original structure.

Use the HISPlayer API to add your own implementation.

License Key

Input the license key that is associated with the SDK. If the license key is not valid, the player won’t work and will throw an error message.

To find this field, go to the Level Outliner and look for the BP_HISPlayer actor. Then, in the Details window, locate the HISPlayer section.

Note: If you are using the FAB marketplace package, entering a license key is not required.

Disable Anti-Aliasing

If you are experiencing a ghosting effect on the stream, then you will need to disable the anti-aliasing effect on your project. To do that on Unreal 5, go to Edit > Project Settings > Engine > Rendering > Default Settings > Anti-Aliasing Method and set it to None.

Default RHIs

Make sure that the Default RHIs option is settled to DirectX11 or DirectX12. Otherwise, go to Edit > Project Settings > Platforms > Windows > Targeted RHIs.

Packaging the project

In order to package the project, you need to make sure that Your_Project.uproject file has been correctly updated on the “Plugins” field:

You can update this file manually, or by clicking on the Update button when this message appears when opening the project with the plugin installed.

Depending on the Unreal version, it is also possible that you need to generate a visual studio project, if you are working on a Blueprint project.

Finally, after packaging the project, you will need to create a new folder called Plugins inside Your_BuildRootDirectory > Your_ProjectName folder, and paste there the HISPlayer folder plugin (similar to the Import Package step)

Setting up PCM Audio Data

It is possible to retrieve the PCM data of a stream at runtime. To start the retrieval process, call the HISPlayer Start PCM Data Process function. To stop the process, call the HISPlayer Stop PCM Data Process. It is important to stop the process before releasing the player.

Every time new PCM data is being received, it is possible to get it in a TArray<float> format, along with the stream's timestamp, by using the On PCM Data Received Event.

Getting the PCM data of a stream is computationally expensive, so its recomended to use it only on a single stream, event though this functionality is compatible with multistream.

Updating the SDK

To update a HISPlayer SDK of a previous version, please follow these steps:

• Go to your Root project folder > Plugins and delete the HISPlayer folder.
• Paste your new HISPlayer SDK folder inside the Plugins folder.
• Go again to your Root project folder and delete the Binaries and Intermediate folders.
• Execute Your_Project.uproject file.

Make sure that your project is closed while doing this process.