iOS端AgoraRTCEngine pushExternalVideoFrame返回false问题咨询

已调用setExternalVideoSource接口并将入参设置为true，调用pushExternalVideoFrame接口时仍返回false。常规AgoraCameraSourcePush采集推流方式可正常运行，切换为自定义视频帧推送逻辑时推流失败，相关实现代码如下：

func updateClientRole(_ role: AgoraClientRole) {
        print("updateClientRole,", role.title)
        self.role = role
        if role == .broadcaster {
            makeConfig(mirror: false)
            
            agoraKit.enableLocalVideo(true)
            agoraKit.enableLocalAudio(true)
            agoraKit.enableAudioVolumeIndication(250, smooth: 3, report_vad: true)
            agoraKit.setAudioProfile(.speechStandard, scenario: .communication)
            agoraKit.setExternalVideoSource(true, useTexture: true, pushMode: true)
            
// 原生采集方式可正常运行
            localVideoView = CustomVideoSourcePreview(frame: view.frame)
            videosView.appendBackgroundViewContainer(uid: myUID, itsTeacher: self.amTeacher).addSubview(localVideoView!)
            customCamera = AgoraCameraSourcePush(delegate: self, videoView: localVideoView!)
            self.customCamera?.startCapture(ofCamera: .front)
            self.localVideoView?.bindFrameToSuperviewBounds()
// 自定义推流方式运行失败
            let myVideoView = videosView.appendBackgroundViewContainer(uid: myUID, itsTeacher: self.amTeacher)
            avatarView = MyAvatarView(to: myVideoView)
            avatarView?.delegate = self
    }
}


func myVideoCapture(_ capture: AgoraCameraSourcePush?, didOutputSampleBuffer pixelBuffer: CVPixelBuffer, rotation: Int, timeStamp: CMTime) {
        
        let videoFrame = AgoraVideoFrame()
        videoFrame.format = 12
        videoFrame.textureBuf = pixelBuffer
        videoFrame.time = timeStamp
        videoFrame.rotation = Int32(rotation)
        let success = agoraKit?.pushExternalVideoFrame(videoFrame)
        print("myVideoCapture.success",success) // 此处打印结果为 myVideoCapture.success Optional(false)
    }

• 接口调用时序错误：setExternalVideoSource需要在加入频道前调用，如果是入会后切换角色时才开启外部视频源，需要在调用该接口后重新启用本地视频轨（先调用enableLocalVideo(false)再调用enableLocalVideo(true)）触发配置生效，否则SDK不会切换到外部源模式，推帧会直接被拒绝。
• 本地视频源冲突：开启外部视频源后没有停止原有AgoraCameraSourcePush的采集逻辑，SDK内部采集通道仍处于占用状态，外部帧输入通道未激活，推帧会返回false。
• 视频帧参数不符合规范：设置useTexture: true配合format=12传CVPixelBuffer时，要保证传入的pixelBuffer是SDK支持的NV12或BGRA格式；rotation参数只能传0/90/180/270四个合法值；传入的timeStamp需要是单调递增的毫秒级时间戳，任意参数不符合要求都会导致帧校验失败返回false。
• 视图绑定逻辑冲突：代码中给同一个uid重复添加了两个视频渲染容器，SDK本地视频渲染轨绑定异常时，也会连带导致外部帧输入逻辑异常。

• 本地日志持久化配置：初始化AgoraKit实例后，调用setLogFile方法指定日志的本地存储路径，同时调用setLogFilter将日志级别设置为Info级，SDK运行过程中的全量日志就会写入指定路径的文件，可直接导出查看。
• 关键日志定位：拿到日志文件后，搜索external video、push frame、video source三类关键字，就能找到推帧返回false的具体错误原因，包含参数错误、源未激活、通道占用等明确提示。
• 运行时实时日志：实现AgoraKit的日志回调代理，可在App运行时实时接收SDK输出的日志，无需导出文件就能直接在控制台观察推帧过程的报错信息。

内容的提问来源于stack exchange，提问作者user16525780