Agora Android 视频黑屏问题排查与正确初始化实践-java教程-PHP中文网

Agora Android 视频黑屏问题排查与正确初始化实践

本文详解 Agora SDK 在 Android 端视频黑屏（音频正常、用户可成功入会）的典型成因，重点指出 enableVideo() 调用时机错误、setupLocalVideo() 与 startPreview() 顺序颠倒、SurfaceView 创建方式不规范等关键问题，并提供结构清晰、可直接运行的修复方案。

本文详解 agora sdk 在 android 端视频黑屏（音频正常、用户可成功入会）的典型成因，重点指出 `enablevideo()` 调用时机错误、`setuplocalvideo()` 与 `startpreview()` 顺序颠倒、surfaceview 创建方式不规范等关键问题，并提供结构清晰、可直接运行的修复方案。

Agora 视频黑屏但音频正常，是 Android 集成中极为常见的“伪连接”问题——表面看用户已成功加入频道（onJoinChannelSuccess 触发）、远端用户也可见（onUserJoined 触发），实则视频渲染链路在某个环节断裂。根据您提供的代码，问题根源并非网络或 Token，而在于 SDK 初始化与视频管线配置的时序与方式存在多处关键缺陷。

? 核心问题定位

enableVideo() 调用过早且孤立
您在 setupVideoSDKEngine() 中创建引擎后立即调用 agoraEngine.enableVideo()，但此时尚未设置任何本地/远程视频画布，也未启动预览。Agora 官方文档明确要求：enableVideo() 必须在 setupLocalVideo() 之后、startPreview() 之前调用，否则视频模块可能无法正确初始化。
SurfaceView 创建方式不安全
手动 new SurfaceView(getBaseContext()) 并直接添加到布局，易导致生命周期错位、Z-order 冲突（尤其未调用 setZOrderMediaOverlay(true) 于本地视图）。正确做法是使用 RtcEngine.CreateRendererView(context) —— 此方法内部已做兼容性处理，确保 Surface 生命周期与 SDK 同步。
startPreview() 位置错误
您在 joinChannel() 中才调用 startPreview()，但该方法应在 setupLocalVideo() 之后、joinChannel() 之前执行。否则，本地摄像头预览流无法及时推送到 SDK，导致本地画面黑屏；同时远端也可能因未收到有效视频流而无法解码渲染。
setupRemoteVideo() 缺少容错与复用逻辑
每次 onUserJoined 都新建 SurfaceView 并 addView()，若用户重复加入或频道内有多人，将导致视图重叠、内存泄漏。应复用已有 View 或在加入前清理容器。

✅ 正确初始化流程（关键代码段）

遵循 Agora 最佳实践，修正后的核心初始化逻辑如下：

private void initializeAgoraEngine() {
    try {
        // ✅ 正确顺序：创建引擎 → 启用视频 → 设置本地画布 → 启动预览 → 加入频道
        rtcEngine = RtcEngine.create(getBaseContext(), "YOUR_APP_ID", mRtcEventHandler);
        rtcEngine.enableVideo(); // 必须在 setupLocalVideo 之后、startPreview 之前！

        // ✅ 使用官方推荐方式创建 RendererView
        localSurfaceView = RtcEngine.CreateRendererView(getBaseContext());
        localSurfaceView.setZOrderMediaOverlay(true); // 本地视图需置顶

        FrameLayout localContainer = findViewById(R.id.local_video_container);
        localContainer.addView(localSurfaceView);

        // ✅ setupLocalVideo 必须在 enableVideo 之后
        rtcEngine.setupLocalVideo(new VideoCanvas(localSurfaceView, 
            VideoCanvas.RENDER_MODE_FIT, 0));

        // ✅ startPreview 必须在 setupLocalVideo 之后、joinChannel 之前
        rtcEngine.startPreview();

        // ✅ 加入频道（Token 可传 null 测试，生产环境务必传有效 Token）
        rtcEngine.joinChannel(token, channelName, null, uid);

    } catch (Exception e) {
        Log.e("Agora", "Failed to init engine", e);
        Toast.makeText(this, "SDK 初始化失败：" + e.getMessage(), Toast.LENGTH_LONG).show();
    }
}

? 布局建议（避免容器冲突）

XML 中两个视频容器应明确尺寸与层级关系，避免 layout_weight 在动态添加 SurfaceView 时引发测量异常：

Android Remote Control

远程控制 Android 设备，支持截图、自动化操作手机 App 等功能。本应用使用 uiautomator2 作为底层框架，通过 ADB 连接设备，用户无需 Root（1）查看手机屏幕；（2）自动化操作手机 App；（3）远程安装/卸载应用……

下载

<!-- activity_video_call.xml -->
<framelayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="match_parent"><!-- 远端视图：铺满背景 --><framelayout android:id="@+id/remote_video_container" android:layout_width="match_parent" android:layout_height="match_parent"></framelayout><!-- 本地小窗：固定尺寸，置于右上角 --><framelayout android:id="@+id/local_video_container" android:layout_width="140dp" android:layout_height="200dp" android:layout_gravity="top|end" android:layout_margin="16dp"></framelayout></framelayout>

⚠️ 其他关键注意事项

权限检查必须同步完成：checkSelfPermission() 应在 onCreate() 中立即执行，若缺失权限，requestPermissions() 后需在 onRequestPermissionsResult() 中回调 initializeAgoraEngine()，不可跳过权限直接初始化 SDK。
Token 动态生成时机：您的 generateToken() 在网络请求回调中触发，但此时 rtcEngine 可能尚未创建。建议将 Token 获取逻辑前置，或确保引擎初始化完成后再 join。
资源释放严格配对：onDestroy() 中必须按 leaveChannel() → stopPreview() → destroy() 顺序释放，且避免在主线程阻塞调用 RtcEngine.destroy()（您原代码中用子线程销毁是正确的）。
日志诊断必备：开启 Agora 日志（rtcEngine.setLogFile()）并过滤 agora 关键字，重点关注 video encoder started, remote video stream received 等提示，快速定位是采集、编码、传输还是渲染环节失败。