Blame view

HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioEffectManager.h 13.3 KB
wangguolei authored
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
/**
 * Module:   TRTC 背景音乐、短音效和人声特效的管理类
 * Function: 用于对背景音乐、短音效和人声特效进行设置的管理类
 */
/// @defgroup TXAudioEffectManager_ios TXAudioEffectManager
/// TRTC 背景音乐、短音效和人声特效的管理类
/// @{
#import <Foundation/Foundation.h>

/////////////////////////////////////////////////////////////////////////////////
//
//                    音效相关的枚举值定义
//
/////////////////////////////////////////////////////////////////////////////////
/// @name 音效相关的枚举值定义
/// @{

/**
 * 1.1 混响特效
 *
 * 混响特效可以作用于人声之上,通过声学算法对声音进行叠加处理,模拟出各种不同环境下的临场感受,目前支持如下几种混响效果:
wangguolei authored
22
 * 0:关闭;1:KTV;2:小房间;3:大会堂;4:低沉;5:洪亮;6:金属声;7:磁性;8:空灵;9:录音棚;10:悠扬;11:留声机;12:自然。
wangguolei authored
23 24 25 26 27 28 29 30 31 32 33 34 35
 */
typedef NS_ENUM(NSInteger, TXVoiceReverbType) {
    TXVoiceReverbType_0 = 0,    ///< disable
    TXVoiceReverbType_1 = 1,    ///< KTV
    TXVoiceReverbType_2 = 2,    ///< small room
    TXVoiceReverbType_3 = 3,    ///< great hall
    TXVoiceReverbType_4 = 4,    ///< deep voice
    TXVoiceReverbType_5 = 5,    ///< loud voice
    TXVoiceReverbType_6 = 6,    ///< metallic sound
    TXVoiceReverbType_7 = 7,    ///< magnetic sound
    TXVoiceReverbType_8 = 8,    ///< ethereal
    TXVoiceReverbType_9 = 9,    ///< studio
    TXVoiceReverbType_10 = 10,  ///< melodious
wangguolei authored
36 37
    TXVoiceReverbType_11 = 11,  ///< phonograph
    TXVoiceReverbType_12 = 12,  ///< nature
wangguolei authored
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
};

/**
 * 1.2 变声特效
 *
 * 变声特效可以作用于人声之上,通过声学算法对人声进行二次处理,以获得与原始声音所不同的音色,目前支持如下几种变声特效:
 * 0:关闭;1:熊孩子;2:萝莉;3:大叔;4:重金属;5:感冒;6:外语腔;7:困兽;8:肥宅;9:强电流;10:重机械;11:空灵。
 */
typedef NS_ENUM(NSInteger, TXVoiceChangeType) {
    TXVoiceChangeType_0 = 0,    ///< disable
    TXVoiceChangeType_1 = 1,    ///< naughty kid
    TXVoiceChangeType_2 = 2,    ///< Lolita
    TXVoiceChangeType_3 = 3,    ///< uncle
    TXVoiceChangeType_4 = 4,    ///< heavy metal
    TXVoiceChangeType_5 = 5,    ///< catch cold
    TXVoiceChangeType_6 = 6,    ///< foreign accent
    TXVoiceChangeType_7 = 7,    ///< caged animal trapped beast
    TXVoiceChangeType_8 = 8,    ///< indoorsman
    TXVoiceChangeType_9 = 9,    ///< strong current
    TXVoiceChangeType_10 = 10,  ///< heavy machinery
    TXVoiceChangeType_11 = 11,  ///< intangible
};

/// @}
/////////////////////////////////////////////////////////////////////////////////
//
//                    背景音乐的播放事件回调
//
/////////////////////////////////////////////////////////////////////////////////
/// @name 背景音乐的事件回调接口
/// @{

// Playback progress block of background music

///背景音乐开始播放
typedef void (^TXAudioMusicStartBlock)(NSInteger errCode);

