AVChatManager.java

浏览该文件的文档.

/*
 * Copyright (c) 2014-2018 NetEase, Inc.
 * All right reserved.
 */

package com.netease.nimlib.sdk.avchat;

import android.content.Context;

import com.netease.nimlib.avchat.AVChatManagerImpl;
import com.netease.nimlib.sdk.Observer;
import com.netease.nimlib.sdk.avchat.constant.AVChatAudioRecordType;
import com.netease.nimlib.sdk.avchat.constant.AVChatCommunicateMode;
import com.netease.nimlib.sdk.avchat.constant.AVChatConnectStatus;
import com.netease.nimlib.sdk.avchat.model.AVChatNetworkProxy;
import com.netease.nimlib.sdk.avchat.model.AVChatParameters;
import com.netease.nrtc.engine.rawapi.IRtcEngine;
import com.netease.nrtc.engine.rawapi.RtcCode;
import com.netease.nrtc.sdk.NRtcConstants;
import com.netease.nrtc.voice.AudioMixing;

import java.util.List;


/**
 * {@inheritDoc}
 */
public abstract class AVChatManager extends AVChatManagerLite {

    /**
     * 获取抽象类具体实现对象
     *
     * @return AVChatManager对象
     */
    public static AVChatManager getInstance() {
        return AVChatManagerImpl.InstanceHolder.instance;
    }

    /**
     * 设置网络代理,需要在发起通话前前设置
     *
     * @param proxy 代理信息
     */
    public abstract void setNetworkProxy(AVChatNetworkProxy proxy);


    /**
     * 获取已经设置的网络代理
     */
    public abstract AVChatNetworkProxy getNetworkProxy();


    /**
     * 是否采用外部语音采集方式，启用后会关闭SDK内部语音采集
     *
     * @param enabled 是否开启
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean setExternalAudioSource(boolean enabled);


    /**
     * 外部输入音频数据, 每次最多允许传递 40ms 数据
     *
     * @param data           音频数据
     * @param samples        样本数量
     * @param sampleRate     采样率，仅支持 8000,16000,32000,44100,48000
     * @param channel        频道数量
     * @param bytesPerSample 每个样本的字节数, 仅支持PCM 16
     * @param blocking       是否阻塞写入数据。
     *                       如果非阻塞写入数据, 内部缓冲不足时会立即返回失败<code>-100</code>，
     *                       如果阻塞写入数据, 当内部缓冲不足时,会等待一定时间后再返回(待写入数据时长), 内部缓冲不足返回失败<code>-100</code>。
     * @return {@code 0} 方法调用成功，其他失败
     * @see #setExternalAudioSource(boolean)
     */
    public abstract int pushExternalAudioData(byte[] data,
                                              int samples,
                                              int sampleRate,
                                              int channel,
                                              int bytesPerSample,
                                              boolean blocking) throws NullPointerException, IllegalArgumentException;

    /**
     * 开始录制某个用户的语音和视频数据到文件，格式为mp4，该用户的语音和视频数据会被记录在MP4文件中，文件保存在客户端本地。
     * <br>在视频模式时录制的是音视频数据，在语音模式时录制的是音频数据。</br>
     * <p>注意：录制双方数据可以采用服务器录制。 </p>
     *
     * @param account 用户账号
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean startAVRecording(String account);

    /**
     * 停止录制某个用户的语音和视频数据到文件，格式为mp4，该用户的语音和视频数据会被记录在MP4文件中，文件保存在客户端本地。
     * <br>在视频模式时录制的是音视频数据，在语音模式时录制的是音频数据。</br>
     * <p>注意：录制双方数据可以采用服务器录制。 </p>
     *
     * @param account 用户账号
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean stopAVRecording(String account);

    /**
     * 通话中开始录音，包含所有用户的语音数据，录音文件格式为wav，文件保存在客户端本地。
     *
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean startAudioRecording();

    /**
     * 通话中开始录音，包含所有用户的语音数据，录音文件格式为wav或aac，文件保存在客户端本地。
     *
     * @param type {@link AVChatAudioRecordType}
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean startAudioRecording(int type);

    /**
     * 通话中停止录音，包含所有用户的语音数据，录音文件格式为wav，文件保存在客户端本地。
     *
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean stopAudioRecording();

    /**
     * 是否打开观众角色, 设置观众角色后所有的语音和视频数据的采集和发送会关闭，允许接收和播放远端其他用户的数据.
     * <p>角色设置仅在多人会话时生效. </p>
     * <p>注意:用户角色和Mute区别。观众角色会影响本地数据的采集、处理和发送等; 本地的 <code>Mute</code> 只会影响发送的数据.</p>
     *
     * @param enable {@code true} 观众模式，{@code false} 普通用户模式
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean enableAudienceRole(boolean enable);


    /**
     * 当前是否处于观众角色.
     * <p>角色设置仅在多人会话时生效. </p>
     *
     * @return {@code true} 观众角色模式，{@code false} 正常用户模式
     */
    public abstract boolean isAudienceRole();


