Session Recorder Unity API

The Session Recorder allows you to record data from system devices (e.g., camera and sensors) and tracking data (e.g., the device position or pose). The recorded data can be played back using the File Driver either on device or in Unity Play Mode in order to recreate a Vuforia session offline. In some instances, it may also be useful to share the recording with the Vuforia team to aid in reproducing a reported issue.

Prerequisites

Supported cameras

Devices with cameras that capture frames in the following pixel formats are supported:

  • NV21
  • NV12
  • YUV420P
  • YV12

NOTE: It is required that the device contains a hardware-accelerated H.264 video encoder which supports encoding images in the pixel format delivered by the camera.

Record sessions in one view orientation

Record a session only in one view (display) orientation (portrait or landscape) and make sure to set the orientation before starting the Vuforia Engine. If the view orientation is not known, startRecording() will not start a recording and return error code UNKNOWN_ORIENTATION. If the orientation is changed during an ongoing recording, the recording will be stopped, and the status info will be set to ERROR_ORIENTATION_CHANGED.

Make a Session Recording

The SessionRecorder is a Singleton accessible from VuforiaBehaviour.Instance.SessionRecorder. Through this class, it is possible to access all the features below.

Session Recorder Behaviour

The SessionRecorderBehaviour provides basic state and error management for the Session Recorder.

The StartRecordingStopRecording and CleanStorage methods encapsulate the Session Recorder functionality and invoke the events events OnStartRecordingOnStopRecording, and OnStorageCleaned after executing the corresponding SessionRecorder methods.

All the other methods from the Session Recorder are also exposed in the Session Recorder Behaviour component in the Unity Editor Inspector panel.

Additional recording configurations options

The recording quality can be set to a lower setting if longer Session Recordings captured on less powerful devices are needed. This is useful for reducing the storage requirements of longer recordings. The options are:

  • HIGH – record with minimal compression artifacts.
  • MEDIUM – record for general purpose recordings with video encoding allowing for longer captures without resulting in too large a file. The recording may not be suitable for playback with AR tracking.

Set the encoding quality before starting the recording with RecordingVideoEncodingQuality.HIGH for high quality or MEDIUM for general purpose and longer session recordings.

Starting and stopping a recording

SessionRecorder.StartRecording starts recording a Vuforia Session and returns a RecordingStartError enum. If the recording started successfully, StartRecording returns RecordingStartError.NONE. Please refer to the reference library for a list of recording error & status codes.

The StartRecording method accepts additional bool input parameters that determines whether the SessionRecorder should also record data from the device’s sensors or audio from the device’s microphone. Sensor recording is enabled by default.

A recording can be stopped by calling SessionRecorder.StopRecording. When a recording is stopped or there are no recordings in progress, the status is RecordingStatus.STOPPED.

Querying the recording status

At any time, it is possible to query the state of the SessionRecorder by calling the method SessionRecorder.GetRecordingStatus.

Querying the location of a recording

It is possible to retrieve the path of the file created by the last recorder session by calling the method SessionRecorder.GetRecordingPath. If called while a recording is in progress, it will return the path of the current recording.

Removing a recording instance

Calling the method SessionRecorder.Clean deletes all the existing recorded session. If called while a recording is in progress, the method will return false and will have no effect.

Permissions

In order to support audio recording capabilities in the Session Recorder, your app must fulfill audio-related, platform-specific permission and configuration requirements. Set the permission in the Project Settings -> Player and request the permission from the user at runtime.

Android

Add the "android.permission.RECORD_AUDIO" permission to the AndroidManifest.xml. You can do this by overriding the Android App Manifest.

In addition, request "Microphone" permission at runtime using Unity’s API:

1
Copy
RequestUserPermission(string permission);

iOS

Add a description to the field Microphone Usage Description * in the Player -> Other Settings explaining why your app requires microphone access, otherwise the app will be rejected by the App Store submission process.

At runtime, use Unity’s API to request access to the microphone on the iOS device:

1
Copy
RequestUserAuthorization(UserAuthorization mode);

UWP

Add to Project Settings -> Player -> Publishing Settings -> Capabilities the following: VideoCapture (when capturing audio).

Other optional capabilities: DictationRecognizer, GrammarRecognizer, and KeywordRecognizer.

Lumin

Enable the "android.permission.RECORD_AUDIO" under Project Settings -> Magic Leap -> Manifest Settings.

At runtime, use the MLPermissions API to request recording permission.

1
Copy
RequestPermission( string permission, Callbacks callbacks);

If the aforementioned platform-specific permission and configuration requirements are not fulfilled by the app, then:

  • The RecordingSource call won't report audio support (i.e., AUDIO will be missing).
  • The SessionRecorder.StartRecording call will fail with DATA_FLAGS_NOT_SUPPORTED if RecordingSource is configured to record audio.

Querying available sources

SessionRecorder.GetSupportedSources returns the data sources that can be recorded on the current device. Use SessionRecorder.GetDefaultSources to get the sources that are recommended for recording on the current device. Using the recommended set of sources will always result in a recording that can be used for AR sequence playback.

Output Format

Each Session Recording is saved to an MP4 file in the private storage space of the app. The file name has the form VuforiaSession-[DATE]-[TIME].mp4, where [DATE] has the form YYYYMMDD (year, month, day) and [TIME] has the form HHMMSS (hour, minute, second). The MP4 file contains the recorded video and the captured tracking data (sensors, poses, etc.) in separate tracks.
Most generic video playback applications can be used to view the recorded video. However, it is not possible to access the recorded tracking data using these applications.

NOTE: If the MP4 file is modified by any third-party tool (e.g., video editor, converter, or similar) it will become unusable for offline playback with Vuforia.

Can this page be better?
Share your feedback via our issue tracker