///背景音乐的播放进度
typedef void (^TXAudioMusicProgressBlock)(NSInteger progressMs, NSInteger durationMs);

///背景音乐已经播放完毕
typedef void (^TXAudioMusicCompleteBlock)(NSInteger errCode);

/// @}
/////////////////////////////////////////////////////////////////////////////////
//
//                    背景音乐的播放控制信息
//
/////////////////////////////////////////////////////////////////////////////////
/// @name 背景音乐的播放控制信息
/// @{

/**
 * 背景音乐的播放控制信息
 *
 * 该信息用于在接口 {@link startPlayMusic} 中指定背景音乐的相关信息,包括播放 ID、文件路径和循环次数等:
 * 1. 如果要多次播放同一首背景音乐,请不要每次播放都分配一个新的 ID,我们推荐使用相同的 ID。
 * 2. 若您希望同时播放多首不同的音乐,请为不同的音乐分配不同的 ID 进行播放。
 * 3. 如果使用同一个 ID 播放不同音乐,SDK 会先停止播放旧的音乐,再播放新的音乐。
 */
@interface TXAudioMusicParam : NSObject

///【字段含义】音乐 ID <br/>
///【特殊说明】SDK 允许播放多路音乐,因此需要使用 ID 进行标记,用于控制音乐的开始、停止、音量等。
@property(nonatomic) int32_t ID;

///【字段含义】音效文件的完整路径或 URL 地址。支持的音频格式包括 MP3、AAC、M4A、WAV
@property(nonatomic, copy) NSString *path;

///【字段含义】音乐循环播放的次数 <br/>
///【推荐取值】取值范围为0 - 任意正整数,默认值:0。0表示播放音乐一次;1表示播放音乐两次;以此类推
@property(nonatomic) NSInteger loopCount;

///【字段含义】是否将音乐传到远端 <br/>
///【推荐取值】YES:音乐在本地播放的同时,远端用户也能听到该音乐;NO:主播只能在本地听到该音乐,远端观众听不到。默认值:NO。
@property(nonatomic) BOOL publish;

///【字段含义】播放的是否为短音乐文件 <br/>
///【推荐取值】YES:需要重复播放的短音乐文件;NO:正常的音乐文件。默认值:NO
@property(nonatomic) BOOL isShortFile;

///【字段含义】音乐开始播放时间点,单位:毫秒。
@property(nonatomic) NSInteger startTimeMS;

///【字段含义】音乐结束播放时间点,单位毫秒,0表示播放至文件结尾。
@property(nonatomic) NSInteger endTimeMS;
@end
/// @}

// Definition of audio effect management module
@interface TXAudioEffectManager : NSObject

/**
 * TXAudioEffectManager对象不可直接被创建
 * 要通过 `TRTCCloud` 或 `TXLivePush` 中的 `getAudioEffectManager` 接口获取
 */
- (instancetype)init NS_UNAVAILABLE;

/////////////////////////////////////////////////////////////////////////////////
//
//                    人声相关的特效接口
//
/////////////////////////////////////////////////////////////////////////////////
/// @name 人声相关的特效接口
/// @{

/**
 * 1.1 开启耳返
 *
 * 主播开启耳返后,可以在耳机里听到麦克风采集到的自己发出的声音,该特效适用于主播唱歌的应用场景中。
 *
 * 需要您注意的是,由于蓝牙耳机的硬件延迟非常高,所以在主播佩戴蓝牙耳机时无法开启此特效,请尽量在用户界面上提示主播佩戴有线耳机。
 * 同时也需要注意,并非所有的手机开启此特效后都能达到优秀的耳返效果,我们已经对部分耳返效果不佳的手机屏蔽了该特效。
 *
 * @note 仅在主播佩戴耳机时才能开启此特效,同时请您提示主播佩戴有线耳机。
wangguolei authored
153
 * @param enable YES:开启;NO:关闭。
wangguolei authored
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
 */
