Skip to content

Camera SDK 接口文档 ​

Camera SDK(sdk-camera)提供 Insta360 相机的连接管理、拍摄控制、实时预览、文件管理和固件升级能力。本文档列出所有公开 API 的接口定义与参数说明。


目录 ​

  1. 设备连接与管理
  2. 系统与硬件信息
  3. 拍摄控制与参数
  4. 实时预览
  5. 文件管理
  6. 固件升级
  7. GPS 数据注入
  8. 事件监听器
  9. 公共数据类型

1. 设备连接与管理 ​

CameraDevice ​

相机设备的核心接口,是所有功能模块的访问入口。

kotlin
interface CameraDevice

工厂方法

kotlin
CameraDevice.get(connectType: ConnectType): CameraDevice

子模块

属性类型说明
systemCameraSystem系统级功能
captureCameraCapture拍摄控制
previewCameraPreview实时预览流
fileCameraFile相机内文件管理
firmwareCameraFirmware固件版本与升级

连接方法

方法形式说明
isConnected()同步是否已连接
scan(timeoutMs, bleScanCallback)同步扫描附近蓝牙设备
stopScan()同步停止蓝牙扫描
bleWakeUp(cameraType, deviceName, listener)同步蓝牙唤醒相机
connect(connectHint, callback)回调通用连接
connect(connectHint)协程通用连接
connectBle(bleDeviceCore, callback)回调蓝牙连接(SDK BleDeviceCore)
connectBle(bleDeviceCore)协程蓝牙连接(SDK BleDeviceCore)
connectBle(kmpBleDevice, callback)回调蓝牙连接(系统 BluetoothDevice / CBPeripheral)
connectBle(kmpBleDevice)协程蓝牙连接(系统 BluetoothDevice / CBPeripheral)
connectWiFi(networkId, callback)回调Wi-Fi 连接
connectWiFi(networkId)协程Wi-Fi 连接
connectUsb(callback)回调USB 连接
connectUsb()协程USB 连接
disconnect(callback) / suspend disconnect()回调 / 协程断开连接,返回 Result<Unit>
getSupportCameraType()同步获取当前连接类型支持的相机型号列表
release()同步释放设备对象所有资源

断连监听

方法说明
registerDisconnectListener(listener)注册断连监听器
unregisterDisconnectListener(listener)注销断连监听器

相机授权

连接后可通过以下方法校验当前设备是否已获得相机端授权。相机端会弹出确认弹窗,用户确认/拒绝后结果通过 AuthorizationListener 回调。

方法形式说明
checkAuthorization(callback) / checkAuthorization()回调 / 协程校验授权,返回 AuthorizationStatus
cancelAuthorization(callback) / cancelAuthorization()回调 / 协程取消当前授权校验
registerAuthorizationListener(listener)同步注册授权结果监听器
unregisterAuthorizationListener(listener)同步注销授权结果监听器

AuthorizationStatus 枚举值:

值说明
AUTHORIZED已授权
UNAUTHORIZED未授权(相机将显示确认弹窗,结果通过 AuthorizationListener 回调)
SYSTEM_BUSY相机繁忙

2. 系统与硬件信息 ​

CameraSystem ​

提供电量、存储、温度、Wi-Fi、设备信息、关机等系统级功能。

kotlin
interface CameraSystem

每项数据均提供三种调用形式:

  • getXxx() — 读取本地缓存(同步)
  • fetchXxx(callback) — 从相机拉取(回调)
  • suspend fetchXxx() — 从相机拉取(协程)

可读写的数据项额外提供 setXxx(...) 方法。

数据项一览

数据项类型可写说明
BatteryDataBatteryData✗电池电量与充电状态
ChargeBoxDataChargeBoxData✗充电盒状态
MuteBoolean✓静音状态
SerialNumberString✗序列号
UuidString✗UUID
OriginOffset / V2 / V3String✗原始偏移量(多版本)
ActivateTimeLong✓激活时间
StorageDataStorageData✗已废弃,请使用 StorageDataList
StorageDataListList<StorageData>✗存储介质状态列表(支持多存储位置)
MediaOffset / V2 / V3String✗媒体偏移量(多版本)
MediaOffsetV6String✗媒体偏移量 V6
FirmwareRevisionString✗固件版本号
WifiDataWiFiData✗Wi-Fi 信息
WifiChannelListWiFiChannel✗Wi-Fi 信道列表
CameraTypeCameraType✗相机型号
VideoEncodeTypeVideoEncode✓视频编码类型
IsSelfieBoolean✗是否自拍模式
CameraLanguageLanguageType✓相机语言
AssistiveGridEnableBoolean✓辅助网格
FreeFrameGridEnableBoolean✓自由比例网格
SharpnessSharpness✓全局锐度
MediaTimeLong✗媒体时间
WindowCropInfoWindowCropInfo✗窗口裁剪信息(缓存)
HalfWindowCropInfoWindowCropInfo✗半窗口裁剪信息(缓存)
OffsetStateInt✗offset 状态(缓存)
OffsetDetectedTypeInt✗offset 检测类型(缓存)
RollingShutterTimeDouble✗滚动快门时间(秒)