    /**
     * 检查音视频模块缺失的权限.
     * <p>在Android 6.0 平台需要获取权限后运行.</p>
     *
     * @param context Android 上下文
     * @return 返回缺失的权限
     */
    public static List<String> checkPermission(Context context) {
        return IRtcEngine.checkPermission(context);
    }

    /**
     * 截取用户的画面
     * <p>文件保存路径: <code>/Sdcard/Android/data/{app_package_name}/files/snapshot</code> .</p>
     *
     * @param account 用户账号
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean takeSnapshot(String account);


    /**
     * 指定本地音频文件或者远程URL来和麦克风采集的音频流进行混音和替换
     *
     * @param path     本地文件路径或者远程URL
     * @param loopback 是否循环播放
     * @param replace  是否替换麦克风采集的音频数据
     * @param cycle    循环的次数
     * @param volume   音量[0.0f - 1.0f]
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean startAudioMixing(String path,
                                             boolean loopback,
                                             boolean replace,
                                             int cycle,
                                             float volume);

    /**
     * 设置伴音本地播放音量
     *
     * @param volume [0.0f - 1.0f]
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean setAudioMixingPlaybackVolume(float volume);

    /**
     * 设置伴音发送音量
     *
     * @param volume [0.0f - 1.0f]
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean setAudioMixingSendVolume(float volume);

    /**
     * 设置伴音进度
     *
     * @param ms 目标位置，单位毫秒，可参考{@link AudioMixing#getCurrentMs()}
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean seekAudioMixing(long ms);

    /**
     * 停止伴音
     *
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean stopAudioMixing();

    /**
     * 恢复伴音
     *
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean resumeAudioMixing();

    /**
     * 暂停伴音
     *
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean pauseAudioMixing();


    /**
     * 预加载或卸载 音效文件（播放音效前的必要操作）
     *
     * @param effectId      音效id ，用户自定义 ， 重复加载同一个id ，会先停止播放并卸载。
     * @param audioFilePath 音效文件路径，如果传 null ，表示卸载相应的音效 。在播放过程中卸载会停止播放并触发播放结束的回调。<br/>
     *                      预加载的结果在{@link AVChatStateObserver#onAudioEffectPreload(int, int) }中回调。<br/>
     *                      如果需要，用户可以自己记录id 与 file 之间的对应关系
     */
    public abstract void preloadAudioEffect(int effectId, String audioFilePath);


    /**
     * 播放音效 ， 播放之前一定要预加载音效文件{@link #preloadAudioEffect(int, String)} ，并在预加载结果回调{@link AVChatStateObserver#onAudioEffectPreload(int effectId, int result) }中判断是否加载成功<br/>
     * <p>
     * 播放完成后会有{@link AVChatStateObserver#onAudioEffectPlayEvent(int effectId, int event)}回调
     *
     * @param effectId 音效id ， 同预加载时的id
     * @param loopback 音效循环次数 ， -1 表示无限循环
     * @param send     是否发送
     * @param volume   播放及发送音量 [0.0f - 1.0f]
     * @return {@code true} : 播放成功，{@code false}: 方法调用失败
     */
    public abstract boolean playAudioEffect(int effectId, int loopback, boolean send, float volume);


    /**
     * 停止播放音效
     *
     * @param effectId 音效id
     * @return {@code true} 方法调用成功，其他失败
     */
    public abstract boolean stopPlayAudioEffect(int effectId);

