Electron 客户端升级指南--实时音视频-火山引擎

文档中心

立即注册

实时音视频

升级指南

Electron 客户端升级指南

如果你希望从此前版本的 Electron 客户端 SDK 升级到最新的客户端 SDK，请在工程文件中，替换最新的客户端 SDK 文件，并参考本文完成 API，回调，参数类型等的替换。

升级过程中，你可能需要参考历史版本文档归档。

3.57

回调变更

序号	变更详情	功能模块	变更前回调	变更后回调	说明
1	参数变更	消息	`onLogout() => void`	`onLogout(reason: LogoutReason) => void`	在 `onLogout` 回调上新增 reason 参数，区分用户主动/被动登出。具体参数类型参看 `LogoutReason`。

类型变更

序号	变更详情	功能模块	改动的数据类型	说明
1	成员变量新增	字幕翻译服务	`SubtitleMessage`	在字幕内容回调 `onSubtitleMessageReceived` 的参数 `SubtitleMessage` 中新增成员变量 `language` 和 `mode`，可用于同时收到字幕原文和字幕译文。
2	成员变量变更	CDN 推流	`MixedStreamLayoutRegionConfig`	转推直播单个用户画面由设置相对于整体画面的归一化比例变更为可设置像素绝对值。
3	成员变量新增	音频管理	`AudioPropertiesInfo`	新增变量 `voicePitch` 返回本地用户的人声基频。
4	成员变量新增	引擎管理	`LogConfig`	新增变量 `log_filename_prefix` 用于自定义日志文件前缀。

规范代码风格

该版本对所有不规范的枚举值和成员变量名进行了统一修复，对齐 Native 端名称，提升代码规范度和易用性。

枚举值

