This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.
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
This article describes how to record sessions using the Session Recorder API. See Recording and Playback for an introduction into this feature and how to use it in Unity.
Recording specifications
The recording frame rate is set to 30 frames per second (fps). In addition, if the camera resolution is above Standard HD (720p), the image scale is halved. The 720p @ 30 fps combination has been confirmed to provide a smooth recording experience across a number of (old and new) devices.
Supported cameras
Currently devices with cameras that capture frames in the following pixel formats are supported:
- NV21
- NV12
- Luminance-only (Grayscale)
Please note that NV12 is internally converted to NV21 before being saved (for the difference between these two pixel formats, see the wiki.videolan.org).
Some Android devices provide camera frames is other formats e.g. YUV420P and YV12, these are not currently supported for recording.
Recordings can be performed only in landscape mode
If the display orientation is not in landscape mode, SessionRecorder will refuse to start a recording and return an OrientationNotSupported exit status. If the display orientation is changed to portrait mode during an ongoing recording, the recording will be stopped. This works around a limitation in the playback mechanism which hampers recognition / detection with portrait-mode recordings.
Classes Overview
The main class is called SessionRecorder. This class operates as a singleton and provides an API for starting and stopping a recording from requested sources. The available sources can also be queried via this API. Last but not least, SessionRecorder also provides a means for removing all previous recordings. This is useful for instance if the device is running low on free space.
Unity API Overview
Session Recorder
The SessionRecorder is a Singleton accessible by calling SessionRecorder.Instance. Through this class it is possible to access all the features detailed in the Native API Overview below.
SessionRecorder.Start starts recording a Vuforia Session and returns a RecordingStatus enum. If the recording started successfully, Start will return RecordingStatus.RECORDING_IN_PROGRESS. The Start method accepts one bool input parameter that determines whether the SessionRecorder should also record data from the device’s sensors. This is enabled by default.
At any time it is possible to query the state of the SessionRecorder by calling the method SessionRecorder.GetRecordingStatus.
Recording can be stopped by calling SessionRecorder.Stop. When a recording has been stopped or there are no recordings in progress, the status is RecordingStatus.RECORDING_NOT_STARTED.
SessionRecorder.GetSupportedSources returns the sources supported by the device whose data can be recorded. The value is a bit-wise combination of the appropriate RecordingSource flags.
It is possible to know the path of 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.
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.
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 OnRecordingStarted, OnRecordingStopped, OnStorageCleaned after executing the corresponding SessionRecorder methods.
All the other methods from the Session Recorder are also exposed in the Session Recorder Behaviour.
Native API Overview
Obtaining the Session Recorder Singleton
A call to SessionRecorder::getInstance returns a reference to the SessionRecorder singleton.
Starting and Stopping a Recording
A recording can be started and stopped respectively by the start and stop methods of SessionRecorder. start returns an enum indicating the recording status. start assumes that Vuforia has been initialized (including the camera). Calling start twice, i.e. a subsequent call after a successful start, has no effect and returns RecordingInProgress (unless the already started recording has been aborted due to an error). In case of a start error, the application logs are also likely to contain details about the error.
Output Format
Each recorded session is saved in a human-readably timestamped directory in the private storage space of the app that is using the SessionRecorder. The directory name has the form VuforiaSession-[DATE]-[TIME],where [DATE] has the form YYYYMMDD (year, month, day) and [TIME] has the form hhmmss (hour, minute, second). Each complete session directory has an .xml file named FileDriverRecording.xml, accompanied by snapshots of the camera scene saved in a sub-directory called Camera. The .xml file stores timestamped descriptors describing the recorded data and is related to the snapshots directory by the snapshot filenames that are included as part of the camera frame descriptors. The camera snapshots are saved as Portable Gray Map (PGM) or custom extended PGM (called XPGM) image files, respectively for grayscale and color images. Please note that although XPGM files are non-standard, they are still viewable by some tools (notably the Preview application on macOS).
Querying Available Sources
SessionRecorder provides a utility method getSupportedSources which returns a bitfield with bits corresponding to the available and supported sources set (For all sources that could potentially be recorded, please see the Source enum). The Camera source also implies the device pose – i.e. if the device pose is available on the current platform, AND if Camera is requested, then device pose is automatically recorded.
Querying the Location of a Recording
The getRecordingPath method can be called for querying the location of the current OR last recording. If this method is called after a successful start, but before a corresponding stop, it returns the path to the current recording. If it is called after stop, but before the next start, it returns the path to the last recording. It is recommended to make a copy this path accordingly if a list of all recordings made by an app is required: SessionRecorder does not keep this information!
Pausing an Application
SessionRecorder does NOT provide a pause/resume capability. This means that when an application that is using the SessionRecorder is paused, it should call stop (BEFORE stopping the camera) and on the subsequent resume, it can call start. If the app thus calls stop on pause AND start on resume, this means the current recording in progress will be finalized on pause; and a new recording will be started on resume.
Please note that if on pausing an application, an ongoing recording is not stopped on pause as instructed above, Vuforia::onPause will force-stop it. However, in this case the resulting recording is not guaranteed to be in a usable state.
Querying the Recording Status
The recording status can be queried during a recording using the getRecordingStatus method. This will tell the caller if the recording has for instance been aborted due to the device running out of space (Note that SessionRecorder will abort an ongoing recording when the free space available on the device falls below a pre-defined threshold, i.e. before the device actually runs out of space).
Removing Previous Recordings
SessionRecorder provides a clean method for removing all recorded datasets. This is convenient for instance if the recorded datasets are not needed any more, and space is to be freed on the device storage. Please note that clean will work only when no recording is in progress.