Table of Contents

Recording EIF files in Unity

This article introduces how to record EIF files in Unity for simulation runs.

Before starting

Starting recording

Use FrameRecorder.enabled = true to start recording, for example:

if (Session.State >= ARSession.SessionState.Ready && Session.Assembly.FrameRecorder.OnSome)
{
    var frameRecorder = Session.Assembly.FrameRecorder.Value;
    frameRecorder.enabled = true;
}

Note that you need to check whether ARAssembly.FrameRecorder exists first.

Note

ARAssembly.FrameRecorder cannot be used in some cases, such as when using FramePlayer.

FrameRecorder.enabled defaults to false, meaning recording is off. Manually configuring it in the editor is also ineffective.

Recording starts during session runtime when FrameRecorder.Status >= FrameRecorder.RecorderStatus.Ready.

If FrameRecorder.Status < FrameRecorder.RecorderStatus.Ready, you can use the OnReady event to wait for recording to be ready.

Session.GetComponent<FrameRecorder>().OnReady.AddListener(() => {
    // Can start recording
});

You can use the OnRecording event to confirm successful startup:

frameRecorder.OnRecording.AddListener((file) =>
{
    Debug.Log($"Recording started: {file}");
});

There is no event triggered for startup failure, but you can check if FrameRecorder.Status is Error to confirm.

Important

The runtime effect when playing EIF in a scene depends on the device used for recording and the frame source selected at that time. Therefore, when recording EIF files, it is recommended to use the same or similar device as the target device to ensure consistent playback effects. Special attention should be paid to whether motion tracking is enabled during recording. If motion tracking is not enabled during recording, it cannot be enabled during playback, and AR features relying on motion tracking (such as dense spatial mapping, Mega, etc.) will not work consistently with the device.

Stopping recording

Use FrameRecorder.enabled = false to stop recording, for example:

frameRecorder.enabled = false;

This operation immediately stops recording and blocks until the file is written.

Important

You must call stop recording, otherwise the recording file will be incomplete, causing some features or the entire file to be unusable:

  • When the recording format is H264, the EIF file cannot jump to a specified time point for playback (seek), and can only be played from the beginning
  • When the recording format is Obsolete, the EIF file cannot be used

File storage and export

You can use the OnRecording event to get the full real path of the recording file:

frameRecorder.OnRecording.AddListener((file) =>
{
    Debug.Log($"Recording started: {file}");
});

By default, the recording file is stored in the application's persistent data path, which can be accessed via Application.persistentDataPath.

You can modify the storage path of the recording file via FrameRecorder.Configuration.FilePath. This path must be set before starting recording and requires AutoFilePath to be turned off. The directory must be created in advance.

Important

You must ensure that the storage directory exists and the application has write permission, otherwise the recording will fail to start.

For example, the following code shows how to store recording files in a custom directory and generate filenames based on the FrameSource type used by the session and the current time:

if (!Directory.Exists(SavePath))
{
    Directory.CreateDirectory(SavePath);
}
var frameRecorder = Session.Assembly.FrameRecorder.Value;
frameRecorder.Configuration.AutoFilePath = false;
frameRecorder.Configuration.FilePath.Type = WritablePathType.Absolute;
frameRecorder.Configuration.FilePath.FolderPath = SavePath;
frameRecorder.Configuration.FilePath.FileName = ARSessionFactory.DefaultName(Session.Assembly.FrameSource.GetType()).Replace(" ", "") + DateTime.Now.ToString("_yyyy-MM-dd_HH-mm-ss.fff");

frameRecorder.enabled = true;

You can also do this in the editor by selecting AR Session (EasyAR), unchecking Auto File Path in the Inspector window, and then configuring:

alt text

Tip

You can modify the storage directory and filename (without extension) via FrameRecorder.RecordingConfiguration.FilePath. The file extension is automatically added based on the recording format.

  • When the recording format is H264, the file extension is .mkveif
  • When the recording format is Obsolete, the file extension is .eif

If the file is stored in the application's persistent data path or other private paths, you can export it to your computer in the following ways:

  • On Android, connect to the computer via USB and use adb pull or other methods to export the file. Files are usually under /sdcarad/Android/data/<app package name>/files.
  • On iOS, export the file via Xcode's Devices window, or access the app's private directory via iTunes or Finder file sharing.
  • Use code to store the file in a public directory, such as Android's download directory or iOS's photo album.
Note

For iOS apps, if you want to access the app's private directory via iTunes or Finder file sharing, you need to add the UIFileSharingEnabled key to the Info.plist in the XCode project before packaging and set its value to YES:

alt text

The text displayed after adding may differ from the added string, which is normal.

Changing recording format

Change the recording format via FrameRecorder.Configuration.Format. This must be set before starting recording.

For example, the following code shows how to force the recording format to H264:

frameRecorder.Configuration.Format = FrameRecorder.InternalFormat.H264;

You can also do this in the editor by selecting AR Session (EasyAR), and modifying Format in the Inspector window:

alt text

Note

H264 is unavailable on some devices (e.g., Windows). Generally, Auto is recommended, which automatically selects the appropriate format based on the device.

Note

On XREAL, recording data in Obsolete format cannot be used for simulation runs and is only for reporting issues.

  • For simulation runs, use data recorded in H264 format.
  • For reporting issues, use data recorded in Obsolete format.

You can use RecordingFormat to view the current recording format.

Auto-recording when session starts

Set AutoStart to true before starting the session to start recording when the session starts, for example:

frameRecorder.AutoStart = true;

You can also do this in the editor by selecting AR Session (EasyAR), and checking Auto Start in the Inspector window:

alt text

Note

Modifying FrameRecorder.enabled in the editor is ineffective.

Data usable by Mega

When using Mega, there are special requirements for EIF and related file content. Older versions of the Unity plugin did not integrate these features, so data recorded with those versions cannot be used with Mega.

The following cases can be used with Mega:

  • Data recorded with Unity plugin 4000 or higher
  • Data recorded with Mega Toolbox
  • If the data is recorded in Obsolete format, such as file x.eif, the x.eif.json file must exist in the same directory to be used

The following cases cannot be used with Mega:

  • Data recorded with Unity plugin 4.6 or lower
  • Data recorded with native EasyAR Sense without adding the same content as in the Unity plugin

Additionally, although Mega can work without motion tracking, the running effects are different. It is recommended to enable motion tracking when recording EIF files to ensure playback effects meet most usage scenarios.

Next steps