变更对象	3.54 及之前版本	3.57
`StreamLayoutMode`	`kLayoutAutoMode` `kLayoutCustomerMode`	`kStreamLayoutModeAuto` `kStreamLayoutModeCustom`
`SEICountPerFrame`	`kSingleSEIPerFrame` `kMultiSEIPerFrame`	`kSEICountPerFrameSingle` `kSEICountPerFrameMulti`
`CapturePreference`	`KAuto` `KManual` `KAutoPerformance`	`kAuto` `kManual` `kAutoPerformance`
`RecordingType`	`kRecordAudioOnly` `kRecordVideoOnly` `kRecordVideoAndAudio`	`kRecordingTypeAudioOnly` `kRecordingTypeVideoOnly` `kRecordingTypeVideoAndAudio`
`VirtualBackgroundSourceType`	`kVirtualBackgroundSourceColor` `kVirtualBackgroundSourceImage`	`kVirtualBackgroundSourceTypeColor` `kVirtualBackgroundSourceTypeImage`
`ZoomConfigType`	`kZoomFocusOffset` `kZoomMoveOffset`	`kZoomConfigTypeFocusOffset` `kZoomConfigTypeMoveOffset`
`ZoomDirectionType`	`kCameraMoveLeft` `kCameraMoveRight` `kCameraMoveUp` `kCameraMoveDown` `kCameraZoomOut` `kCameraZoomIn` `kCameraReset`	`kZoomDirectionTypeMoveLeft` `kZoomDirectionTypeMoveRight` `kZoomDirectionTypeMoveUp` `kZoomDirectionTypeMoveDown` `kZoomDirectionTypeZoomOut` `kZoomDirectionTypeZoomIn` `kZoomDirectionTypeReset`
`AudioFrameCallbackMethod`	`kAudioFrameCallbackRecord` `kAudioFrameCallbackPlayback` `kAudioFrameCallbackMixed` `kAudioFrameCallbackRemoteUser` `kAudioFrameCallbackRecordScreen`	`kRecord` `kPlayback` `kMixed` `kRemoteUser` `kRecordScreen`
`AudioAlignmentMode`	`kAudioAlighmentModeOff` `kAudioAlighmentModeAudioMixing`	`kAudioAlignmentModeOff` `kAudioAlignmentModeAudioMixing`
`SetRoomExtraInfoResult`	`kSetRoomExtraInfoErrorNotJoinRoom` `kSetRoomExtraInfoErrorKeyIsNull` `kSetRoomExtraInfoErrorValueIsNull` `kSetRoomExtraInfoResultUnknow` `kSetRoomExtraInfoErrorKeyIsEmpty` `kSetRoomExtraInfoErrorTooOften` `kSetRoomExtraInfoErrorSilentUser` `kSetRoomExtraInfoErrorKeyTooLong` `kSetRoomExtraInfoErrorValueTooLong` `kSetRoomExtraInfoErrorServer` `kSetRoomExtraInfoResultSuccess`	`kSetRoomExtraInfoResultErrorNotJoinRoom` `kSetRoomExtraInfoResultErrorKeyIsNull` `kSetRoomExtraInfoResultErrorValueIsNull` `kSetRoomExtraInfoResultResultUnknow` `kSetRoomExtraInfoResultErrorKeyIsEmpty` `kSetRoomExtraInfoResultErrorTooOften` `kSetRoomExtraInfoResultErrorSilentUser` `kSetRoomExtraInfoResultErrorKeyTooLong` `kSetRoomExtraInfoResultErrorValueTooLong` `kSetRoomExtraInfoResultErrorServer` `kSetRoomExtraInfoSuccess`
`HardwareEchoDetectionResult`	`kHardwareEchoDetectionCanceled` `kHardwareEchoDetectionUnknown` `kHardwareEchoDetectionNormal` `kHardwareEchoDetectionPoor`	`kHardwareEchoDetectionResultCanceled` `kHardwareEchoDetectionResultUnknown` `kHardwareEchoDetectionResultNormal` `kHardwareEchoDetectionResultPoor`
`StreamMixingEvent`	`kStreamMixingStart` `kStreamMixingStartSuccess` `kStreamMixingStartFailed` `kStreamMixingUpdate` `kStreamMixingUpdateSuccess` `kStreamMixingUpdateFailed` `kStreamMixingStop` `kStreamMixingStopSuccess` `kStreamMixingStopFailed` `kStreamMixingChangeMixType` `kStreamMixingFirstAudioFrameByClientMix` `kStreamMixingFirstVideoFrameByClientMix` `kStreamMixingUpdateTimeout` `kStreamMixingStartTimeout` `kStreamMixingRequestParamError` `kStreamMixingMixImageEvent`	`kStreamMixingEventStart` `kStreamMixingEventStartSuccess` `kStreamMixingEventStartFailed` `kStreamMixingEventUpdate` `kStreamMixingEventUpdateSuccess` `kStreamMixingEventUpdateFailed` `kStreamMixingEventStop` `kStreamMixingEventStopSuccess` `kStreamMixingEventStopFailed` `kStreamMixingEventChangeMixType` `kStreamMixingEventFirstAudioFrameByClientMix` `kStreamMixingEventFirstVideoFrameByClientMix` `kStreamMixingEventUpdateTimeout` `kStreamMixingEventStartTimeout` `kStreamMixingEventRequestParamError` `kStreamMixingEventMixImageEvent`
`SingleStreamPushEvent`	`kSingleStreamPushStart` `kSingleStreamPushSuccess` `kSingleStreamPushFailed` `kSingleStreamPushStop` `kSingleStreamPushTimeout` `kSingleStreamPushParamError`	`kSingleStreamPushEventStart` `kSingleStreamPushEventSuccess` `kSingleStreamPushEventFailed` `kSingleStreamPushEventStop` `kSingleStreamPushEventTimeout` `kSingleStreamPushEventParamError`

成员变量

