NIMMediaManagerProtocol.h

浏览该文件的文档.

//
//  NIMMediaManagerProtocol.h
//  NIMLib
//
//  Created by Netease.
//  Copyright (c) 2015年 Netease. All rights reserved.
//
 
#import <Foundation/Foundation.h>
 
NS_ASSUME_NONNULL_BEGIN
 
/**
 *  音频输出设备类型
 */
typedef NS_ENUM(NSInteger, NIMAudioOutputDevice){
    /**
     *  听筒
     */
    NIMAudioOutputDeviceReceiver,
    /**
     *  扬声器
     */
    NIMAudioOutputDeviceSpeaker
};
 
/**
 *  云信支持的音频类型
 */
typedef NS_ENUM(NSInteger, NIMAudioType) {
    /**
     *  aac
     */
    NIMAudioTypeAAC,
    /**
     *  amr
     */
    NIMAudioTypeAMR
};
 
 
/**
 *  语音转文字
 *
 *  @param error 执行结果,如果成功error为nil
 *  @prarm text  转换后的文本
 */
typedef void(^NIMAudioToTextBlock)(NSError * __nullable error,NSString * __nullable text);
 
 
/**
 *  语音转文字选项
 */
@interface NIMAudioToTextOption : NSObject
 
/**
 *  音频URL
 *  @discussion 目前只支持云信服务器的URL，不支持外链
 */
@property (nonatomic,copy)      NSString    *url;
 
/**
 *  音频本地地址
 *  @discussion APP需要保证音频已经下载到本地
 */
@property (nonatomic,copy)      NSString    *filepath;
@end
 
 
/**
 *  多媒体委托
 */
@protocol NIMMediaManagerDelegate <NSObject>
 
@optional
 
/**
 *  开始播放音频的回调
 *
 *  @param filePath 音频文件路径
 *  @param error    错误信息
 */
- (void)playAudio:(NSString *)filePath didBeganWithError:(nullable NSError *)error;
 
/**
 *  播放完音频的回调
 *
 *  @param filePath 音频文件路径
 *  @param error    错误信息
 */
- (void)playAudio:(NSString *)filePath didCompletedWithError:(nullable NSError *)error;
 
/**
 *  播放完音频的进度回调
 *
 *  @param filePath 音频文件路径
 *  @param value    播放进度 0.0 - 1.0
 */
- (void)playAudio:(NSString *)filePath progress:(float)value;
 
/**
 *  停止播放音频的回调
 *
 *  @param filePath 音频文件路径
 *  @param error    错误信息
 */
- (void)stopPlayAudio:(NSString *)filePath didCompletedWithError:(nullable NSError *)error;
 
/**
 *  播放音频开始被打断回调
 */
- (void)playAudioInterruptionBegin;
 
/**
 *  播放音频结束被打断回调
 */
- (void)playAudioInterruptionEnd;
 
/**
 *  开始录制音频的回调
 *
 *  @param filePath 录制的音频的文件路径
 *  @param error    错误信息
 *  @discussion 如果录音失败，filePath 有可能为 nil
 */
- (void)recordAudio:(nullable NSString *)filePath didBeganWithError:(nullable NSError *)error;
 
/**
 *  录制音频完成后的回调
 *
 *  @param filePath 录制完成的音频文件路径
 *  @param error    错误信息
 */
- (void)recordAudio:(nullable NSString *)filePath didCompletedWithError:(nullable NSError *)error;
 
/**
 *  录音被取消的回调
 */
- (void)recordAudioDidCancelled;
 
/**
 *  音频录制进度更新回调
 *
 *  @param currentTime 当前录制的时间
 */
- (void)recordAudioProgress:(NSTimeInterval)currentTime;
 
/**
 *  录音开始被打断回调
 */
- (void)recordAudioInterruptionBegin;
 
/**
 *  录音结束被打断回调
 */
- (void)recordAudioInterruptionEnd;
 
@end
 
/**
 *  多媒体控制协议
 */
@protocol NIMMediaManager <NSObject>
 
@required
 
/**
 *  录音进度更新间隔
 *  @discussion 如果值大于0，则会按照相应间隔调用recordAudioProgress:回调,默认值为0.3
 */
@property (nonatomic, assign) NSTimeInterval recordProgressUpdateTimeInterval;
 
/**
 *  连接外接音频设备时是否仍使用内置麦克风，设置不做持久化，app运行周期有效
 *  @discussion 默认为NO，为NO时则跟随系统last in原则输入音频，为YES时则使用内置麦克风
 */