    /**
     * 注册/注销来电或者呼出电话（自己或者对方无响应）超时的通知，默认超时时间为45秒
     *
     * @param observer 观察者，参数true表示呼出电话超时对方应答，false表示来电自己超时未接听
     * @param register {@code true} 注册监听，{@code false} 注销监听
     * @deprecated 用户外部实现超时，SDK内部未来不再提供
     */
    @Deprecated
    public abstract void observeTimeoutNotification(Observer<Long> observer, boolean register);


    /**
     * <p>开启耳返</p>
     * <p>
     * <p>在通话建立后可以打开耳返功能，打开后可以从耳机中实时听到自己的声音。</p>
     *
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean startPlayCapturedAudio();


    /**
     * <p>关闭耳返</p>
     * <p>
     * <p>在成功开启耳返功能后, 可以随时关闭耳返效果。</p>
     *
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean stopPlayCapturedAudio();


    /**
     * <p>设置耳返音量</p>
     * <p>
     * <p>在成功打开耳返功能后，可以实时调整耳返音量。</p>
     *
     * @param volume 播放耳返音量 [0.0f - 1.0f]
     * @return {@code true} 方法调用成功，{@code false} 方法调用失败
     */
    public abstract boolean setPlayCapturedAudioVolume(float volume);


    /**
     * 互动直播设置主画面
     *
     * @param account  被设置的用户账号
     * @param callback 设置状态回调
     */
    public abstract void setAsMainArea(String account, AVChatRoomServerCallback callback);


    /**
     * 是否开启外部语音混音输入
     *
     * @param enabled  是否开启
     * @param asSource 参与语音发送数据混音
     * @param asSink   参与语音播放数据混音
     * @return {@code 0} 方法调用成功，其他失败
     */
    public abstract boolean setExternalAudioMixingStream(boolean enabled,
                                                         boolean asSource,
                                                         boolean asSink);

    /**
     * 输入外部需要混音的数据, 数据输入间隔需要保证和数据长度严格一致
     *
     * @param audioData         语音数据
     * @param samplesPerChannel 语音数据每个声道包含采样数
     * @param sampleRate        语音数据采样率
     * @param channel           语音数据采样率
     * @return {@code 0} 方法调用成功，其他失败
     */
    public abstract int pushExternalAudioMixingStream(byte[] audioData,
                                                      int samplesPerChannel,
                                                      int sampleRate,
                                                      int channel);


    /**
     * 设置是否自动发布，是否自动订阅 ，默认是自动发布和订阅，必须在joinRoom之前设置
     * 说明：音频暂不支持手动发布，一直是发布的 ，但支持手动/自动订阅
     *
     * @param autoPub true表示自动发布；false表示手动发布
     * @param autoSub true表示自动订阅；false表示手动订阅
     * @return 操作成功是 0 ，失败 -1
     */
    public abstract int setAutoPublish(boolean autoPub, boolean autoSub);

    /**
     * 查询当前是否为自动发布模式
     *
     * @return true为自动发布，false为手动发布
     */
    public abstract boolean isAutoPublishVideo();

    /**
     * 查询当前视频是否为自动订阅模式
     *
     * @return 返回true为自动订阅，false为手动订阅
     */
    public abstract boolean isAutoSubscribeVideo();


    /**
     * 查询当前音频是否为自动订阅模式
     *
     * @return 返回true为自动订阅，false为手动订阅
     */
    public abstract boolean isAutoSubscribeAudio();


    /**
     * 设置本地视频多流模式。该方法设置单流（默认）、多流模式，发送端开启多流模式后，接收端可以选择接收大流、小流。
     * 注意：必须在joinChannel之前设置，同一通通话不能修改。
     *
     * @param mode 流模式，参考 ：<br/>
     *             {@link NRtcConstants.Subscribe#PUBLISH_MODEL_SINGLE_STREAM}: 单流<br/>
     *             {@link NRtcConstants.Subscribe#PUBLISH_MODEL_DUAL_STREAM}: 双流<br/>
     * @return 0 ：设置成功，但点对点模式下设置不会生效 <br/>
     * -1 ：失败 <br/>
     */