变更对象	3.54 及之前版本	3.57
`SourceCrop`	`LocationX` `LocationY` `WidthProportion` `HeightProportion`	`location_x` `location_y` `width_proportion` `height_proportion`
`EchoTestConfig`	`audioPropertiesReportInterval` `roomId`	`audio_properties_report_interval` `room_id` `enable_audio` `enable_video`
`VideoEncoderConfig`	`frameRate` `maxBitrate` `minBitrate` `encoderPreference`	`frame_rate` `max_bitrate` `min_bitrate` `encoder_preference`
`ScreenCaptureSourceInfo`	`primaryMonitor`	`primary_monitor`
`ScreenVideoEncoderConfig`	`frameRate` `maxBitrate` `minBitrate` `encoderPreference`	`frame_rate` `max_bitrate` `min_bitrate` `encoder_preference`
`VideoCaptureConfig`	`capturePreference` `frameRate`	`capture_preference` `frame_rate`
`RTCWatermarkConfig`	`visibleInPreview` `positionInLandscapeMode` `positionInPortraitMode`	`visible_in_preview` `position_in_landscape_mode` `position_in_portrait_mode`
`MixedStreamVideoConfig`	`enable_Bframe`	`enable_bframe`
`RtcRoomStats`	`txLostrate` `rxLostrate`	`tx_lostrate` `rx_lostrate`

错误码变更

以下表格中的错误码发生了变化，你需要进行相应的处理：

变更详情	错误码	备注
名称变更	`AudioRecordingErrorCode` `kAudioRecordingErrorNotInRoom` `kAudioRecordingAlreadyStarted` `kAudioRecordingNotStarted`	变更为： `kAudioRecordingErrorCodeNotInRoom` `kAudioRecordingErrorCodeAlreadyStarted` `kAudioRecordingErrorCodeNotStarted`
名称变更	`StreamMixingErrorCode` `kStreamMixingErrorOK` `kStreamMixingErrorBase` `kStreamMixingErrorInvalidParam` `kStreamMixingErrorInvalidState` `kStreamMixingErrorInvalidOperator` `kStreamMixingErrorTimeout` `kStreamMixingErrorInvalidParamByServer` `kStreamMixingErrorSubTimeoutByServer` `kStreamMixingErrorInvalidStateByServer` `kStreamMixingErrorAuthenticationByCDN` `kStreamMixingErrorTimeoutBySignaling` `kStreamMixingErrorMixImageFail` `kStreamMixingErrorUnKnownByServer`	变更为： `kStreamMixingErrorCodeOK` `kStreamMixingErrorCodeBase` `kStreamMixingErrorCodeInvalidParam` `kStreamMixingErrorCodeInvalidState` `kStreamMixingErrorCodeInvalidOperator` `kStreamMixingErrorCodeTimeout` `kStreamMixingErrorCodeInvalidParamByServer` `kStreamMixingErrorCodeSubTimeoutByServer` `kStreamMixingErrorCodeInvalidStateByServer` `kStreamMixingErrorCodeAuthenticationByCDN` `kStreamMixingErrorCodeTimeoutBySignaling` `kStreamMixingErrorCodeMixImageFail` `kStreamMixingErrorCodeUnKnownByServer`

3.54

该版本为全部 API 增加返回值，通过返回值可以明确发现失败的 API 调用，定位失败原因。具体返回值的含义参看各 API 注释。

方法变更

变更详情	功能模块	变动前方法	变动后方法	说明
拆分	音视频传输	`setPublicStreamVideoSink`	拆分为两个方法绑定：`setPublicStreamVideoSink` 解绑：`unsetPublicStreamVideoSink`
行为变更	音频管理	`enumerateAudioCaptureDevices` `enumerateAudioPlaybackDevices`		等待超时后返回空列表，超时时间默认为 10 s
行为变更	视频管理	`enumerateVideoCaptureDevices`		等待超时后返回空列表，超时时间默认为 10 s
参数变更	引擎管理	`createRTCVideo`删除了入参 document_path。使用 `setLogConfig` 指定日志相关配置。
混音相关的方法从 `RTCVideo` 中剥离出来，具体变动情况请参看混音相关的新旧接口对应表	混音	`RTCVideo`	`RTCMediaPlayer` `RTCAudioEffectPlayer`	一般来说，对于短时间的音效（比如小于 20s），可以使用音效类；对于较长的音频或 PCM 数据，可以使用音乐类。

类型变更

变更详情	数据类型	说明
参数变更	`IAudioFrame`	变量 `type` 名称变更为 `frame_type`
类型变更	`format`	类型由 `number` 变更为枚举类 `VideoPixelFormat`
参数增删	`IDataFrame`	删除无意义字段 `u32_data_size`
参数增删	`IPublicStreamParam`	增加参数 `bg_color`

