Building and Using the File Driver Sample

The File Driver Sample demonstrates how to implement a driver which uses the External Camera and the External Device Tracking APIs to feed Vuforia Engine camera frames and device poses, respectively.

The File Driver sample can be downloaded from the Developer Portal. The File Driver should be configured to load an MP4 file that was recorded using the SessionRecorder API. The device tracking poses, which are embedded in the recording, are fed into Vuforia Engine along with camera frames from the video track.

NOTE: The File Driver sample package is in the XML/XPGM format. It will be removed in a future Vuforia Engine release and replaced with the MP4 file format.

The File Driver package includes two sets of frame-and-pose image sequences: Stones Image Target and Astronaut Image Target. Native developers should use the Stones Image Target while Unity developers should use the Astronaut Image Target sequence.

Use the Session Recorder API to create your own sequences as MP4 files, See the Session Recorder API and Recording and Playback for details.

Building the File Driver


Supported image file formats for the File Driver

The recording format from the Session Recorder API is MP4. Other image formats such as .xpgm, .png, and .jpg are deprecated but still supported in the File Driver. Other formats determined by the individual platform image loader will also be deprecated. 


  1. Extract the File Driver package and the Vuforia SDK package.
  2. Run the appropriate build command:
    Note: The -vh  or -vf  command line options may be omitted if the driver is put in the SDK's samples directory.


python android -vh [path to Vuforia SDK]/build/include


python uwp -vh [path to Vuforia SDK]/build/include


Correct the file line of the ios.toolchain.cmake file, located in the cmake directory to point to the correct Xcode location. Alternatively, remove this block completely so cmake will find it for you.


Then run the following command (the iOS option is -vf and the value is the folder containing Vuforia.framework):

python ios -vf [path to Vuforia SDK]/build
  1. Output files should be placed in the build/bin directory by default: for Android, FileDriver.dll for Windows, and FileDriver.framework

