[Proposal] INSCameraSDK framework architecture and dependency

[jessearmand]

As a background, I realized that on my integration of the iOS enterprise SDK version v1.8.2_build4, I can remove INSCoreMedia from the list of modules to be imported into the iOS application's Swift code.

However, INSCameraSDK has a dependency to INSCoreMedia. To elaborate more on this, please read the following:

INSCameraSDK v1.8.2-build4 has implicit dependencies on INSCoreMedia even for applications that only need basic camera control functionality. This results in:

1. Linking Failures: The INSInstaCameraInput symbol is referenced in INSCameraSDK
2. Forced Dependencies: All INSCameraSDK users must include or link INSCoreMedia framework that provides INSInstaCameraInput symbol
3. No clear separation between core camera control and media playback features

Root Cause

The current framework structure tightly couples camera control with media processing:

• INSCameraSDK references INSInstaCameraInput but doesn't implement it
• INSCoreMedia.xcframework located in iOS_v1.8.2_build4/INSCameraSDKSample-bluetooth/Carthage/Build/INSCoreMedia.xcframework doesn't implement it
• INSCoreMedia.xcframework located in iOS_v1.8.2_build4/INSCameraSDKSample-bluetooth/Frameworks/INSCoreMedia.xcframework contains the implementation

This creates a situation where developers must choose between:

• Using the lite framework and getting linker errors
• Using the full framework and shipping unnecessary media processing code

Technical Details

Symbol Analysis

• Missing Symbol: _OBJC_CLASS_$_INSInstaCameraInput and _OBJC_METACLASS_$_INSInstaCameraInput

nm -gU INSCoreMedia.xcframework/ios-arm64/INSCoreMedia.framework/INSCoreMedia | grep INSInstaCameraInput
0000000004a3d518 S _OBJC_CLASS_$_INSInstaCameraInput
0000000004a3d4f0 S _OBJC_METACLASS_$_INSInstaCameraInput

• Referenced In: INSCameraSDK.framework (undefined references)
• Available In: Full INSCoreMedia.xcframework only
• Missing From: INSCoreMedia.xcframework (lite version)

Here are the ways to determine if INSInstaCameraInput is loaded at runtime from INSCameraSDK.xcframework:

1. Using nm (Symbol Table Analysis)

nm INSCameraSDK.xcframework/ios-arm64/INSCameraSDK.framework/INSCameraSDK | grep -i instacamerainput

U _OBJC_CLASS_$_INSInstaCameraInput

• Shows U _OBJC_CLASS_$_INSInstaCameraInput (undefined symbol)
• The "U" indicates it's an undefined reference, meaning it's expected to be resolved at runtime

2. Using objdump

objdump -t INSCameraSDK.xcframework/ios-arm64/INSCameraSDK.framework/INSCameraSDK | grep -i instacamerainput

0000000000000000         *UND* _OBJC_CLASS_$_INSInstaCameraInput

• Shows *UND* (undefined) symbol for _OBJC_CLASS_$_INSInstaCameraInput

3. Using strings

strings INSCameraSDK.xcframework/ios-arm64/INSCameraSDK.framework/INSCameraSDK | grep -i instacamerainput

T@"INSInstaCameraInput",&,N,V_input
@"INSInstaCameraInput"

• Shows string references including @"INSInstaCameraInput"

4. Using otool for Dependencies

otool -L INSCameraSDK.xcframework/ios-arm64/INSCameraSDK.framework/INSCameraSDK | grep -i inscoremedia

@rpath/INSCoreMedia.framework/INSCoreMedia (compatibility version 1.0.0, current version 1.0.0)

• Shows INSCoreMedia.framework as a dependency where INSInstaCameraInput likely resides

Affected Components

The following 10 headers in INSCameraSDK create hard dependencies on INSCoreMedia:

Player/Render/Session Layer:

• INSCameraPreviewPlayer.h, INSCameraSessionPlayer.h, INSCameraPlayerRender.h
• INSCameraPlayerRenderView.h, INSCameraPlayerRenderSession.h, INSOffsetCalculator+Convert.h

Processing/Stabilization Layer:

• INSCameraFlatPanoOutput.h, INSCameraStabilizer.h, INSDisplayInfo.h, INSCameraMediaSession.h

Reproduction Steps

1. Create new iOS project
2. Add INSCameraSDK.xcframework and INSCoreMedia.xcframework from iOS_v1.8.2_build4/INSCameraSDKSample-bluetooth/Carthage/Build/INSCoreMedia.xcframework
3. Use any live session features (e.g., INSInstaCameraSession) or simply launch the app with INSCameraSDK imported
4. Build for arm64 → Dynamic Linker Error: Symbol not found: _OBJC_CLASS_$_INSInstaCameraInput

dyld[77717]: Symbol not found: _OBJC_CLASS_$_INSInstaCameraInput
  Referenced from: <5E604B2F-FCF9-34B7-9D84-8A8E8E7D8CC9> /private/var/folders/6j/h78c119x50q2q347jj98w9yw0000gp/X/8ADC0B3D-5480-56A9-8586-F2955355A8A6/d/Wrapper/SCEApp.app/Frameworks/INSCameraSDK.framework/INSCameraSDK
  Expected in:     <A24D0769-FB1B-3D7D-9598-1BC7E33B21E5> /private/var/folders/6j/h78c119x50q2q347jj98w9yw0000gp/X/8ADC0B3D-5480-56A9-8586-F2955355A8A6/d/Wrapper/SCEApp.app/Frameworks/INSCoreMedia.framework/INSCoreMedia

Current State Impact

Developer Experience Issues

• Unclear Dependencies: Inconsistent documentation explaining implicit dependencies to INSCoreMedia
• Binary Size: Apps requiring only camera control forced to ship large media processing framework
• Build Complexity: Developers must manually manage framework variants

INSInstaCameraInput Usage References

The problematic symbol is referenced in:

• INSCameraPlayerRenderSession.h:19 - parameter in method signature
• INSInstaCameraSession.h:10,49,57 - import, property, and initializer parameter
• Multiple header files referencing the class definition

---

Proposed Solution: Framework Architecture Refactor

The following is only a suggestion or proposal, the framework name such as INSCameraSDKCore or INSCameraSDKPlayer can be replaced based on a suitable naming convention.

1. Framework Split Strategy

Current Structure:

INSCameraSDK.framework → INSCoreMedia.framework, INSCameraServiceSDK.framework (forced dependency)

Proposed Structure:

INSCameraSDKCore.framework     # Camera control only, no INSCoreMedia dependency
INSCameraSDKPlayer.framework   # Media playback, depends on INSCoreMedia
INSCameraServiceSDK.framework (it should not depend on the other frameworks)

2. Component Separation

INSCameraSDKCore (lightweight):

• Camera connection and control
• Bluetooth pairing and commands
• Device activation and management
• Basic stitching and timelapse
• No media processing dependencies

INSCameraSDKPlayer (media-focused):

• Preview and session players
• Real-time stabilization
• Flat panorama output
• Live session management
• Depends on full INSCoreMedia

3. INSCoreMedia Variants

If they can be separated, provide clear framework variants:

• INSCoreMedia-Lite.xcframework: Offline rendering only (~8MB)
• INSCoreMedia.xcframework: Live sessions + offline (~20MB)

4. Benefits

For Developers:

• Smaller Apps: Reduction in framework size for camera-only apps
• Clearer Dependencies: Explicit choice between core vs full functionality
• Better Documentation: Clear separation of concerns

For Insta360:

• Reduced Support: Fewer dependency-related issues
• Faster Development: Independent evolution of camera and media layers
• Better Testing: Isolated testing of components

---

Implementation Suggestion

Analysis & Planning

• Audit all INSCoreMedia dependencies in INSCameraSDK
• Define public APIs for Core vs Player frameworks
• Create module map specifications

Core Framework Creation

• Extract camera control code to INSCameraSDKCore
• Remove INSCoreMedia dependencies from INSCameraSDKCore
• Implement optional/weak linking patterns for frameworks that are optional

Player Framework Creation

• Move media processing code to INSCameraSDKPlayer
• Ensure proper INSCoreMedia integration
• Add re-export module maps