操作方法

方法形式说明
setLocalTime(localTime, callback) / setLocalTime(localTime)回调 / 协程设置本地时间
openCameraWiFi(channel, callback) / openCameraWiFi(channel)回调 / 协程开启 Wi-Fi
closeCameraWiFi(callback) / closeCameraWiFi()回调 / 协程关闭 Wi-Fi
resetCameraWiFi(channel, callback) / resetCameraWiFi(channel)回调 / 协程重置 Wi-Fi
setWiFiCountry(countryCode, callback) / setWiFiCountry(countryCode)回调 / 协程设置 Wi-Fi 国家代码
activeCamera(appId, secretKey, callback) / activeCamera(appId, secretKey)回调 / 协程激活相机
calibrateGyro(callback) / calibrateGyro()回调 / 协程校准陀螺仪
setLockScreenState(state, callback) / setLockScreenState(state)回调 / 协程设置屏幕锁定状态
formatSdCard(callback) / formatSdCard()回调 / 协程已废弃,请使用 formatStorage(等价于 formatStorage(FileLocation.CAMERA))
formatStorage(fileLocation, callback) / formatStorage(fileLocation)回调 / 协程格式化指定存储位置,默认 FileLocation.CAMERA
setMainStorage(fileLocation, callback) / setMainStorage(fileLocation)回调 / 协程设置主存储位置(仅 X6 支持)
shutdown()同步关闭相机电源

状态监听

方法说明
registerBatteryListener(listener) / unregisterBatteryListener(listener)电池状态
registerChargeBoxStatusListener(listener) / unregisterChargeBoxStatusListener(listener)充电盒状态
registerTemperatureListener(listener) / unregisterTemperatureListener(listener)温度状态
registerStorageStatusListener(listener) / unregisterStorageStatusListener(listener)存储卡状态

3. 拍摄控制与参数 ​

CameraCapture ​

提供拍照、录像的启停控制以及所有拍摄参数的读写。

kotlin
interface CameraCapture

CameraParam<T> ​

统一封装单个拍摄参数的读取、写入、支持列表查询和变化监听。

kotlin
interface CameraParam<T>
方法说明
suspend getValue(): Result<T>读取当前缓存值
suspend fetchValue(): Result<T>从相机读取最新值
suspend setValue(value: T): Result<Unit>写入新值(自动触发监听器)
suspend getSupported(): Result<List<T>>获取当前模式下的可选值列表
getName(): String获取参数名称标识
addListener(listener: (T) -> Unit)订阅参数变化回调
removeListener(listener: (T) -> Unit)取消订阅参数变化回调

拍摄参数列表

所有参数均以 CameraParam<T> 属性形式挂载在 CameraCapture 上:

属性类型 T说明
lensTypeSensorMode镜头类型(单/双镜头等)
functionModeFunctionMode拍摄功能模式(录像/拍照/延时等)
photoResolutionPhotoResolution照片分辨率
videoResolutionRecordResolution视频分辨率
hdrPhotoModePhotoHdrType照片 HDR 模式
hdrSwitchBoolean视频 HDR 开关
aebInt自动包围曝光(AEB)
rawTypeRawTypeRAW 格式类型
exposureProgramExposureProgram曝光程序
exposureISOIntISO
exposureShutterSpeedPair<Double, Double>快门速度
videoISOTopLimitInt视频 ISO 上限
exposureBiasDouble曝光补偿(EV)
whiteBalanceInt白平衡
fovTypeFovType视场角类型
flowStateLevelFlowStateLevel防抖等级
photographySelfTimerInt拍照倒计时
splicingBaseEnableBoolean拼接基础开关
videoSelfieModeVideoSelfieMode视频自拍模式
exportTypeExportType导出类型
photoSizeIdPhotoSize照片尺寸/比例
colorModeVideoGammaMode色彩模式
filterModeVideoGammaMode滤镜模式
accelerateFrequencyInt加速频率(延时摄影)
recordDurationInt录制时长
exposureIndividualPanoExposureMode独立曝光模式
livingBitrateInt直播码率
burstCaptureParamsPair<Int, Int>连拍参数(张数, 间隔)
p3SwitchBooleanP3 色域开关
iLogSwitchBooleani-Log 色彩模式开关
pureVideoEnhanceSwitchBoolean纯净夜拍增强开关
doubleZoomEnableBoolean双倍变焦开关
lapseTimeDouble间隔拍摄时间间隔
livePhotoModeBoolean实况照片(Live Photo)
lensAccessoryLensAccessoryType镜头配件类型
iq3AModeIq3AMode3A 专业模式(NORMAL ↔ PRO);exposureISO/exposureShutterSpeed/whiteBalance/videoISOTopLimit 等参数在各模式下的可选值收窄由相机端声明驱动,SDK 不做自动模式切换