错误码变更

变更详情	错误码	备注
枚举值增删	`ErrorCode`	删除枚举值：`kErrorCodeOverScreenPublishLimit = -1081`、`kErrorCodeOverVideoPublishLimit = -1082`

附：混音相关的新旧接口对应表

接口分类	接口用途	废弃类/接口	新类/接口（音效 RTCAudioEffectPlayer）	新类/接口（音乐 RTCMediaPlayer）	备注
混音主调接口	将音效文件加载至内存	`preloadAudioMixing` `unloadAudioMixing`	`preload` `unload` `unloadAll`	`open`
	播放/停止/暂停/恢复	`startAudioMixing` `stopAudioMixing` `stopAllAudioMixing` `pauseAudioMixing` `pauseAllAudioMixing` `resumeAudioMixing` `resumeAllAudioMixing`	`start` `stop` `stopAll` `pause` `pauseAll` `resume` `resumeAll`	`start` `stop` `pause` `resume`
	获取/指定位置/时长	`setAudioMixingPosition` `getAudioMixingCurrentPosition` `getAudioMixingDuration`	`setPosition` `getPosition` `getDuration`	`setPosition` `getPosition` `getTotalDuration` `getPlaybackDuration`
	获取/指定音量	`setAudioMixingVolume` NA	`setVolume` `setVolumeAll` `getVolume`	`setVolume` `getVolume`
	调整音调	`setAudioMixingPitch`	NA	`setAudioPitch`
	设置声道模式	`setAudioMixingDualMonoMode`	NA	`setAudioDualMonoMode`
	获取/设置音轨数	`getAudioTrackCount` `selectAudioTrack`	NA	`getAudioTrackCount` `selectAudioTrack`	`Index` 取值修改为从 0 开始
	设置播放速度	`setAudioMixingPlaybackSpeed`	NA	`setPlaybackSpeed`
	设置播放进度回调间隔	`setAudioMixingProgressInterval`	NA	`setProgressInterval`
	设置响度	`setAudioMixingLoudness`	NA	`setLoudness`
混音回调接口	播放状态回调	`onAudioMixingStateChanged`	`setEventHandler` `onAudioEffectPlayerStateChanged`	`setEventHandler` `onMediaPlayerStateChanged` `onMediaPlayerPlayingProgress`

3.52

方法变更

变更详情	功能模块	方法	说明
参数变更	引擎管理	`feedback`	参数数据类型变更
接口名称变更	CDN 推流	`startLiveTranscoding`	用 `startPushMixedStreamToCDN` 替代
		`stopLiveTranscoding`	用 `stopPushStreamToCDN` 替代
		`updateLiveTranscoding`	用 `updatePushMixedStreamToCDN` 替代
接口废弃	高级功能	`updatePosition` `updateSelfOrientation`	用 `updateSelfPosition()` 替代，新接口支持本地用户同时设置自己的发声位置和发声朝向。
接口废弃	高级功能	`updateListenerPosition` `updateListenerOrientation`	用 `updateRemotePosition()`替代，新接口支持本地用户设置远端用户的发声位置和发声朝向。

回调变更

变更详情方法说明

变更详情	方法	说明
参数变更	`onPublicStreamSEIMessageReceived`	参数 `sourceType` 的类型由 `SEIMessageSourceType` 变更为 `DataMessageSourceType` 拆分为： `onPublicStreamSEIMessageReceived`：接收客户端插入的 SEI 消息。 `onPublicStreamDataMessageReceived`：接收服务端插入的 SEI 消息和其他数据信息，例如音量信息。

参数变更

onPublicStreamSEIMessageReceived

参数 sourceType 的类型由 SEIMessageSourceType 变更为 DataMessageSourceType
拆分为：

onPublicStreamSEIMessageReceived：接收客户端插入的 SEI 消息。
onPublicStreamDataMessageReceived：接收服务端插入的 SEI 消息和其他数据信息，例如音量信息。

