本文档描述了云手机 Android 客户端 SDK 提供的接口。 ## 接口概览 **生命周期接口** |接口名称 |接口描述 | |---|---| |[getStatus](/docs/6394/75742#.6I635Y-WLXZlcGhvbmVlbmdpbmUt55qE54q25oCB) |获取当前 vePhoneEngine 的状态 | |[prepare](/docs/6394/75742#.c2RrLXByZXBhcmUt5Ye95pWw) |设置 SDK 全局上下文对象，并下载插件 | |[start](/docs/6394/75742#.5byA5aeL5pKt5pS-) |启动云手机，开始拉流播放 | |[stop](/docs/6394/75742#.5YGc5q2i) |停止拉流并通知服务端释放实例资源 | |[addCloudCoreManagerListener](/docs/6394/75742#.6I635Y-WLXZlcGhvbmVlbmdpbmUt55qE54q25oCB) |设置生命周期回调监听 | |[removeCloudCoreManagerListener](/docs/6394/75742#.6I635Y-WLXZlcGhvbmVlbmdpbmUt55qE54q25oCB) |取消生命周期回调监听 | |[ICloudCoreManagerStatusListener](/docs/6394/75742#.6I635Y-WLXZlcGhvbmVlbmdpbmUt55qE54q25oCB) |vePhoneSDK 生命周期回调 | **音视频控制接口** |接口名称 |接口描述 | |---|---| |[pause](/docs/6394/75742#.5pqC5YGc) |暂停从云机拉流 | |[resume](/docs/6394/75742#.5oGi5aSN) |恢复从云机拉流 | |[muteAudio](/docs/6394/75742#.6Z2Z6Z-z5byA5YWz) |媒体流静音开关 | |[isAudioMuted](/docs/6394/75742#.6Z2Z6Z-z5byA5YWz) |检查当前是否处在静音状态 | |[muteVideo](/docs/6394/75742#.6KeG6aKR5byA5YWz) |媒体流视频开关 | |[isVideoMuted](/docs/6394/75742#.6KeG6aKR5byA5YWz) |检查视频播放状态 | |[getLocalAudioPlaybackVolume](/docs/6394/75742#.6LCD6IqC5pys5Zyw5pKt5pS-5ZKM6YeH6ZuG6Z-z6YeP) |获取客户端本地播放音量 | |[setLocalAudioPlaybackVolume](/docs/6394/75742#.6LCD6IqC5pys5Zyw5pKt5pS-5ZKM6YeH6ZuG6Z-z6YeP) |设置客户端本地播放音量 | |[setLocalAudioCaptureVolume](/docs/6394/75742#.6LCD6IqC5pys5Zyw5pKt5pS-5ZKM6YeH6ZuG6Z-z6YeP) |设置采集客户端本地音量 | |[setJitterBufferDelay](/docs/6394/75742#.6K6-572u6Z-z6aKRLWppdHRlcmJ1ZmZlci3nvJPlhrLml7bplb8=) |设置音频 JitterBuffer 缓冲时长 | |[getJitterBufferDelay](/docs/6394/75742#.6K6-572u6Z-z6aKRLWppdHRlcmJ1ZmZlci3nvJPlhrLml7bplb8=) |获取音频 JitterBuffer 缓冲时长 | |[setAudioPlaybackDevice](/docs/6394/75742#.6K6-572u6Z-z6aKR6L6T5YWl6L6T5Ye65rqQ) |指定音频播放设备 | |[startSendAudioStream](/docs/6394/75742#.5byA5ZCvLeWFs-mXremfs-mikeaVsOaNruWPkemAgQ==) |采集并发送音频数据 | |[stopSendAudioStream](/docs/6394/75742#.5byA5ZCvLeWFs-mXremfs-mikeaVsOaNruWPkemAgQ==) |关闭音频数据发送 | |[setAudioSourceType](/docs/6394/75742#.6Z-z6aKR6Ieq6YeH6ZuG) |设置音频数据的采集模式 | |[pushExternalAudioFrame](/docs/6394/75742#.6Z-z6aKR6Ieq6YeH6ZuG) |音频自采集推流接口 | |[publishLocalAudio](/docs/6394/75742#.6Z-z6aKR6Ieq6YeH6ZuG) |发布本地音频 | |[unpublishLocalAudio](/docs/6394/75742#.6Z-z6aKR6Ieq6YeH6ZuG) |取消发布本地音频 | |[switchCamera](/docs/6394/75742#.Y2FtZXJhLeazqOWFpQ==) |切换前后摄像头 | |[startVideoStream](/docs/6394/75742#.Y2FtZXJhLeazqOWFpQ==) |开始指定摄像头采集并推流 | |[stopVideoStream](/docs/6394/75742#.Y2FtZXJhLeazqOWFpQ==) |停止摄像头采集和推流 | |[enableAutoMaxScreenBrightness](#.Y2FtZXJhLeazqOWFpQ==) |当云端请求前置摄像头时，本地设备是否自动调整屏幕亮度到最大 | |[isAutoMaxScreenBrightnessEnabled](#.Y2FtZXJhLeazqOWFpQ==) |查询是否自动调整屏幕亮度到最大的设置 | |[setLocalVideoCanvas](/docs/6394/75742#.Y2FtZXJhLeazqOWFpQ==) |设置本地视频画面布局 | |[setLocalVideoMirrorMode](/docs/6394/75742#.Y2FtZXJhLeazqOWFpQ==) |镜像翻转本地摄像头画面 | |[setVideoEncoderConfig](/docs/6394/75742#.Y2FtZXJhLeazqOWFpQ==) |配置本地视频编码质量策略 | |[updateVideoRenderMode](/docs/6394/75742#.5pu05paw55S76Z2i5riy5p-T5qih5byP) |更新画面渲染模式 | |[setVideoSourceType](/docs/6394/75742#.6KeG6aKR6Ieq6YeH6ZuG) |设置视频数据的采集模式 | |[pushExternalVideoFrame](/docs/6394/75742#.6KeG6aKR6Ieq6YeH6ZuG) |视频自采集推流接口 | |[publishLocalVideo](/docs/6394/75742#.6KeG6aKR6Ieq6YeH6ZuG) |发布本地视频 | |[unpublishLocalVideo](/docs/6394/75742#.6KeG6aKR6Ieq6YeH6ZuG) |取消发布本地视频 | |[setAudioInjectionState](/docs/6394/75742#.6Z-z6aKR5rOo5YWl54q25oCB) |开启/关闭音频注入功能 | |[setVideoInjectionState](/docs/6394/75742#.Y2FtZXJhLeazqOWFpQ==) |开启/关闭视频注入功能 | |[getAudioInjectionState](/docs/6394/75742#.6Z-z6aKR5rOo5YWl54q25oCB) |查询音频注入功能状态 | |[getVideoInjectionState](/docs/6394/75742#.Y2FtZXJhLeazqOWFpQ==) |查询视频注入功能状态 | |[setAudioInjectionListener](/docs/6394/75742#.6Z-z6aKR5rOo5YWl54q25oCB) |注册音频注入开关及状态回调 | |[setVideoInjectionListener](/docs/6394/75742#.Y2FtZXJhLeazqOWFpQ==) |注册视频注入开关及状态回调 | **运行状态监控接口** |接口名称 |接口描述 | |---|---| |[IPlayerListener](/docs/6394/75742#.5byA5aeL5pKt5pS-) |拉流播放状态监听 | |[IStreamListener](/docs/6394/75742#.5byA5aeL5pKt5pS-) |获取音视频流信息监听 | |[IMessageReceiver](/docs/6394/75742#.5pS25Y-R5raI5oGv) |消息接收回调监听 | |[setStreamProfileChangeListener](/docs/6394/75742#.5riF5pmw5bqm5YiH5o2i) |设置清晰度切换回调监听 | **进程相关接口** |接口名称 |接口描述 | |---|---| |[setAccelerometerSensorState](/docs/6394/75742#.5Lyg5oSf5Zmo5byA5YWz) |加速度传感器开关 | |[setGyroSensorState](/docs/6394/75742#.5Lyg5oSf5Zmo5byA5YWz) |陀螺仪传感器开关 | |[setGravitySensorState](/docs/6394/75742#.5Lyg5oSf5Zmo5byA5YWz) |重力传感器开关 | |[setOrientationSensorState](/docs/6394/75742#.5Lyg5oSf5Zmo5byA5YWz) |方向传感器开关 | |[setMagneticSensorState](/docs/6394/75742#.5Lyg5oSf5Zmo5byA5YWz) |磁力传感器开关 | |[setVibratorState](/docs/6394/75742#.6ZyH5Yqo5byA5YWz) |本地震动传感器开关 | |[setLocationServiceState](/docs/6394/75742#.5a6a5L2N5Yqf6IO9) |本地位置信息开关 | |[setRemoteLocationMock](/docs/6394/75742#.5a6a5L2N5Yqf6IO9) |手动设置云手机的经纬度信息 | |[setLocationServiceMode](/docs/6394/75742#.5a6a5L2N5Yqf6IO9) |设置远端请求位置信息的模式 | |[rotate](/docs/6394/75742#.5bGP5bmV5peL6L2s) |旋转云手机画面方向 | |[setVideoRotationMode](/docs/6394/75742#.5YiH5o2i5peL6L2s5qih5byP) |切换视频旋转模式 | |[getVideoRotationMode](/docs/6394/75742#.5YiH5o2i5peL6L2s5qih5byP) |获取已设置的视频旋转模式 | |[sendKeyEvent](/docs/6394/75742#.5Y-R6YCB6ZSu55uY5LqL5Lu25oyH5Luk) |发送键盘事件指令 | |[setInterceptSendTouchEvent](/docs/6394/75742#.5Zue5Lyg6Kem5o6n5LqL5Lu2) |设置是否拦截 SDK 向云机实例发送的触控事件 | |[launchApp](/docs/6394/75742#.5ZCv5YqoLeWFs-mXreS6keacui1hcHA=) |启动云机 App | |[closeApp](/docs/6394/75742#.5ZCv5YqoLeWFs-mXreS6keacui1hcHA=) |关闭云机 App | |[switchBackground](/docs/6394/75742#.5a6i5oi356uv5YmN5ZCO5Y-w5YiH5o2i) |设置客户端应用切换前后台的状态 | |[setRemoteAppForeground](/docs/6394/75742#.5LqR5py65bqU55So5YiH5o2i5YmN5Y-w) |将云机应用切换到前台 | |[setIdleTime](/docs/6394/75742#.6K6-572u5L-d5rS75pe26Ze0) |设置客户端切后台之后，云机服务的保活时间 | |[setAutoRecycleTime](/docs/6394/75742#.6K6-572uLeiOt-WPluaXoOaTjeS9nOWbnuaUtuacjeWKoeaXtumXtA==) |设置无操作推流回收服务时间 | |[getAutoRecycleTime](/docs/6394/75742#.6K6-572uLeiOt-WPluaXoOaTjeS9nOWbnuaUtuacjeWKoeaXtumXtA==) |获取已设置的无操作回收服务时间 | |[enableControl](/docs/6394/75742#.5pON5o6n5p2D5o6n5Yi2) |开启或关闭用户对云手机的操控权 | |[sendMessage](/docs/6394/75742#.5pS25Y-R5raI5oGv) |与云机实例之间收发消息 | |[getLocalInputManager](/docs/6394/75742#.5pys5Zyw6ZSu55uY) |管理本地键盘与云机应用的交互 | |[sendClipBoardMessage](/docs/6394/75742#.5Y-R6YCB5Ymq6LS05p2_5raI5oGv) |发送本地剪贴板消息到云机 | |[switchVideoStreamProfile](/docs/6394/75742#.5riF5pmw5bqm5YiH5o2i) |切换视频流的清晰度 | |[screenShot](/docs/6394/75742#.5LqR5omL5py655S76Z2i5oiq5Zu-) |云手机画面截图 | |[startRecording](/docs/6394/75742#.5LqR5omL5py655S76Z2i5b2V5bGP) |开始云手机画面录屏 | |[stopRecording](/docs/6394/75742#.5LqR5omL5py655S76Z2i5b2V5bGP) |停止云手机画面录屏 | |[getFocusedWindowApp](/docs/6394/75742#.5p-l6K-i5bGP5bmV5b2T5YmN54Sm54K55bqU55So) |获取屏幕当前焦点窗口应用 | |[setNavBarStatus](/docs/6394/75742#.5a-86Iiq5qCP5byA5YWz) |设置导航栏开关状态 | |[getNavBarStatus](/docs/6394/75742#.5a-86Iiq5qCP5byA5YWz) |查询云手机当前导航栏开关设置 | |[updateExpireTime](/docs/6394/75742#.5pu05pawLXRva2VuLeacieaViOacnw==) |更新拉流 Token 有效期 | |[startPushFile](#.5pS25Y-R5paH5Lu2) |启动客户端向云机实例推送文件 | |[stopPushFile](#.5pS25Y-R5paH5Lu2) |停止客户端向云机实例推送文件 | |[startPullFile](#.5pS25Y-R5paH5Lu2) |启动客户端拉取云机实例上的文件 | |[stopPullFile](#.5pS25Y-R5paH5Lu2) |停止客户端拉取云机实例上的文件 | **调试及日志接口** |接口名称 |接口描述 | |---|---| |[setDebug](/docs/6394/75742#.6K6-572uLWRlYnVnLeaooeW8jw==) |是否设置调试模式 | |[getDeviceId](/docs/6394/75742#.6I635Y-W6K6-5aSHLWlk) |获取 SDK 生成的设备 ID | |[getSDKVersion](/docs/6394/75742#.6I635Y-WLXNkay3niYjmnKzkv6Hmga8=) |获取 SDK 版本信息 | ## 生命周期接口 ### 获取 vePhoneEngine 的状态描述：获取当前 vePhoneEngine 的状态，状态说明如下： |状态 |说明 | |---|---| |1. (0x0001) |未初始化状态 | |2. (0x0002) |初始化成功 | |3. (0x0004) |正常调用 start 接口 | |5. (0x0008) |收到云机首帧 | |6. (0x0010) |停止拉取云机视音频流，但不会改变云机的运行状态 | 参考以下示例： ```java // vePhoneEngine class int getStatus() ``` ```java // vePhoneEngine class void addCloudCoreManagerListener(@NonNull ICloudCoreManagerStatusListener listener) void removeCloudCoreManagerListener(@NonNull ICloudCoreManagerStatusListener listener) public interface ICloudCoreManagerStatusListener { void onPrepared(); } ``` **addCloudCoreManagerListener(listener)** 描述：设置 vePhoneEngine 生命周期回调监听。 **removeCloudCoreManagerListener(listener)** 描述：取消 vePhoneEngine 生命周期回调监听。 **ICloudCoreManagerStatusListener** 描述：vePhoneEngine 生命周期回调。 |接口名称 |接口描述 | |---|---| |onPrepared() |SDK 初始化成功回调 | ### SDK prepare 函数描述：`prepare` 函数主要作用是设置 SDK 的 Android Application 全局上下文对象，并开始下载对应的插件。因此需要在调用 `start` 接口前调用 vePhoneEngine 的 `prepare` 函数。注意：调用 vePhoneEngine `prepare` 函数就是正式开始使用 SDK 了。因此在运行过程中需要采集必要的用户信息。在调用 vePhoneEngine 的 `prepare` 函数前，必须提示并获得用户授权。如果用户已经授权过，则可以在 Application `onCreate` 的时候调用（vePhone SDK 需要采集的必要信息和可选信息，参考 [云手机 SDK 隐私政策](/docs/6394/70477)）。 > * 第一次调用 `prepare` 函数时，SDK 会进行一次资源异步加载。如果资源加载失败，不需要重新调用 `prepare`。SDK 会在调用 `start` 接口启动游戏时检查资源是否已成功加载，如果没有，则会重新进行异步资源的加载待加载成功后会进行真正的 start。资源加载完成后会，有 `ICloudCoreManagerStatusListener` 的 `onPrepared` 回调。 > * `prepare` 函数只需要调用一次。特别注意：多进程会多次执行 Application 的 `onCreate`，需要在 `onCreate` 中添加当前进程判断。详细信息，可参考 [Github Demo](https://github.com/volcengine/vePhone/tree/main/Quick%20Start/Android)。 ```java /** * vePhoneEngine class * @param application Android上下文 */ public void prepare(Application application) ``` #### 火山引擎账号在申请云手机服务之前，需要在 `\app\src\main\AndroidManifest.xml` 文件的 meta\-data 中填入注册的火山引擎用户账号（`VOLC_ACCOUNT_ID`）。参考以下示例： ```java ``` > 可通过火山引擎官网页面右上角 **用户 \> 账号管理 \> 主账号信息** 获取用户账号。 ### 开始播放描述：当成功初始化完成后，可以调用 `start()`，拉流开始播放。入参：`config` 返回值：开始播放触发的回调为 `IStreamListener` 的 `onFirstRemoteVideoFrame` 参考以下示例： ```java public void start(@NonNull PhonePlayConfig config, @NonNull IPlayerListener playerListener) ``` `config` 字段描述如下： |名称 |参数范围 |是否必填 |说明 | |---|---|---|---| |userId |String |是 |自定义客户端用户 ID，用于标识用户在流媒体房间中的身份，小于64位 | |accountId |String |否 |用于动态修改用户的火山引擎账号。|\ | | | |:::warning|\ | | | |当修改此账号时，需要同步修改传入的 `ak`、`sk`、`token` 参数。该参数若不填写，SDK 会默认读取 AndroidManifest.xml 中声明的 `accountId`。|\ | | | ||\ | | | |:::| |ak |String |是 |用于用户鉴权的临时 Access Key，通过调用服务端 STSToken 接口获取，参考 [临时 Token 签发](/docs/6394/75752) | |sk |String |是 |用于用户鉴权的临时 Secret Key，通过调用服务端 STSToken 接口获取，参考 [临时 Token 签发](/docs/6394/75752) | |token |String |是 |用于用户鉴权的临时 Token，通过调用服务端 STSToken 接口获取，参考 [临时 Token 签发](/docs/6394/75752) | |productId |String |是 |云手机业务 ID，可通过火山引擎云手机控制台『业务管理』页面获取 | |roundId |String |否 |当次启动的生命周期标识，可以用该参数查询使用时长，链路日志等|\ | | | |命名规则如下：|\ | | | ||\ | | | |* 最大长度为128位的非空字符串，支持的字符集范围为:|\ | | | |* 大写字母 A ~ Z|\ | | | |* 小写字母 a ~ z|\ | | | |* 数字 0 ~ 9|\ | | | |* 下划线 "_", 减号 "\-" | |container |FrameLayout 或其子类 |是 |用来承载画面的 Container | |podId |String |否 |实例 ID，可通过火山引擎云手机控制台『实例管理』页面获取（**如不指定，则由具体调度逻辑调度** **Pod**） | |appId |String |否 |需要启动的应用 ID（**推流时直接打开应用**），可通过火山引擎云手机控制台『应用管理』页面获取 | |configurationCode |String |否 |火山侧套餐 ID | |enableLocalKeyboard |Boolean |否 |是否启用手机本地输入法（默认为 false） | |setLightSensorState |Boolean |否 |是否开启光线传感器（默认为 false） | |setMagneticSensorState |Boolean |否 |是否使能磁力传感器（默认为 false），建议同时开启的传感器数量不超过三个。 | |setAccelerometerSensorState |Boolean |否 |是否使能加速度传感器（默认为 false），建议同时开启的传感器数量不超过三个。 | |setGravitySensorState |Boolean |否 |是否使能重力传感器（默认为 false），建议同时开启的传感器数量不超过三个。 | |setOrientationSensorState |Boolean |否 |是否使能方向传感器（默认为 false），建议同时开启的传感器数量不超过三个。 | |setGyroSensorState |Boolean |否 |是否使能陀螺仪传感器（默认为 false），建议同时开启的传感器数量不超过三个。 | |setVibratorState |Boolean |否 |是否开启震动传感器（默认为 true），建议同时开启的传感器数量不超过三个。 | |setLocationServiceState |Boolean |否 |是否使能定位服务（默认为 false） | |remoteLocationMock |LocationInfo |否 |指定云机定位数据：|\ | | | ||\ | | | |* latitude：纬度|\ | | | |* longitude：经度 | |locationStrategy |String |否 |定位数据上传方案（默认为 GPS）：|\ | | | ||\ | | | |* GPS（默认的定位同步方案，能满足静止、步行导航等一般性的定位需求）|\ | | | |* NMEA（高性能定位同步方案，上报频率和对网络传输延迟要求均较高，适用于云机导航等场景） | |rotation |Rotation |否 |屏幕的横竖屏模式，建议使用默认设置 AUTO_ROTATION | |reset |Boolean |否 |退出后，是否重置设备环境：|\ | | | ||\ | | | |* true: 重置|\ | | | |* false: 不重置（默认） | |videoStreamProfileId |Int |否 |清晰度档位 ID，可选枚举值和对应的清晰度配置，参考 [云手机清晰度档位说明](/docs/6394/155915) | |autoRecycleTime |Int |否 |设置无操作自动回收服务时长，单位秒（如不设置或设置为0，则使用默认时长300秒，支持设置的上限值为7200，即2小时） | |streamType |String |否 |指定启动云手机时拉取音视频流类型（如不指定，则正常拉取音视频流）：|\ | | | ||\ | | | |* VIDEO（仅拉取视频流，不拉取音频流）|\ | | | |* AUDIO（仅拉取音频流，不拉取视频流）|\ | | | |* BOTH（启动后音视频正常拉流，默认） | |remoteWindowSize |Int |否 |设置云机推流分辨率（width 和 height），取值范围 \>= 0，说明如下：|\ | | | ||\ | | | |* 如果不传，默认获取初始化时 Container 的宽高作为请求参数上传；|\ | | | |* 当 width = 0，height = 0 时，服务端按照原始画面和分辨率推流；|\ | | | |* 当 width \> 0， height \> 0 时，将指定的宽高作为请求参数上传给服务端做分辨率适配（如果云机屏幕为竖屏，指定的 width 必须小于 height）；|\ | | | |* 其他情况把初始化时 Container 的宽高作为请求参数上传 | |videoRenderMode |Int |否 |指定视频流渲染模式：|\ | | | ||\ | | | |* 0：（VIDEO_RENDER_MODE_FIT，等比缩放居中模式，默认）|\ | | | |* 1：（VIDEO_RENDER_MODE_FILL，非等比拉伸模式）|\ | | | |* 2：（VIDEO_RENDER_MODE_COVER，等比例缩放模式）|\ | | | ||\ | | | |渲染模式的详细说明，参考 [更新画面渲染模式](/docs/6394/75742#.5pu05paw55S76Z2i5riy5p-T5qih5byP) | |videoRotationMode |Int |否 |指定视频旋转模式：|\ | | | ||\ | | | |* 0：（EXTERNAL，外部旋转，默认值；此模式下，用户需通过监听 `IStreamListener.onRotation` 回调，从外部调整页面方向从而实现画面方向与云手机实例同步）|\ | | | |* 1：（INTERNAL，内部旋转；此模式下，SDK 内部对画面进行方向处理，外部不需要做任何画面方向的处理） | |renderViewType |Int |否 |视频流渲染组件（不同类型的主要差异在转场动画、渲染性能等方面）：|\ | | | ||\ | | | |* 1（SURFACE_VIEW，默认）|\ | | | |* 2（TEXTURE_VIEW） | |userTag |String |否 |用户标签，由业务方指定 | |extra |Map |否 |根据业务需要，自定义扩展参数 | |waitTime |int |否 |云手机实例进房后，等待客户端加入房间的最大允许时长。当云手机处于房间中而没有客户端加入，或者所有客户端都已离开房间后，云手机将在到达此参数设置的时长后自动退出房间。|\ | | | |单位为 s，默认值为 10，取值范围为 [10, 259200]，传入非法参数时自动调整为默认值即 10s。|\ | | | |请根据实际需求合理设置此参数，以确保云手机在没有客户端活动时能够及时释放资源。 | |expireTime |long |否 |拉流 Token 有效期，单位为秒，取值范围 [0,172800]，即 2 天。若不设置本参数，Token 有效期会始终在后台自动更新；若设置本参数，Token 有效期则本参数中的设置为准。 | `config` 最简配置参考示例（必填参数）： ```java PhonePlayConfig.Builder builder = new PhonePlayConfig.Builder(); builder.userId("your_user_id") .container(mContainer) .ak("your_ak") .sk("your_sk") .token("token") .productId("your_product_id") PhonePlayConfig config = builder.build(); ``` `config` 完整配置参考示例： ```java PhonePlayConfig.Builder builder = new PhonePlayConfig.Builder(); PhonePlayConfig config = builder.userId("your_user_id") .container(layout) .ak("your_ak") .sk("your_sk") .token("token") .productId("your_product_id") .podId("pod_id") .appId("your_app_id") .roundId("round_id") .rotation("landscape") .userTag("tag01") .configurationCode("config_code") .enableLocalKeyboard(false) .setMagneticSensorState(false) .setAccelerometerSensorState(false) .setGravitySensorState(false) .setGyroSensorState(false) .setLocationServiceState(false) .setOrientationSensorState(false) .setVibratorState(false) .reset(false) .videoStreamProfileId(1) .autoRecycleTime(120) .streamType(VIDEO) .waitTime(120) .renderViewType(RenderViewType.SURFACE_VIEW) .extra(new HashMap()); ``` #### IPlayerListener 拉流播放状态回调监听： |接口名称 |接口描述 | |---|---| |onServiceInit(Map extras) |加入房间前回调，用于获取并初始化各个功能服务，例如设置各种事件监听回调：|\ | ||\ | |* extras：保留参数，用于透传一些额外参数 | |onPlaySuccess(String roundId, int videoStreamProfileId) |播放成功回调：|\ | ||\ | |* roundId：当次启动的生命周期标识符|\ | |* videoStreamProfileId：当前云手机画面的清晰度，首帧渲染到画面时触发该回调 | |onNetworkChanged(int type) |网络连接类型和状态切换回调：|\ | ||\ | |* \-1: 网络连接类型未知|\ | |* 0: 网络连接已断开|\ | |* 1: 网络类型为 LAN|\ | |* 2: 网络类型为 Wi\-Fi（包含热点）|\ | |* 3: 网络类型为 2G 移动网络|\ | |* 4: 网络类型为 3G 移动网络|\ | |* 5: 网络类型为 4G 移动网络|\ | |* 6: 网络类型为 5G 移动网络 | |onWarning(int code, String message) |SDK 内部产生告警回调，参考 [警告码](/docs/6394/75742#.6K2m5ZGK56CB5Y-K6K-05piO) | |onError(int code, String message) |SDK内部产生错误回调，参考 [错误码](/docs/6394/75742#.6ZSZ6K-v56CB5Y-K6K-05piO)|\ | |> 注意：在出现报错时，需要调用 `stop()` 接口，恢复到初始状态，排查问题后，再调用 `start()`。 | 参考示例： ```java public interface IPlayerListener { void onServiceInit(@NonNull Map extras); void onPlaySuccess(String roundId, int videoStreamProfileId); void onNetworkChanged(int type); void onWarning(int code, String message); void onError(int code, String message); } ``` #### IStreamListener 获取音视频流信息回调监听。 |接口名称 |接口描述 | |---|---| |onFirstAudioFrame(String uid) |订阅视频流到收到音频首帧回调：|\ | ||\ | |* uid：远端实例视频流 ID | |onFirstRemoteVideoFrame(String uid) |订阅视频流到收到视频首帧回调：|\ | ||\ | |* uid：远端实例视频流 ID | |onStreamPaused() |调用 `pause()`，暂停播放后的回调 | |onStreamResumed() |调用 `resumeplay()` 或 `muteAudio(false)`，恢复播放后的回调 | |onStreamStats(StreamStats streamStats) |视频流的当前性能状态回调：|\ | ||\ | |* streamStats：远端数据间视频流的性能状态，参考以下 **StreamStats 类型说明** | |onStreamConnectionStateChanged(int state) |视频流连接状态变更回调：|\ | ||\ | |* 1：连接断开|\ | |* 2：首次连接，正在连接中|\ | |* 3：首次连接成功|\ | |* 4：连接断开后重新连接中|\ | |* 5：连接断开后重连成功|\ | |* 6：网络连接断开超过 10 秒，仍然会继续重连 | |onNetworkQuality(int quality) |网络质量回调，每隔 2 秒上报一次网络质量评级：|\ | ||\ | |* quality：网络质量评级（可根据当前返回的网络质量评级进行推流参数降级或者终止拉流；详细信息，参考以下**onNetworkQuality 相关信息**） | |onDetectDelay(long elapse) |当前操作延迟回调，单位毫秒 | |onRotation(@NonNull RotationState state) |客户端旋转回调 | |onPodExit(int reason, String msg) |实例端退出回调，参考以下 **onPodExit 相关信息** | 参考示例： ```java public PhonePlayConfig.Builder streamListener(IStreamListener listener)``` ```java public interface IStreamListener { void onFirstAudioFrame(String uid); void onFirstRemoteVideoFrame(String uid); void onStreamPaused(); void onStreamResumed(); void onStreamStats(StreamStats streamStats); void onStreamConnectionStateChanged(int state); void onNetworkQuality(int quality); void onDetectDelay(long elapse); void onRotation(@NonNull RotationState state); void onPodExit(int reason, String msg); } ``` #### onPodExit 相关信息 |错误码 |错误信息 |说明 | |---|---|---| |40000 |ERROR_REMOTE_ABNORMAL_EXIT |实例退出。原因：云机服务异常退出。建议：请联系火山引擎云手机服务对接人员。 | |40001 |ERROR_REMOTE_OPENAPI_EXIT |实例退出。原因：通过控制台操作或调用服务端 OpenAPI 接口退出，属于符合预期的操作。 | |40002 |ERROR_REMOTE_INVISIVLE |实例退出。原因：云机实例状态被切换为不可见，属于符合预期的操作。 | |40003 |ERROR_REMOTE_KICKOFF |实例退出。原因：用户被断开连接，属于符合预期的操作。 | |40004 |ERROR_STREAM_STOPPED_AUTO_RECYCLE |实例退出。原因：用户长时间未操作，服务端自动断开应用连接。 | |40005 |ERROR_REMOTE_EXIT |实例退出。原因：服务端主动退出。 | |40006 |ERROR_REMOTE_STOPPED_API |应用停止。原因：服务端主动停止了应用。 | |40007 |ERROR_DUPLICATE_USER |应用停止。原因：在不同设备上，前后使用了相同的 userId 和 appId，前一个 start 请求会返回此错误码。建议：请检查调用启动云手机接口的参数是否重复。如果需要重新启动被停止的应用，请再次使用相同的 userId 和 appId 调用启动云手机接口。 | |40008 |ERROR_POD_STOPPED_BACKGROUND_TIMEOUT |应用停止。原因：应用切换后台，超过指定的保活时长未切换前台，服务端自动断开连接。建议：客户端需要提示用户因为应用切后台超过保活时长，连接断开。 | |40009 |ERROR_POD_EXIT_GENERAL |应用停止。原因：云机服务退出。建议：请联系火山引擎技术支持。 | |40011 |ERROR_REMOTE_POWER_OFF |实例异常退出。原因：云机实例关机。建议：重启云机实例。 | #### onNetworkQuality 相关信息网络质量评级说明： |接口名称 |接口描述 |接口描述 | |---|---|---| |2 |NETWORK_QUALITY_GOOD |表示当前网络状况良好，能够较好地承载当前业务 | |4 |NETWORK_QUALITY_BAD |表示当前网络质量欠佳，会影响当前业务的主观体验 | |5 |NETWORK_QUALITY_VERY_BAD |表示当前网络已经无法承载当前业务的媒体流，需要采取相应策略，比如降低媒体流的码率或者更换网络 | |6 |NETWORK_QUALITY_DOWN |表示当前网络完全无法正常通信 | #### StreamStats 类型说明 |接口名称 |接口描述 | |---|---| |getReceivedVideoBitRate() |获取视频接收码率瞬时值（单位 kbps） | |getReceivedAudioBitRate() |获取音频接收码率瞬时值（单位 kbps） | |getDecoderOutputFrameRate() |获取解码器输出帧率（单位 fps） | |getRendererOutputFrameRate() |获取渲染帧率（单位 fps） | |getReceivedResolutionHeight() |获取远端视频流高度 | |getReceivedResolutionWidth() |获取远端视频流宽度 | |getVideoLossRate() |丢包率 | |getRtt() |获取客户端与服务端往返延时（单位 ms） | |getE2eDelay() |获取用户体验级别的端到端延时，从发送端采集完成编码开始到接收端解码完成渲染开始的延时（单位 ms） | |getStallCount() |卡顿次数 | |getStallDuration() |获取卡顿时长（统计周期内的视频卡顿总时长，单位 ms） | |getFrozenRate() |获取卡顿率（视频卡顿的累计时长占视频总有效时长的百分比） | |getVideoCodecType() |获取当前视频编码格式：|\ | ||\ | |* 0：unknown|\ | |* 1：H264|\ | |* 2：H265 | 参考示例： ```java public class StreamStats { private int receivedVideoBitRate; private int receivedAudioBitRate; private int decoderOutputFrameRate; private int rendererOutputFrameRate; private int receivedResolutionHeight; private int receivedResolutionWidth; private float videoLossRate; private int rtt; private int e2eDelay; private int stallCount; private int stallDuration; private int frozenRate; public int getReceivedVideoBitRate() { return receivedVideoBitRate; } public int getReceivedAudioBitRate() { return receivedAudioBitRate; } public int getDecoderOutputFrameRate() { return decoderOutputFrameRate; } public int getRendererOutputFrameRate() { return rendererOutputFrameRate; } public int getReceivedResolutionHeight() { return receivedResolutionHeight; } public int getReceivedResolutionWidth() { return receivedResolutionWidth; } public int getVideoLossRate() { return videoLossRate; } public int getRtt() { return rtt; } public int getE2eDelay() { return e2eDelay; } public int getStallCount() { return stallCount; } public int getStallDuration() { return stallDuration; } public int getFrozenRate() { return frozenRate; } public int getVideoCodecType() { return videoCodecType; } } ``` #### LocalStreamStats **本地音频流数据统计（LocalAudioStreamStats）：** |**参数** |**类型** |**描述** | |---|---|---| |audioLossRate |Float |音频丢包率；此次统计周期内的音频上行丢包率，单位为 % ，取值范围为 [0,1] | |sendKBitrate |Float |发送码率；此次统计周期内的音频发送码率，单位为 kbps | |recordSampleRate |Integer |采集采样率；此次统计周期内的音频采集采样率信息，单位为 Hz | |statsInterval |Integer |统计间隔；此次统计周期的间隔，单位为 ms | |rtt |Integer |往返时延；单位为 ms | |numChannels |Integer |音频声道数 | |sentSampleRate |Integer |音频发送采样率；此次统计周期内的音频发送采样率信息，单位为 Hz | **本地视频流数据统计（LocalVideoStreamStats）：** |**参数** |**类型** |**描述** | |---|---|---| |sentKBitrate |Float |发送码率；此次统计周期内的视频发送码率，单位为 kbps | |inputFrameRate |Integer |采集帧率；此次统计周期内的视频采集帧率，单位为 fps | |sentFrameRate |Integer |发送帧率；此次统计周期内的视频发送帧率，单位为 fps | |encoderOutputFrameRate |Integer |编码器输出帧率；当前编码器在此次统计周期内的输出帧率，单位为 fps | |rendererOutputFrameRate |Integer |本地渲染帧率；此次统计周期内的本地视频渲染帧率，单位为 fps | |targetKBitrate |Integer |目标发送码率；此次统计周期内的视频目标发送码率，单位为 kbps | |targetFrameRate |Integer |目标发送帧率；当前编码器在此次统计周期内的目标发送帧率，单位为 fps | |statsInterval |Integer |统计间隔；单位为 ms | |videoLossRate |Float |视频丢包率；此次统计周期内的视频上行丢包率，取值范围： [0,1] | |rtt |Integer |往返时延；单位为 ms | |encodedBitrate |Integer |视频编码码率；此次统计周期内的视频编码码率，单位为 kbps | |encodedFrameWidth |Integer |视频编码宽度；单位为 px | |encodedFrameHeight |Integer |视频编码高度；单位为 px | |encodedFrameCount |Integer |此次统计周期内发送的视频帧总数 | |codecType |Integer |视频的编码类型 | 参考示例： ```java public class LocalStreamStats { public final LocalVideoStreamStats mLocalVideoStreamStats; public final LocalAudioStreamStats mLocalAudioStreamStats; public LocalStreamStats(LocalVideoStreamStats localVideoStreamStats, LocalAudioStreamStats localAudioStreamStats) { mLocalVideoStreamStats = localVideoStreamStats; mLocalAudioStreamStats = localAudioStreamStats; } public static class LocalVideoStreamStats { public float sentKBitrate; public int inputFrameRate; public int sentFrameRate; public int encoderOutputFrameRate; public int rendererOutputFrameRate; public int targetKBitrate; public int targetFrameRate; public int statsInterval; public float videoLossRate; public int rtt; public int encodedBitrate; public int encodedFrameWidth; public int encodedFrameHeight; public int encodedFrameCount; public int codecType; public LocalVideoStreamStats(float sentKBitrate, int inputFrameRate, int sentFrameRate, int encoderOutputFrameRate, int rendererOutputFrameRate, int targetKBitrate, int targetFrameRate, int statsInterval, float videoLossRate, int rtt, int encodedBitrate, int encodedFrameWidth, int encodedFrameHeight, int encodedFrameCount, int codecType) { this.sentKBitrate = sentKBitrate; this.inputFrameRate = inputFrameRate; this.sentFrameRate = sentFrameRate; this.encoderOutputFrameRate = encoderOutputFrameRate; this.rendererOutputFrameRate = rendererOutputFrameRate; this.targetKBitrate = targetKBitrate; this.targetFrameRate = targetFrameRate; this.statsInterval = statsInterval; this.videoLossRate = videoLossRate; this.rtt = rtt; this.encodedBitrate = encodedBitrate; this.encodedFrameWidth = encodedFrameWidth; this.encodedFrameHeight = encodedFrameHeight; this.encodedFrameCount = encodedFrameCount; this.codecType = codecType; } } public static class LocalAudioStreamStats { public float audioLossRate; public float sendKBitrate; public int recordSampleRate; public int statsInterval; public int rtt; public int numChannels; public int sentSampleRate; public LocalAudioStreamStats(float audioLossRate, float sendKBitrate, int recordSampleRate, int statsInterval, int rtt, int numChannels, int sentSampleRate) { this.audioLossRate = audioLossRate; this.sendKBitrate = sendKBitrate; this.recordSampleRate = recordSampleRate; this.statsInterval = statsInterval; this.rtt = rtt; this.numChannels = numChannels; this.sentSampleRate = sentSampleRate; } } } ``` #### 错误码启动云手机可能返回的错误码和相关说明如下： |错误码 |错误信息 |说明 | |---|---|---| |10000 |ERROR_START_GENERAL |启动云手机失败。原因：通用错误。建议：请检查 `start()` 接口参数。 | |10009 |ERROR_START_AUTHENTICATION_KEY_FAILED |开始游戏失败。原因：火山引擎服务鉴权失败。建议：请检查临时鉴权 Token 的有效期，参考 [生成临时 Token 接口](/docs/6394/75752)。 | |10011 |ERROR_START_CONNECTION_ENDED |启动云手机失败。原因：在调用启动接口后，且启动成功回调触发前，云手机被停止（可能是因为服务端应用崩溃或者调用了OpenAPI stop 请求）。 | |10020 |ERROR_STREAM_ID_NOT_EXIST |视频流 ID 不存在。原因：启动云手机时指定了视频流 ID，但是云机不存在与该视频流 ID 对应的虚拟屏。建议：检查实例已配置的正确视频流 ID。 | |10027 |ERROR_START_INVALID_LOCAL_TIME |启动云手机失败。原因：用户手机时间和服务端时间相差超过7天，导致鉴权 Token 过期。建议：需要客户端提示用户把手机时间修正为标准时间。 | |11001 |ERROR_START_PRODUCT_NOT_EXIST |启动云手机失败。原因：业务 ID 错误。建议：请通过火山引擎云手机控制台『业务详情』页面获取。 | |11002 |ERROR_START_APPLICATION_NOT_EXIST |启动云手机失败。原因：应用 ID 错误。建议：请通过火山引擎云手机控制台『应用管理』页面获取。 | |11003 |ERROR_START_CONFIGURATION_CODE_NOT_EXIST |启动云手机失败。原因：资源套餐 ID 错误。建议：请通过调用服务端 [ListPod](/docs/6394/75749) 接口获取。 | |11004 |ERROR_START_POD_NOT_EXIST |启动云手机失败。原因：实例 ID 错误。建议：请通过火山引擎云手机控制台『实例管理』页面获取。 | |11005 |ERROR_REQUEST_PARAMETER_BINDING_ERROR |请求参数绑定错误。建议：请检查请求参数是否正确。 | |11006 |ERROR_INVALID_REQUEST_PARAMETER |请求参数错误。建议：请检查请求参数是否正确。 | |11007 |ERROR_BUSINESS_ID_ERROR |业务 ID 错误。建议：请检查业务是否存在，可通过火山引擎云手机控制台『业务详情』页面获取。 | |11008 |ERROR_ACCOUNT_ID_INIT_ERROR |火山引擎账号 ID 错误。建议：请检查使用的账号和签名，可通过火山引擎官网页面右上角 **用户 \> 账号管理 \> 主账号信息** 获取正确的账号。 | |11009 |ERROR_ACCOUNT_ID_IS_INVALID |火山引擎账号 ID 不合法。建议：通过火山引擎官网页面右上角 **用户 \> 账号管理 \> 主账号信息** 获取正确的账号。 | |11010 |ERROR_USER_IS_INVALID |子账号不合法。建议：请检查子账号是否有业务和实例相关操作权限。可参考 [创建和管理子账号权限](/docs/6394/154568)。 | |11011 |ERROR_GENERIC_INSTANCE_ERROR |套餐、实例不存在。建议：请检查实例状态、订购的资源是否过期。 | |11012 |ERROR_INSTANCE_OFFLINE |实例离线。建议：请检查实例状态。 | |11013 |ERROR_UNIVERSAL_STARTUP_FAILED |启动云手机失败。 | |11014 |ERROR_INTERNAL_POD_START_FAILED |启动云手机失败。建议：请检查实例状态或联系火山引擎云手机技术支持。 | |11015 |ERROR_INTERNAL_POD_MUTE_FAILED |启动云手机失败。建议：请检查实例状态或联系火山引擎云手机技术支持。 | |11016 |ERROR_INTERNAL_CONFIG_FAILED |启动云手机失败。建议：请检查实例状态或联系火山引擎云手机技术支持。 | |11019 |ERROR_ACCOUNTID_MISMATCH |指定的火山引擎账号校验失败。建议：通过火山引擎官网页面右上角 **用户 \> 账号管理 \> 主账号信息** 获取正确的账号。 | |11020 |ERROR_POD_NOT_READY |云机实例未就绪。建议：请检查指定的实例已开机运行。 | |11021 |ERROR_DOWN_STREAM_UNKNOWN_ERROR |服务端下游错误。建议：请联系火山引擎云手机技术支持。 | ### 停止描述：停止从云机拉流，同时通知服务端释放实例资源（异步）。 ```java // vePhoneEngine class void stop() ``` ## 音视频控制接口 ### 暂停描述：当 vePhoneEngine 处于播放状态时，调用 `pause()` 暂停从云机拉流，此时并不改变云机的运行状态。返回值：暂停成功会收到 `onStreamPaused` 的接口回调。 ```java // vePhoneEngine class void pause() ``` ### 恢复描述：当 vePhoneEngine 处于暂停状态时，调用 `resumePlay()` 重新从云机拉流播放。返回值：恢复播放成功会收到 `onStreamResumed` 的接口回调。 ```java // vePhoneEngine class void resume() ``` ### 静音开关描述：媒体流静音开关，及检查静音状态。 ```java // vePhoneEngine class void muteAudio(boolean mute) //true: 静音; false: 开音。 boolean isAudioMuted() //当前是否处在静音状态，返回：true: 静音；false: 开音。 ``` ### 视频开关描述：媒体流视频开关，及检查视频状态。 ```java // vePhoneEngine class void muteVideo(boolean mute) //true: 停止播放视频流; false: 播放视频流。 boolean isVideoMuted() //当前是否处在暂停状态，返回：true: 暂停； false：播放。 ``` ### 调节本地播放和采集音量描述：调节客户端本地播放和采集音量。 ```java // AudioService class int getLocalAudioPlaybackVolume() //获取客户端本地播放音量 int setLocalAudioPlaybackVolume(int volume) //设置客户端本地播放音量，范围 [0,100] int setLocalAudioCaptureVolume(int volume) //设置采集客户端本地音量，范围 [0,100] ``` ### 设置音频 JitterBuffer 缓冲时长描述：设置（获取）音频 JitterBuffer 缓冲时长。 |接口名称 |接口描述 | |---|---| |setJitterBufferDelay(int delay, int duration) |设置音频 JitterBuffer 缓冲时长：|\ | ||\ | |* delay：音频 JitterBuffer 缓冲时长，单位：ms。当 delay<30ms 时，内部会处理成30以防止过低；可以通过设置 delay=0 使延迟时间恢复到正常值|\ | |* duration：平滑过渡时长，单位：ms，推荐设置为5000以上；该值越小，音频快放慢放现象越明显 | |getJitterBufferDelay() |获取音频 JitterBuffer 缓冲时长，返回：delay，单位：ms | ```java // AudioService class void setJitterBufferDelay(int delay, int duration); //设置音频JitterBuffer缓冲时长 int getJitterBufferDelay(); //获取音频JitterBuffer缓冲时长 ``` ### 设置音频输入输出源描述：设置或切换播放、采集音频的设备。 > * 设置音频播放设备时，需要保证已开启音频数据发送，否则设置无效； > * 当使用蓝牙耳机进行音频采集、播放时，需要获取蓝牙权限。 ```java // AudioService class void setAudioPlaybackDevice(deviceId) //指定音频播放设备（系统喇叭、外接喇叭和耳机、有线外接播放器，蓝牙播放器等） ``` ### 开启/关闭音频数据发送描述：开启或关闭采集麦克风音频数据后发送给云机实例，进而注入到实例的 Android 系统中。注意: 需要开启麦克风使用权限。 ```java // AudioService class void onRemoteAudioStartRequest() //收到云机实例请求开始发送音频数据事件 void onRemoteAudioStopRequest() //收到云机实例请求停止发送音频数据事件 int startSendAudioStream() //获取麦克风权限后，采集并发送音频数据 int stopSendAudioStream() //关闭音频数据发送，并且不进行音频采集 ``` ### 音频注入状态描述：设置及获取音频注入状态，用于多端同时对同一个 pod 进行拉流的场景。 |接口名称 |接口描述 | |---|---| |setAudioInjectionState(boolean state) |设置音频注入状态。|\ | |**参数**：|\ | |state：|\ | |true：开启|\ | |false：关闭|\ | |**返回值**：|\ | |0：调用成功|\ | |\-1：调用失败，DataChennel 为空 | |getAudioInjectionState() |获取音频注入状态。|\ | |**返回值**：|\ | |0：调用成功|\ | |\-1：调用失败，DataChennel 为空 | |setAudioInjectionState(boolean state) |设置音频注入状态监听器。|\ | |**参数**：listener \- 音频注入状态监听器，参看 `AudioInjectionListener` 说明 | ```java // AudioService class int setAudioInjectionState(boolean state); //设置音频注入状态 int getAudioInjectionState(); //获取音频注入状态 void setAudioInjectionListener(AudioInjectionListener listener); //设置音频注入状态监听器 ``` **AudioInjectionListener** 音频注入状态监听器 ```java interface AudioInjectionListener { /** * 音频注入状态改变的回调 * * @param callUserId 改变音频注入状态的用户ID * @param state 音频注入状态 true：开启 false：关闭 * @param code 错误码 0：成功 <0：失败 * @param msg 错误信息 */ void onAudioInjectionStateChanged(String callUserId, boolean state, int code, String msg); /** * 获取音频注入状态的结果回调 * * @param state 音频注入状态 true：开启 false：关闭 * @param code 错误码 0：成功 <0：失败 * @param msg 错误信息 */ void onGetAudioInjectionState(boolean state, int code, String msg); } ``` ### 音频自采集描述：设置音频数据的采集模式（自定义音频源或 SDK 内部采集音频），支持自采集音频数据。 ```java // AudioService class /** * 设置本地音频源类型 * @param index 音频流索引 * @param type 音频源类型 * @return -1表示调用失败，0表示调用成功 */ int setAudioSourceType(int index, int type); /** * 音频自采集推流接口 * @param index 音频流索引 * @param frame 音频帧 * @return -1表示调用失败，0表示调用成功 */ int pushExternalAudioFrame(int index, VeAudioFrame frame); /** * 发布本地音频，音频自采集需要调用此接口 * @return -1表示调用失败，0表示调用成功 */ int publishLocalAudio(); /** * 取消发布本地音频，音频自采集需要调用此接口 * @return -1表示调用失败，0表示调用成功 */ int unpublishLocalAudio(); ``` |接口名称 |接口描述 | |---|---| |setAudioSourceType(int index, int type) |设置音频数据的采集模式|\ | |**参数：** |\ | ||\ | |* index：音频流索引|\ | | * 0（主流）|\ | | * 1（屏幕流）|\ | |* type：音频源类型|\ | | * 0（自定义采集音频源）|\ | | * 1（内部采集音频源） | |publishLocalAudio() |发布本地音频，音频自采集需要调用此接口 | |unpublishLocalAudio() |取消发布本地音频，音频自采集需要调用此接口 | |pushExternalAudioFrame(int index, VeAudioFrame frame) |音频自采集推流接口（需要先调用 setAudioSourceType，将采集模式设置为自定义采集音频源，然后调用 publishLocalAudio 发布本地音频）|\ | |**参数：** |\ | ||\ | |* index：音频流索引|\ | |* frame：外部采集的音频流 | 参考示例： ```java private static class AudioRecordThread extends Thread { private final AudioRecord mAudioRecord; private static final int sampleRateInHz = VeAudioFrame.VeAudioSampleRate.AUDIO_SAMPLE_RATE_48000.value; private static final int samples = sampleRateInHz / 100; private static final int channelConfig = AudioFormat.CHANNEL_IN_MONO; private static final int audioFormat = AudioFormat.ENCODING_PCM_16BIT; private final int bufferSizeInBytes; private volatile boolean recording = true; private final AudioService mAudioService; @RequiresPermission(android.Manifest.permission.RECORD_AUDIO) private AudioRecordThread(AudioService audioService) { super("AudioRecordThread"); mAudioService = audioService; if (channelConfig == AudioFormat.CHANNEL_IN_MONO) { bufferSizeInBytes = samples * 2; } else { bufferSizeInBytes = samples * 2 * 2; } mAudioRecord = new AudioRecord( MediaRecorder.AudioSource.MIC, sampleRateInHz, channelConfig, audioFormat, bufferSizeInBytes ); } @Override public void run() { AudioDumper dumper = new AudioDumper(); // 设置音频源为SDK外部采集 mAudioService.setAudioSourceType(StreamIndex.MAIN, AudioSourceType.EXTERNAL); // 发布本地音频，需要先调用此接口才能调用后续的pushExternalAudioFrame mAudioService.publishLocalAudio(); try { mAudioRecord.startRecording(); byte[] audioBuffer = new byte[bufferSizeInBytes]; int offset = 0; int ret = 0; VeAudioFrame frame = new VeAudioFrame( 0, VeAudioFrame.VeAudioSampleRate.AUDIO_SAMPLE_RATE_48000, VeAudioFrame.VeAudioChannel.AUDIO_CHANNEL_MONO, ByteBuffer.allocateDirect(bufferSizeInBytes), 0, VeAudioFrame.VeAudioFrameType.FRAME_TYPE_PCM16 ); outer: while (recording) { offset = 0; long startTime = System.currentTimeMillis(); while (offset < bufferSizeInBytes && recording) { ret = mAudioRecord.read(audioBuffer, offset,bufferSizeInBytes - offset); if (ret < 0) { break outer; } offset += ret; } if (recording) { // Now we got audio frame data, deal with it. frame.timestamp_us = startTime; frame.dataSize = bufferSizeInBytes; frame.dataBuffer.clear(); frame.dataBuffer.put(audioBuffer); frame.dataBuffer.flip(); mAudioService.pushExternalAudioFrame(StreamIndex.MAIN, frame); } } } finally { mAudioRecord.stop(); mAudioService.unpublishLocalAudio(); // 可选：把音频输入源重新改回SDK内部采集 mAudioService.setAudioSourceType(StreamIndex.MAIN, AudioSourceType.INTERNAL); } } } ``` ### 增大/减小音量描述：增大或减小云机设备音量。 ```java // vePhoneEngine class void volumeUp() void volumeDown() ``` ### 更新画面渲染模式描述：更新视频流画面渲染模式。 |接口名称 |接口描述 | |---|---| |updateVideoRenderMode(int renderMode) |设置视频流的渲染模式，renderMode 的枚举值为：|\ | ||\ | |* 0：VIDEO_RENDER_MODE_FIT，等比缩放居中模式|\ | | * 画面等比缩放居中显示于 Container，当推流分辨率比例与 Container 比例一致时效果为全屏显示；|\ | | * 当推流分辨率与 Container 比例不一致时，效果为一个方向占满画布，另一个方向在两侧会有同等比例黑边；|\ | | * 无画面内容裁切|\ | |* 1：VIDEO_RENDER_MODE_FILL，非等比拉伸模式|\ | | * 非等比拉伸画面并充满整个 Container；|\ | | * 无画面内容裁切|\ | |* 2：VIDEO_RENDER_MODE_COVER，等比例缩放模式|\ | | * 画面短边撑满容器，长边被裁切；|\ | | * 可能有画面内容裁切 | 参考示例： ```java // vePhoneEngine class public interface VideoRenderModeManager { /** * * @param `renderMode` 渲染模式 * @return -1 当前设置不支持；-2 未连接实例/视频流状态异常； -3 画布异常； -4 内部错误；-5 参数错误 */ int `update``VideoRenderMode(int renderMode)`; ``` ### 视频自采集描述：设置视频数据的采集模式（自定义视频源或 SDK 内部采集视频），支持自采集视频数据。 ```java // CameraManager class /** * 设置本地视频源类型 * @param index 视频流索引 * @param type 视频源类型 * @return -1表示调用失败，0表示调用成功 */ int setVideoSourceType(int index, int type); /** * 视频自采集推流接口 * @param index 视频流索引 * @param frame 视频帧 * @return -1表示调用失败，0表示调用成功 */ int pushExternalVideoFrame(int index, VeVideoFrame frame); /** * 发布本地视频，视频自采集需要调用此接口 * @return -1表示调用失败，0表示调用成功 */ int publishLocalVideo(); /** * 取消发布本地视频，视频自采集需要调用此接口 * @return -1表示调用失败，0表示调用成功 */ int unpublishLocalVideo(); ``` |接口名称 |接口描述 | |---|---| |setVideoSourceType(int index, int type) |设置视频数据的采集模式|\ | |**参数：** |\ | ||\ | |* index：视频流索引|\ | | * 0（主流）|\ | | * 1（屏幕流）|\ | |* type：视频源类型|\ | | * 0（自定义采集视频源）|\ | | * 1（内部采集视频源） | |publishLocalVideo() |发布本地视频，视频自采集需要调用此接口 | |unpublishLocalVideo() |取消发布本地视频，视频自采集需要调用此接口 | |pushExternalVideoFrame(int index, VeVideoFrame frame) |视频自采集推流接口（需要先调用 setVideoSourceType，将采集模式设置为自定义采集视频源，然后调用 publishLocalVideo 发布本地视频）|\ | |**参数：** |\ | ||\ | |* index：视频流索引|\ | |* frame：外部采集的视频流 | 参考示例： ```java // mVideoFrameProducer为视频帧生产者 if (mVideoFrameProducer != null) { if (start) { // 开启视频推流，首先设置视频源为SDK外部采集 mCameraManager.setVideoSourceType(StreamIndex.MAIN, VideoSourceType.EXTERNAL); // 发布本地视频，需要先调用此接口才能调用后续的pushExternalVideoFrame mCameraManager.publishLocalVideo(); mVideoFrameProducer.mFrameConsumer = frame -> { if (mCameraManager != null) { mCameraManager.pushExternalVideoFrame(StreamIndex.MAIN, frame); } }; mVideoFrameProducer.start(mRequestCameraId); } else { // 关闭视频推流 mVideoFrameProducer.stop(); // 可选：恢复视频源为SDK内部采集 mCameraManager.setVideoSourceType(StreamIndex.MAIN, VideoSourceType.INTERNAL); // 取消发布本地视频 mCameraManager.unpublishLocalVideo(); } } ``` ### Camera 注入描述：获取 CameraManager 对象，该对象支持发送本地视频流和监听云机请求本地摄像头的打开和关闭。 |接口名称 |接口描述 | |---|---| |getCameraManager() |获取 CameraManager 对象 | ```java // vePhoneEngine class public @Nullable CameraManager getCameraManager() ``` ```java public interface CameraManager { int switchCamera(CameraId cameraId); int startVideoStream(CameraId cameraId); void stopVideoStream(); void setRemoteRequestListener(RemoteCameraRequestListener remoteRequestListener); void setCameraManagerListener(CameraManagerListener cameraManagerListener); void setLocalVideoCanvas(SurfaceView surfaceView, RenderMode mode); void setLocalVideoMirrorMode(MirrorMode mode); void setVideoEncoderConfig(List videoStreamDescriptions); void enableAutoMaxScreenBrightness(boolean enable); boolean isAutoMaxScreenBrightnessEnabled(); int setVideoInjectionState(boolean state); int getVideoInjectionState(); void setVideoInjectionListener(VideoInjectionListener listener); } ``` |接口名称 |接口描述 | |---|---| |switchCamera(CameraId cameraId) |切换前后摄像头，用于中途切换|\ | |**参数：** |\ | |CameraId：*FRONT（前置摄像头）；BACK（后置摄像头）* |\ | |**返回值：** |\ | |0：调用成功|\ | |\-1：调用失败（可能原因为尚未收到 onPlaySuccess 播放成功回调） | |startVideoStream(CameraId cameraId) |开始指定摄像头采集并推流|\ | |**参数：** |\ | |CameraId：*FRONT（前置摄像头）；BACK（后置摄像头）* |\ | |**返回值：** |\ | |0：调用成功|\ | |\-1：调用失败（可能原因为尚未收到 onPlaySuccess 播放成功回调）|\ | |**调用时机:** |\ | |在收到 RemoteCameraRequestListener 的方法|\ | |onVideoStreamStartRequested 中去调用|\ | |**调用结果：** |\ | |CameraManagerListener 回调接口的|\ | |onLocalVideoStateChanged 方法中会回调调用结果 | |stopVideoStream() |停止推流|\ | |**调用时机：** |\ | |在收到 RemoteCameraRequestListener 的方法|\ | |onVideoStreamStopRequested 中去调用 | |setRemoteRequestListener() |设置监听云机请求打开本地摄像头的回调方法|\ | |**参数：** |\ | |RemoteCameraRequestListener：云机请求打开（关闭）摄像头 | |setCameraManagerListener() |设置监听当前推流状态和首帧采集|\ | |**参数：** |\ | |CameraManagerListener：监听调用 startVideoStream 的推流结果 | |setLocalVideoCanvas(SurfaceView surfaceView, RenderMode mode) |设置本地视频画面布局|\ | |**参数：** |\ | ||\ | |* 1：RENDER_MODE_HIDDEN（默认，视窗填满优先；缩放完成后，视频帧的一边长和视窗的对应边长一致，另一边长大于等于视窗对应边长）|\ | |* 2：RENDER_MODE_FIT（视频帧内容全部显示优先；缩放完成后，视频帧的一边长和视窗的对应边长一致，另一边长小于等于视窗对应边长）|\ | |* 3：RENDER_MODE_Fill（视频帧自适应画布；视频帧非等比缩放，直至画布被填满。在此过程中，视频帧的长宽比例可能会发生变化） | |setLocalVideoMirrorMode(MirrorMode mode) |使用“前置摄像头”采集时，是否开启镜像翻转本地摄像头画面|\ | |**参数：** |\ | ||\ | |* 0：MIRROR_MODE_OFF（默认，不开启镜像翻转）|\ | |* 1：MIRROR_MODE_ON（开启镜像翻转） | |setVideoEncoderConfig(`List` videoStreamDescriptions) |根据客户端的网络情况以及接收端的网络情况以及订阅方式，配置本地视频编码质量参数|\ | |**参数：** |\ | ||\ | |* width（宽度）|\ | |* height（高度）|\ | |* frameRate（帧率）|\ | |* maxBitrate（最大码率） | |enableAutoMaxScreenBrightness(boolean enable) |在开启前置摄像头进行视频采集时，设置是否自动调节屏幕至最大亮度。建议在 `startVideoStream` 前调用。|\ | |**参数**：|\ | ||\ | |* enable|\ | | * true：（默认值）自动调节屏幕亮度至最大；|\ | | * false：不自动调节屏幕亮度。|\ | ||\ | |关闭前置摄像头时，屏幕亮度会恢复至之前的亮度。 | |boolean isAutoMaxScreenBrightnessEnabled() |是否已设置自动调节屏幕至最大亮度|\ | ||\ | |* **返回值：** |\ | | * true：是；|\ | | * false：否。 | |setVideoInjectionState(boolean state) |视频注入功能开关|\ | |**参数：** |\ | ||\ | |* state：true（开启）；false（关闭）|\ | ||\ | |**返回值：** |\ | |0：调用成功|\ | |\-1：调用失败，引擎未初始化 | |getVideoInjectionState() |查询视频注入功能开关状态|\ | |**返回值：** |\ | |0：调用成功|\ | |\-1：调用失败，引擎未初始化 | |setVideoInjectionListener(VideoInjectionListener listener) |注册视频注入回调|\ | |**参数：** |\ | |listener：视频注入回调，参看 `VideoInjectionListener` 说明 | **RemoteCameraRequestListener** 监听云机请求本地摄像头的打开和关闭。 ```java public interface RemoteCameraRequestListener { /** * 云机请求本地摄像头 * @param CameraId：FRONT（前置摄像头）；BACK（后置摄像头） * */ void onVideoStreamStartRequested(CameraId cameraId); /** * 云机关闭本地摄像头回调 */ void onVideoStreamStopRequested(); } ``` **CameraManagerListener** 监听本地推流状态。 ```java public interface CameraManagerListener { /** * * @param localVideoStreamState 枚举值：当前推流状态 * @param errorCode 错误码 */ void onLocalVideoStateChanged(LocalVideoStreamState localVideoStreamState, LocalVideoStreamError errorCode); /** * 第一帧被采集 */ void onFirstCapture(); } ``` **VideoInjectionListener** 监听视频注入状态 ```java interface VideoInjectionListener { /** * 视频注入状态改变的回调 * * @param callUserId 改变视频注入状态的用户ID * @param state 视频注入状态 true：开启 false：关闭 * @param code 错误码 0：成功 <0：失败 * @param msg 错误信息 */ void onVideoInjectionStateChanged(String callUserId, boolean state, int code, String msg); /** * 获取视频注入状态的结果回调 * * @param state 视频注入状态 true：开启 false：关闭 * @param code 错误码 0：成功 <0：失败 * @param msg 错误信息 */ void onGetVideoInjectionState(boolean state, int code, String msg); } ``` 监听本地推流状态。 **LocalVideoStreamState** ```java public enum LocalVideoStreamState { LOCAL_VIDEO_STREAM_STATE_STOPPED(0), LOCAL_VIDEO_STREAM_STATE_RECORDING(1), LOCAL_VIDEO_STREAM_STATE_ENCODING(2), LOCAL_VIDEO_STREAM_STATE_FAILED(3); } ``` 推流状态说明： |**状态码** |**说明** | |---|---| |*LOCAL_VIDEO_STREAM_STATE_STOPPED* |本地视频采集停止状态（默认初始状态） | |*LOCAL_VIDEO_STREAM_STATE_RECORDING* |本地视频采集设备启动成功 | |*LOCAL_VIDEO_STREAM_STATE_ENCODING* |本地视频采集后，首帧编码成功 | |*LOCAL_VIDEO_STREAM_STATE_FAILED* |本地视频启动失败 | **LocalVideoStreamError** ```java public enum LocalVideoStreamError { LOCAL_VIDEO_STREAM_ERROR_OK(0), LOCAL_VIDEO_STREAM_ERROR_FAILURE(1), LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION(2), LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY(3), LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(4), LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE(5), LOCAL_VIDEO_STREAM_ERROR_ENCODE_FAILURE(6); } ``` 错误码说明： |**错误码** |**说明** | |---|---| |LOCAL_VIDEO_STREAM_ERROR_OK |状态正常 | |LOCAL_VIDEO_STREAM_ERROR_FAILURE |本地视频流发布失败 | |LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION |没有权限启动本地视频采集设备 | |LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY |本地视频采集设备被占用 | |LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND |本地视频采集设备不存在或已移除 | |LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE |本地视频采集失败，建议检查采集设备是否正常工作 | |LOCAL_VIDEO_STREAM_ERROR_ENCODE_FAILURE |本地视频编码失败 | #### 参考代码 ```java // 在收到 IPlayerListener 的 onPlaySuccess 回调后，获取 CameraManager，监听远端请求，同时调用对应的方法 @Override public void onServiceInit(@NonNull Map extras) { CameraManager mCameraManager = VePhoneEngine.getInstance().getCameraManager(); mCameraManager.setRemoteRequestListener(new RemoteCameraRequestListener() { @Override public void onVideoStreamStartRequested(CameraId cameraId) { AcLog.d(TAG, "onVideoStreamStartRequested, cameraId :" + cameraId); mRequestCameraId = cameraId; // 注意：需要camera使用权限，请提前申请 PermissionUtils.permission(Manifest.permission.CAMERA) .callback(new PermissionUtils.SimpleCallback() { @Override public void onGranted() { mCameraManager.startVideoStream(mRequestCameraId); } @Override public void onDenied() { // 提示用户使用摄像头注入功能需要授予camera使用权限 } }).request(); }); VePhoneEngine.getInstance().getCameraManager().setCameraManagerListener(new CameraManagerListener() { @Override public void onLocalVideoStateChanged(LocalVideoStreamState localVideoStreamState, LocalVideoStreamError errorCode) { // 打印当前推流状态，用于排查问题 AcLog.d(TAG, "LocalVideoStreamState" + localVideoStreamState.toString() + ",LocalVideoStreamError" + errorCode); } @Override public void onFirstCapture() { AcLog.d(TAG, "onFirstCapture"); } }); } ``` ## 进程相关接口 ### 传感器开关描述：获取传感器使用权限。 ```java // vePhoneEngine class // 由于传感器数据量庞大，建议根据实际需求合理启用传感器，以避免数据拥塞引发的触控卡顿。建议同时开启的传感器数量不超过三个。 void enableAccelSensor(boolean enable) //是否启用加速度传感器 void enableGyroscopeSensor(boolean enable) //是否启用陀螺仪传感器 void enableGravitySensor(boolean enable) //是否启用重力传感器 void enableOrientationSensor(boolean enable) //是否启用方向传感器 void enableMagneticSensor(boolean enable) //是否启用磁力传感器 ``` 对于云手机多用户加房场景，建议使用下面的接口来代替上面的接口： ```java // SensorService class // state 加速度传感器开关状态 true：开启 false：关闭 // 由于传感器数据量庞大，建议根据实际需求合理启用传感器，以避免数据拥塞引发的触控卡顿。建议同时开启的传感器数量不超过三个。 void setAccelerometerSensorState(boolean state) // 设置加速度传感器开关状态 void setGyroSensorState(boolean state) // 设置陀螺仪开关状态 void setGravitySensorState(boolean state) // 设置重力传感器开关状态 void setOrientationSensorState(boolean state) // 设置方向传感器开关状态 void setMagneticSensorState(boolean state) // 设置磁力传感器开关状态 void getAccelerometerSensorState() // 查询加速度传感器开关状态 void getGyroSensorState() // 查询陀螺仪开关状态 void getGravitySensorState() // 查询重力传感器开关状态 void getOrientationSensorState() // 查询方向传感器开关状态 void getMagneticSensorState() // 查询磁力传感器开关状态 void setSensorsStateListener(SensorsStateListener listener) // 设置传感器开关状态监听器 ``` ```java // SensorService class interface SensorsStateListener { /** * 传感器开关状态改变的回调 * * @param callUserId 改变传感器开关状态的用户ID * @param type 传感器类型 * 1 -- TYPE_ACCELERATION * 2 -- TYPE_GYROSCOPE * 3 -- TYPE_MAGNETIC * 4 -- TYPE_ORIENTATION * 5 -- TYPE_GRAVITY * * @param state 传感器开关状态 true：开启 false：关闭 * @param code 错误码 0：成功 <0：失败 * @param msg 错误信息 */ void onSensorsStateChanged(String callUserId, int type, boolean state, int code, String msg); /** * 获取传感器开关状态的结果回调 * * @param type 传感器类型 * 1 -- TYPE_ACCELERATION * 2 -- TYPE_GYROSCOPE * 3 -- TYPE_MAGNETIC * 4 -- TYPE_ORIENTATION * 5 -- TYPE_GRAVITY * * @param state 传感器开关状态 true：开启 false：关闭 * @param code 错误码 0：成功 <0：失败 * @param msg 错误信息 */ void onGetSensorsState(int type, boolean state, int code, String msg); } ``` ### 震动开关描述：本地震动传感器开关。开启后，当云机的应用令手机发生震动时，本地手机会同步震动。注意：需要打开系统的震动开关后才能生效。 ```java // vePhoneEngine class void setVibratorState(boolean enable) ``` 建议使用下面的接口来代替上面的接口： ```java // SensorService class // state 振动开关状态 true：开启 false：关闭 void setVibratorState(boolean state) // 设置振动开关状态 boolean getVibratorState() // 查询振动开关状态 ``` ### 定位功能描述：定位功能默认是关闭的。如需开启，需要开发者开启 SDK 定位功能并为应用申请系统定位权限才能使用。可通过以下两种方法开启 SDK 定位功能： * 启动时开启：`PhonePlayConfig.Builder#enableLocationService` 设置为 `true` * 运行时开启：`LocationService#enableLocationService` 设置为 `true` |接口名称 |接口描述 | |---|---| |enableLocationService(boolean enable) |运行时动态开启或关闭定位服务 | |setRemoteLocationMock(Double latitude, Double longitude) |手动设置云手机的位置信息：|\ | ||\ | |* latitude：纬度|\ | |* longitude：经度 | |setLocationServiceMode(int mode) |设置云机请求获取位置信息的模式：|\ | ||\ | |* 0（自动模式，默认，需要通过 enableLocationService 接口开启定位服务）|\ | |* 1（手动模式，需要通过 setRemoteLocationMock 接口设置云手机的位置信息） | |setLocationEventListener(LocationEventListener listener) |在 `onServiceInit` 回调中，设置定位事件监听器 | 对于云手机多用户加房场景，建议使用下面的接口替换上面的接口： |**接口名称** |**接口描述** | |---|---| |void setLocationServiceState(boolean state) |设置位置服务开关状态|\ | ||\ | |* state 位置服务开关状态：|\ | | * `true`：开启|\ | | * `false`：关闭 | |void getLocationServiceState() |获取位置服务开关状态 | |void setLocationServiceStateListener(LocationServiceStateListener listener) |设置位置服务开关状态监听器|\ | ||\ | |* `listener`：监听器 | 用于云手机多用户加房场景的代码示例如下： ```java /** * 用于云手机多用户加房场景 */ interface LocationServiceStateListener { /** * 位置服务开关状态改变的回调 * * @param callUserId 改变位置服务开关状态的用户ID * @param state 位置服务开关状态 true：开启 false：关闭 * @param code 错误码 0：成功 <0：失败 * @param msg 错误信息 */ void onLocationServiceStateChanged(String callUserId, boolean state, int code, String msg); /** * 获取位置服务开关状态的结果回调 * * @param state 位置服务开关状态 true：开启 false：关闭 * @param code 错误码 0：成功 <0：失败 * @param msg 错误信息 */ void onGetLocationServiceState(boolean state, int code, String msg); } ``` #### LocationEventListener 定位事件相关回调。 |接口名称 |接口描述 | |---|---| |onReceivedRemoteLocationRequest(LocationService.RequestOptions options) |在手动定位模式下，收到云机实例位置请求的回调|\ | ||\ | |* options：位置请求选项 | |onRemoteLocationRequestEnded() |在手动定位模式下，云机实例定位请求结束 | |onRemoteLocationUpdated(LocationService.LocationInfo location) |云机实例位置更新后的回调 | |onSentLocalLocation(LocationService.LocationInfo location) |在自动定位模式下，向云机实例发送本地设备位置信息后的回调 | #### 参考代码在云手机启动成功后，可以按业务需要切换云手机的定位模式： * 自动模式下（默认），SDK 会按照系统定位回调的频率将客户端的当前位置信息上报给云机实例以实现位置同步。 * 切换到手动模式下，SDK 会将云机定位请求回调给客户端，此时可以通过 `LocationService#setRemoteLocationMock()` 接口发送自定义位置信息给云机实例。推荐在`onServiceInit()` 回调中切换手动模式。 ```java // 1. 前提需要开启定位服务 PhonePlayConfig.Builder builder = new PhonePlayConfig.Builder(); PhonePlayConfig mPhoneConfig = builder.userId(uid) .container(mContainer) ......省略无关代码 .setLocationServiceState(true) //true表示开启，false表示关闭，默认为false .build(); VePhoneEngine.getInstance().start(mPhoneConfig, mListener); // 2. 在onServiceInit中切换手动模式 @Override public void onServiceInit(@NonNull Map extras) { LocationService service = VePhoneEngine.getInstance().getLocationService(); // 设置定位相关事件回调 service.setLocationEventListener(new LocationService.LocationEventListener() { @Override public void onReceivedRemoteLocationRequest(LocationService.RequestOptions options) { // 手动模式下，云机请求定位会触发onReceivedRemoteLocationRequest回调 // 例如：云机打开了导航APP或其他基于LBS服务的APP service.setRemoteLocationMock(new LocationService.LocationInfo(xxx, yyyy)); } @Override public void onRemoteLocationRequestEnded() { // 手动模式下，云机结束定位会触发onRemoteLocationRequestEnded回调 // 例如：云机关闭了导航APP或其他基于LBS服务的APP } @Override public void onSentLocalLocation(LocationService.LocationInfo location) { } @Override public void onRemoteLocationUpdated(LocationService.LocationInfo location) { } }); // 切换到手动定位模式 service.setLocationServiceMode(LocationService.MODE_MANUAL); } ``` ### 屏幕旋转描述：旋转画面方向。`orientation` 在收到 SDK `IStreamListener onRotation` 回调后，旋转 Activity。然后使用 Activity 的 `onConfigurationChanged(Configuration newConfiguration)` 回调中的值 `newConfiguration.orientation`。 ```java // vePhoneEngine class void rotate(int orientation) ``` ### 切换旋转模式描述：切换视频旋转模式 |接口名称 |接口描述 | |---|---| |setVideoRotationMode(int mode) |设置视频旋转模式：|\ | |**参数：** |\ | ||\ | |* mode：旋转模式|\ | | * 0（EXTERNAL，外部旋转；此模式下，用户需通过监听 `IStreamListener.onRotation` 回调，从外部调整页面方向从而实现画面方向与云手机实例同步）|\ | | * 1（INTERNAL，内部旋转；此模式下，SDK 内部对画面进行方向处理，外部不需要做任何画面方向的处理） | |getVideoRotationMode() |获取已设置的视频旋转模式 | ### 发送键盘事件指令描述：发送键盘事件指令到云机实例，当前仅支持 Home键、返回键、菜单键和最近任务列表。有关 Android 系统支持的键盘事件和键值，参考：[https://developer.android.com/reference/android/view/KeyEvent](https://developer.android.com/reference/android/view/KeyEvent)。 |接口名称 |接口描述 | |---|---| |sendKeyEvent(int keyCode) |发送键盘事件，`keyCode` 代表事件的键值，当前仅支持以下键盘事件：|\ | ||\ | |* 3（`KeyEvent.KEYCODE_HOME`，Home键）|\ | |* 4（`KeyEvent.KEYCODE_BACK`，返回键）|\ | |* 82（`KeyEvent.KEYCODE_MENU`，菜单键）|\ | |* 187（`KeyEvent.KEYCODE_APP_SWITCH`，最近任务列表） | |sendKeyEvent(int action, int keyCode) |发送键盘事件。|\ | |`action` 代表事件类型，当前支持以下类型：|\ | ||\ | |* 0（`KeyEvent.ACTION_DOWN`，按键按下动作）|\ | |* 1（`KeyEvent.ACTION_UP`，按键抬起动作）|\ | ||\ | |`keyCode` 代表事件的键值，当前支持以下键盘事件：|\ | ||\ | |* 3（`KeyEvent.KEYCODE_HOME`，Home键）|\ | |* 4（`KeyEvent.KEYCODE_BACK`，返回键）|\ | |* 82（`KeyEvent.KEYCODE_MENU`，菜单键）|\ | |* 187（`KeyEvent.KEYCODE_APP_SWITCH`，最近任务列表） | ```java public class VePhoneEngine { /** * 发送键盘事件 * @param keyCode 键盘事件键值 * @return 0 表示调用成功，-1 表示调用失败或不支持该keyCode */ public int sendKeyEvent(int keyCode); /** * 发送键盘事件 * * @param action 事件类型 * @param keyCode 键盘事件键值 * @return 0 表示调用成功，-1 表示调用失败或不支持该keyCode */ public int sendKeyEvent(int action, int keyCode); } ``` ### 回传触控事件描述：回传触控事件（业务方根据需要消费触控事件）。 |接口名称 |接口描述 | |---|---| |setInterceptSendTouchEvent(boolean intercept) |设置是否拦截 SDK 向云机实例发送的触控事件：|\ | ||\ | |* intercept：|\ | | * true：拦截（需设置为拦截，才会回传触控事件）|\ | | * false：不拦截 | |setSimpleTouchEventListener(SimpleTouchEventListener listener) |设置监听器：|\ | ||\ | |* listener：触控事件列表监听器 | |onSimpleTouchEvent(ListsimpleTouchEvents) |触控事件列表回调，可在该回调中处理触控事件：|\ | ||\ | |* simpleTouchEvents：参考以下 **SimpleTouchEvent 结构说明** | **SimpleTouchEvent 结构说明** |**字段** |**类型** |**说明** | |---|---|---| |x |float |触控点相较于 Container 左侧的偏移量，取值范围：[0, 1] | |y |float |触控点相较于 Container 顶部的偏移量，取值范围：[0, 1] | |pointerId |int |与当前触控事件相关的触控点 ID | |action |int |当前触控事件对应的动作，包括：|\ | | ||\ | | |* ACTION_DOWN|\ | | |* ACTION_UP|\ | | |* ACTION_CANCEL|\ | | |* ACTION_POINTER_DOWN|\ | | |* ACTION_POINTER_UP|\ | | |* ACTION_MOVE | ```java // vePhoneEngine class public TouchEventService getTouchEventService() ``` ```java public interface TouchEventService { /** * 设置是否拦截 SDK 向云机实例发送的触控事件 * * @param intercept true -- 拦截 * false -- 不拦截 */ void setInterceptSendTouchEvent(boolean intercept); /** * 设置监听器 * * @param listener 触控事件列表监听器 */ void setSimpleTouchEventListener(SimpleTouchEventListener listener); interface SimpleTouchEventListener { /** * 触控事件列表回调，用户可在该回调中处理触控事件 */ void onSimpleTouchEvent(List simpleTouchEvents); } } ``` 示例代码： ```java // 示例代码 public class PhoneActivity extends AppCompatActivity implements IPlayerListener, IStreamListener { @Override public void onServiceInit(Map map) { TouchEventService touchEventService = VePhoneEngine.getInstance().getTouchEventService(); if (touchEventService != null) { // 拦截 SDK向云机实例发送的触控事件 touchEventService.setInterceptSendTouchEvent(true); touchEventService.setSimpleTouchEventListener(new TouchEventService.SimpleTouchEventListener() { @Override public void onSimpleTouchEvent(List list) { // 获取回传的触控事件，如何消费由业务方决定 Log.d(TAG, "onSimpleTouchEvent: " + list); } }); } } } ``` ### 启动/关闭云机 App 描述：启动或关闭云机 App（`pkgName` 为应用包名）。 ```java // vePhoneEngine class void launchApp(@NonNull String pkgName) void closeApp(@NonNull String pkgName) ``` ### 客户端前后台切换描述：设置客户端应用切换前后台的状态。 |接口名称 |接口描述 | |---|---| |switchBackground(boolean on) |客户端切换前后台|\ | |**参数：** |\ | ||\ | |* true：切后台|\ | |* false：切前台 | |setBackgroundSwitchListener(BackgroundSwitchListener listener) |设置监听客户端应用切换前后台的回调方法|\ | |**参数：** |\ | |BackgroundSwitchListener：监听客户端应用切换前后台 | 参考示例： ```java // vePhoneEngine class public @Nullable PodControlService getPodControlService() ``` ```java public interface PodControlService { void switchBackground(boolean on); void setBackgroundSwitchListener(BackgroundSwitchListener listener); } ``` **BackgroundSwitchListener** 监听客户端应用切换前台或后台。 > 如果重复调用切换前后台接口，`IPlayerListener` 的 `onWarning` 会给出告警提示。 |接口名称 |接口描述 | |---|---| |onBackgroundSwitched() |客户端应用切换前台或后台的回调（用户手动调用 `switchBackground` 接口或者触摸屏幕发生切换前后台都会触发这个回调）：|\ | ||\ | |* true（切换到后台）|\ | |* from（切换到前台） | 参考示例： ```java public interface BackgroundSwitchListener { void onBackgroundSwitched(boolean on); } ``` ### 云机应用切换前台描述：将指定云机应用切换到前台。 |接口名称 |接口描述 | |---|---| |getRemoteBackgroundAppList() |获取已切换到后台的云机应用列表 | |setRemoteAppForeground(String packageName) |将指定云机应用切换到前台：|\ | ||\ | |* packageName（应用包名，非必传） | |setGroundChangeListener(AppGroundSwitchedListener appGroundSwitchedListener) |设置云机应用切换前后台状态变化的监听 | **AppGroundSwitchManager.AppGroundSwitchedListener** 云机应用切换前台或后台状态。 |接口名称 |接口描述 | |---|---| |onRemoteAppSwitchedBackground(int switchedType ，|云机应用切换到后台：|\ |, String packageName) ||\ | |* switchedType（0：手动；1：自动）|\ | |* packageName（应用包名） | |onRemoteAppSwitchedForeground(int switchedType，|云机应用切换到前台：|\ |, String packageName) ||\ | |* switchedType（0：手动；1：自动）|\ | |* packageName（应用包名） | |onRemoteAppSwitchedFailed(int errorCode, String errorMsg) |云机应用切换前后台失败，错误码及其含义：|\ | ||\ | |* \-3：主动切换的应用不存在|\ | |* \-2：主动切换的应用失败|\ | |* \-1：切换的参数异常|\ | |* 2：重复拉取到前台 | |onRevicedRemoteAppList(ListremoteAppInfos) |获取后台应用列表的返回函数，应用列表是 packageName 的列表 | 参考示例： ```java interface AppGroundSwitchManager { void getRemoteBackgroundAppList(); void setRemoteAppForeground(String packageName); void setGroundChangeListener(AppGroundSwitchedListener appGroundSwitchedListener); interface AppGroundSwitchedListener { void onRemoteAppSwitchedBackground(int switchedType, String packageName); void onRemoteAppSwitchedForeground(int switchedType, String packageName); void onRemoteAppSwitchedFailed(int errorCode, String errorMsg); void　onRevicedRemoteAppList(List remoteAppInfos); } } ``` ### 设置保活时间描述：在应用运行中动态设置客户端切后台之后，云机服务的保活时间（如不设置，则使用默认保活时长 10 秒；支持设置的上限值为 7200，即 2 小时；如需设置更长时间，可联系火山引擎云手机技术支持）。 > 当客户端切后台或者断网时开始计时。如用户在设置的保活时间到达时未切回前台，服务端将断开连接。 |接口名称 |接口描述 | |---|---| |int setIdleTime(long time) |指定保活时长|\ | ||\ | |* time 保活时长，单位:秒|\ | ||\ | |返回值|\ | ||\ | |* 0 调用成功|\ | |* <0 调用失败 | |int getIdleTime() |获取保活时长|\ | |返回值|\ | ||\ | |* 0 调用成功|\ | |* <0 调用失败 | |void setIdleTimeListener(IdleTimeListener listener) |设置保活时长监听器 | 参考示例： ```java // vePhoneEngine class public @Nullable PodControlService getPodControlService() ``` ```java public interface IdleTimeListener { /** * 保活时长改变的回调 * * @param callUserId 改变保活时长的用户ID * @param code 错误码，0：成功，<0：失败 * @param time 保活时长 */ void onIdleTimeChanged(String callUserId, int code, long time); /** * 获取保活时长的结果回调 * * @param code 错误码，0：成功，<0：失败 * @param time 保活时长 */ void onGetIdleTime(int code, long time); } ``` ### 拉流过程中支持设置全屏显示描述：在拉流过程中可以设置云端实例是否全屏显示。 > 在拉流前可以在 start() 接口中通过 remoteWindowSize 参数设置是否全屏显示： > 1. 不调用 remoteWindowSize，则拉流时默认为全屏显示； > 2. 传参 remoteWindowSize(0, 0)，拉流时以 16:9 的比例显示。 |**接口名称** |**接口描述** | |---|---| |enableFullScreen(boolean enable) |拉流过程中设置是否全屏显示|\ | ||\ | |* enable：是否全屏显示|\ | | * true：全屏，指start接口传入container的大小显示|\ | | * false：非全屏，指16:9的比例显示 | |setFullScreenListener(FullScreenListener listener) |设置全屏状态回调 | 参考示例： ```java // vePhoneEngine class public PodControlService getPodControlService() ``` ```java public interface FullScreenListener { /** * 当全面屏状态发生变化时会收到该回调 * * @param callUserId 设置全面屏状态的用户ID * @param width 视频流的宽度 * @param height 视频流的高度 */ void onFullScreenStateChanged(String callUserId, int width, int height); } ``` ### 指令分发场景通知用户房间状态描述：当指令分发实例的房间状态发生改变时会通知用户 |**接口名称** |**接口描述** | |---|---| |void setPodRoomStateListener(PodRoomStateListener listener) |设置指令分发实例的房间状态回调 | 参考示例： ```java // vePhoneEngine class public PodControlService getPodControlService() ``` ```java public interface PodRoomStateListener { /** * 当指令分发实例的房间状态发生改变时会收到该回调 * * @param podType 实例类型 0--指令接收端，1--指令发送端 * @param roomState 房间状态 0--退房，1--进房 * @param podList 实例列表 */ void onSyncPodRoomState(int podType, int roomState, List podList); } ``` ### 设置/获取无操作回收服务时间描述：在应用运行中动态设置无操作推流服务回收时长。该接口用于设定一个时长，如果在这个时长内客户端没有任何操作，云手机实例将停止推流并自动退出。 > 如果已在 `start()` 接口中通过 `autoRecycleTime` 参数设置，动态设置的时长优先级高。 |接口名称 |接口描述 | |---|---| |setAutoRecycleTime(int time, SetAutoRecycleTimeCallback callback) |设置无操作推流服务回收时长：|\ | ||\ | |* time（无操作推流服务回收时长，单位秒；支持设置的范围为 [0, 86400]，即0到24小时；如不设置或设置为0，则使用默认时长300秒）|\ | |* callback（设置无操作推流服务回收时长的回调） | |getAutoRecycleTime(GetAutoRecycleTimeCallback callback) |获取已设置的无操作回收服务时间：|\ | ||\ | |* callback（获取无操作推流服务回收时长的回调） | 对于**云手机多用户加房**的场景，建议使用下面的接口来替换上面的接口： |**接口名称** |**接口描述** | |---|---| |int setAutoRecycleTime(int time) |设置无操作推流服务回收时长 | |int getAutoRecycleTime() |获取无操作推流服务回收时长 | |void setAutoRecycleTimeListener(AutoRecycleTimeListener listener) |设置无操作回收时长监听器 | 参考示例： ```java // vePhoneEngine class public @Nullable PodControlService getPodControlService() ``` ```java public interface PodControlService { /** * @param time 无操作回收时长 * @param callback 设置无操作推流服务回收时长的回调 * @return 0：正常返回；-1：ICoreEngine为空；-2：time参数小于0 */ int setAutoRecycleTime(int time, SetAutoRecycleTimeCallback callback); /** * @param callback 获取已设置无操作推流服务回收时长的回调 * @return 0：正常返回；-1：ICoreEngine为空 */ int getAutoRecycleTime(GetAutoRecycleTimeCallback callback); } ``` ```java /** * 用于云手机多用户加房场景 */ public interface AutoRecycleTimeListener { /** * 无操作回收时长改变的回调 * * @param callUserId 改变无操作回收时长的用户ID * @param code 错误码，0：成功，<0：失败 * @param time 无操作回收时长 */ void onAutoRecycleTimeChanged(String callUserId, int code, long time); /** * 获取无操作回收时长的结果回调 * * @param code 错误码，0：成功，<0：失败 * @param time 无操作回收时长 */ void onGetAutoRecycleTime(int code, long time); } ``` ### 发送模拟重力传感器数据描述：该方法用于向云端实例发送“摇一摇”指令，云端实例会使用传感器来模拟“摇一摇”的操作。 |**接口名称** |**接口描述** | |---|---| |`int sendShakeEventToRemote(int duration)` |发送摇一摇模拟数据到云端实例：|\ | ||\ | |* duration：摇一摇时长，单位：毫秒，取值范围：[1800, 30000]。|\ | |* 返回值： 0 \-\- 调用成功；< 0 \-\- 调用失败 | |`void setShakeEventListener(ShakeEventListener listener)` |设置摇一摇事件结果的监听器：|\ | ||\ | |* listener：监听器，参看下方 `ShakeEventListener` 说明。 | #### ShakeEventListener 摇一摇事件结果的监听器。 |**接口定义** |**接口描述** | |---|---| |`void onShakeResponse(int result, String msg)` |摇一摇的结果回调：|\ | ||\ | |* result：摇一摇结果。0：异常；1：完成；2：进行中。|\ | |* msg：摇一摇结果的详细信息。 | ### 操控权控制描述：当多个用户通过不同客户端连接到同一云手机实例时，支持开启或关闭用户对云手机的操控权。 |接口名称 |接口描述 | |---|---| |enableControl(String userId, boolean enable) |设置指定用户是否具有云手机操控权（每个新用户连接云手机时默认具备操控权，可以通过本接口动态关闭控制权）：|\ | ||\ | |* userId：用户 ID|\ | |* enable：开启或关闭该用户的操控权|\ | | * true：开启操控权|\ | | * false：关闭操控权|\ | ||\ | |**说明：** |\ | ||\ | |* 可同时设置多个用户具有云手机的操控权，操控权的唯一性可根据业务需要设置|\ | |* 请在 `onFirstRemoteVideoFrame` 回调中调用本方法 | |hasControl(String userId) |异步查询指定用户是否具有云手机操控权：|\ | ||\ | |* userId：用户 ID | |getAllControls() |异步查询全部用户的操控权详情 | |setControlListener(ControlListener listener) |设置用户操控权回调 | 参考示例： ```java // vePhoneEngine class public UserService getUserService() ``` ```java public interface UserService { /** * 设置指定用户是否具有云手机操控权 * @param userId 用户ID * @param enable 开启或关闭该用户的操控权 * @return 0：方法调用成功； -1：方法调用失败 * @notes 1. 请在 onFirstRemoteVideoFrame 回调中调用本方法 * 2. 操作结果通过 {@link ControlListener#onEnableControlResult(int, ControlState, String)} 返回。 */ int enableControl(String userId, boolean enable); /** * 异步查询指定用户是否具有云手机操控权
* 查询结果通过 {@link ControlListener#onHasControlResult(int, ControlState, String)} 返回。 * @param userId 用户ID * @return 0：方法调用成功； -1：方法调用失败 */ int hasControl(String userId); /** * 异步查询全部用户的操控权详情
* 查询结果通过 {@link ControlListener#onAllControlsResult(int, List, String)} 返回。 * @return 0：方法调用成功； -1：方法调用失败 */ int getAllControls(); /** * 设置用户操控权回调 * @param listener 回调 */ void setControlListener(ControlListener listener); } ``` #### ControlListener 查询和设置用户操控权结果回调。 |接口名称 |接口描述 | |---|---| |onUserJoin(String uid) |远端用户上线回调 | |onUserLeave(String uid) |远端用户下线回调 | |onControlStateChanged(ControlState state) |当前或其他用户通过 `enableControl` 设置操控权的结果回调|\ | |**说明：** 连接到云手机的所有用户都会收到操控权变更的回调 | |onEnableControlResult(int code, ControlState state, String msg) |设置指定用户的操控权结果回调|\ | |**说明：** 仅进行操控权设置的用户会收到回调 | |onHasControlResult(int code, ControlState state, String msg); |查询指定用户是否具有控制权的结果回调 | |onAllControlsResult(int code, `List` states, String msg) |查询全部用户的操控权详情的结果回调 | 参考示例： ```java interface ControlListener { /** * 远端用户上线 * @param uid 用户ID */ void onUserJoin(String uid); /** * 远端用户下线 * @param uid 用户ID */ void onUserLeave(String uid); /** * 当前或其他用户通过{@link UserService#enableControl(String, boolean)}设置操控权时收到该回调 * @see UserService#enableControl(String, boolean) */ void onControlStateChanged(@NonNull ControlState state); /** * 设置指定用户操控权结果回调 * @param code 0-成功并返回操控权状态，其他为失败错误码 * @param state 用户操控权状态 * @param msg 提示信息 * @see UserService#enableControl(String, boolean) */ void onEnableControlResult(int code, @Nullable ControlState state, @NonNull String msg); /** * 查询指定用户是否具有控制权结果回调 * @param code 0-成功并返回操控权状态，其他为失败错误码 * @param state 用户操控权状态 * @param msg 提示信息 * @see UserService#hasControl(String) */ void onHasControlResult(int code, @Nullable ControlState state, @NonNull String msg); /** * 查询全部用户的操控权详情结果回调 * @param code 0-成功并返回操控权状态，其他为失败错误码 * @param states 用户操控权状态 * @param msg 提示信息 * @see UserService#getAllControls() */ void onAllControlsResult(int code, @Nullable List states, @NonNull String msg); } ``` 回调参数： ```java class ControlState { public final @NonNull String userId; //目标用户ID public final boolean enable; //目标用户是否具有操控权 } ``` ### 收发消息描述：客户端应用与云手机实例之间收发消息。请在收到 `vePhoneEngine#addCloudCoreManagerListener` 回调之后使用。消息收发类接口需结合 Message Channel SDK 使用，Message Channel SDK 使用方法参考 [Message Channel SDK 接入说明](/docs/6394/95333)。 |**适用场景** |**接口名称** |**接口描述** |**参数说明** |**返回值说明** | |---|---|---|---|---| |云手机端只有 **1 个**应用注册消息通道。 |`IChannelMessage sendMessage(String payload, boolean needAck)` |向云手机应用发送**文本**消息，并设置是否需要消息接收回执。 |* `payload`：文本消息内容，不超过 60KB。|[IChannelMessage](#ichannelmessage) 消息实体。 |\ | | | |* `needAck`：是否需要消息接收回执。| |\ | | | | * `true`：（默认值）是；| |\ | | | | * `false`：否。 | | |^^|`IChannelBinaryMessage sendBinaryMessage(byte[] payload, boolean needAck)` |向云手机应用发送**二进制**消息，并设置是否需要消息接收回执。 |* `payload`：二进制消息内容，不超过 60KB。|[IChannelBinaryMessage](#ichannelbinarymessage) 消息实体。 |\ | | | |* `needAck`：是否需要消息接收回执。| |\ | | | | * `true`：（默认值）是；| |\ | | | | * `false`：否。 | | |^^|`IChannelMessage sendMessage(String payload, long timeout)` |向云手机应用发送**文本**消息，并设置消息发送超时时长。 |* `payload`：消息内容，不超过 60KB。|[IChannelMessage](#ichannelmessage) 消息实体。 |\ | | | |* `timeout`：消息发送超时时长，大于 0，单位为 ms，默认值为 30000ms。如果超过指定的时长还未收到对应的接收消息反馈，则会通过 `IMessageReceiver#onSentResult` 返回消息发送失败的信息。 | | |^^|`IChannelBinaryMessage sendBinaryMessage(byte[] payload, long timeout)` |向云手机应用发送**二进制**消息，并设置消息发送超时时长。 |* `payload`：消息内容，不超过 60KB。|[IChannelBinaryMessage](#ichannelbinarymessage) 消息实体。 |\ | | | |* `timeout`：消息发送超时时长，大于 0，单位为 ms，默认值为 30000ms。如果超过指定的时长还未收到对应的接收消息反馈，则会通过 `IMessageReceiver#onSentResult` 返回消息发送失败的信息。 | | |^^|`void setMessageListener(IMessageReceiver listener)` |设置消息接收回调监听器。 |`listener`：消息接收回调监听器，参看 [IMessageReceiver](#imessagereceiver)。 |/ | |云手机端有**多个**应用注册消息通道。 |`IChannelMessage sendMessage(String payload, boolean needAck, String destChannelUid)` |向云手机应用发送**文本**消息，并设置是否需要消息接收回执。 |* `payload`：文本消息内容，不超过 60KB。|[IChannelMessage](#ichannelmessage) 消息实体。 |\ | | | |* `needAck`：是否需要消息接收回执。| |\ | | | | * `true`：（默认值）是；| |\ | | | | * `false`：否。| |\ | | | |* `destChannelUid`：目标应用的消息通道 ID。 | | |^^|`IChannelBinaryMessage sendBinaryMessage(byte[] payload, boolean needAck, String destChannelUid)` |向云手机应用发送**二进制**消息，并设置是否需要消息接收回执。 |* `payload`：二进制消息内容，不超过 60KB。|[IChannelBinaryMessage](#ichannelbinarymessage) 消息实体。 |\ | | | |* `needAck`：是否需要消息接收回执。| |\ | | | | * `true`：（默认值）是；| |\ | | | | * `false`：否。| |\ | | | |* `destChannelUid`：目标应用的消息通道 ID。 | | |^^|`IChannelMessage sendMessage(String payload, long timeout, String destChannelUid)` |向云手机应用发送**文本**消息，并设置消息发送超时时长。 |* `payload`：消息内容，不超过 60KB。|[IChannelMessage](#ichannelmessage) 消息实体。 |\ | | | |* `timeout`：消息发送超时时长，大于 0，单位为 ms，默认值为 30000ms。如果超过指定的时长还未收到对应的接收消息反馈，则会通过 `IMessageReceiver#onSentResult` 返回消息发送失败的信息。| |\ | | | |* `destChannelUid`：目标应用的消息通道 ID。 | | |^^|`IChannelBinaryMessage sendBinaryMessage(byte[] payload, long timeout, String destChannelUid)` |向云手机应用发送**二进制**消息，并设置消息发送超时时长。 |* `payload`：消息内容，不超过 60KB。|[IChannelBinaryMessage](#ichannelbinarymessage) 消息实体。 |\ | | | |* `timeout`：消息发送超时时长，大于 0，单位为 ms，默认值为 30000ms。如果超过指定的时长还未收到对应的接收消息反馈，则会通过 `IMessageReceiver#onSentResult` 返回消息发送失败的信息。| |\ | | | |* `destChannelUid`：目标应用的消息通道 ID。 | | |^^|`void setMessageListener(IMessageReceiver listener)` |设置消息接收回调监听器。 |`listener`：消息接收回调监听器，参看 [IMessageReceiver](#imessagereceiver)。 |/ | #### IMessageReceiver 消息接收回调监听器。 |**接口名称** |**接口描述** | |---|---| |`void onReceiveMessage(IChannelMessage message)` |文本消息接收回调。 | |`void onReceiveBinaryMessage(IChannelBinaryMessage message)` |二进制消息接收回调。 | |`void onSentResult(boolean success, String mid)` |文本/二进制消息发送结果回调。 | |`void onError(int errorCode, String message)` |错误上报回调。 | |`void onRemoteOnline(String channelUid)` |消息通道建连回调，建议在发送消息前监听该回调检查通道是否已连接。 | |`void` `onRemoteOffline(String channelUid)` |消息通道断连回调，可能导致消息传输失败。 | #### IChannelMessage 文本消息实体。 |**接口名称** |**接口描述** | |---|---| |`String getMid()` |获取消息编号。 | |`String getSrcChannelUid()` |获取消息发送方的 ChannelUid。 | |`String getDestChannelUid()` |获取消息接收方的 ChannelUid。 | |`String getPayload()` |获取携带的消息内容。 | |`long getTimeMillis()` |获取消息发送时间。 | #### IChannelBinaryMessage 二进制消息实体。 |**接口名称** |**接口描述** | |---|---| |`String getMid()` |获取消息编号。 | |`String getSrcChannelUid()` |获取消息发送方的 ChannelUid。 | |`String getDestChannelUid()` |获取消息接收方的 ChannelUid。 | |`byte[] getPayload()` |获取携带的消息内容。 | |`long getTimeMillis()` |获取消息发送时间。 | 参考示例： ```java // vePhoneEngine class public @Nullable IMessageChannel getMessageChannel() ``` ```java public interface IMessageChannel { IChannelMessage sendMessage(String payload, boolean needAck); IChannelMessage sendMessage(String payload, boolean needAck, String destChannelUid); IChannelMessage sendMessage(String payload, long timeout); IChannelMessage sendMessage(String payload, long timeout, String destChannelUid); IChannelBinaryMessage sendBinaryMessage(byte[] payload, boolean needAck); IChannelBinaryMessage sendBinaryMessage(byte[] payload, boolean needAck, String destChannelUid); IChannelBinaryMessage sendBinaryMessage(byte[] payload, long timeout); IChannelBinaryMessage sendBinaryMessage(byte[] payload, long timeout, String destChannelUid); void setMessageListener(IMessageReceiver listener); interface IMessageReceiver { void onReceiveMessage(IChannelMessage message); void onReceiveBinaryMessage(IChannelBinaryMessage message); void onSentResult(boolean success, String mid); void onError(int errorCode, String message); void onRemoteOnline(String channelUid); void onRemoteOffline(String channelUid); } interface IChannelMessage { String getMid(); String getSrcChannelUid(); String getDestChannelUid(); String getPayload(); long getTimeMillis(); } interface IChannelBinaryMessage { String getMid(); String getSrcChannelUid(); String getDestChannelUid(); byte[] getPayload(); long getTimeMillis(); } } ``` #### 错误码收发消息可能返回的错误码和相关说明如下： |错误码 |错误信息 |说明 | |---|---|---| |50000 |ERROR_MESSAGE_GENERAL |未知错误 | |50001 |ERROR_MESSAGE_NOT_CONNECTED |发送消息错误。原因：客户端 SDK 与火山引擎云游戏 PaaS 服务未连接。建议：请检查网络后，重新调用发送消息接口，进行消息发送。 | |50002 |ERROR_MESSAGE_FAILED_TO_PARSE_MSG |消息通道数据解析失败。原因：无法解析接收到的消息。 | |50003 |ERROR_MESSAGE_CHANNEL_UID_ILLEGAL |指定的消息通道 ID 无效。原因：指定的消息通道 ID 与云机初始化 veMessageChannelClient 时填入的用户 ID 不符。 | |50004 |ERROR_MESSAGE_FAILED |发送消息错误。建议：请检查网络。 | |50005 |ERROR_MESSAGE_NOT_CLOUD_RUNTIME |消息通道错误。原因：云机 SDK 未运行。建议：请检查网络。 | |50006 |ERROR_MESSAGE_CONNECT_VERIFY_FAILED |消息通道错误。原因：鉴权失败。建议：请检查参数配置。 | |50007 |ERROR_MESSAGE_OVER_SIZED |通过客户端 SDK 发送的消息错误。原因：消息包体过大（不应超过60KB）。建议：减小发送包体大小，重新发送。 | |50009 |ERROR_MESSAGE_TIMEOUT_ILLEGAL |发送消息错误。原因：指定的消息发送超时时长不符合要求，必须为大于 0 的值。 | ### 收发文件描述：云手机客户端 SDK 支持通过 FileExchange 类实现与云机实例进行文件传输。需要注意的是 FileExchange 是一个接口类，通过 VePhoneEngine 的 `getFileExchange()` 方法获取对象引用。 :::tip 使用文件传输功能，需要注意以下前提条件： * 文件传输相关接口需要在收到 `onPlaySuccess` 播放成功回调之后使用。 * 文件传输功能需配合 2025 年 7 月 8 日之后发布的公共镜像版本使用。 * 文件传输功能依赖第三方库实现数据的发送和接收功能，请确保工程中已引入以下库（注意：如果已经依赖了大于 2.7.0 版本的 jackson 模块，则需对文件传输功能进行回归测试验证）： `implementation 'com.squareup.okhttp3:okhttp:4.9.0'` `implementation 'com.fasterxml.jackson.core:jackson-annotations:2.7.0'` `implementation 'com.fasterxml.jackson.core:jackson-databind:2.7.0'` ::: 参考示例： ```Java // vePhoneEngine class public @Nullable FileExchange getFileExchange() ``` |接口名称 |接口描述 | |---|---| |startPushFile(File file, File target, IPushFileListener listener) |启动客户端向云机实例推送文件（有关 File 类的详细说明，参考 [Android 官方文档说明](https://developer.android.com/reference/java/io/File)） | |stopPushFile(File file) |停止客户端向云机实例推送文件 | |startPullFile(File file, IPullFileListener listener) |启动客户端拉取云机实例上的文件 | |stopPullFile(File file) |停止客户端拉取云机实例上的文件 | |IPushFileListener |监听客户端向云机实例推送文件的状态回调 | |IPullFileListener |监听客户端拉取云机实例上的文件状态回调 | #### 推送文件数据描述：用于客户端发送文件到云机实例，该接口支持发送本地文件，并且可通过 IPushFileListener 监听发送进度以及到达情况。注意：当有多个发送任务时，SDK 内部会串行执行，依次发送。 ```Java // FileExcahnge class /** * 推送本地文件到云机实例上指定文件夹内 * * @param file 推送的本地文件 * @param target 云机实例上的目标文件夹 * @param listener 用于接收推送进度和到达回执 * */ void startPushFile(File file, File target, IPushFileListener listener); ``` #### IPushFileListener 描述：用于向云机实例推送文件时监听进度以及到达情况。 |接口名称 |接口描述 | |---|---| |onStart(File file) |推送启动时回调 | |onProgress(File file, int progress) |推送进度变化时回调：|\ | ||\ | |* progress（0\-100之间的整数） | |onComplete(File file) |推送完成时回调 | |onError(File file, int err) |当推送失败时回调：|\ | |err 指定错误类型，可参考 [错误码](https://www.volcengine.com/docs/6394/75742#.6ZSZ6K-v56CB5Y-K6K-05piO) | |onCancel(File file) |推送被取消时回调 | ```Java public interface IPushFileListener { /** * 推送启动时回调 * * @param file 推送的本地文件 */ void onStart(File file); /** * 推送进度变更时回调 * * @param file 推送的本地文件 * @param progress 推送进度，取值范围(0,100) */ void onProgress(File file, int progress); /** * 推送完成时回调 * * @param file 推送的本地文件 */ void onComplete(File file); /** * 推送取消时回调 * * @param file 推送的本地文件 */ void onCancel(File file); /** * 当推送失败时回调 * * @param file 推送的本地文件 * @param err 推送失败错误码 */ void onError(File file, int err); } ``` #### 停止推送文件数据描述：停止客户端向云机实例推送文件。 ```Java // FileExcahnge class /** * 取消推送本地文件到云机实例 * * @param file 要取消推送的本地文件 * */ void stopPushFile(File file); ``` #### 拉取文件数据描述：客户端拉取云机实例上的文件，通过 IPullFileListener 来接收拉取文件的状态信息。 ```Java // FileExcahnge class /** * 将云机实例中的文件上传至云存储并返回HTTP下载地址 * * @param file 云机实例上要拉取的文件 * @param listener 用于接收文件拉取进度和到达回执 * */ void startPullFile(File file, IPullFileListener listener); /** * 从云机实例上拉取文件到客户端本地文件夹 * * @param file 云机实例上要拉取的文件 * @param target 客户端本地目标文件夹 * @param listener 用于接收文件拉取进度和到达回执 * */ void startPullFile(File file, File target, IPullFileListener listener); ``` #### IPullFileListener 描述：用于接收客户端拉取云机实例上的文件状态信息回调。 |接口名称 |接口描述 | |---|---| |onStart(File file) |拉取文件开始时回调 | |onProgress(File file, int progress) |拉取文件进度变化时回调|\ | ||\ | |* progress（0\-100之间的整数） | |onComplete(File file) |拉取文件完成时回调 | |onError(File file, int err) |拉取文件失败时回调：|\ | |err 指定错误类型，可参考 [错误码](https://www.volcengine.com/docs/6394/75742#.6ZSZ6K-v56CB5Y-K6K-05piO) | |onCancel(File file) |拉取文件被取消时回调 | ```Java public interface IPullFileListener { /** * 拉取启动时回调 * * @param file 云机实例上的文件 */ void onStart(File file); /** * 拉取进度回调 * * @param file 云机应用上的文件 */ void onProgress(File file, int progress); /** * 拉取完成时回调 * * @param file 云机实例上的文件 * @param url 文件下载地址 */ void onComplete(File file, String url); /** * 拉取取消时回调 * * @param file 云机实例上的文件 */ void onCancel(File file); /** * 当拉取失败时回调 * * @param file 云机实例上的文件 * @param err 拉取失败错误码 */ void onError(File file, int err); } ``` #### 停止拉取文件数据描述：客户端停止拉取云机实例上的文件。 ```Java // FileExchange class /** * 停止拉取云机实例上的文件 * * @param file 要停止拉取的文件 * */ void stopPullFile(File file) ``` ### 本地键盘描述：获取 LocalInputManager，管理本地键盘与云机应用的交互。 #### LocalInputManager ```java // vePhoneEngine class public @Nullable LocalInputManager getLocalInputManager() ``` |接口名称 |接口描述 | |---|---| |setRemoteInputCallBack(RemoteInputCallBack remoteInputCallBack) |设置监听远端键盘弹出的回调，参考以下 **RemoteInputCallBack** | |setKeyboardType(int keyboardType) |切换本地/云机输入法类型|\ | ||\ | |* keyboardType：输入法类型|\ | | * 0：使用云机键盘|\ | | * 1：使用本地键盘|\ | ||\ | |说明：需要在云手机属性 `persist.sys.native_ime` 设置为 `true` 的前提下，该接口才能生效；详细说明，参考 [System Properties 属性列表](/docs/6394/671880#system-properties-%E5%B1%9E%E6%80%A7%E5%88%97%E8%A1%A8) | |getKeyboardType() |查询当前使用的本地/云机输入法类型 | |coverCurrentEditTextMessage(String text) |设置当前输入框的内容 | |enableShowCurrentInputText(boolean enable) |显示自带的 textView，用于显示当前输入框内容，默认不打开 | |closeAutoKeyBoard(boolean isIntercept) |拦截是否打开本地键盘，默认不拦截 SDK 调起本地键盘；当传入true时，由用户自行处理键盘的弹出和内容的发送 | |getEditText() |获取隐藏的输入框对象 | |sendInputText(text) |直接向云机实例输入框发送文本：|\ | ||\ | |* text（发送的文本数据） | |isTextInputEnable() |检查云机实例输入框是否支持发送文本 | 参考示例： ```java public interface LocalInputManager { /** * 设置监听远端键盘弹出的回调 * @param remoteInputCallBack */ void setRemoteInputCallBack(RemoteInputCallBack remoteInputCallBack); /** * 切换本地/云机输入法类型，切换结果通过{@link RemoteInputCallBack#onKeyboardTypeChanged(int)}返回 * @param keyboardType 输入法类型 * @return 0：方法调用成功 -1 方法调用失败 */ int setKeyboardType(int keyboardType); /** * 查询当前本地/云机输入法类型，查询结果通过{@link RemoteInputCallBack#onGetKeyboardTypeResult(int)}返回 * @return 0：方法调用成功 -1 方法调用失败 */ int getKeyboardType(); /** * 设置当前输入框的内容 * @param text 内容字符串 */ void coverCurrentEditTextMessage(String text); /** * 显示自带的输入view ，默认不打开 * @param enable 是否打开 */ void enableShowCurrentInputText(boolean enable); /** * 拦截是否打开本地键盘；默认false 不拦截sdk调起本地键盘；传入true 用户自行处理键盘的弹出和内容的发送 * @param isIntercept 是否拦截本地键盘弹出。 */ void closeAutoKeyBoard(boolean isIntercept); /** * 获取本地隐藏的输入框 * @return 本地的edittext */ EditText getEditText(); /** * 向云机实例输入框发送文本 * @param text 文本数据 * @return 0：方法调用成功 -1 方法调用失败 */ int sendInputText(String text); /** * 云机实例输入框是否支持发送文字 * @return true-支持；false-不支持 */ boolean isTextInputEnable(); } ``` #### RemoteInputCallBack 远端键盘弹出的回调。 |接口名称 |接口描述 | |---|---| |onPrepare(String hintText , int inputType) |远端当前输入框的一些状态回调 | |onCommandShow() |请求弹出软键盘的回调，会多次回调 | |onCommandHide() |请求收起软键盘的回调 | |onTextChange(String text) |远端输入框内容的更改回调 | |onTextInputEnableStateChanged(boolean enable) |云机实例输入框是否支持发送文本状态变化回调：|\ | ||\ | |* enable（是否支持发送文本）：|\ | | * true（支持）|\ | | * false（不支持） | |onKeyboardTypeChanged(int type) |本地/云机输入法类型发生切换回调：|\ | ||\ | |* type：切换后的输入法类型|\ | | * 0：云机键盘|\ | | * 1：本地键盘 | |onGetKeyboardTypeResult(int type) |查询本地/云机输入法类型结果回调|\ | ||\ | |* type：当前输入法类型|\ | | * 0：云机键盘|\ | | * 1：本地键盘 | 参考示例： ```java interface RemoteInputCallBack { /** * @param hintText 提示文 * @param inputType 输入格式 */ void onPrepare(String hintText , int inputType); /** * 远端键盘请求弹出 */ void onCommandShow(); /** * 远端键盘请求收起 */ void onCommandHide(); /** * 监听本地输入内容的改变，可以自定义显示给用户 * @param text 改变的内容 */ void onTextChange(String text); /** * 云机实例输入框是否支持发送文字状态变化回调 * @param enable true-支持；false-不支持 */ void onTextInputEnableStateChanged(boolean enable); /** * 本地/云机输入法类型发生切换回调 * @param type 切换后的输入法类型 */ void onKeyboardTypeChanged(int type); /** * 查询本地/云机输入法类型结果回调 * @param type */ void onGetKeyboardTypeResult(int type); } ``` ### 发送剪贴板消息描述：获取剪贴板管理类、注册云机实例剪贴板回调、发送本地剪贴板消息到云机（需要在收到 onPlaySuccess 播放成功回调之后使用）。 |接口名称 |接口描述 | |---|---| |sendClipBoardMessage() |发送本地剪贴板数据到云机，支持发送文本数据 | |onClipBoardMessageReceived() |收到云机返回的剪贴板数据回调 | 参考示例： ```java // vePhoneEngine class public @Nullable IClipBoardServiceManager getClipBoardServiceManager() ``` ```java /** * @desc 剪贴板操作发送剪贴板数据 */ public interface IClipBoardServiceManager { /** * 云机实例同步过来的剪贴板数据 * @param iClipBoardListener */ void setBoardSyncClipListener(IClipBoardListener iClipBoardListener); /** * 手动发送剪贴板数据 * * @param data 剪贴板数据 */ void sendClipBoardMessage(ClipData data); } ``` :::tip clipData mimeType 仅支持： ClipDescription.MIMETYPE_TEXT_PLAIN ClipDescription.MIMETYPE_TEXT_HTML ::: ```java /** * @desc 回调用户云机剪贴板数据的 listener */ public interface IClipBoardListener { /** * @param clipData 云机返回的剪贴板数据 */ void onClipBoardMessageReceived(ClipData clipData); } ``` ### 清晰度切换描述：在云手机运行过程中，可通过指定清晰度 ID，切换视频流的清晰度。 |接口名称 |接口描述 | |---|---| |switchVideoStreamProfile() |切换视频流的清晰度（`streamProfileId` 的可选值和清晰度配置说明，参考 [云手机清晰度档位说明](/docs/6394/155915) | |setStreamProfileChangeListener() |设置清晰度切换成功的回调 | #### StreamProfileChangeCallBack 清晰度切换成功的回调。 |接口名称 |接口描述 | |---|---| |onVideoStreamProfileChange() |* isSuccess（清晰度是否成功切换）|\ | |* from（切换前的清晰度）|\ | |* to（当前的清晰度） | 对于**云手机多用户加房**的场景，建议使用下面的接口来替换上面的接口： |**接口名称** |**接口描述** | |---|---| |setVideoStreamProfileId(int streamProfileId) |设置当前视频流清晰度档位（`streamProfileId` 的可选值和清晰度配置说明，参考 [云手机清晰度档位说明](/docs/6394/155915) | |getVideoStreamProfileId() |查询当前视频流清晰度档位 | |setVideoStreamProfileListener(VideoStreamProfileListener listener) |设置视频流清晰度档位变化监听器 | 参考示例： ```java // vePhoneEngine class public @Nullable StreamProfileManager getClarityService() ``` ```java public interface StreamProfileManager { void switchVideoStreamProfile(int streamProfileId); void setStreamProfileChangeListener(StreamProfileChangeCallBack streamProfileChangeCallBack); } ``` ```java public interface StreamProfileChangeCallBack { void onVideoStreamProfileChange(boolean isSuccess, int from, int current); } ``` ```java /** * 用于云手机多用户加房场景 */ interface VideoStreamProfileListener { /** * 视频流清晰度档位改变的回调 * * @param callUserId 设置视频流清晰度档位的用户ID * @param result 设置结果 true：成功 false：失败 * @param from 变化前的档位 * @param current 变化后的档位 */ void onVideoStreamProfileChanged(String callUserId, boolean result, int from, int current); /** * 查询视频流清晰度档位的结果回调 * * @param result 查询结果 true：成功 false：失败 * @param current 当前的档位 */ void onGetVideoStreamProfile(boolean result, int current); } ``` ### 云手机画面截图描述：对当前云手机画面进行截图，并获取在云手机实例中保存截图文件的路径以及下载截图文件的地址。 |接口名称 |接口描述 | |---|---| |screenShot() |发起对云手机画面截图请求（默认上传截图文件到火山引擎对象存储） | |screenShot(boolean saveOnPod) |发起对云手机画面截图请求，并指定是否保存截图文件在云手机实例：|\ | ||\ | |* saveOnPod（是否保存截图文件在云手机实例）：|\ | | * true（上传截图文件到火山引擎对象存储，并保存截图文件在云手机实例中）|\ | | * false（上传截图文件到火山引擎对象存储，上传完成后，删除保存在云手机实例中的文件，默认）|\ | ||\ | |截图文件保存和清理逻辑如下：|\ | ||\ | |* 当保存截图文件在云手机实例时，截图超过1000张时会清理之前保存的截图文件；|\ | |* 当上传截图文件到对象存储时，截图上传到对象存储成功后再清理云手机实例中的截图文件；|\ | |* 当云手机存储空间小于600MB时，如指定 `saveOnPod=true`，则不可执行截图操作；如指定 `saveOnPod=false`，可执行截图操作。 | |setScreenShotListener(ScreenShotListener listener) |设置云手机画面截图结果的回调 | 截图结果的回调： |接口名称 |接口描述 | |---|---| |onScreenShot(int code, String savePath, String downloadUrl, String msg) |* code（返回码，0：截图成功并已保存，其他为失败错误码）|\ | |* savePath（在云手机实例中保存截图文件的完整路径，例如：`/sdcard/Pictures/Screenshots/20220721_164937.jpg`）|\ | |* downloadUrl（截图成功时返回截图文件的下载链接，链接有效期1小时）|\ | |* msg（提示信息） | 参考示例： ```java // vePhoneEngine class public @Nullable PodControlService getPodControlService() public interface PodControlService { /** * 设置云手机截图回调 * @param listener 回调 */ void setScreenShotListener(ScreenShotListener listener); /** * 云手机截图 * @return -1表示调用失败，0表示调用成功 * @see PodControlService#screenShot(boolean) */ int screenShot(); /** * 云手机截图，结果通过{@link ScreenShotListener#onScreenShot(int, String, String, String)}返回 * * @param saveOnPod 是否保存截图到云手机本地，默认关闭 * @return -1表示调用失败，0表示调用成功 * @see PodControlService#setScreenShotListener(ScreenShotListener) */ int screenShot(boolean saveOnPod); } interface ScreenShotListener { /** * 截图回调 * * @param code 0-成功并已保存，其他为失败错误码 * @param savePath 截图成功时返回文件在云手机的完整保存路径 * @param downloadUrl 截图文件的下载链接 * @param msg 提示信息 * @see PodControlService#screenShot() */ void onScreenShot(int code, String savePath, String downloadUrl, String msg); } ``` ### 云手机画面录屏描述：对当前云手机画面进行录屏，并获取在云手机实例中保存录屏文件的路径以及下载录屏文件的地址。 |接口名称 |接口描述 | |---|---| |startRecording(int duration, boolean saveOnPod) |发起对云手机画面录屏请求：|\ | ||\ | |* duration（设置最大录屏时长，单位：秒，支持设置的最大值为14400，即4小时）|\ | |* saveOnPod（是否保存录屏文件在云手机实例）：|\ | | * true（上传录屏文件到火山引擎对象存储，并保存录屏文件在云手机实例中）|\ | | * false（上传录屏文件到火山引擎对象存储，上传完成后，删除保存在云手机实例中的文件，默认）|\ | ||\ | |录屏文件保存和清理逻辑如下：|\ | ||\ | |* 当保存录屏文件在云手机实例时，录屏文件超过500个时会清理之前保存的录屏文件；|\ | |* 当上传录屏文件到对象存储时，录屏文件上传到对象存储成功后再清理云手机实例中保存的录屏文件；|\ | |* 录屏文件在对象存储中保存的时间为24小时。 | |stopRecording() |主动停止对当前云手机画面进行录屏 | |setScreenRecordListener(ScreenRecordListener listener) |设置云手机画面录屏结果的回调 | 录屏结果的回调： |接口名称 |接口描述 | |---|---| |onRecordingStatus(int status, String savePath, String downloadUrl, String msg) |* status：录屏任务状态，包括：|\ | | * 0（录制成功，正常结束，上传录屏文件到对象存储成功，返回录像文件保存路径）|\ | | * 1（开始录制成功，正常结束）|\ | | * 2（开始录制成功）|\ | | * 3（开始录制失败，正在录制中时调用了开始录制）|\ | | * 4（结束录制失败，没有录制中的任务）|\ | | * 5（录制失败，云手机存储空间不足，已占用存储空间总量的80%）|\ | | * 6（录制结束，达到录制时限，返回录像文件保存路径）|\ | | * 7（开始录制失败，录制时长超过上限）|\ | |* savePath：（`saveOnPod` 为 true，且 `status` 为 0、1、2 时返回）在云手机实例中保存录像文件的完整路径，默认为 `/sdcard/Pictures/Recordings/recording_yymmdd_[秒级时间戳].mp4`）|\ | |* downloadUrl：（`status` 为 0 时返回）录屏文件下载链接|\ | |* msg：提示信息 | 参考示例： ```java // vePhoneEngine class public @Nullable PodControlService getPodControlService() public interface PodControlService { /** * 设置云手机录屏回调 * * @param listener 回调 */ void setScreenRecordListener(ScreenRecordListener listener); /** * 开始录屏 * * @param duration 录屏时长 * @param saveOnPod 是否保存录屏文件在云手机实例 * @return -1表示调用失败，0表示调用成功 */ int startRecording(int duration, boolean saveOnPod); /** * 停止录屏 * * @return -1表示调用失败，0表示调用成功 */ int stopRecording(); } interface ScreenRecordListener { /** * 录屏结果回调 * * @param status 录屏任务状态 * @param savePath 录屏成功时返回录像文件在云手机中的完整存放路径 * @param downloadUrl 录屏文件下载链接 * @param msg 提示信息 */ void onRecordingStatus(int status, String savePath, String downloadUrl, String msg); } ``` ### 查询屏幕当前焦点应用描述：查询屏幕当前的焦点窗口应用名称。 |接口名称 |接口描述 | |---|---| |getFocusedWindowApp() |获取屏幕当前焦点应用包名 | |setFocusedWindowAppListener(FocusedWindowAppListener listener) |设置获取屏幕当前焦点应用包名结果回调 | 获取屏幕当前焦点应用结果的回调： |接口名称 |接口描述 | |---|---| |onResult(int code, String packageName, String msg) |获取焦点应用结果回调|\ | ||\ | |* code（返回码，0：成功并返回应用包名，其他为失败错误码）|\ | |* packageName（当前焦点应用包名）|\ | |* msg（提示信息） | |onFocusedWindowAppChanged(String appPackageName) |焦点窗口应用发生变化时回调|\ | ||\ | |* packageName（变化后的焦点应用包名） | 参考示例： ```java // vePhoneEngine class public @Nullable PodControlService getPodControlService() public interface PodControlService { /** * 获取屏幕当前焦点应用包名，结果通过{@link FocusedWindowAppListener#onResult(int, String, String)}接口返回 * * @return -1表示调用失败，0表示调用成功 * @see FocusedWindowAppListener#onResult(int, String, String) */ int getFocusedWindowApp(); /** * 设置屏幕当前焦点应用包名结果回调 * * @param listener 回调 */ void setFocusedWindowAppListener(FocusedWindowAppListener listener); interface FocusedWindowAppListener { /** * 获取屏幕当前焦点应用包名回调 * * @param code 0-成功并返回应用包名，其他为失败错误码 * @param packageName 应用包名 * @param msg 错误信息 */ void onResult(int code, String packageName, String msg); /** * 焦点窗口应用发生变化时回调，如果仅应用内Activity窗口发生变化，但是应用包名未变化则不回调 * * @param packageName 变化后的应用包名 */ void onFocusedWindowAppChanged(String appPackageName); } ``` ### 导航栏开关描述：设置和查询云手机当前导航栏开关状态（打开/隐藏）。 |接口名称 |接口描述 | |---|---| |setNavBarStatus(int status) |设置导航栏开关状态（异步，设置结果通过 NavBarStatusChangeListener 接收），枚举值如下：|\ | ||\ | |* 1（打开导航栏，launcher和非全面屏应用会显示导航栏，但申请全面屏时，应用导航栏自动隐藏）|\ | |* 0（隐藏导航栏） | |getNavBarStatus() |查询云手机当前导航栏开关设置（异步，查询结果通过 NavBarStatusChangeListener 接收） | |setNavBarStatusChangeListener(NavBarStatusChangeListener listener) |设置云手机导航栏开关状态变化监听 | 云手机导航栏开关状态变化回调（设置和查询导航栏开关状态都会触发该回调的执行）： |接口名称 |接口描述 | |---|---| |onNavBarStatus(int status, int reason) |导航栏开关状态变化回调：|\ | ||\ | |* status（开关状态）：|\ | | * 1（导航栏已打开）|\ | | * 0 （导航栏已隐藏）|\ | | * \-1（参数错误）|\ | |* reason（调用来源）：|\ | | * 0（服务端切换操作的回调）|\ | | * 1（SDK 调用，`getNavBarStatus(int)` 方法返回结果）|\ | | * 2（SDK 调用，`setNavBarStatus()` 方法返回结果）|\ | | * \-1（SDK 查询错误） | 参考示例： ```java // vePhoneEngine class public @Nullable PodControlService getPodControlService() public interface PodControlService { /** * 设置导航栏开关状态 * @param status 0-隐藏导航栏；1-打开导航栏； * @return -1表示调用失败，0表示调用成功 */ int setNavBarStatus(int status); /** * 异步获取当前导航栏的状态 * 具体的状态信息，通过{@link NavBarStatusChangeListener}接收 * * @return -1表示调用失败，0表示调用成功 */ int getNavBarStatus(); /** * 设置导航栏开关状态变化监听 * * @param listener 回调 */ void setNavBarStatusChangeListener(NavBarStatusChangeListener listener); } interface NavBarStatusChangeListener { /** * 服务端改变导航栏状态 * * @param status 0:隐藏导航栏；1:打开导航栏；-1:无效状态 * @param reason 回调原因(来源) */ void onNavBarStatus(int status, int reason); } ``` ### 更新 Token 有效期描述：拉流过程中动态更新 Token 过期时间。 |**接口名称** |**接口描述** | |---|---| |updateExpireTime |若启动拉流时限定了拉流 Token 有效期，Token 到期前 30s 时会收 WARNING_TOKEN_WILL_EXPIRE(34001) 警告，提示拉流即将过期，期间可调用本接口更新 Token 到期时间，延长拉流时间。若未更新，则到期后将自动断开与云手机实例的连接。|\ | |**参数**：|\ | |ak：用户鉴权临时 access key|\ | |sk：用户鉴权临时 secret key|\ | |token：用户鉴权临时 Token|\ | |expireTime：拉流有效期 | |setUpdateExpireTimeListener |设置更新拉流 Token 有效期结果的监听器。|\ | |**参数**：|\ | |listener：监听器，参看 `UpdateExpireTimeListener`。 | 参考示例： ```java /** * 设置过期时长 * * @param expireTime 过期时长，单位：秒，取值范围：[0, 48 * 60 * 60] * @return 0: 调用成功，<0: 调用失败 */ int updateExpireTime(String ak, String sk, String token, @IntRange(from = 0, to = 48 * 60 * 60) long expireTime); /** * 设置过期时长结果的监听器 * * @param listener 监听器 */ void setUpdateExpireTimeListener(UpdateExpireTimeListener listener); interface UpdateExpireTimeListener { /** * 更新过期时间结果回调 * * @param result 0：更新成功，<0：更新失败 * @param msg 详细信息 */ void onUpdateExpireTimeResult(int result, String msg); ``` ## 调试及日志接口 ### 设置 Debug 模式描述：设置调试模式，在该模式下会打印日志信息。 ```java // vePhoneEngine class static void setDebug(boolean debug) ``` ### 获取设备 ID 描述：获取 SDK 生成的设备 ID，用于后台查询 SDK 日志，进行调试和问题排查（建议接入方在需要问题排查时，提供给火山引擎技术支持）。 ```java public String getDeviceId() ``` ### 获取 SDK 版本信息 ```java // vePhoneEngine class static String getSDKVersion() ``` ### 同步 WiFi 与 Radio 信息 > * 确保使用的 Android 客户端 SDK 包版本为 1.63.2 及以上。 > * 目前已知该功能暂不支持 Android 16。由于涉及隐私合规问题，使用前需在 `AndroidManifest.xml` 文件中声明 vePhoneSDK 需要的权限： ```objectivec

``` #### SyncInfoScope `syncInfoScope(@SyncInfoScope int scope)`用于配置允许同步的设备信息范围，默认为关闭状态（`{@link SyncInfoScope#NONE}`），可按需开启。 ```Java /** * 客户端向pod同步的信息范围，由于会涉及隐私合规问题故默认关闭{@link SyncInfoScope#NONE}，业务方可以按需开启 */ @Retention(RetentionPolicy.CLASS) @IntDef({SyncInfoScope.ALL, SyncInfoScope.NONE, SyncInfoScope.WIFI, SyncInfoScope.RADIO}) public @interface SyncInfoScope { int ALL = -1; // 开启全部信息同步 int NONE = 0; // 关闭 int WIFI = 1; // 仅同步 WiFi 信息 int RADIO = 1 << 1; // 仅同步 Radio 信息 } ``` #### SyncInfoStrategy `syncInfoStrategy(SyncInfoStrategy strategy)`用于配置信息同步策略。 * `SyncInfoStrategy.oneshot()`：会话生命周期内仅上报一次（默认同步策略）。 * `SyncInfoStrategy.whenChanged()`：当网络类型发生变化时触发。 * `SyncInfoStrategy.cyclic(int intervalInSeconds)`：以固定周期进行上报。 ## 警告码及说明警告码回调接口为 `IPlayerListener#onWarning`，具体错误原因见回调接口中的 `message`。 |警告码 |警告信息 |说明 | |---|---|---| |10010 |WARNING_START_NO_STOP_BEFORE |启动云手机失败。原因：同一个客户端连续调用了两次启动接口之间没有调用停止接口。建议：请调用停止接口，结束上一次 “游戏”，再调用启动接口。 | |10019 |WARNING_START_INVALID_AUTO_RECYCLE_TIME |设置无操作推流服务回收时长出错。建议：请参考 `setAutoRecycleTime` 接口描述进行设置。 | |30007 |WARNING_SDK_LACK_OF_LOCATION_PERMISSION |SDK 无定位服务权限。原因：定位服务权限未开启。建议：检查设备定位服务权限是否开启。 | |30012 |WARNING_UNEXPECTED_CONTEXT_TYPE |客户端传入 Context 类型错误。原因：预期客户端传入 Activity，但实际传入了全局 Context。建议：请将 Container 的 Context 修改为 Activity。 | |30013 |WARNING_SDK_LOCATION_DISABLED |云端请求定位时，客户端未开启定位功能。 | |34001 |WARNING_TOKEN_WILL_EXPIRE |拉流 token 即将过期，如果想继续维持拉流状态，请调用 [updateExpireTime](#.5pu05pawLXRva2VuLeacieaViOacnw==) 接口以延长拉流有效期。 | |40037 |WARNING_LOCAL_ALREADY_SET_BACKGROUND |应用切换后台失败。原因：应用已处于后台，请勿重复调用。 | |40038 |WARNING_LOCAL_ALREADY_SET_FOREGROUND |应用切换前台失败。原因：应用已处于前台，请勿重复调用。 | |40040 |WARNING_FOREGROUND_CHANGE_STATUS_NO_PACKAGENAME |云机应用切换前台失败。原因：应用包名不存在。建议：请检查指定的应用包名是否正确。 | |40041 |WARNING_FOREGROUND_CHANGE_STATUS_REPEAT |云机应用切换前台失败。原因：云机应用已处于前台，请勿重复调用。 | |40043 |WARNING_FOREGROUND_CHANGE_STATUS_NOTFOND |云机应用切换前台失败。原因：指定的应用不在后台或已被关闭。 | |40044 |WARNING_GAME_STOPPED_INGAME_EXIT |应用停止。原因：一般是因为云机运行的应用主动退出了。建议：客户端需要提示用户目前应用主动被结束了，如果需要，可以重新开始应用。 | |40054 |WARNING_NATIVE_IME_DISABLED |不允许设置输入法类型 | |61001 |WARNING_START_NET_REQUEST_CANCEL |网络请求取消 | ## 错误码及说明错误码回调接口为 `IPlayerListener#onError`，具体错误原因见回调接口中的 `message` 。 |错误码 |错误信息 |说明 | |---|---|---| |20000 |ERROR_STREAM_GENERAL |串流连接错误。原因：网络原因。建议：请检查网络。 | |20002 |ERROR_STREAM_CHANGE_CLARITY_ID_NOT_IN_START_STATE |切换清晰度失败。原因：当前处于非播放状态。建议：请调用启动接口，在收到播放成功回调后，再调用切换清晰度档位接口。 | |30000 |ERROR_SDK_GENERAL |客户端 SDK 通用错误。 | |30001 |ERROR_SDK_INIT_FAILED |客户端 SDK 初始化失败。 | |30002 |ERROR_SDK__EMPTY |客户端调用 SDK 接口错误。原因：接口参数为空。建议：请参考接口说明文档，检查接口参数。 | |30009 |ERROR_INIT_ACCOUNT_ID_ILLEGAL |未指定火山引擎账号。建议：通过火山引擎官网页面右上角 **用户 \> 账号管理 \> 主账号信息** 获取正确的账号。 | |30010 |ERROR_CREATE_ENGINE_ERROR |创建 Engine 失败。建议：联系火山引擎云游戏技术支持。 | |30201 |ERROR_DOWNLOAD_PLUGIN_FAILED |下载插件失败。建议：检查 vePhoneSDK 以及插件包的依赖是否配置正确。 | |30203 |ERROR_INJECT_DEX_FAILED |classLoader 加载插件失败。建议：检查 vePhoneSDK 以及插件包是否已成功下载。 | |30204 |ERROR_CHECK_PLUGIN_FAILED |检查插件失败。建议：检查 vePhoneSDK 以及插件包是否已成功下载。 | |30205 |ERROR_LOAD_PLUGIN_FAILED |加载插件失败。检查 vePhoneSDK 以及插件包是否已成功下载。 | |31006 |ERROR_ABI_IS_NOT_SUPPORT |未能识别的 ABI 类型。原因：设备可能为模拟器或者特殊设备。建议：联系火山引擎云游戏技术支持。 | |40010 |ERROR_POD_STREAM_TIMEOUT |拉流超时的兜底错误码（拉流超时相关错误码还包括 40012、40013、40014、40015）。如遇该报错可稍后重试，或在业务内设置弹窗报错逻辑。 | |40012 |ERROR_CLIENT_JOIN_TIMEOUT |客户端加房超时，通常是手机网络异常导致。 | |40013 |ERROR_POD_JOIN_TIMEOUT |Pod 加房超时，通常是 Pod 状态、性能或网络等异常导致，请稍后重试。 | |40014 |ERROR_POD_PUBLISH_TIMEOUT |Pod 发布视频流超时，通常是 Pod 性能或网络原因导致，请稍后重试。 | |40015 |ERROR_CLIENT_FIRST_FRAME_TIMEOUT |客户端接收首帧超时，通常是手机网络异常导致。 | |40045 |ERROR_STORAGE_NOT_ENOUGH |云手机存储空间不足。原因：存储云手机画面截图文件的空间不足，请清理存储空间后再尝试截图操作。 | |40046 |ERROR_POD_UNKNOWN_FAILURE |未知错误，云手机画面截图失败，请稍后重试。 | |40055 |ERROR_REMOTE_STOPPED_TOKEN_EXPIRED |应用停止。原因：拉流 token 已过期，请再次调用 start 接口重新启动拉流。 | |60001 |ERROR_NET_REQUEST_ERROR |网络请求失败。 | |60002 |ERROR_HTTP_REQUEST_ERROR |网络请求失败。 | |71001 |ERROR_FILE_CHANNEL_FILE_NOT_FOUND |文件传输失败。原因：推送或拉取的文件不存在。建议：请检查文件名是否正确且确保文件存在后重试。 | |71002 |ERROR_FILE_CHANNEL_FILE_NO_ACCESS |文件传输失败。原因：无访问权限推送或拉取文件。建议：提示用户通过客户端申请目标目录的文件读写权限。 | |71003 |ERROR_FILE_CHANNEL_NETWORK_ABORT |文件传输失败。原因：推送或拉取文件过程中网络异常中断。建议：请检查网络连接后重试。 | |71004 |ERROR_FILE_CHANNEL_TIMEOUT |文件传输失败。原因：推送或拉取文件过程中超时。建议：请检查网络连接后重试。 | |71005 |ERROR_FILE_CHANNEL_STORAGE_NOT_ENOUGH |文件传输失败。原因：推送或拉取文件磁盘空间不足。建议：请确保有足够的存储空间保存文件。 | |71006 |ERROR_FILE_CHANNEL_INTERNAL_ERROR |文件传输失败。原因：推送或拉取文件发生内部错误，通常是依赖库集成原因触发的。建议：请检查应用引入依赖库是否与云手机 SDK 冲突。 | |71007 |ERROR_FILE_CHANNEL_UNSPPORTED |文件传输失败。原因：发送文件不支持低于8.0版本的 Android 系统。建议：请检查系统版本是否低于 Android 8.0。 |