- (void)enableVoiceEarMonitor:(BOOL)enable;

/**
 * 1.2 设置耳返音量
 *
 * 通过该接口您可以设置耳返特效中声音的音量大小。
 *
 * @param volume 音量大小,取值范围为0 - 100,默认值:100。
 * @note 如果将 volume 设置成 100 之后感觉音量还是太小,可以将 volume 最大设置成 150,但超过 100 的 volume 会有爆音的风险,请谨慎操作。
 */
- (void)setVoiceEarMonitorVolume:(NSInteger)volume;

/**
 * 1.3 设置人声的混响效果
 *
 * 通过该接口您可以设置人声的混响效果,具体特效请参考枚举定义{@link TXVoiceReverbType}。
 *
 * @note 设置的效果在退出房间后会自动失效,如果下次进房还需要对应特效,需要调用此接口再次进行设置。
 */
- (void)setVoiceReverbType:(TXVoiceReverbType)reverbType;

/**
 * 1.4 设置人声的变声特效
 *
 * 通过该接口您可以设置人声的变声特效,具体特效请参考枚举定义{@link TXVoiceChangeType}。
 *
 * @note 设置的效果在退出房间后会自动失效,如果下次进房还需要对应特效,需要调用此接口再次进行设置。
 */
- (void)setVoiceChangerType:(TXVoiceChangeType)changerType;

/**
 * 1.5 设置语音音量
 *
 * 该接口可以设置语音音量的大小,一般配合音乐音量的设置接口 {@link setAllMusicVolume} 协同使用,用于调谐语音和音乐在混音前各自的音量占比。
 *
 * @param volume 音量大小,取值范围为0 - 100,默认值:100。
 * @note 如果将 volume 设置成 100 之后感觉音量还是太小,可以将 volume 最大设置成 150,但超过 100 的 volume 会有爆音的风险,请谨慎操作。
 */
- (void)setVoiceVolume:(NSInteger)volume;

/**
 * 1.6 设置语音音调
 *
 * 该接口可以设置语音音调,用于实现变调不变速的目的。
 *
 * @param pitch 音调,取值范围为-1.0f~1.0f,默认值:0.0f。
 */
- (void)setVoicePitch:(double)pitch;

/// @}
/////////////////////////////////////////////////////////////////////////////////
//
//                    背景音乐的相关接口
//
/////////////////////////////////////////////////////////////////////////////////
/// @name 背景音乐的相关接口
/// @{

/**
 * 2.1 开始播放背景音乐
 *
 * 每个音乐都需要您指定具体的 ID,您可以通过该 ID 对音乐的开始、停止、音量等进行设置。
 *
 * @note
 * 1. 如果要多次播放同一首背景音乐,请不要每次播放都分配一个新的 ID,我们推荐使用相同的 ID。
 * 2. 若您希望同时播放多首不同的音乐,请为不同的音乐分配不同的 ID 进行播放。
 * 3. 如果使用同一个 ID 播放不同音乐,SDK 会先停止播放旧的音乐,再播放新的音乐。
 *
 * @param musicParam 音乐参数
 * @param startBlock 播放开始回调
 * @param progressBlock 播放进度回调
 * @param completeBlock 播放结束回调
 */
- (void)startPlayMusic:(TXAudioMusicParam *)musicParam onStart:(TXAudioMusicStartBlock _Nullable)startBlock onProgress:(TXAudioMusicProgressBlock _Nullable)progressBlock onComplete:(TXAudioMusicCompleteBlock _Nullable)completeBlock;

/**
 * 2.2 停止播放背景音乐
 *
 * @param id  音乐 ID
 */
- (void)stopPlayMusic:(int32_t)id;

/**
 * 2.3 暂停播放背景音乐
 *
 * @param id  音乐 ID
 */
- (void)pausePlayMusic:(int32_t)id;