错误码变更

变更详情 错误码 说明

变更详情	错误码	说明
枚举值变更	`PublicStreamErrorCode`` \| 新增枚举值： \|	`kPublicStreamErrorCodePullNoPushStream = 1300` 名称变更： `kPublicStreamOK = 0` 更新为 `kPublicStreamErrorCodeOK = 0` `kPublicStreamPushInvalidParam = 1191` 更新为 `kPublicStreamErrorCodePushInvalidParam = 119` `kPublicStreamPushInvalidStatus = 1192` 更新为 `kPublicStreamErrorCodePushInvalidStatus = 1192` `kPublicStreamPushInternalError = 1193` 更新为 `kPublicStreamErrorCodePushInternalError = 1193` `kPublicStreamPushFailed = 1195` 更新为 `kPublicStreamErrorCodePushFailed = 1195` `kPublicStreamPushTimeout = 1196` 更新为 `kPublicStreamErrorCodePushTimeout = 1196`
`ErrorCode`	新增错误码枚举值：`kErrorCodeJoinRoomRoomForbidden=-1025` 和 `kErrorCodeJoinRoomUserForbidden=-1026`。当服务端在指定房间封禁指定用户，而此用户加入房间失败，或从房间中被踢出时收到。
废弃枚举值：`kErrorCodeOverScreenPublishLimit=-1081`，用 `kErrorCodeOverStreamPublishLimit=-1080` 代替。

枚举值变更

PublicStreamErrorCode` | 新增枚举值： |

kPublicStreamErrorCodePullNoPushStream = 1300

名称变更：

kPublicStreamOK = 0 更新为 kPublicStreamErrorCodeOK = 0
kPublicStreamPushInvalidParam = 1191 更新为 kPublicStreamErrorCodePushInvalidParam = 119
kPublicStreamPushInvalidStatus = 1192 更新为 kPublicStreamErrorCodePushInvalidStatus = 1192
kPublicStreamPushInternalError = 1193 更新为 kPublicStreamErrorCodePushInternalError = 1193
kPublicStreamPushFailed = 1195 更新为 kPublicStreamErrorCodePushFailed = 1195
kPublicStreamPushTimeout = 1196 更新为 kPublicStreamErrorCodePushTimeout = 1196

ErrorCode 新增错误码枚举值：kErrorCodeJoinRoomRoomForbidden=-1025 和 kErrorCodeJoinRoomUserForbidden=-1026。当服务端在指定房间封禁指定用户，而此用户加入房间失败，或从房间中被踢出时收到。

废弃枚举值：kErrorCodeOverScreenPublishLimit=-1081，用 kErrorCodeOverStreamPublishLimit=-1080 代替。

3.50

接口类名称由 veRTCVideo 变更为 RTCVideo，veRTCRoom 变更为 RTCRoom。

方法变更

变更详情	功能模块	变动前方法	变动后方法	备注
返回值变更	房间管理	`joinRoom` 返回值含义如下： `-1`：无效的参数。 `-2`：已经在房间内。	`joinRoom` 返回值含义如下： `-1`：调用失败。 `-2`：无效的参数。 `-4`：已经在房间内。	返回值为 `0` 代表成功，不变。
	网络管理	`stopEchoTest` 返回 `-1` 代表失败，未开启回路检测。	`stopEchoTest` 返回 `-3` 代表失败，未开启回路检测
	引擎管理	`setBusinessId` 返回值含义如下： `< 0`：失败，具体原因参照 `BusinessCheckCode`。 `-6001`：用户已经在房间中。 `-6002`：输入非法。	`setBusinessId` 返回值含义如下： `< 0`：失败，具体原因参照 `ReturnStatus` `-2`：输入非法。