@property (nonatomic, assign) BOOL shouldUseBuiltInMic;
 
#pragma mark - play audio
/**
 *  切换音频输出设备
 *
 *  @param outputDevice 音频输出设备
 *
 *  @return 是否切换成功
 */
- (BOOL)switchAudioOutputDevice:(NIMAudioOutputDevice)outputDevice;
 
/**
 *  在播放声音的时候,如果手机贴近耳朵,是否需要自动切换成听筒播放
 *
 *  @param needProximityMonitor 是否需要贴耳传感器监听
 */
- (void)setNeedProximityMonitor:(BOOL)needProximityMonitor;
 
 
/**
 *  是否正在播放音频
 *
 */
- (BOOL)isPlaying;
 
/**
 *  播放音频文件
 *
 *  @discussion 开始播放，NIMMediaManagerDelegate中的playAudio:didBeganWithError:回调会被触发，播放完成后, NIMMediaManagerDelegate中的playAudio:didCompletedWithError:回调会被触发
 *  @param filepath 音频文件路径
 */
- (void)play:(NSString *)filepath;
 
/**
 *  停止播放音频
 *
 *  @discussion 音频播放完成后NIMMediaManagerDelegate中的playAudio:didCompletedWithError:回调会被触发
 */
- (void)stopPlay;
 
 
/**
 *  设置播放音频的起始时间
 *  @param timestamp 起始时间
 *  @discussion 起始时间不能大于整个音频的时间，否则播放无效。调用此方法后，不需要再调用 play: 方法，自动播放
 */
- (BOOL)seek:(NSTimeInterval)timestamp;
 
#pragma mark - record audio
 
/**
 *  是否正在录音
 *
 */
- (BOOL)isRecording;
 
/**
 *  开始录制音频
 *
 *  @param duration 最长录音时间
 *  @discussion 开始录音，NIMMediaManagerDelegate中的recordAudio:didBeganWithError:回调会被触发，录音完成后, NIMMediaManagerDelgate中的recordAudio:didCompletedWithError:回调会被触发
 *              默认使用 aac 编码格式
 */
- (void)recordForDuration:(NSTimeInterval)duration;
/**
 *  开始录音
 *
 *  @param type     音频类型
 *  @param duration 最大时长
 *  @discussion 开始录音，NIMMediaManagerDelegate中的recordAudio:didBeganWithError:回调会被触发，录音完成后, NIMMediaManagerDelegate中的recordAudio:didCompletedWithError:回调会被触发
 */
- (void)record:(NIMAudioType)type
      duration:(NSTimeInterval)duration;
 
/**
 *  停止录制音频
 *
 *  @discussion 停止录音后NIMMediaManagerDelegate中的recordAudio:didCompletedWithError:回调会被触发
 */
- (void)stopRecord;
 
/**
 *  取消录制音频
 *
 *  @discussion 录音取消后，NIMMediaManagerDelegate中的recordAudioDidCancelled回调会被触发
 */
- (void)cancelRecord;
 
/**
 *  获取录音分贝
 *
 */
- (float)recordPeakPower;
 
/**
 *  获取录音分贝
 *
 */
- (float)recordAveragePower;
 
 
/**
 *  语音转文字
 *
 *  @param option  语音转文字选项
 *  @param result  完成回调
 */
- (void)transAudioToText:(NIMAudioToTextOption *)option
                  result:(NIMAudioToTextBlock)result;
 
 
#pragma mark - common setting
 
/**
 *  禁止在IM 录制、播放音频时设置AVAudioSession, 防止影响其他音视频效果
 *  @param disabled YES则禁止重置
 */
- (void)disableResetAudioSession:(BOOL)disabled;
 
/**
 *  设置录制或者播放完成以后是否自动deactivate AVAudioSession
 *
 *  @param deactivate 是否deactivate，默认为YES
 */
- (void)setDeactivateAudioSessionAfterComplete:(BOOL)deactivate;
 
#pragma mark - delegates
/**
 *  添加多媒体委托
 *
 *  @param delegate 多媒体委托
 */
- (void)addDelegate:(id<NIMMediaManagerDelegate>)delegate;
 
/**
 *  移除多媒体委托
 *
 *  @param delegate 多媒体委托
 */
- (void)removeDelegate:(id<NIMMediaManagerDelegate>)delegate;
 
 
@end
 
 
NS_ASSUME_NONNULL_END