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 StartRecording
, StopRecording
and CleanStorage
methods encapsulate the Session Recorder functionality and invoke the events events OnStartRecording
, OnStopRecording
, 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 In addition, request 1
|
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 |
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 At runtime, use the MLPermissions API to request recording permission. 1
|
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 ifRecordingSource
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.