Distribution & Documentation

• Create xcframework binaries for arm64 architecture (iphonesimulator), x86_64 is no longer needed
• Update documentation and migration guides

---

Environment

• SDK Version: 1.8.2-build4
• Platform: iOS arm64
• Xcode: 16.4+

[fabriciorodzprocore]

Hey @jessearmand I noticed you say INSCameraServiceSDK is independent, but If I add INSCoreMedia from the carthage folder and INSCameraSDK from the frameworks folder, I get:

Library not loaded: @rpath/INSCameraServiceSDK.framework/INSCameraServiceSDK

Are you experiencing the same or I'm missing something?

Note: I'm trying to import the sdk without having to import INSCameraServiceSDK, but if I need to import it at lest I would like to avoid the classes duplicate error.

[jessearmand]

Hey @jessearmand I noticed you say INSCameraServiceSDK is independent, but If I add INSCoreMedia from the carthage folder and INSCameraSDK from the frameworks folder, I get:

Library not loaded: @rpath/INSCameraServiceSDK.framework/INSCameraServiceSDK

Are you experiencing the same or I'm missing something?

Note: I'm trying to import the sdk without having to import INSCameraServiceSDK, but if I need to import it at lest I would like to avoid the classes duplicate error.

Yes, that's true INSCameraServiceSDK is actually a dependency of INSCameraSDK

otool -L INSCameraSDK.xcframework/ios-arm64/INSCameraSDK.framework/INSCameraSDK
INSCameraSDK.xcframework/ios-arm64/INSCameraSDK.framework/INSCameraSDK:
        @rpath/INSCameraSDK.framework/INSCameraSDK (compatibility version 1.0.0, current version 1.0.0)
        @rpath/INSCameraServiceSDK.framework/INSCameraServiceSDK (compatibility version 1.0.0, current version 1.0.0)
        @rpath/INSCoreMedia.framework/INSCoreMedia (compatibility version 1.0.0, current version 1.0.0)
        /System/Library/Frameworks/Foundation.framework/Foundation (compatibility version 300.0.0, current version 3423.0.0)
        /usr/lib/libobjc.A.dylib (compatibility version 1.0.0, current version 228.0.0)
        /usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 1900.178.0)
        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1351.0.0)
        /System/Library/Frameworks/AVFoundation.framework/AVFoundation (compatibility version 1.0.0, current version 2.0.0)
        /System/Library/Frameworks/AudioToolbox.framework/AudioToolbox (compatibility version 1.0.0, current version 1000.0.0)
        /System/Library/Frameworks/CoreFoundation.framework/CoreFoundation (compatibility version 150.0.0, current version 3423.0.0)
        /System/Library/Frameworks/CoreGraphics.framework/CoreGraphics (compatibility version 64.0.0, current version 1889.4.8)
        /System/Library/Frameworks/CoreImage.framework/CoreImage (compatibility version 1.0.0, current version 6.0.0)
        /System/Library/Frameworks/CoreMedia.framework/CoreMedia (compatibility version 1.0.0, current version 3210.19.1)
        /System/Library/Frameworks/CoreVideo.framework/CoreVideo (compatibility version 1.2.0, current version 1.5.0)
        /System/Library/Frameworks/GLKit.framework/GLKit (compatibility version 1.0.0, current version 129.0.0)
        /System/Library/Frameworks/OpenGLES.framework/OpenGLES (compatibility version 1.0.0, current version 1.0.0)
        /System/Library/Frameworks/QuartzCore.framework/QuartzCore (compatibility version 1.2.0, current version 1.11.0)
        /System/Library/Frameworks/UIKit.framework/UIKit (compatibility version 1.0.0, current version 8444.1.105)
        /System/Library/Frameworks/VideoToolbox.framework/VideoToolbox (compatibility version 1.0.0, current version 3210.19.1)

[jessearmand]

I think what I meant was INSCameraServiceSDK is a framework that doesn't depend on anything. While the rest is dependent on the other frameworks. What I'm proposing is to provide options for framework users to only import one for camera controls, without necessarily importing the one for media processing