# 使用 AI 画质插件 (Beta) (/zh-CN/realtime-media/rtc/build/extensions/web/super-clarity) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## 使用 AI 画质插件(Beta 版) [#使用-ai-画质插件beta-版] AI 画质插件封装了声网自研的 AI 画质增强算法,可以在不改变分辨率的条件下智能提升视频画质,优化接收端的观看体验。AI 画质增强算法对移动端机型的覆盖率达到 95% 以上,并且在低端机上也能保证较大分辨率视频的渲染画质。 ## 实现原理 [#实现原理] 声网 Web SDK 的媒体传输管道包含采集、前处理、编码、传输、解码、后处理和播放等环节。 在后处理阶段,插件可以对管道中的音视频数据进行处理,从而实现 AI 画质等功能。 ## 前提条件 [#前提条件] 开始之前,请确保你满足以下条件: - 已集成 v4.19.0 或以上版本的 Web SDK,实现基础的实时音视频互动功能,具体参考[快速开始](../../../get-started/quick-start?platform=web)文档。 - 使用下表列出的浏览器版本,未列出的浏览器暂不支持: | 浏览器 | 版本要求 | | --------------------- | --------------- | | 桌面端、移动端 Chrome | 96 或以上 | | 桌面端 Safari | 15.4 或以上 | | 移动端 Safari | iOS 16.0 或以上 | ## 示例代码 [#示例代码] 以下是一段使用 AI 画质插件的完整代码,供开发者参考。 ```javascript const extension = new SuperClarityExtension(); AgoraRTC.registerExtensions([extension]); const context = { uid: undefined, client: undefined, track: undefined, processor: undefined, }; async function join(appid, channel) { context.client = AgoraRTC.createClient({ mode: "live", codec: "vp8", role: "host" }); client.on("user-published", onUserPublished); client.on("user-unpublished", onUserUnpublished); await client.join(appid, channel, null); } async function onUserPublished(user, mediaType) { if (!context.client || mediaType !== "video" || !!context.uid) { return; } context.uid = user.uid; context.track = await context.client.subscribe(user, mediaType); context.processor = extension.createProcessor(); context.processor.on("first-video-frame", (stats) => { console.log("plugin have first video frame, stats:", stats); }); context.processor.on("error", (msg) => { console.log("plugin error:", msg); }); context.processor.on("stats", (stats) => { console.log("plugin stats:", Date.now(), stats); }); context.track.pipe(context.processor).pipe(context.track.processorDestination); await context.processor.enable(); context.track.play('any element id') } async function onUserUnpublished(user, mediaType) { if (!context.client || mediaType !== "video" || context.uid !== user.uid) { return; } context.processor.unpipe(); context.track.unpipe(); await context.processor.release(); context.processor = undefined; context.track.stop(); context.track = undefined; } join('your-appid', 'your-channel'); ``` ## 实现步骤 [#实现步骤] 本节介绍使用 AI 画质插件的主要流程。 ### 1. 集成插件 [#1-集成插件] 1. 通过 npm 将 AI 画质插件 [agora-extension-super-clarity](https://www.npmjs.com/package/agora-extension-super-clarity) 集成到你的项目中: ```bash npm install agora-extension-super-clarity ``` 2. 通过以下任意一种方式引入 AI 画质插件。 - 方法一:在 JavaScript 文件中加入以下代码引入。 ```typescript import { SuperClarityExtension, SuperClarityEvents, SuperClarityProcessor, } from 'agora-extension-super-clarity'; ``` - 方法二:在 HTML 文件中通过 Script 标签引入。引入后即可在 JavaScript 文件中直接使用 `SuperClarityExtension` 对象。 ```html ``` ### 2. 注册插件 [#2-注册插件] 在加入频道之前,创建 `SuperClarityExtension` 对象并调用 SDK 的[`registerExtensions`](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#registerextensions) 方法注册插件。 ```typescript // 创建 SuperClarityExtension 对象 const extension = new SuperClarityExtension(); // 注册插件 AgoraRTC.registerExtensions([extension]); const context = { uid: undefined, client: undefined, track: undefined, processor: undefined, }; async function join(appid, channel) { context.client = AgoraRTC.createClient({ mode: "live", codec: "vp8", role: "host" }); client.on("user-published", onUserPublished); client.on("user-unpublished", onUserUnpublished); await client.join(appid, channel, null); } // 加入频道 join('your-appid', 'your-channel'); ``` ### 3. 开启插件 [#3-开启插件] 订阅远端视频轨道时,按照以下步骤开启 AI 画质插件: 1. 调用插件的 `createProcessor` 方法创建插件的 `processor`,并监听相关事件。 2. 调用 SDK 的 [`IRemoteVideoTrack.pipe`](/zh-CN/api-reference/rtc/web/interfaces/iremotevideotrack#pipe) 方法连接 AI 画质插件与该视频轨道之间的管线。 3. 调用插件的 `enable` 方法开启插件。开启后,播放该视频轨道即可看到 AI 画质插件的效果。 :::warning[注意] 为了避免多个 `processor` 同时工作导致性能问题,目前最多支持创建两个 `processor`,即 AI 画质插件最多同时对两个视频轨道生效。 ::: ```typescript async function onUserPublished(user, mediaType) { if (!context.client || mediaType !== "video" || !!context.uid) { return; } context.uid = user.uid; context.track = await context.client.subscribe(user, mediaType); // 创建 processor context.processor = extension.createProcessor(); // 监听 processor 相关事件 context.processor.on("first-video-frame", (stats) => { console.log("plugin have first video frame, stats:", stats); }); context.processor.on("error", (msg) => { console.log("plugin error:", msg); }); context.processor.on("stats", (stats) => { console.log("plugin stats:", Date.now(), stats); }); // 连接 processor 与视频轨道之间的管线 context.track.pipe(context.processor).pipe(context.track.processorDestination); // 开启插件 await context.processor.enable(); context.track.play('any element id') } ``` ### 4. 切换视频轨道 [#4-切换视频轨道] 虽然插件限制了创建的 `processor` 数量,但你可以通过切换视频轨道的方式,实现使用同一个 `processor` 对多个视频轨道进行 AI 画质处理。 需要切换视频轨道时,调用 SDK 的 [`IRemoteVideotrack.unpipe`](/zh-CN/api-reference/rtc/web/interfaces/iremotevideotrack#unpipe) 方法断开 `processor` 与当前视频轨道的连接,然后调用 SDK 的 `IRemoteVideotrack.pipe` 方法连接新的视频轨道。 ```javascript { // 取消 processor 和当前视频轨道的连接管线 await processor.disable(); processor.unpipe(); track?.unpipe(); track?.pipe( track.processorDestination ); } { // 连接新的视频轨道 track2.pipe(processor).pipe(track2.processorDestination); await processor.enable() track2.play(ele) } ``` ### 5. 销毁插件 [#5-销毁插件] 需要停止使用 AI 画质插件时,调用 SDK 的 `IRemoteVideotrack.unpipe` 方法断开 `processor` 与当前视频轨道的管线,然后调用插件的 `release` 方法销毁 `processor`、调用 SDK 的 `stop` 方法停止视频轨道并置空销毁,否则可能存在异常风险。 ```javascript async function onUserUnpublished(user, mediaType) { if (!context.client || mediaType !== "video" || context.uid !== user.uid) { return; } // 先断开 processor 与当前视频轨道的管线 context.processor.unpipe(); context.track.unpipe(); // 再销毁 processor 和视频轨道 await context.processor.release(); context.processor = undefined; context.track.stop(); context.track = undefined; } ``` ## 开发注意事项 [#开发注意事项] AI 画质插件在 iOS 设备上有可能无法自适应分辨率切换,因此当远端视频分辨率发生变化时,你需要先销毁 `processor` 再重新创建。 ```typescript const isIOS = // @ts-ignore /iPad|iPhone|iPod/.test(navigator.userAgent) && !window.MSStream; const isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent); const versions = navigator.userAgent.match(/Version\/([\d.]+).*Safari/); let version = 0; if (versions && versions.length > 1) { version = parseInt(versions[1]); } var shouldCleanResource: boolean = isIOS && isSafari && version < 16 ? true : false; var extension: SuperClarityExtension | undefined = undefined; var initSCProcessor = async () => { if (!extension) { extension = new SuperClarityExtension(); AgoraRTC.registerExtensions([extension]); } var processor = extension.createProcessor(); processor.on(SuperClarityEvents.FIRST_VIDEO_FRAME, (stats: any) => { console.log('plugin have first video frame, stats:', stats); }); processor.on(SuperClarityEvents.ERROR, (msg: any) => { console.log('plugin error:', msg); }); processor.on(SuperClarityEvents.STATS, (stats: any) => { console.log('plugin stats:', Date.now(), stats); }); return processor; }; var destroySCProcessor = async (processor) => { if (!processor ) { return; } processor.removeAllListeners(SuperClarityEvents.FIRST_VIDEO_FRAME); processor.removeAllListeners(SuperClarityEvents.ERROR); processor.removeAllListeners(SuperClarityEvents.STATS); await processor .release(); processor= undefined; }; // 刷新 processor { var info:{ w?:number, h?:number}={} if (shouldCleanResource) { setInterval(async ()=>{ !info.w && info.w = track?.getStats().receiveResolutionWidth; !info.h && info.h = track?.getStats().receiveResolutionHeight; if ( (track?.getStats().receiveResolutionWidth && info.w && track?.getStats().receiveResolutionWidth !== info.w) || (track?.getStats().receiveResolutionHeight && info.h && track?.getStats().receiveResolutionHeight !== info.h) ) { info.w = track?.getStats().receiveResolutionWidth; info.h = track?.getStats().receiveResolutionHeight; if (processor) { processor.unpipe(); track?.unpipe(); track?.pipe(track.processorDestination); await destroySCProcessor(processor); processor= undefined; } processor = await initSCProcessor(); track!.pipe(processor !).pipe(track!.processorDestination); await processor !.enable(); } }, 1000); } } ``` ## API 参考 [#api-参考] 本节提供 AI 画质插件的 API 参考。 ### ISuperClarityExtension [#isuperclarityextension] #### createProcessor [#createprocessor] ```typescript createProcessor(): ISuperClarityProcessor; ``` 创建 `ISuperClarityProcessor` 实例。 ### ISuperClarityProcessor [#isuperclarityprocessor] #### enable [#enable] ```typescript enable(): void | Promise; ``` 开启 AI 画质功能。 #### disable [#disable] ```typescript disable(): void | Promise; ``` 停止 AI 画质功能。 #### release [#release] ```typescript release(): Promise; ``` 释放插件占用的所有资源。