/**
 * 2.4 恢复播放背景音乐
 *
 * @param id  音乐 ID
 */
- (void)resumePlayMusic:(int32_t)id;

/**
 * 2.5 设置所有背景音乐的本地音量和远端音量的大小
 *
 * 该接口可以设置所有背景音乐的本地音量和远端音量。
 * - 本地音量:即主播本地可以听到的背景音乐的音量大小。
 * - 远端音量:即观众端可以听到的背景音乐的音量大小。
 *
 * @param volume 音量大小,取值范围为0 - 100,默认值:100。
 * @note 如果将 volume 设置成 100 之后感觉音量还是太小,可以将 volume 最大设置成 150,但超过 100 的 volume 会有爆音的风险,请谨慎操作。
 */
- (void)setAllMusicVolume:(NSInteger)volume;

/**
 * 2.6 设置某一首背景音乐的远端音量的大小
 *
 * 该接口可以细粒度地控制每一首背景音乐的远端音量,也就是观众端可听到的背景音乐的音量大小。
 *
 * @param id     音乐 ID
 * @param volume 音量大小,取值范围为0 - 100;默认值:100
 * @note 如果将 volume 设置成 100 之后感觉音量还是太小,可以将 volume 最大设置成 150,但超过 100 的 volume 会有爆音的风险,请谨慎操作。
 */
- (void)setMusicPublishVolume:(int32_t)id volume:(NSInteger)volume;

/**
 * 2.7 设置某一首背景音乐的本地音量的大小
 *
 * 该接口可以细粒度地控制每一首背景音乐的本地音量,也就是主播本地可以听到的背景音乐的音量大小。
 *
 * @param id     音乐 ID
 * @param volume 音量大小,取值范围为0 - 100,默认值:100。
 * @note 如果将 volume 设置成 100 之后感觉音量还是太小,可以将 volume 最大设置成 150,但超过 100 的 volume 会有爆音的风险,请谨慎操作。
 */
- (void)setMusicPlayoutVolume:(int32_t)id volume:(NSInteger)volume;

/**
 * 2.8 调整背景音乐的音调高低
 *
 * @param id    音乐 ID
 * @param pitch 音调,默认值是0.0f,范围是:[-1 ~ 1] 之间的浮点数;
 */
- (void)setMusicPitch:(int32_t)id pitch:(double)pitch;

/**
 * 2.9 调整背景音乐的变速效果
 *
 * @param id    音乐 ID
 * @param speedRate 速度,默认值是1.0f,范围是:[0.5 ~ 2] 之间的浮点数;
 */
- (void)setMusicSpeedRate:(int32_t)id speedRate:(double)speedRate;

/**
 * 2.10 获取背景音乐的播放进度(单位:毫秒)
 *
 * @param id    音乐 ID
 * @return 成功返回当前播放时间,单位:毫秒,失败返回-1
 */
- (NSInteger)getMusicCurrentPosInMS:(int32_t)id;

/**
 * 2.11 获取背景音乐的总时长(单位:毫秒)
 *
 * @param path 音乐文件路径。
 * @return 成功返回时长,失败返回-1
 */
- (NSInteger)getMusicDurationInMS:(NSString *)path;

/**
 * 2.12 设置背景音乐的播放进度(单位:毫秒)
 *
 * @note 请尽量避免过度频繁地调用该接口,因为该接口可能会再次读写音乐文件,耗时稍高。
 *       因此,当用户拖拽音乐的播放进度条时,请在用户完成拖拽操作后再调用本接口。
 *       因为 UI 上的进度条控件往往会以很高的频率反馈用户的拖拽进度,如不做频率限制,会导致较差的用户体验。
 *
 * @param id  音乐 ID
 * @param pts 单位: 毫秒
 */
- (void)seekMusicToPosInMS:(int32_t)id pts:(NSInteger)pts;

/// @}
@end  // End of interface TXAudioEffectManager
/// @}