    public abstract int setLocalVideoSimulcastModel(int mode);


    /**
     * 手动发布视频流
     *
     * @return 0 ：操作成功，但是否发布成功还得看回调结果{@link AVChatStateObserver#onPublishVideoResult(int)} <br/>
     * {@link RtcCode.Subscribe#VIDEO_IS_MUTED_ERR }：当前视频是mute 的  <br/>
     * {@link RtcCode.Subscribe#IS_AUDIENCE_ERR} ：当前是观众 <br/>
     * {@link RtcCode.Subscribe#IS_AUDIO_MODE_ERR}：当前是音频模式 <br/>
     * {@link RtcCode.Subscribe#ACTION_DUPLICATE_ERR}：当前有正在进行中的操作 <br/>
     * {@link RtcCode.Subscribe#MODE_CONFLICT_ERR}：模式冲突，当前是自动模式<br/>
     * {@link RtcCode.Subscribe#FORBID_ACTION}：非法操作 ， 订阅相关的操作只在会议模式下有效 ，点对点不支持<br/>
     * -1 ：其它失败 <br/>
     */
    public abstract int publishVideo();

    /**
     * 手动取消发布视频流
     *
     * @return 0 ：操作成功，但是否取消发布成功还得看回调结果{@link AVChatStateObserver#onUnpublishVideoResult(int)} <br/>
     * {@link RtcCode.Subscribe#VIDEO_IS_MUTED_ERR }：当前视频是mute 的  <br/>
     * {@link RtcCode.Subscribe#IS_AUDIENCE_ERR} ：当前是观众 <br/>
     * {@link RtcCode.Subscribe#IS_AUDIO_MODE_ERR}：当前是音频模式 <br/>
     * {@link RtcCode.Subscribe#ACTION_DUPLICATE_ERR}：当前有正在进行中的操作 <br/>
     * {@link RtcCode.Subscribe#MODE_CONFLICT_ERR}：模式冲突，当前是自动模式<br/>
     * {@link RtcCode.Subscribe#FORBID_ACTION}：非法操作 ， 订阅相关的操作只在会议模式下有效 ，点对点不支持<br/>
     * -1 ：其它失败 <br/>
     */
    public abstract int unpublishVideo();


    /**
     * 手动订阅视频流
     *
     * @param account   要订阅的account
     * @param videoType 要订阅的流类型，参考:<br/>
     *                  {@link NRtcConstants.Subscribe#VIDEO_TYPE_HIGH_RES}: 大流<br/>
     *                  {@link NRtcConstants.Subscribe#VIDEO_TYPE_LOW_RES}: 小流<br/>
     * @return 0：操作成功 ，但是否订阅成功还得看回调结果{@link AVChatStateObserver#onSubscribeVideoResult(String, int, int)} <br/>
     * {@link RtcCode.Subscribe#ACTION_DUPLICATE_ERR}：当前有正在进行中的操作 <br/>
     * {@link RtcCode.Subscribe#MODE_CONFLICT_ERR}：模式冲突，当前是自动模式<br/>
     * {@link RtcCode.Subscribe#FORBID_ACTION}：非法操作 ， 订阅相关的操作只在会议模式下有效 ，点对点不支持<br/>
     * {@link RtcCode.Subscribe#TYPE_CONFLICT_ERR}：视频类型冲突，需要取消之前订阅的流<br/>
     * -1 ：其它失败 <br/>
     */
    public abstract int subscribeVideo(String account, int videoType);

    /**
     * 手动取消订阅视频流
     *
     * @param account 要取消订阅的account
     * @return 0：操作成功 ，但是否取消订阅成功还得看回调结果{{@link AVChatStateObserver#onUnsubscribeVideoResult(String, int, int)}}<br/>
     * {@link RtcCode.Subscribe#ACTION_DUPLICATE_ERR}：当前有正在进行中的操作 <br/>
     * {@link RtcCode.Subscribe#MODE_CONFLICT_ERR}：模式冲突，当前是自动模式<br/>
     * {@link RtcCode.Subscribe#FORBID_ACTION}：非法操作 ， 订阅相关的操作只在会议模式下有效 ，点对点不支持<br/>
     * -1 ：其它失败 <br/>
     */
    public abstract int unsubscribeVideo(String account);