拆分	视频管理	registerFaceDetectionObserver	* enableFaceDetection * disableFaceDetection	解除人脸识别与视频特效之间的耦合，提升接口易用性。
废弃	范围语音	registerRangeAudioObserver onRangeAudioInfor	None	此前，在手动订阅的场景下，如果你希望使用范围语音功能，你必须注册相关回调获取的衰减系数，设定音量。自此版本起，无论是手动订阅还是自动订阅，衰减效果都由 SDK 实现，无需使用此接口。
替代	音频管理	muteAudioPlayback	setPlaybackVolume	将本地音量设置为 0 可静音本地音频播放
参数类型变更	屏幕共享	public setVideoEncoderConfig(solutions: VideoEncoderConfig[]): number	setScreenVideoEncoderConfig(screenSolution: VideoEncoderConfig): any;	参数类型变更为新增的 VideoEncoderConfig
拆分	音视频处理	* checkLicense * setAlgoModelPath	initCVResource
		enableEffect	* enableVideoEffect * disableVideoEffect
		updateNode	updateEffectNode
		setBackgroundSticker	* enableVirtualBackground * disableVirtualBackground
参数变更	消息	public sendSEIMessage(stream_index: number, message: Uint8Array, repeat_count: number) => number	public sendSEIMessage(stream_index: number,message: Uint8Array,repeat_count: number,mode: SEICountPerFrame): number	支持 SEI 多发模式，即在 1 帧间隔内多次发送 SEI 数据时，多个 SEI 随下个视频帧同时发送。

回调变更

以下表格中的回调发生了变化。你需要在工程文件中找到该回调，并进行相关修改：

变更详情	功能模块	变动前方法	变动后方法	备注
参数变更	消息	onPublicStreamSEIMessageReceived(public_stream_id: string, message: string) => void	onPublicStreamSEIMessageReceived(public_stream_id: string, source_type: SEIMessageSourceType) => void	新增参数 source_type
接口废弃	音频管理	onRemoteAudioStateChanged 和 onRemoteVideoStateChanged	/
替代	CDN 推流	* onStreamMixingVideoFrame * onStreamMixingAudioFrame * onStreamMixingDataFrame	* onMixingVideoFrame * onMixingAudioFrame * onMixingDataFrame

类型变更

变更详情	数据类型	备注
成员变量变更	FaceDetectResult	新增成员变量：frame_timestamp_us
成员变量变更	TranscoderAudioParam	新增成员变量：audio_codec_type
成员变量变更	TranscoderVideoParam	新增成员变量：bFrame 删除了：lowLatency 名称变更：video_codec_profile 变更为 video_codec_type，类型由 TranscoderVideoCodecProfile 改为 TranscoderVideoCodecType
成员变量变更	TranscoderLayoutRegion	新增成员变量： corner_radius type data data_param spatial_position
成员变量变更，名称变更	ITranscoderParam	类型名称由 TranscoderParam 改为 ITranscoderParam 新增成员变量：expected_mix_type: StreamMixingType
枚举值变更	TranscoderAudioCodecProfile	删除了 kByteAACProfileMain kByteAACProfileHEv1 对应的数值由 2 变更为 1 kByteAACProfileHEv2 对应的数值由 3 变更为 2
配置变更	RoomProfileType	房间属性的默认值 kRoomProfileTypeCommunication = 0，对应的由 kRoomProfileTypeChatRoom = 6 变更为 kRoomProfileTypeMeeting = 16。
新增	PublicStreamErrorCode	onPlayPublicStreamResult 和 onPushPublicStreamResult 中的 errorCode 参数类型由 int 改为 PublicStreamErrorCode
参数数据结构改动	AudioPropertiesConfig	数据结构中，新增参数 smooth
取值范围拓展	TranscoderLayoutRegion 中，width 和 height	取值范围由 (0.0, 1.0] 拓展为 [0.0, 1.0]。

最近更新时间：2025.10.20 14:23:31

这个页面对您有帮助吗？

有用

无用

实时音视频

3.57 #

回调变更 #

类型变更 #

规范代码风格

错误码变更 #

3.54 #

方法变更 #

类型变更 #

错误码变更 #

3.52 #

方法变更 #

回调变更 #

错误码变更 #

3.50 #

方法变更 #

回调变更 #

类型变更 #

3.57

回调变更

类型变更

错误码变更

3.54

方法变更

类型变更

错误码变更

3.52

方法变更

回调变更

错误码变更

3.50

方法变更

回调变更

类型变更