开发音频插件

  • Web

更新时间

了解云市场在不同平台上的开发音频插件方式,包括接入流程、关键配置和平台差异。

本文展示如何开发一个与声网 Web SDK 4.x 搭配使用的音频插件。

技术原理

声网为开发音频插件提供以下抽象类:

  • 必需的基础类:
    • AudioExtension:实现插件的初始化,包括创建插件、设置日志上报、设置事件上报等。
    • AudioProcessor:实现音频数据的处理能力,包括接收、处理和返回处理完的音频数据。
  • 可选的辅助类:
    • Ticker:帮助管理周期性任务。
    • Logger:向声网 SDK 上传日志。
    • Reporter:向声网 SDK 报告事件。

前提条件

开发前,请确保你的开发环境满足以下要求:

准备开发环境

通过 npm 将插件开发模块(agora-rte-extension)集成到你的项目中:

  1. 运行以下命令安装:

    Shell
    npm install --save agora-rte-extension
  2. 在你的 .js 文件中加入以下代码导入插件开发模块:

    JavaScript
    import {AudioExtension, AudioProcessor} from 'agora-rte-extension'

开发音频插件

本节详细介绍开发音频插件必须实现的 API。你还可以根据实际需要实现一些辅助类 API,优化插件的设计和性能,详见 API 参考。

实现插件初始化

插件初始化通过 AudioExtension 类实现。你需要实现 AudioExtension 类的 createProcessor 方法:

createProcessor

TypeScript
abstract class AudioExtension<T extends AudioProcessor> {
    createProcessor(): T;
}

创建 AudioProcessor 实例。

插件使用者调用 extension.createProcessor 时,SDK 会调用该方法。你需要在该方法中返回创建好的 AudioProcessor 实例。

实现音频数据处理

实现音频数据处理包括以下步骤:

  1. 接收待处理的音频:通过 AudioProcessor 类的 onNode 方法和 IAudioProcessorContext 接口的 getAudioContext 方法实现。
  2. 处理音频:需要你自行实现。
  3. 输出处理后的音频:通过 AudioProcessor 类的 output 方法实现。

onNode

TypeScript
abstract onNode?(node: AudioNode, context: IAudioProcessorContext): void;

从前一个节点接收到待处理的音频数据回调。

参数

  • node:前一个 AudioNode。AudioNode 是 Web Audio API 提供的接口类,详见 Web Audio API interfaces。

  • context:当前音频处理管道的 context。

output

TypeScript
output(track: MediaStreamTrack | AudioNode, context: IProcessorContext): void;

输出处理后的音频数据。

参数

  • track:处理后的音频数据。推荐使用 AudioNode。

  • context:当前音频处理管道的 context。

getAudioContext

TypeScript
getAudioContext(): Promise<AudioContext>;

获取当前音频处理管道的 AudioContext。AudioContext 是 Web Audio API 提供的接口类,详见 Web Audio API interfaces。

示例项目

声网提供一个 Web 插件开发的示例项目供你参考,你可以前往下载或查看其中的源代码。

以下示例代码展示了如何开发一个音频插件:

TypeScript
class YourExtension extends AudioExtension<YourProcessor> {
    // 创建 Processor
    protected _createProcessor(): YourProcessor {
        return new YourProcessor();
    }
}

class CustomAudioProcessor extends AudioProcessor {
    // 从前一个 AudioNode 接收到音频数据
    onNode(node: AudioNode, context: IAudioProcessorContext) {
        // 创建 AudioNode
        const audioContext = context.getAudioContext();
        const gainNode = audioContext.createGain();

        // 连接前一个 AudioNode
        node.connect(gainNode);
    }

    process() {
        // TODO:添加你的插件的音频处理逻辑

        // 输出处理后的音频数据
        this.output(gainNode, context);
    }
}

API 参考

本节介绍开发音频插件的辅助类 API。

AudioProcessor

name

TypeScript
name: string;

Processor 的名称。

enabled

TypeScript
enabled :boolean;

Processor 的开启状态。

ID

TypeScript
public readonly ID:string;

Processor 的标识符。

Kind

TypeScript
public get Kind():'video' | 'audio';

Processor 的类型,分为视频和音频两种。

context

TypeScript
protected context?: IProcessorContext;

用于 Processor 请求原始媒体流并重新进行采集。

onPiped

TypeScript
abstract onPiped?(context: IProcessorContext): void;

LocalVideoTrack 连接到当前媒体处理管道的回调。

注意

如果只是连接多个 Processor,不会触发该回调。例如:插件使用者调用 processorA.pipe(processorB)。

onUnPiped

TypeScript
abstract onUnPiped?(): void;

Processor 断开与媒体处理管道的连接回调。

onEnableChange

TypeScript
abstract onEnableChange?(enabled: boolean): void | Promise<void>;

Processor 的开启状态变化回调。

inputNode

TypeScript
protected inputNode?:AudioNode;

Processor 接收到的音频。

outputNode

TypeScript
protected outputNode?:AudioNode;

Processor 处理后的音频。

IAudioProcessorContext

TypeScript
interface IAudioProcessorContext extends IProcessorContext {
    getAudioContext(): Promise<AudioContext>;
}

用于 AudioProcessor 获取当前音频处理管道的 AudioContext。

Ticker

constructor

TypeScript
public constructor(type:"Timer" | "RAF" | "Oscillator", interval: number):Ticker;

Ticker 的构造函数。

参数

  • type:类型,支持以下三种:

    • Timer: 使用 setTimeout 作为插件内部的计时器。

    • (推荐)RAF: 使用 requestAnimationFrame 作为插件内部的计时器。大多数情况下,该类型的 Ticker 渲染性能最好。

    • Oscillator: 使用 WebAudio 的 OscillatorNode 作为插件内部的计时器。该类型的 Ticker 在浏览器页面不被浏览时也能运行。

  • interval:两次回调之间的间隔。 Ticker 会按照这个间隔执行,但无法保证 100% 精准。

Ticker.add

TypeScript
public add(fn: Function): void;

添加计时任务。

Ticker.remove

TypeScript
public remove():void;

取消添加的计时任务。

Ticker.start

TypeScript
public start():void;

开始计时。

Ticker.stop

TypeScript
public stop():void;

停止计时。

Logger

TypeScript
interface IExtensionLogger {
    debug(...args: any): void;
    error(...args: any): void;
    info(...args: any): void;
    warning(...args: any): void;
}

提供四种级别的日志。

插件使用者如果在调用 AgoraRTC.registerExtension 注册插件时选择了上传日志,则通过 Logger 类上报的日志会被上传。

Reporter

Reporter.reportApiInvoke

TypeScript
public reportApiInvoke<T>(params: ReportApiInvokeParams): AgoraApiExecutor<T>;

向 SDK 报告 API 调用的相关事件。

其中 ReportApiInvokeParams 和 AgoraApiExecutor 的定义如下:

TypeScript
interface ReportApiInvokeParams {
    // 被调用的 API 的名称
    name: string;
    // 与该 API 有关的参数或选项
    options: any;
    // 是否报告该 API 的调用结果
    reportResult?: boolean;
    // 定义多久为调用超时
    timeout?: number;
}
interface AgoraApiExecutor<T> {
    // API 调用成功
    onSuccess: (result: T) => void;
    // API 调用失败
    onError: (err: Error) => void;
}