Using the File Driver


  1. Add for each needed architecture from build/bin to your Android app project by modifying either or CMakeLists.txt or build.gradle. Select the option that best fits your project:

      Add libFileDriver prebuilt definition to your file:

      include $(CLEAR_VARS)
      LOCAL_MODULE := libFileDriver-prebuilt
      LOCAL_SRC_FILES = [path-in-your-filesystem]/FileDriver/build/bin/Android/Release/$(TARGET_ARCH_ABI)/   

      When defining your local module in the same add libFileDriver-prebuilt as a dependency to your LOCAL_SHARED_LIBRARIES:

      LOCAL_SHARED_LIBRARIES := libFileDriver-prebuilt
    • CMakeLists.txt:

      Add libFileDriver prebuilt definition to your CMakeLists.txt file:



      When linking libraries in CMake, link libFileDriver library in the same CMakeLists.txt:
    • Gradle: 

      If using either or CMakeLists.txt you will also need to update your build.gradle to include the library in the APK. Use the following code in your app/build.gradle:

      android {
          sourceSets.main {
              jniLibs.srcDirs += '[path-in-your-filesystem]/FileDriver/build/bin/Android/Release/'


      NOTE: If you are using the Android Plugin version 4.x and a CMakeLists.txt then the above change to build.gradle is not required.
  2. Add FileDriver.jar from build/bin to your Android-app project. Use the following code in your app/build.gradle:
    dependencies {
        implementation files("[path-in-your-filesystem]/FileDriver/build/bin/Android/Release/FileDriver.jar")


  3. Add the sample sequence from the data directory to your Android-app project. Use the following code in your app/build.gradle:
    android {
        sourceSets.main {
            assets.srcDirs += '[path-in-your-filesystem]/FileDriver/data/stones'


  4. Add then your configuration for the driver before creating a new Engine instance with vuEngineStart()
    VuDriverConfig driverConfig = vuDriverConfigDefault();
    driverConfig.driverName = "";
    driverConfig.userData = FileDriverUserData*;
    vuEngineConfigSetAddDriverConfig(configSet, &driverConfig);



  1. Add FileDriver.dll from build/bin/uwp into your Visual Studio UWP app project.
    1. Import the FileDriver.dll to the root of your project. Remember to use a .dll that matches your architecture (x86/x64) and build type (Debug/Release) configurations.
    2. Click FileDriver.dll from the project file list and set property Content to True.
  2. Add a sample sequence from the data directory into your Visual Studio UWP app project. For example, to use the “stones” sequence:
    1. Import FileDriver/data/stones/FileDriverSequence.xml into your project.
    2. Copy ‘Camera' folder containing images from Driver sequence into the root of the VuforiaSamples project.
      • NOTE: the root is the Vuforia Samples folder where the VuforiaSamples.vcxproj is present.
    3. Right click on the project ‘VuforiaSamples’ and click Add->Existing item.
    4. Select all the images from the Camera folder that was copied into the root of the VuforiaSamples project. Visual Studio will proceed to add all the selected images.
    5. Select all images in the Solution Explorer and right click and select Properties.
    6. Mark Content as ‘Yes’, save the project and proceed to the App package creation process.
    7. Select all files and set property Content to True.
  3. Add the following call before calling vuEngineStart():
VuDriverConfig driverConfig = vuDriverConfigDefault();
driverConfig.driverName = "FileDriver.dll";
driverConfig.userData = ”driverDataDirectory”;
vuEngineConfigSetAddDriverConfig(configSet, &driverConfig);


  1. In your Xcode project, open the build settings screen and select the General tab. 
  2. In the Embedded Binaries section, click the icon to add a new binary. 
  3. From the file selection menu, locate the iOS File Driver Framework in bin/Release-iphoneos/FileDriver.framework
  1. In the Linked Frameworks and Libraries section, remove the FileDriver entry. The entry should not be listed in this section and the application should not try to link against it.
  1. Drag the FileDriverSequence.xml file and the camera image files into the left-hand project pane. Package the image files into a Camera folder in the app bundle with the folder structure as seen below.
  1. Add the following call before calling vuEngineStart():
VuDriverConfig driverConfig = vuDriverConfigDefault();
driverConfig.driverName = "FileDriver.framework";
driverConfig.userData = ”driverDataDirectory”;
vuEngineConfigSetAddDriverConfig(configSet, &driverConfig);


Changing the Sequence

To load a specific sequence of pose and images, provide a new path using the driverName data structure and the vuEngineConfigSetAddDriverConfig() call.

Custom Sequences (Deprecated)

Please note that the custom file driver XML file format is deprecated, and this section will be removed in a future version of Vuforia Engine.

Developers looking to create their own sequence, should consider the following:

  • A top level XML file groups a device pose and a matching camera frame under one <Element> tag. This XML file also contains global attributes, such as total number of camera frames, width, and height, which apply to the entire sequence. For more information, refer to the Format of Camera and Pose XML Sequence File article.
  • The width and height of each frame should remain consistent and match the intrinsic information provided with each frame.
  • The framerate at which frames are provided to Vuforia Engine does not necessarily need to match the rate at which they were captured.
  • The samples currently use PNG format, but other image formats may be supported depending on the platform. Ensure that the files can be read at the rate which matches the desired framerate. For instance, if the desired framerate is 30 FPS, then the device needs to be able to read 30 files per second.
  • Avoid compression artifacts in the files.
  • Developers need to create/name their file sequences to easily process the sequence in the appropriate order. The sample uses 'filename#####.png' notation, where ##### represents the frame index, padded to 5-digits.


  1. Copy the compiled binaries from build/bin to:
    • Android: Assets/Plugins/Android/
    • UWP: Assets/Plugins/WindowsStoreApps/[x64, x86]
    • iOS: Assets/Plugins/iOS/

Note: Ensure the correct plugin platform options are set for the imported libraries. The selection options should match the intended platform (see below).

  1. Add the sequence to your Unity project. Copy your recording .MP4 from YourDirectory/VuforiaDriver-x-y-z/Data/Astronaut into the Assets/StreamingAssets folder. This ensures it's included in the application build.

  1. In the VuforiaConfiguration window, enable Delayed initialization. This sets the driver library name before Vuforia Engine is initialized in order to use the file driver from Unity.
  2. Also, make sure to add a license key as the file driver will not work without it.

  1. The driver library can then be set from any app level script, e.g., in a Start() method. After that, Vuforia Engine can be initialized:
VuforiaApplication.Instance.Initialize(driverName, sUserDataPtr);

Now, the image sequence should play in a loop instead of the device camera being used.

On iOS, The resulting .xcodeproj should be modified to include the FileDriver.framework as an embedded framework. Remember to remove it from the list of linked libraries (refer to the step relating to linked libraries in the Using the File Driver iOS section):

using System;
using System.Runtime.InteropServices;
using UnityEngine;
using Vuforia;

public class LoadDriver : MonoBehaviour
    struct FileDriverUserData
        public string sequenceDirectoryAbsolutePath;

    static FileDriverUserData sUserData;
    static IntPtr sUserDataPtr = IntPtr.Zero;

    void Start()
        var recordingPath = string.Empty;

        // The sequence stored directly in the StreamingAssets folder will end up in Application.streamingAssetsPath at runtime on iOS
        recordingPath = Application.streamingAssetsPath;

        sUserData = new FileDriverUserData { sequenceDirectoryAbsolutePath = recordingPath };
        sUserDataPtr = Marshal.AllocHGlobal(Marshal.SizeOf(typeof(FileDriverUserData)));
        Marshal.StructureToPtr(sUserData, sUserDataPtr, false);

        var driverName = "";
        driverName = "";
        driverName = "FileDriver.dll";
        driverName = "FileDriver.framework";

        VuforiaApplication.Instance.Initialize(driverName, sUserDataPtr);
        VuforiaApplication.Instance.OnVuforiaDeinitialized += OnVuforiaDeinitialized;

    static void OnVuforiaDeinitialized()
        // Preserve the pointer to the user data for the whole Vuforia lifecycle