耳返

---

1 功能简介

1.1 功能描述

耳返即耳机采集监听，在设备上插入耳机（普通耳机或蓝牙耳机）后，能从本机耳机侧听到本设备麦克风采集的声音。

本文介绍耳返功能的两种实现方式：

1. ZEGO SDK 自带的普通耳返功能
2. 耳返优化

目前一些 Android 设备厂商对旗下一些具体机型增加了系统级别的耳返优化的功能。对耳返性能有较高要求的开发者可以针对不同厂商的机型，或者与具体 Android 系统厂商沟通以申请获得特定厂商优化后的耳返功能的使用权限，或者在系统直接支持的情况下在系统设置中打开。

以 华为 mate 10 为例(华为对该款设备增加了系统级别的耳返优化的功能)，开发者在向具体设备厂商获取上述权限后，使用 ZEGO Android SDK 调用相关接口并在插入耳机之后，会在应用界面看到一个耳机的小图标，点击之后会出现如下效果：

使用具体厂商对特定机型优化后的耳返功能的优点：耳返延迟更低，可以使用具体厂商支持的混响效果和音质特效等。

一般地，应用开发者在有权限(对于华为机型，开发者应用包名需要添加到厂商的系统白名单，对于 oppo 机型，需要在系统设置中打开设置)使用具体厂商优化后的耳返功能后，需要根据具体厂商的要求调用相关的接口判断某设备是否支持该特性，不同厂商暴露的私有接口和调用逻辑是不一样的。ZEGO Android SDK 适配了支持此功能的部分厂商(华为，oppo，vivo)的私有接口。
即集成了 ZEGO Android SDK 的应用的包名被添加到具体厂商支持该功能的系统白名单上，在应用推流或启动本地预览之后，插入耳机可在应用界面直接看到操作系统对该功能支持的图标控件。

1.2 常用场景

该功能支持极低的耳返延迟，可以帮助主播在k歌等场景下实时监听自己的声音是否变调以让观众达到最佳地视听效果。

Android 系统下，直接使用系统公有接口实现的耳返延迟一般都比较大，经测试较多机型都在200ms以上，这样的耳返的延迟对于以下场景影响很大：

1. 耳返的实时性比较差，不利于主播及时做出自己唱歌音调调整；
2. 配合背景音乐混音使用时，播放端会出现人声明显落后伴奏的情况。

目前 ZEGO Android SDK 对支持耳返优化功能的具体厂商的机型做了适配，在厂商支持的机型上，耳返延迟和耳返音质会有非常明显的优化。

相关功能的 Demo 源码，请联系 ZEGO 技术支持获取。

2 使用普通耳返

开启预览后或者开始推流后可调用 enableLoopback(true) 开启采集监听即耳返，主播方讲话后，会听到自己的声音。ZEGO Android SDK 本身自带的普通耳返功能与耳返优化相比，在耳返延迟和耳返音质上相对较差。

2.1 开启耳返

• 接口原型：

  public boolean enableLoopback(boolean enable)

• 参数：

  enable：true--开启采集监听；false--关闭采集监听；默认为 false。

• 备注：

  开启耳返后，在连接上耳麦时耳返功能才实际生效。

2.2 设置耳返音量

开启预览后或者开始推流后可调用 setLoopbackVolume 调整耳返的音量。

• 接口原型：

  public void setLoopbackVolume(int volume)

• 参数：

  volume：音量大小，取值范围[0, 200]；默认为 100。

3 使用耳返优化

请注意前置条件：
由于低延迟耳返的功能跟具体的手机厂商和手机厂商的具体机型强相关，需要开发者与具体的手机厂商联系，询问厂商具体机型是否支持低延迟耳返的功能，若支持，需要具体的手机厂商将开发者的应用添加白名单，低延迟耳返的功能才能起作用。

白名单是指开发者与具体厂商沟通后让厂商将开发者自己的应用的包名列为具体手机系统的白名单。

3.1 开启适配

调用 ZEGO Android SDK 类对象的静态方法 setConfig，传入开启适配的参数。

//调用这个接口，会针对满足条件的应用在支持的机型进行适配启用系统的耳返优化的功能
ZegoLiveRoom.setConfig("adapt_to_system_karaoke=true");

3.2 初始化 SDK

如何初始化请查看 快速开始-初始化

3.3 开启优化的系统耳返功能

3.3.1 方式 1: 通过推流来启用麦克风

1. 登录房间

登录房间请查看 快速开始-登录房间

2. 开始推流

如何推流请查看 快速开始-推流

3.3.2 方式 2：在不推流的情况下，通过启动预览来占用麦克风

调用启动预览接口如下：

zg.startPreview(); //需要启动预览，因为在不推流的情况下，需要启动本地预览来启动SDK的引擎来占用麦克风
//zg.startPublishing(streamid,title,flag);//这里注释掉推流的接口表示不推流

经上述几个步骤之后，若应用的包名已添加到具体厂商的系统的白名单，可在应用界面上看到耳机的小图标，点击之后可看到效果。

注意：

1. 与具体手机厂商从系统层面实现的优化的低延迟耳返功能不同，ZEGO Android SDK 本身支持基于软件层面实现的耳返功能(通过在登录房间并通过上述步骤启用麦克风之后，调用 ZegoLiveRoom 对象的 enableLoopback(true) 实现)，如果在符合条件的场景下二者同时开启，会产生耳返的重音现象。建议开发者在此种情况下禁止应用开启 ZEGO Android SDK 本身自带的耳返功能。
2. 由于 ZegoLiveRoom.setConfig("adapt_to_system_karaoke=true"); 只是适配性接口，对于不支持厂商系统级优化耳返功能的机型也可以调用该接口，此时如果想要使用普通耳返，应调用 ZegoLiveRoom 对象的 enableLoopback(true) 实现。