    /**
     * 手动订阅所有的活跃音频流
     *
     * @return 0：操作成功 ，但是否订阅成功还得看回调结果{{@link AVChatStateObserver#onSubscribeAudioResult(int)}<br/>
     * {@link RtcCode.Subscribe#ACTION_DUPLICATE_ERR}：当前有正在进行中的操作 <br/>
     * {@link RtcCode.Subscribe#MODE_CONFLICT_ERR}：模式冲突，当前是自动模式<br/>
     * {@link RtcCode.Subscribe#FORBID_ACTION}：非法操作 ， 订阅相关的操作只在会议模式下有效 ，点对点不支持<br/>
     * -1 ：其它失败 <br/>
     */
    public abstract int subscribeActiveAudio();

    /**
     * 手动取消订阅所有的活跃音频流
     *
     * @return 0：操作成功，但是否取消订阅成功还得看回调结果{{@link AVChatStateObserver#onUnsubscribeAudioResult(int)}<br/>
     * {@link RtcCode.Subscribe#ACTION_DUPLICATE_ERR}：当前有正在进行中的操作 <br/>
     * {@link RtcCode.Subscribe#MODE_CONFLICT_ERR}：模式冲突，当前是自动模式<br/>
     * {@link RtcCode.Subscribe#FORBID_ACTION}：非法操作 ， 订阅相关的操作只在会议模式下有效 ，点对点不支持<br/>
     * -1 ：其它失败 <br/>
     */
    public abstract int unsubscribeActiveAudio();


    /**
     * 设置弱网条件下发布的音视频流回退选项 ， 在加入房间前设置才有效
     *
     * @param option : 回退选项 ，默认值为{@link NRtcConstants.PublishFallbackOption#STREAM_FALLBACK_AUDIO_ONLY} ， 参考如下：
     *               {@link NRtcConstants.PublishFallbackOption#STREAM_FALLBACK_DISABLED} <br/>
     *               {@link NRtcConstants.PublishFallbackOption#STREAM_FALLBACK_AUDIO_ONLY} <br/>
     * @return 0： 设置成功
     */
    public abstract int setPublishFallbackOption(int option);

    /**
     * 注册远端用户 pcm 音频数据回调
     *
     * @param account  远端用户account ，用户离开SDK会自动取消注册
     * @param callback 监听器 ，填 null 表示取消之前的注册的
     * @return 是否注册成功
     */
    public abstract boolean registerRemoteAudioCallBack(String account, IAVChatRemoteAudioCallBack callback);


    /**
     * 注册播放前 pcm 音频数据回调
     *
     * @param callback 监听器 ，填 null 表示取消之前的注册的
     *                 说明：如果用户需要特定的采集率但又不想自己重采样，可以修改{@link AVChatParameters#KEY_AUDIO_PLAYBACK_DEFAULT_SAMPLE_RATE}
     * @return 是否注册成功
     */
    public abstract boolean registerPlayAudioCallBack(IAVChatPlayAudioCallBack callback);

    /**
     * 注册话单观察者
     *
     * @param observer 话单观察者
     * @param register true代表注册，false代表反注册
     */
    public abstract void registerAVChatRecordObserver(IAVChatRecordObserver observer, boolean register);

    /**
     * 获取当前通话状态
     *
     * @return 当前通话状态
     * @see AVChatConnectStatus#NONE
     * @see AVChatConnectStatus#CONNECT_ING
     * @see AVChatConnectStatus#CONNECTED
     * @see AVChatConnectStatus#RE_CONNECT_ING
     * @see AVChatConnectStatus#DISCONNECT
     */
    public abstract int getConnectStatus();


    /**
     * 切换通话模式，只能在非观众模式下的通话过程中能切换
     *
     * @param mode 通话模式
     * @return 0： 切换成功
     * @see AVChatCommunicateMode#VIDEO_MODE 视频模式 ，音频视频可以同时发，手动发布模式的话，还需要手动发布一下视频
     * @see AVChatCommunicateMode#AUDIO_MODE 音频模式 ，只能发音频，会停止视频发送
     */
    public abstract int switchCommunicateMode(int mode);

}