参数管理方法

方法说明
getSupportParam(): List<CameraParam<*>>获取当前相机支持的参数列表
suspend syncAllParams()强制从相机同步所有参数
suspend loadJson(): Result<Unit>加载相机参数配置 JSON(连接后调用)

getSupportParamNames() 和 getAllParams() 已废弃,请统一使用 getSupportParam()。

拍摄控制方法

方法说明
suspend startCapture(gpsInfo: GpsInfo? = null)开始拍摄,可选携带 GPS 信息写入媒体文件
suspend stopCapture(gpsInfo: GpsInfo? = null)停止拍摄,可选携带 GPS 信息写入媒体文件
suspend setGpsInfo(gpsInfo: GpsInfo)拍摄过程中更新 GPS 信息
suspend isWorking(): Boolean是否正在拍摄
isPreRecording(): Boolean是否处于预录制状态
cancelPreRecord()取消预录制
suspend getBurstTime(): Result<Unit>获取连拍时间
suspend getRemaining(): Result<Int>当前模式剩余录制时间(秒)或拍摄张数
getRemaining(functionMode): Result<Int>指定模式剩余量(缓存)
suspend fetchRemaining(functionMode): Result<Int>从相机拉取指定模式剩余量
registerCaptureStatusListener(listener)注册拍摄状态监听器
unregisterCaptureStatusListener(listener)注销拍摄状态监听器

4. 实时预览 ​

CameraPreview ​

控制相机实时预览流的开启/关闭、参数获取及姿态监听。

kotlin
interface CameraPreview
方法说明
startStream()开启预览流(自动同步解码配置)
stopStream()停止预览流
requestStreamIframe()请求立即发送关键帧,用于恢复花屏
getPreviewParams(): Result<PreviewParams>获取当前预览流参数快照(供媒体侧使用)
getCurrentFunctionMode(): Result<FunctionMode>获取当前预览会话的功能模式
getVideoBitrate(): Result<Int>获取缓存的视频码率(bps)
suspend fetchVideoBitrate(): Result<Int>从相机拉取最新视频码率
suspend setVideoBitrate(bitrate: Int): Result<Unit>设置视频码率
setStreamEncode(isH265: Boolean)手动覆盖预览流解码配置(通常无需调用)
setPipeline(pipeline: KMPCameraPreviewPipeline?)设置预览渲染管线
registerPostureListener(listener)注册相机姿态更新监听器
unregisterPostureListener(listener)注销相机姿态更新监听器
registerCameraStreamListener(listener)注册预览流状态监听器
unregisterCameraStreamListener(listener)注销预览流状态监听器
suspend startLive(params: CameraLiveParams): Result<Unit>发起 RTMP 直播推流(需先切到直播模式并开启预览流)
startLive(params: CameraLiveParams, callback: Callback<Unit>)发起直播推流(callback 风味)
suspend stopLive(): Result<Unit>停止直播推流
stopLive(callback: Callback<Unit>)停止直播推流(callback 风味)
registerCameraLiveListener(listener)注册直播推流状态监听器
unregisterCameraLiveListener(listener)注销直播推流状态监听器

startLive 返回成功仅表示推流请求已受理,实际推流状态通过 CameraLiveListener 异步回调。

CameraStreamListener ​