4 FAQ

Q1：在设置之后，推流出去，为什么拉流听到的音效没有对应的效果？

  答：耳返为耳机采集监听的功能，只有本机设备才有效果。

Q2：按照文档设置了，为什么依然没效果？

  答：ZEGO Android SDK 只是适配了具有耳返优化效果功能的设备，系统层面的耳返优化功能并非是 SDK 的自带功能，如果按文档设置之后无效果，可以：
    1. 咨询具体手机厂商此款设备是否具有耳返优化的功能；

    2. 开发者是否跟具体厂商沟通，向具体厂商申请将开发者的应用加入开发者系统的白名单；

    3. 是否是 Android 系统，而非其他非 Android 平台的系统，该功能目前只有特定厂商的 Android 平台才支持；

    4. 某些厂商的机型中，耳返优化功能更高级别的系统才支持，较低级别的系统并不支持，此时须调用本文上述提到的 SDK 自带的耳返功能实现。

Q3：如何对具有该功能的设备获取使用权限？

  答：开发者需自行联系具体设备的厂商的技术支持，向其申请，然后提供开发者应用的包名，让其添加到具体系统设备的白名单上。

Q4：为什么按照文档的设置之后，在某些设备上会出现完全变音的效果？该如何处理？

  答：因为 Android 机型繁杂，对该特性的支持程度不一，某些机型在开启低延迟特性后甚至会出现声音不正常的现象。ZEGO Android SDK 已进行海量机型的测试，若发现某款机型有异常现象，可联系 ZEGO 技术支持进行处理。

Q5：在确认将我们的应用包名加入对应设备系统厂商的白名单了，也确认这款设备具有低延迟效果的功能，为什么还是无效果？

  答：可以按以下步骤进行排查：

    1. 是否启动了 SDK 的引擎（SDK 的引擎通过推流，拉流，启动预览这三个步骤之一启动），对于麦克风的采集需要引擎启动时才会占用；

    2. 麦克风是否被其他应用或进程正在占用；

    3. 是否有禁用麦克风采集，或者有推音频流；

    4. 是否有插上耳机；

    5. 耳机是否能正常工作，可以打开其他音乐 App 并带上耳机测试；

    6. 经上述步骤之后，依然无效果，可以联系 ZEGO 技术支持排查定位。

Q6：对于确认没有耳返优化功能的机型按照文档进行设置进行推流，是否会出现问题？对于这样的机型，应该如何设置？

  答：ZEGO Android SDK 只是对具有耳返优化功能的机型进行适配，SDK 底层调用的是具体设备厂商的私有接口，若该设备无此功能，则只是会适配失效，不影响正常使用。因此，对于这样的机型，可以依然如本文档所述，调用开启适配的接口，此时若希望依然有耳返功能，可以使用 ZEGO Android SDK 本身的耳返功能，即调用 ZegoLiveRoom 对象设置 enableLoopback(true);，也会起到一定的优化效果。

Q7：为什么耳返会出现有重音现象？

  答：当在符合条件机型按本文档设置之后，又开启了 ZEGO Android SDK 本身的耳返功能，会出现这样的问题，因为这两个设置是并行的设置，所以建议开发者在此种情况下，开发者在跟设备厂商沟通时，获取支持耳返优化功能的机型的列表，针对这些机型，只使用系统优化的耳返功能，在应用层面不允许开启 ZEGO Android SDK 本身的耳返功能，即不调用 enableLoopback(true); 或者将其设置为 false。

Q8：对于支持与不支持的手机分别应该怎么设置？

  答：对于支持的机型在开发者应用的包名添加到厂商的系统白名单之后，对于支持的机型，应该设置按文档设置 ZegoLiveRoom.setConfig("adapt_to_system_karaoke=true"); 但是需要禁用 ZEGO Android SDK 本身的耳返功能，避免出现重音问题。
对于不支持的机型，adapt_to_system_karaoke 参数是否设置为 true 都可以，此种情况下，若设置为 true，且应用有耳返的需求，可根据文档开启 ZEGO Android SDK 的自带耳返功能，这样会有更低耳返延迟的效果。

Q9：ZegoLiveRoom.setConfig("adapt_to_system_karaoke=true");设置为 false 会怎么样？

  答：在不支持的机型，该参数设置为 false 并无太大影响, 在符合适配条件的机型中，由于音频采集方式的问题，需要将该参数设置为 true，否则会产生变声的情况。

Q10：既然无论是否支持的机型 adapt_to_system_karaoke 都可以设置为 true，为什么 SDK 内部不默认就置为 true？

  答：这是因为某些厂商的符合条件的一些机型不在应用界面出现可控制的开关小图标，如果默认设置为 true，将会带上耳机时无法关闭耳返功能。

Q11：华为，oppo，vivo 这三家厂商的机型都需要把应用包名加到厂商的系统白名单吗？

  答：oppo 在支持的机型中，在系统的设置界面可以直接打开开关，此种情况，业务可以在应用界面设置的地方引导用户去设置界面设置；vivo 已做了适配，华为需要与厂商申请申请将自己应用的包名添加到系统的白名单中。