Troubleshooting

This guide covers common issues you may encounter when integrating the iOS Video SDK and how to resolve them.

License errors

License-related issues are the most common cause of SDK failures. These errors typically occur during initialization or when processing images, resulting in black output or exceptions.

Expired certificate

The SDK validates your license on every initialization.

Symptom: checkStatus() returns -1. Processed images appear completely black.

Cause: The certificate has passed its expiration date.

Solution:

1. Contact EyeQ to obtain a new certificate.
2. Update your app with the new credentials.
3. If testing, verify your device date/time is set correctly as incorrect system time can cause valid certificates to appear expired.

Invalid API key or certificate

Mismatched or malformed credentials will prevent the SDK from initializing properly.

Symptom: checkStatus() returns -2. SDK initialization fails silently.

Cause: The API key and certificate don't match, or one is incorrectly formatted.

Solution:

1. Verify the API key and certificate are from the same license.
2. Check for copy/paste errors such as extra whitespace, missing characters, or truncated strings.
3. Use raw string literals to avoid escape character issues:

let pfcDynamic = PFCDynamic(
    apiKey: "YOUR_API_KEY",
    certificate: #"YOUR_CERTIFICATE"#
)

Checking license status

Always verify your license before processing images:

let status = pfcDynamic.checkStatus()
switch status {
case 0:
    print("SDK initialized successfully")
case -1:
    print("Certificate expired")
case -2:
    print("Invalid API key or certificate")
case -3:
    print("Failed to initialize AI model")
case -4:
    print("Failed to load model file")
case -5:
    print("Failed to create context")
default:
    print("Unknown error: \(status)")
}

Initialization failures

These errors occur when the SDK cannot load or initialize its neural network model.

Failed to initialize AI model

Symptom: checkStatus() returns -3.

Cause: The TensorFlow Lite runtime could not initialize the neural network model.

Solution: The iOS framework bundles all required dependencies. If you see this error, ensure the XCFramework is properly embedded in your target.

Failed to load model file

Symptom: checkStatus() returns -4.

Cause: The PFCDynamicModel.pnnc file is missing from the framework bundle.

Solution:

1. Re-download the SDK package from EyeQ.
2. Verify the XCFramework contains the model file at DynamicFramework.framework/PFCDynamicModel.pnnc.
3. In Xcode, clean the build folder (Product → Clean Build Folder) and rebuild.
4. Ensure the framework is set to "Embed & Sign" in your target's General settings.

Failed to create context

Symptom: checkStatus() returns -5.

Cause: OpenGL or Metal context creation failed, typically on simulator or restricted environments.

Solution:

1. Test on a physical device instead of the simulator.
2. Ensure no other frameworks are holding exclusive GPU resources.
3. Check that your app has the necessary entitlements for GPU access.

Build errors

Bitcode errors

The SDK framework does not include Bitcode, which can cause archive failures.

Symptom: Build fails with "Bitcode bundle could not be generated" error when archiving.

Solution:

1. Select your project in the navigator.
2. Go to Build Settings.
3. Search for "Enable Bitcode".
4. Set to No for your target.

Framework embedding issues

Incorrect framework configuration causes runtime crashes on app launch.

Symptom: App crashes immediately on launch with "Library not loaded" or "image not found" errors.

Solution:

1. Select your target in Xcode.
2. Go to General → Frameworks, Libraries, and Embedded Content.
3. Ensure DynamicFramework.xcframework is set to Embed & Sign.
4. If using CocoaPods or SPM, ensure the framework is properly linked.

Performance issues

Slow processing speed

Optimizations:

1. Enable frame skipping: Reduce processing load on lower-end devices:

pfcDynamic.setParams(deflickerCurve: 0.08, deflickerImage: 0.9, skip: 1)

2. Process on background queue: Never block the main thread:

videoQueue.async {
    let processed = try? self.pfcDynamic.processImage(cgImage, strength: 0.8)

    DispatchQueue.main.async {
        self.imageView.image = UIImage(cgImage: processed)
    }
}

Video flickering

Flickering in video output occurs when correction parameters vary frame-to-frame without temporal smoothing.

Cause: Deflickering not configured, or resetDeflicker() called too frequently.

Solution:

1. Enable deflickering before processing video frames:

pfcDynamic.setParams(deflickerCurve: 0.08, deflickerImage: 0.9, skip: 0)

2. Only reset when necessary: Call resetDeflicker() only in these situations:

Memory issues

Processing high-resolution images can consume significant memory.

// Use autoreleasepool for batch processing
for image in images {
    autoreleasepool {
        let processed = try? pfcDynamic.processImage(image, strength: 0.8)
        // Use processed image
    }
}

Platform-specific issues

Simulator limitations

The iOS Simulator has limited GPU capabilities and no camera access.

What works: Basic image processing with processImage().

What doesn't work: Camera capture, real-time video processing, accurate performance testing.

Solution: Always test video and camera features on a physical device.

GPUImage conflicts

The SDK uses GPUImage internally, which can conflict with external GPUImage dependencies.

Symptom: Crashes or undefined behavior when using GPUImage framework alongside the SDK.

Solution:

1. Remove external GPUImage dependency if possible.
2. If you must use GPUImage, isolate SDK usage in a separate module or process.
3. Contact EyeQ support for guidance on specific conflict scenarios.

Getting help

If you encounter issues not covered in this guide:

1. Review the sample projects for working implementation examples.
2. Check the API reference for method signatures and parameter details.
3. Verify your SDK version matches the documentation.

When contacting EyeQ support, include:

• SDK version number
• iOS version
• Device model
• Complete error message or stack trace
• Minimal code sample that reproduces the issue
• Output of checkStatus()