kotlin
interface CameraStreamListener
回调说明
onOpening()预览流开始打开
onOpened()预览流成功打开
onIdle()预览流已关闭
onParamsChanged(paramsUpdate: PreviewStreamParamsUpdate)预览流参数变化(分辨率/帧率/裁剪信息等)
onStreamDataNotify(streamData: PreviewStreamFrame)收到预览流数据帧(默认空实现)

CameraLiveParams ​

直播推流参数,传入 CameraPreview.startLive()。

kotlin
data class CameraLiveParams(
    val rtmpUrl: String,
    val width: Int,
    val height: Int,
    val fps: Int,
    val bitrate: Int,
    val netId: Long = -1L
)
属性说明
rtmpUrlRTMP 推流地址
width / height推流画面分辨率(像素)
fps推流帧率
bitrate推流码率(单位 Mbps,底层内部转换为 bps)
netId推流使用的网络 id,默认 -1(底层默认网络)。SDK 不管理网络,绑定指定网络(如蜂窝)时由调用方传入对应 network id

CameraLiveListener ​

直播推流状态回调,通过 CameraPreview.registerCameraLiveListener() 注册。所有回调在非主线程分发,更新 UI 需自行切换到主线程。

kotlin
interface CameraLiveListener
回调说明
onStarted()推流成功启动
onFps(fps: Int)推流帧率更新,fps 为当前实时帧率
onStopped()推流正常停止
onFailed(errorCode: Int, message: String?)推流发生错误,errorCode 为底层错误码

PreviewStreamFrame ​

kotlin
data class PreviewStreamFrame(
    val data: ByteArray,
    val timestamp: Long,
    val type: PreviewStreamType = PreviewStreamType.UNKNOWN
)
属性说明
data帧原始字节数据
timestamp帧时间戳(送入 MediaCodec 前通常需转换为微秒)
type帧类型,见下表

PreviewStreamType ​

枚举值说明
VIDEO普通视频帧
VIDEO_L左眼/左侧视频帧
VIDEO_R右眼/右侧视频帧
AUDIO音频帧
GYRO陀螺仪/姿态数据帧
OTHER其他类型
UNKNOWN未知类型

val isVideo: Boolean — 判断是否为视频帧(VIDEO / VIDEO_L / VIDEO_R)。

PreviewStreamParamsUpdate ​

kotlin
data class PreviewStreamParamsUpdate(
    val windowCropInfo: WindowCropInfo?,
    val offsetData: CameraPreviewOffsetData?,
    val stabOffset: String?,
    val previewWidth: Int,
    val previewHeight: Int,
    val previewFps: Int,
)
属性说明
windowCropInfo窗口裁剪信息,用于全景拼接
offsetData镜头偏移/校正参数
stabOffset防抖偏移量字符串
previewWidth / previewHeight当前预览分辨率(像素)
previewFps当前预览帧率

5. 文件管理 ​

CameraFile ​

提供相机内部媒体文件的列表查询、下载和删除功能。

kotlin
interface CameraFile

服务器信息

