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.
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.
To retrieve recordings on iOS, the App needs to specify the
UIFileSharingEnabled property in the .plist file so that the App ‘Documents’ area is visible to users.
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.
Currently devices with cameras that capture frames in the following pixel formats are supported:
- 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.
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
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
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
Recording can be stopped by calling
SessionRecorder.Stop. When a recording has been stopped or there are no recordings in progress, the status is
SessionRecorder.GetSupportedSources returns the sources supported by the device whose data can be recorded. The value is a bit-wise combination of the appropriate
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
SessionRecorderBehaviour provides basic state and error management for the Session Recorder.
CleanStorage methods encapsulate the Session Recorder functionality and invoke the events
OnStorageCleaned after executing the corresponding
All the other methods from the Session Recorder are also exposed in the Session Recorder Behaviour.
Obtaining the Session Recorder Singleton
A call to
SessionRecorder::getInstance returns a reference to the
Starting and Stopping a Recording
A recording can be started and stopped respectively by the
stop methods of
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.
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.
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.