方法说明
getEndpoint(): String文件服务器完整 URL(如 http://192.168.42.1:80/)
getHost(): String主机地址
getProt(): Int端口号

文件列表

方法形式说明
listMediaFiles(mediaFileType, includeRecording, callback)回调获取全量文件列表,返回 URI 列表
listMediaFiles(mediaFileType, includeRecording)协程同上
listMediaFiles(mediaFileType, start, limit, includeRecording, callback)回调分页获取,返回 Pair<List<String>, Int>(列表, 总数)
listMediaFiles(mediaFileType, start, limit, includeRecording)协程同上
getFileInfoList(callback)回调获取详细文件信息列表
getFileInfoList()协程同上

文件操作

方法形式说明
deleteMediaFiles(vararg uris, callback)回调删除指定文件
deleteMediaFiles(vararg uris)协程删除指定文件
downloadMediaFile(url, targetDir, progressCallback?)协程下载媒体文件,返回本地路径
downloadMediaFile(url, targetDir, progressCallback)进度回调下载媒体文件
downloadCameraLogFile(targetDir, progressCallback?)协程下载相机日志文件,返回本地路径
downloadCameraLogFile(targetDir, progressCallback)进度回调下载相机日志文件

6. 固件升级 ​

CameraFirmware ​

kotlin
interface CameraFirmware
方法形式说明
getVersion(): Result<String>同步获取当前固件版本号
upgradeFirmware(filePath, callback)进度回调固件升级,进度值 0.0–1.0
upgradeFirmware(filePath, progress?)协程固件升级,可选进度回调

7. GPS 数据注入 ​

拍摄时如需将 GPS 信息写入媒体文件,调用方直接持有并管理自己的定位数据源,通过 CameraCapture.startCapture(gpsInfo) / stopCapture(gpsInfo) 传入起止时刻的 GPS 信息,录制过程中如需更新,调用 CameraCapture.setGpsInfo(gpsInfo)。

GpsInfo ​

kotlin
data class GpsInfo(
    val latitude: Double,
    val longitude: Double,
    val altitude: Double,
    val timestampMs: Long
)
属性说明
latitude纬度(度)
longitude经度(度)
altitude海拔高度(米)
timestampMs时间戳(毫秒)
toByteArray()序列化为小端序字节数组

8. 事件监听器 ​

DisconnectListener ​

设备与相机断开连接时触发。通过 CameraDevice.registerDisconnectListener() 注册。

回调参数说明
onDisconnect(throwable: Throwable?)throwable:断连原因(正常断开时为 null)连接断开

BleWakeUpListener ​

蓝牙唤醒结果回调。通过 CameraDevice.bleWakeUp() 传入。

回调参数说明
onWakeUpSuccess()—蓝牙唤醒成功
onWakeUpError(errCode: Int)errCode:错误码蓝牙唤醒失败

BatteryListener ​

通过 CameraSystem.registerBatteryListener() 注册。

回调参数说明
onBatteryLevelChange(batteryData: BatteryData)batteryData:电量与充电状态电量变化
onLowBatteryWarning()—低电量警告

ChargeBoxStatusListener ​

通过 CameraSystem.registerChargeBoxStatusListener() 注册。

回调参数说明
onChargeBoxStatusChange(chargeBoxData: ChargeBoxData)chargeBoxData:充电盒状态充电盒状态变化

TemperatureListener ​

通过 CameraSystem.registerTemperatureListener() 注册。

回调参数说明
onTemperatureUpdate(tempState: TempState)tempState:温度等级相机温度状态变化

StorageStateListener ​

通过 CameraSystem.registerStorageStatusListener() 注册。

回调参数说明
onStorageStateListChanged(storageDataList: List<StorageData>)storageDataList:所有存储介质的状态列表存储状态变化

CaptureStatusListener ​

通过 CameraCapture.registerCaptureStatusListener() 注册。

回调参数说明
onCaptureStarting(functionMode)当前拍摄模式拍摄即将开始
onCaptureWorking(functionMode)当前拍摄模式拍摄进入工作状态
onCaptureStopping(functionMode)当前拍摄模式拍摄即将停止
onCaptureFinish(functionMode, filePaths)filePaths:生成的文件路径列表拍摄完成并生成文件
onCaptureError(functionMode, throwable)throwable:错误原因拍摄发生错误
onCaptureTimeChanged(functionMode, captureTime)captureTime:已录制时长录制时长变化(录像模式)
onCaptureCountChanged(functionMode, captureCount)captureCount:已拍张数拍摄张数变化(连拍/间隔)
onCaptureSubStatusChanged(functionMode, subStatus)subStatus:子状态拍摄子状态变化(如 HDR 处理)

CameraPostureUpdate ​

通过 CameraPreview.registerPostureListener() 注册,实时接收相机空间姿态数据。

回调参数说明
updatePosture(cameraPosture: CameraPosture)cameraPosture:姿态数据姿态数据更新(陀螺仪/加速度计)

AuthorizationListener ​

通过 CameraDevice.registerAuthorizationListener() 注册,接收相机端授权操作结果。

回调参数说明
onAuthorizationResult(operationType, result)operationType:触发此授权的操作类型;result:授权结果用户在相机端确认或拒绝授权后回调

9. 公共数据类型 ​

以下类型在 Camera 和 Media 模块之间存在关联,此处一并列出。

KMPCameraPreviewPipeline ​

来自 verticalCommon,在 Camera 和 Media 侧均有使用:

  • Camera 侧:CameraPreview.setPipeline(pipeline) — 将管线注入相机预览
  • Media 侧:PreviewPlayer.getPipeline() — 获取当前渲染管线

管线对象由媒体侧创建后传入相机侧,作为预览数据的传输通道。


PreviewStreamParamsUpdate(Camera → Media) ​

相机预览流参数变化时,通过 CameraStreamListener.onParamsChanged() 回调此对象。媒体侧的 PreviewPlayer.setOffset() 和 setWindowCropInfo() 通常基于此对象中的数据进行更新。

详见 §4 实时预览 - PreviewStreamParamsUpdate。