diff --git "a/markdown/beauty/\345\205\266\344\273\226/beauty_overview.md" "b/markdown/beauty/\345\205\266\344\273\226/beauty_overview.md" new file mode 100644 index 00000000000..fd7e47ff5d6 --- /dev/null +++ "b/markdown/beauty/\345\205\266\344\273\226/beauty_overview.md" @@ -0,0 +1,37 @@ +实时音视频互动中,美颜功能可以让用户展现更好的精神面貌,并提供有趣的贴纸特效。声网与第三方厂商合作,开发了声网美颜场景化 API,使开发者能够方便地集成美颜功能。声网美颜场景化 API,也称为 Beauty API,封装了声网 RTC SDK 和第三方美颜 SDK 的 API 调用逻辑,开发者只需几行代码就能在声网的实时音视频互动中使用第三方提供的丰富美颜功能。 + +## 获取资源 + +声网目前已与商汤美颜、字节火山美颜、相芯美颜合作,提供美颜场景化 API,开发者可以根据自己的需求选择不同厂商进行集成。集成过程中,你可以参考如下资源: + +|美颜厂商 | 美颜场景化 API 版本号 |GitHub 示例项目 | 参考文档 | +|-----|-----------|---------------|------------| +| 商汤 | 1.0.1.1|
  • [Android 项目](https://github.com/AgoraIO-Community/BeautyAPI/tree/1.0.1.1/Android)
  • [iOS 项目](https://github.com/AgoraIO-Community/BeautyAPI/tree/1.0.1.1/iOS)
  • |
  • [跑通项目 (Android)](./beauty_run_github_project_sensetime_android)
  • [跑通项目 (iOS)](./beauty_run_github_project_sensetime_ios)
  • [实现美颜 (Android)](./beauty_integration_sensetime_android)
  • [实现美颜 (iOS)](./beauty_integration_sensetime_android)
  • | +| 字节火山 |1.0.2 或之后|
  • [Android 项目](https://github.com/AgoraIO-Community/BeautyAPI/tree/main/Android)
  • [iOS 项目](https://github.com/AgoraIO-Community/BeautyAPI/tree/main/iOS)
  • |
  • [跑通项目 (Android)](./beauty_run_github_project_bytedance_android)
  • [跑通项目 (iOS)](./beauty_run_github_project_bytedance_ios)
  • [实现美颜 (Android)](./beauty_integration_bytedance_android)
  • [实现美颜 (iOS)](./beauty_integration_bytedance_android)
  • | +| 相芯 |1.0.2 或之后|
  • [Android 项目](https://github.com/AgoraIO-Community/BeautyAPI/tree/main/Android)
  • [iOS 项目](https://github.com/AgoraIO-Community/BeautyAPI/tree/main/iOS)
  • |
  • [跑通项目 (Android)](./beauty_run_github_project_faceunity_android)
  • [跑通项目 (iOS)](./beauty_run_github_project_faceunity_ios)
  • [实现美颜 (Android)](./beauty_integration_faceunity_android)
  • [实现美颜 (iOS)](./beauty_integration_faceunity_android)
  • | + + +## 版本说明 + +本节说明秀场直播示例项目、场景化美颜示例项目、美颜 SDK 的版本信息。 + +### 秀场直播 + +|秀场直播版本号| GitHub 示例项目 | +|-----|--------| +| 3.0.0.1 |
  • [Android 项目](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/tree/v3.0.0.1-all-Android/Android/scenes/show)
  • [iOS 项目](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/tree/v3.0.0-all-iOS/iOS/AgoraEntScenarios/Scenes/Show)
  • | +| 3.0.1 |
  • [Android 项目](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/tree/feat/scene/all_android_3.0.1/Android/scenes/show)
  • [iOS 项目](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/tree/feat/scene/all_ios_3.0.1/iOS/AgoraEntScenarios/Scenes/Show)
  • | + +
    声网已在 3.0.1 版(最新版)的秀场直播示例项目中集成 1.0.1.1 版场景化美颜(商汤)供你参考。
    + +### 场景化美颜 + +各版本的场景化美颜示例项目代码可以在 `BeautyAPI` 仓库的 [Tags](https://github.com/AgoraIO-Community/BeautyAPI/tags) 中查看。 + +![](https://web-cdn.agora.io/docs-files/1694426614022) + +### 美颜 SDK + +Beauty API 中封装的声网 RTC SDK 和第三方厂商美颜 SDK 版本请参考 [README](https://github.com/AgoraIO-Community/BeautyAPI/blob/main/README.zh)。 + +![](https://web-cdn.agora.io/docs-files/1694425497610) \ No newline at end of file diff --git "a/markdown/beauty/\345\205\266\344\273\226/placeholder_beauty_api_ref_android.md" "b/markdown/beauty/\345\205\266\344\273\226/placeholder_beauty_api_ref_android.md" new file mode 100644 index 00000000000..e69de29bb2d diff --git "a/markdown/beauty/\345\205\266\344\273\226/placeholder_beauty_api_ref_ios.md" "b/markdown/beauty/\345\205\266\344\273\226/placeholder_beauty_api_ref_ios.md" new file mode 100644 index 00000000000..e69de29bb2d diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/Android.wsd" "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/Android.wsd" new file mode 100644 index 00000000000..3d52716bbd4 --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/Android.wsd" @@ -0,0 +1,45 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "商汤美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 RtcEngine == +app -> rtc: RtcEngine.create \n创建并初始化 RtcEngine 对象 +== 初始化美颜 SDK == +app -> beauty: 创建并初始化 STRenderKit +== 初始化 Beauty API == +app -> api: createSenseTimeBeautyAPI \n创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +app -> rtc: enableVideo \n开启视频模块 +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: registerVideoFrameObserver \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannel +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: release \n销毁 Beauty API 对象 +app -> beauty: release \n销毁 STRenderKit +app -> rtc: destroy \n销毁 RtcEngine 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_integration_sensetime_android.md" "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_integration_sensetime_android.md" new file mode 100644 index 00000000000..0503f52110c --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_integration_sensetime_android.md" @@ -0,0 +1,348 @@ +本文介绍如何通过声网美颜场景化 API (Beauty API) 集成商汤美颜到实时音视频互动中。 + +## 示例项目 + +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/1.0.1.1) 示例项目供你参考。 + +## 准备开发环境 + +### 前提条件 + +- [Git](https://git-scm.com/downloads) +- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 11 +- [Android Studio](https://developer.android.com/studio/) 3.5 及以上 +- Android 手机,版本 Android 5.0(API Level 21)及以上 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) +- 已联系商汤技术获取最新的美颜 SDK、美颜资源、美颜证书 +- 已在项目中添加 Kotlin 插件 + +### 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +跑通示例项目时,你需要将**鉴权机制**设置为**调试模式:APP ID**。从头搭建 Android 项目集成美颜功能时,声网推荐你将**鉴权机制**设置为**安全模式:APP ID + Token**,以保障安全性。 + + +### 创建 Android 项目 + +按照以下步骤准备开发环境: + +1. 如需创建新项目,在 **Android Studio** 里,依次选择 **Phone and Tablet > Empty Activity**,创建 [Android 项目](https://developer.android.com/studio/projects/create-project)。 + +
    创建项目后,Android Studio 会自动开始同步 gradle, 稍等片刻至同步成功后再进行下一步操作。
    + +2. 使用 Maven Central 将声网 RTC SDK 集成到你的项目中。 + + a. 在 `/Gradle Scripts/build.gradle(Project: )` 文件中添加如下代码,添加 Maven Central 依赖: + + ```java + buildscript { + repositories { + ... + mavenCentral() + } + ... + } + + allprojects { + repositories { + ... + mavenCentral() + } + } + ``` + +
    如果你的 Android 项目设置了 dependencyResolutionManagement,添加 Maven Central 依赖的方式可能存在差异。
    + + b. 在 `/Gradle Scripts/build.gradle(Module: .app)` 文件中添加如下代码,将声网 RTC SDK 集成到你的 Android 项目中: + + ```java + ... + dependencies { + ... + // x.y.z,请填写具体的 RTC SDK 版本号,如:4.0.0 或 4.1.0-1。 + // 通过互动直播产品发版说明获取最新版本号。 + implementation 'io.agora.rtc:full-sdk:x.y.z' + } + ``` + +3. 将商汤美颜 SDK 集成到你的项目中。请联系商汤技术支持获取美颜 SDK、美颜资源、证书等文件。下载并解压文件,然后添加到美颜项目对应的文件路径下: + + | 文件 | 项目路径 | + |--------------------------------------------------------------------|------------------------------------------------------| + | Android/models | app/src/main/assets/beauty_sensetime/models | + | Android/sample/SenseMeEffects/app/src/main/assets/sticker_face_shape | app/src/main/assets/beauty_sensetime/sticker_face_shape | + | Android/sample/SenseMeEffects/app/src/main/assets/style_lightly | app/src/main/assets/beauty_sensetime/style_lightly | + | Android/sample/SenseMeEffects/app/src/main/assets/makeup_lip | app/src/main/assets/beauty_sensetime/makeup_lip | + | SenseME.lic | app/src/main/assets/beauty_sensetime/license/SenseME.lic | + + +4. 将声网美颜场景化 API 集成到你的项目中。添加 [Android/lib_sensetime/src/main/java/io/agora/beautyapi/sensetime](https://github.com/AgoraIO-Community/BeautyAPI/tree/1.0.1.1/Android/lib_sensetime/src/main/java/io/agora/beautyapi/sensetime) 目录下的文件到项目中,具体文件如下: + - `utils` 文件夹 + - `SenseTimeBeautyAPI.kt` 文件 + - `SenseTimeBeautyAPIImpl.kt` 文件 + +
    为方便后续代码升级,请不要修改你添加的这些文件的名称和路径。
    + +5. 添加网络及设备权限。 + + 在 `/app/Manifests/AndroidManifest.xml` 文件中,在 `` 后面添加如下权限: + + ```xml + + + + + + + + + + + + + ``` + +5. 在 `/Gradle Scripts/proguard-rules.pro` 文件中添加如下行,以防止声网 SDK 的代码被混淆: + + ```java + -keep class io.agora.**{*;} + -dontwarn javax.** + -dontwarn com.google.devtools.build.android.** + ``` + +## 实现美颜 + +本节展示如何在直播间内实现美颜功能,参考 [API 时序图](#api-时序图)可查看总览。声网 RTC SDK 承担实时音视频的业务,商汤美颜 SDK 提供美颜功能,声网 Beauty API 封装了两个 SDK 中的 API 调用逻辑以简化你需要实现的代码逻辑。通过 Beauty API,你可以实现基础美颜功能,但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。 + +### 1. 初始化 RtcEngine + +调用声网 RTC SDK 中的 `create` 创建并初始化 `RtcEngine` 对象。 + +```kotlin +// 初始化声网 RtcEngine +private val mRtcEngine by lazy { + RtcEngine.create(RtcEngineConfig().apply { + mContext = applicationContext + // 传入你从控制台获取的声网项目的 APP ID + mAppId = BuildConfig.AGORA_APP_ID + mEventHandler = object : IRtcEngineEventHandler() {} + }).apply { + // 开启声网 clear_vision 高清视频插件 + enableExtension("agora_video_filters_clear_vision", "clear_vision", true) + } +} +``` + +### 2. 初始化美颜 SDK + +创建来自美颜 SDK 的 `STRenderKit` 实例。 + +```kotlin +private val mSTRenderKit by lazy { + STRenderKit( + this, + "beauty_sensetime" + ) +} +``` + +### 3. 初始化 Beauty API + +调用 `createSenseTimeBeautyAPI` 创建 Beauty API 对象。Beauty API 对象基于 `STRenderKit` 对象封装。 + +```kotlin +// 创建 Beauty API 对象 +private val mSenseTimeApi by lazy { + createSenseTimeBeautyAPI() +} +``` + +调用 `initialize` 初始化 Beauty API 对象。你需要在 `config` 参数中传入如下字段: + +- `mRtcEngine`:传入之前初始化的 `RtcEngine` 对象。 +- `mSTRenderKit`:传入之前初始化的 `STRenderKit` 对象。 +- `captureMode`:视频的采集模式: + - 如果你使用声网模块采集视频,请传入 `CaptureMode.Agora`。 + - 如果自定义采集视频,请传入 `CaptureMode.Custom`。 +- `statsEnable`:是否开启美颜统计数据回调。`true` 代表开启,`false` 代表不开启。开启后,会有周期性的 `onBeautyStats` 回调事件。 +- `statsDuration`:美颜统计数据回调的周期。单位为毫秒。 +- `eventCallback`:你希望监听的回调事件。 + +```kotlin +// 初始化 Beauty API 对象 +mSenseTimeApi.initialize( + Config( + // RtcEngine + mRtcEngine, + // STRenderKit + mSTRenderKit, + // 设置视频采集模式 + // CaptureMode.Agora 意味着使用声网模块采集视频 + // CaptureMode.Custom 意味着使用开发者自定义采集视频 + captureMode = if (isCustomCaptureMode) CaptureMode.Custom else CaptureMode.Agora, + // 是否开启美颜统计数据 + // 开启后,会有周期性的 onBeautyStats 回调事件 + statsEnable = true, + // 设置美颜统计数据的统计区间为 1000 毫秒(默认) + statsDuration = 1000, + // 用于监听 Beauty API 的回调事件 + eventCallback = object: IEventCallback{ + override fun onBeautyStats(stats: BeautyStats) { + Log.d(TAG, "BeautyStats stats = $stats") + } + } + ) +) +``` + +### 4. 开启美颜 + +调用 Beauty API 的 `enable` 方法并将参数设为 `true` 开启美颜。 + +```kotlin +mSenseTimeApi.enable(true) +``` + +### 5. 开启视频采集 + +开发者可以使用声网模块采集视频,也可以自定义采集视频。本节介绍在这两种场景下如何开启视频采集。 + +#### 使用声网模块采集视频 + +使用声网模块采集视频视频时,你需要先调用 `RtcEngine` 类的 `enableVideo` 开启声网 SDK 的视频模块,然后调用 Beauty API 的 `setupLocalVideo` 开启本地视图。 + +```kotlin +// 开启视频模块 +mRtcEngine.enableVideo() +// 设置本地视图 +mSenseTimeApi.setupLocalVideo(mBinding.localVideoView, Constants.RENDER_MODE_FIT) +``` + +#### 自定义视频采集 + +自定义视频采集时,你需要先调用 `RtcEngine` 类的 `enableVideo` 开启声网 SDK 的视频模块,然后通过 `RtcEngine` 类的 `registerVideoFrameObserver` 注册原始视频数据观测器并在其中实现 `onCaptureVideoFrame` 函数。 + +通过 Beauty API 的 `onFrame` 函数,你可以将外部自采集的视频数据传入并进行处理。当处理结果不为 `SKIPPED`(忽略)时,用自采集的视频数据替代 `onCaptureVideoFrame` 函数中的 `VideoFrame`,并传入声网 SDK。 + +```kotlin +// 开启视频模块 +mRtcEngine.enableVideo() +// 注册原始视频数据观测器 +// 自定义视频采集时,即 CaptureMode 为 Custom 时,你需要注册原始视频观测器 +mRtcEngine.registerVideoFrameObserver(object : IVideoFrameObserver { + private var shouldMirror = true + + override fun onCaptureVideoFrame( + sourceType: Int, + videoFrame: VideoFrame? + ) : Boolean { + when(mSenseTimeApi.onFrame(videoFrame!!)){ + // 当处理结果为 SKIPPED(忽略)时,代表你丢帧,即外部自采集的视频数据不传入声网 SDK + // 当处理结果为其他时,外部自采集的视频数据传入声网 SDK + ErrorCode.ERROR_OK.value -> { + shouldMirror = false + return true + } + ErrorCode.ERROR_FRAME_SKIPPED.value -> { + shouldMirror = false + return false + } + else -> { + val mirror = videoFrame.sourceType == VideoFrame.SourceType.kFrontCamera + if(shouldMirror != mirror){ + shouldMirror = mirror + return false + } + return true + } + } + } + + // 设置是否对原始视频数据作镜像处理 + override fun getMirrorApplied() = shouldMirror + + // 设置观测点为本地采集时的视频数据 + override fun getObservedFramePosition() = IVideoFrameObserver.POSITION_POST_CAPTURER + + // override 视频观测器中的其他回调函数 + ... +}) +``` + + +### 6. 加入频道 + +调用 `RtcEngine` 类的 `joinChannel` 加入频道,同时传入如下参数: + +- `token`:用于鉴权的动态密钥。如果在[创建声网项目](#创建声网项目)时启用**调试模式**,那么将 `token` 参数传空。如果启用**安全模式**,那么你先参考[使用 Token 鉴权](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/token_server_android_ng?platform=Android)在你的业务服务端生成 Token,然后将生成的 Token 传入该参数。 +- `channelId`:频道名。 +- `options`:频道媒体设置选项。 + + +```kotlin +mRtcEngine.joinChannel(null, mChannelName, 0, ChannelMediaOptions().apply { + // 设置频道场景为直播 + channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING + // 设置用户角色为主播,主播可以在频道里发布和订阅音视频流 + clientRoleType = Constants.CLIENT_ROLE_BROADCASTER + // 设置是否发布摄像头采集的视频流(适用于使用声网模块采集视频的情况) + publishCameraTrack = true + // 设置是否发布自定义采集的视频流(适用于自定义采集视频的情况) + publishCustomVideoTrack = false + // 设置是否发布麦克风采集的音频流 + publishMicrophoneTrack = false + // 设置进入频道时是否自动订阅频道内其他用户的音频流 + autoSubscribeAudio = false + // 设置进入频道时是否自动订阅频道内其他用户的视频流 + autoSubscribeVideo = true +}) +``` + +### 7. 设置美颜效果 + +调用 Beauty API 中 `setBeautyPreset` 方法设置使用的美颜参数的类型: + +- `DEFAULT`:默认且推荐的美颜参数。 +- `CUSTOM`:开发者自定义的美颜参数。 + +不同的美颜参数会带来不同的美颜效果。如果你没有特殊美颜要求,推荐你使用 `DEFAULT`。 + +```kotlin +mSenseTimeApi.setBeautyPreset(if (enable) BeautyPreset.DEFAULT else BeautyPreset.CUSTOM) +``` + +
    通过 Beauty API 的 setBeautyPreset 方法,你可以实现基础美颜功能。但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。
    + +### 8. 离开频道 + +调用 `RtcEngine` 类的 `leaveChannel` 离开频道。 + +```kotlin +mRtcEngine.leaveChannel() +``` + +### 9. 销毁资源 + +调用 Beauty API 的 `release` 销毁 Beauty API。 + +```kotlin +mSenseTimeApi.release() +``` + +调用美颜 SDK 的 `release` 销毁 `STRenderKit`。 + +```kotlin +mSTRenderKit.release() +``` + +调用 `RtcEngine` 的 `destroy` 销毁 `RtcEngine`。 + +```kotlin +RtcEngine.destroy() +``` + + +### API 时序图 + +![](https://web-cdn.agora.io/docs-files/1693553307432) \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_integration_sensetime_ios.md" "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_integration_sensetime_ios.md" new file mode 100644 index 00000000000..ca79fc90615 --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_integration_sensetime_ios.md" @@ -0,0 +1,312 @@ +本文介绍如何通过声网美颜场景化 API (Beauty API) 集成商汤美颜到实时音视频互动中。 + +## 示例项目 + +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/1.0.1.1) 示例项目供你参考。 + +## 准备开发环境 + +### 前提条件 + +- [Git](https://git-scm.com/downloads) +- [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) +- [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 12.0 及以上 +- iOS 设备,版本 13.0 及以上 +- 有效的苹果开发者账号 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) +- 已联系商汤技术获取最新的美颜 SDK、美颜资源、美颜证书 + + +### 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +跑通示例项目时,你需要将**鉴权机制**设置为**调试模式:APP ID**。从头搭建 Android 项目集成美颜功能时,声网推荐你将**鉴权机制**设置为**安全模式:APP ID + Token**,以保障安全性。 + + +### 创建 iOS 项目 + +在 Xcode 中进行以下操作,在你的 app 中实现场景化美颜功能: + +1. [创建一个新的项目](https://help.apple.com/xcode/mac/current/#/dev07db0e578),**Application** 选择 **App**,**Interface** 选择 **Storyboard**,**Language** 选择 **Swift**。 + +
    如果你没有添加过开发团队信息,会看到 Add account… 按钮。点击该按钮并按照屏幕提示登入 Apple ID,点击 Next,完成后即可选择你的 Apple 账户作为开发团队。
    + +2. 为你的项目设置[自动签名](https://help.apple.com/xcode/mac/current/#/dev23aab79b4)。 + +3. 设置部署你的 app 的[目标设备](https://help.apple.com/xcode/mac/current/#/deve69552ee5)。 + +4. 添加项目的设备权限。在项目导航栏中打开 `info.plist` 文件,编辑[属性列表](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6),添加以下属性: + + | key | type | value | + | -------------------------------------- | ------ | ------------------------------------------------------------ | + | Privacy - Microphone Usage Description | String | 使用麦克风的目的,例如 for a live interactive streaming | + | Privacy - Camera Usage Description | String | 使用摄像头的目的,例如 for a live interactive streaming | + +
    • 如果你的项目中需要添加第三方插件或库(例如第三方摄像头),且该插件或库的签名与项目的签名不一致,你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation
    • 更多注意事项,可以参考 Preparing Your App for Distribution
    + +5. 将商汤美颜 SDK 集成到你的项目中。请联系商汤技术支持获取美颜 SDK、美颜资源、证书等文件。下载并解压文件,然后添加到美颜项目对应的文件路径下: + + | 文件 | 项目路径 | + |------------------|----------------| + | SenseMe/remoteSourcesLib | iOS/SenseLib/remoteSourcesLib | + | SenseMe/st_mobil_sdk | iOS/SenseLib/st_mobile_sdk | + |SenseMe/st_mobil_sdk/license/SENSEME.lic | iOS/SenseLib/SENSEME.lic | + +6. 将声网美颜场景化 API 集成到你的项目中。添加 [iOS/BeautyAPi/BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/1.0.1.1/iOS/BeautyAPi/BeautyAPI) 目录下的文件到项目中,具体文件如下: + + - `Render/SenseRender` 文件夹 + - `SenseRender` 文件夹 + - `BeautyAPI.h` 文件 + - `BeautyAPI.m` 文件 + - `BeautyConfig.h` 文件 + - `BeautyConfig.m` 文件 + +
    为方便后续代码升级,请不要修改你添加的这些文件的名称和路径。
    + +7. 将声网 RTC SDK 和商汤美颜依赖库集成到你的项目。 + + 1. 在终端里进入项目根目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。 + 2. 打开 `Podfile` 文件,修改文件为如下内容。注意将 `Your App` 替换为你的 Target 名称。 + + ```shell + platform :ios, '9.0' + # 替换成你的 target 名称 + target 'Your App' do + # x.y.z 请填写具体的 RTC SDK 版本号,如 4.0.1 或 4.0.0.4 + # 可通过互动直播发版说明获取最新版本号 + pod 'AgoraRtcEngine_iOS', 'x.y.z' + # 配置商汤美颜的依赖库 + pod 'SenseLib', :path => 'sense.podspec' + end + ``` + + +8. 在终端内运行 pod install 命令安装声网 RTC SDK 和商汤美颜依赖。 + +9. 成功安装后,Terminal 中会显示 Pod installation complete!。项目文件夹下会生成一个后缀为 .xcworkspace 的文件,通过 Xcode 打开该文件进行后续操作。 + +## 实现美颜 + +本节展示如何在直播间内实现美颜功能,参考 [API 时序图](#api-时序图)可查看总览。声网 RTC SDK 承担实时音视频的业务,商汤美颜 SDK 提供美颜功能,声网 Beauty API 封装了两个 SDK 中的 API 调用逻辑以简化你需要实现的代码逻辑。通过 Beauty API,你可以实现基础美颜功能,但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。 + +### 1. 初始化 AgoraRtcEngineKit + +调用声网 RTC SDK 中的 `sharedEngineWithConfig` 创建并初始化 `AgoraRtcEngineKit` 对象。调用 `enableVideo` 开启声网 SDK 的视频模块。 + +```swift +// 初始化 AgoraRtcEngineKit +private lazy var rtcEngine: AgoraRtcEngineKit = { + let config = AgoraRtcEngineConfig() + // 传入你从控制台获取的声网项目的 APP ID + config.appId = KeyCenter.AppId + config.channelProfile = .liveBroadcasting + let rtc = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self) + // 设置用户角色为主播,主播可以发送音视频流也可以接收音视频流 + rtc.setClientRole(.broadcaster) + // 开启 SDK 音频模块 + rtc.enableAudio() + // 开启 SDK 视频模块 + rtc.enableVideo() + // 设置默认音频路由为扬声器 + rtc.setDefaultAudioRouteToSpeakerphone(true) + return rtc +}() +``` + +### 2. 初始化美颜和 Beauty API + +创建 SenseBeautyRender 和 Beauty API 对象。Beauty API 对象基于 `SenseBeautyRender` 对象封装。 + + +```swift +private lazy var senseRender = SenseBeautyRender() +private lazy var beautyAPI = BeautyAPI() +``` + + +调用 `initialize` 初始化 Beauty API 对象。你需要在 `config` 参数中传入如下字段: + +- `AgoraRtcEngineKit`:传入之前初始化的 `AgoraRtcEngineKit` 对象。 +- `beautyRender`:传入之前初始化的 `SenseBeautyRender` 对象。 +- `captureMode`:视频的采集模式: + - 如果你使用声网模块采集视频,请传入 `CaptureMode.Agora`。 + - 如果自定义采集视频,请传入 `CaptureMode.Custom`。 +- `statsEnable`:是否开启美颜统计数据回调。`true` 代表开启,`false` 代表不开启。开启后,会有周期性回调事件。 +- `statsDuration`:美颜统计数据回调的周期。单位为秒。 +- `eventCallback`:监听的美颜统计数据回调事件。 + + +```swift +let config = BeautyConfig() +// AgoraRtcEngineKit +config.rtcEngine = rtcEngine +// 设置视频采集模式 +// .agora 意味着使用声网模块采集视频 +// .custom 意味着使用开发者自定义采集视频 +config.captureMode = capture == "Custom" ? .custom : .agora +// SenseBeautyRender +config.beautyRender = senseRender +// 是否开启美颜统计数据 +// 开启后,会有周期性回调事件 +config.statsEnable = false +// 设置美颜统计数据的统计区间为 1 秒(默认) +config.statsDuration = 1 +// Beauty API 的回调事件 +config.eventCallback = { stats in + print("min == \(stats.minCostMs)") + print("max == \(stats.maxCostMs)") + print("averageCostMs == \(stats.averageCostMs)") +} + +// 初始化 Beauty API 对象 +let result = beautyAPI.initialize(config) +if result != 0 { + print("initialize error == \(result)") +} +``` + + +### 3. 开启美颜 + +调用 Beauty API 的 `enable` 方法并将参数设为 `true` 开启美颜。 + +```swift +beautyAPI.enable(true) +``` + +### 4. 开启视频采集 + +开发者可以使用声网模块采集视频,也可以自定义采集视频。本节介绍在这两种场景下如何开启视频采集。 + +#### 使用声网模块采集视频 + +使用声网模块采集视频视频时,调用 Beauty API 的 `setupLocalVideo` 开启本地视图。 + +```swift +beautyAPI.setupLocalVideo(localView, renderMode: .hidden) +``` + + +#### 自定义视频采集 + +自定义视频采集时,你需要通过 `AgoraRtcEngineKit` 类的 `setVideoFrameDelegate` 注册原始视频数据观测器并在其中实现 `onCaptureVideoFrame` 函数。 + +通过 Beauty API 的 `onFrame` 函数,你可以将外部自采集的视频数据传入并进行处理。 + + +```swift +if capture == "Custom" { + // 注册原始视频数据观测器 + // 自定义视频采集时,即 CaptureMode 为 Custom 时,你需要注册原始视频观测器 + rtcEngine.setVideoFrameDelegate(self) +} + +extension BeautyViewController: AgoraVideoFrameDelegate { + func onCapture(_ videoFrame: AgoraOutputVideoFrame, sourceType: AgoraVideoSourceType) -> Bool { + // 将外部自采集的视频数据传入声网 SDK + guard let pixelBuffer = videoFrame.pixelBuffer else { return true } + beautyAPI.onFrame(pixelBuffer) { pixelBuffer in + videoFrame.pixelBuffer = pixelBuffer + } + + return true + } + + // 设置是否对原始视频数据作镜像处理 + func getMirrorApplied() -> Bool { + beautyAPI.isFrontCamera + } + + // 设置观测点为本地采集时的视频数据 + func getObservedFramePosition() -> AgoraVideoFramePosition { + .postCapture + } + + // 实现视频观测器中的其他回调函数 + ... +} +``` + + + +### 5. 加入频道 + +调用 `AgoraRtcEngineKit` 类的 `joinChannelByToken` 加入频道,同时传入如下参数: + +- `token`:用于鉴权的动态密钥。如果在[创建声网项目](#创建声网项目)时启用**调试模式**,那么将 `token` 参数传空。如果启用**安全模式**,那么你先参考[使用 Token 鉴权](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/token_server_ios_ng?platform=iOS)在你的业务服务端生成 Token,然后将生成的 Token 传入该参数。 +- `channelId`:频道名。 +- `mediaOptions`:频道媒体设置选项。 + + + +```swift +let mediaOption = AgoraRtcChannelMediaOptions() +mediaOption.clientRoleType = isBroadcast ? .broadcaster : .audience +// 设置进入频道时是否自动订阅频道内其他用户的音频流 +mediaOption.autoSubscribeAudio = true +// 设置进入频道时是否自动订阅频道内其他用户的视频流 +mediaOption.autoSubscribeVideo = true +// 设置是否发布摄像头采集的视频流(适用于使用声网模块采集视频的情况) +// 用户角色为主播时,设置发布 +// 用户角色为观众时,设置不发布 +mediaOption.publishCameraTrack = mediaOption.clientRoleType == .broadcaster +// 设置是否发布自定义采集的视频流(适用于自定义采集视频的情况) +mediaOption.publishCustomVideoTrack = false +// 设置是否发布麦克风采集的音频流 +// 用户角色为主播时,设置发布 +// 用户角色为观众时,设置不发布 +mediaOption.publishMicrophoneTrack = mediaOption.clientRoleType == .broadcaster + +// 加入频道 +let result = rtcEngine.joinChannel(byToken: nil, channelId: channelName ?? "", uid: 0, mediaOptions: mediaOption) +if result != 0 { + print("join failed") +} +``` + + +### 6. 设置美颜效果 + +调用 Beauty API 中 `setBeautyPreset` 方法设置使用的美颜参数的类型: + +- `BeautyPresetModeDefault`:默认且推荐的美颜参数。 +- `BeautyPresetModeCustom`:开发者自定义的美颜参数。 + +不同的美颜参数会带来不同的美颜效果。如果你没有特殊美颜要求,推荐你使用 `BeautyPresetModeDefault`。 + +```swift +beautyAPI.setBeautyPreset(.default) +``` + +
    通过 Beauty API 的 setBeautyPreset 方法,你可以实现基础美颜功能。但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。
    + +### 7. 离开频道 + +调用 `AgoraRtcEngineKit` 类的 `leaveChannel` 离开频道。 + +```swift +rtcEngine.leaveChannel() +``` + + +### 8. 销毁资源 + +调用 Beauty API 的 `destory` 销毁 Beauty API。 + +```swift +beautyAPI.destory() +``` + +
    Beauty API 1.0.1.1 版中 destory方法的命名存在笔误,会在 1.0.2 版本修正。
    + +调用 `AgoraRtcEngineKit` 的 `destroy` 销毁 `AgoraRtcEngineKit`。 + +```swift +AgoraRtcEngineKit.destroy() +``` + + +### API 时序图 + +![](https://web-cdn.agora.io/docs-files/1693553315915) \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_run_github_project_sensetime_android.md" "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_run_github_project_sensetime_android.md" new file mode 100644 index 00000000000..9e88c67abd9 --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_run_github_project_sensetime_android.md" @@ -0,0 +1,78 @@ +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/1.0.1.1) 示例项目供你参考。本文介绍如何快速跑通该示例项目,体验商汤美颜效果。 + +## 前提条件 + +- [Git](https://git-scm.com/downloads) +- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 11 +- [Android Studio](https://developer.android.com/studio/) 3.5 及以上 +- Android 手机,版本 Android 5.0(API Level 21)及以上 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) + +
    声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。
    + + +## 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + + +## 克隆仓库 + +运行以下命令克隆仓库到本地: + +```shell +git clone git@github.com:AgoraIO-Community/BeautyAPI.git +``` + +## 集成第三方美颜 SDK + +1. 联系商汤技术支持获取最新的美颜 SDK、美颜资源、美颜证书。 + +2. 下载并解压美颜 SDK,然后将 SDK 中如下文件添加到美颜示例项目对应的文件路径下: + + | SDK 文件 | 项目路径 | + |--------------------------------------------------------------------|------------------------------------------------------| + | Android/models | app/src/main/assets/beauty_sensetime/models | + | Android/sample/SenseMeEffects/app/src/main/assets/sticker_face_shape | app/src/main/assets/beauty_sensetime/sticker_face_shape | + | Android/sample/SenseMeEffects/app/src/main/assets/style_lightly | app/src/main/assets/beauty_sensetime/style_lightly | + | Android/sample/SenseMeEffects/app/src/main/assets/makeup_lip | app/src/main/assets/beauty_sensetime/makeup_lip | + | SenseME.lic | app/src/main/assets/beauty_sensetime/license/SenseME.lic | + + +3. 在 `app/build.gradle` 文件中,将 `applicationId` 修改为你的包名,例如 `com.example.app`。包名用于在设备上唯一标识应用程序。在开发应用时,你需要设置包名。在此处设置的包名需要与你申请美颜 SDK 时提供的包名一致。 + + ```java + android { + defaultConfig { + applicationId "io.agora.entfull" + ... + } + } + ``` + +## 配置示例项目 + +运行美颜项目前,你需要在 `local.properties` 文件中添加并设置如下参数: + +```shell +AGORA_APP_ID = "YOUR_APP_ID" +``` + +你可以在[创建声网项目](#create)后,从控制台获取参数的值,详情如下: + +| 参数 | 描述 | 获取方式 | +|----|----|----| +| `AGORA_APP_ID` | 声网项目的 App ID | [获取 App ID](https://docportal.shengwang.cn/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#获取-app-id) | + + +## 编译并运行示例项目 + +1. 开启 Android 设备的开发者选项,打开 USB 调试,通过 USB 连接线将 Android 设备接入电脑。 + +2. 用 Android Studio 打开 `BeautyAPI/Android` 文件夹。 + +3. 在 Android Studio 中,点击 **Sync Project with Gradle Files** 按钮,让项目与 Gradle 文件同步。 + +4. 待同步成功后,点击 `Run 'app'`。片刻后,美颜应用便会安装到你的 Android 设备上。 + +5. 打开美颜应用,进行体验。 diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_run_github_project_sensetime_ios.md" "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_run_github_project_sensetime_ios.md" new file mode 100644 index 00000000000..995d09e1c2d --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/beauty_run_github_project_sensetime_ios.md" @@ -0,0 +1,71 @@ +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/1.0.1.1) 示例项目供你参考。本文介绍如何快速跑通该示例项目,体验商汤美颜效果。 + +## 前提条件 + +- [Git](https://git-scm.com/downloads) +- [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) +- [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 13.0 及以上 +- iOS 设备,版本 11.0 及以上 +- 有效的苹果开发者账号 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) + +
    声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。
    + + +## 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +## 克隆仓库 + +运行以下命令克隆仓库到本地: + +```shell +git clone git@github.com:AgoraIO-Community/BeautyAPI.git +``` + +## 集成第三方美颜 SDK + +1. 联系商汤技术支持获取最新的美颜 SDK、美颜资源、美颜证书。 + +2. 下载并解压美颜 SDK 等文件,然后将如下文件添加到美颜示例项目对应的文件路径下: + + | 文件 | 项目路径 | + |-----|-----| + | SenseMe/remoteSourcesLib | iOS/SenseLib/remoteSourcesLib | + | SenseMe/st_mobil_sdk | iOS/SenseLib/st_mobile_sdk | + |SenseMe/st_mobil_sdk/license/SENSEME.lic | iOS/SenseLib/SENSEME.lic | + + + +## 配置示例项目 + +1. 运行美颜项目前,你需要在 `iOS/BeautyAPi/KeyCenter.swift` 文件中设置如下参数: + + ```swift + static let AppId: String = <#YOUR_APP_ID#> + ``` + + 你可以在[创建声网项目](#create)后,从控制台获取这些参数的值,详情如下: + + | 参数 | 描述 | 获取方式 | + |----|----|----| + | `AppId` | 声网项目的 App ID | [获取 App ID](https://docportal.shengwang.cn/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#获取-app-id) | + + +2. 在 `iOS/` 目录下运行 `pod install`,然后等待依赖库安装完成。 + + +## 编译并运行示例项目 + +![](https://web-cdn.agora.io/docs-files/1690276905446) + +1. 连接上 iOS 设备后,点击 `BeautyAPi.xcodeproj` 文件以通过 Xcode 打开项目,并在 **iOS Device** 选项中勾选上你的 iOS 设备。 + +2. 在项目 **TARGETS** 下的 **Signing & Capabilities** 界面勾选 **Automatically manage signing**,配置你的苹果开发者账号和 **Bundle Identifier**。Bundle ID 是设备上应用程序的唯一标识。在开发应用时,你需要设置 Bundle ID。在此处设置的 Bundle ID 需要与你申请商汤美颜 SDK 时提供的 Bundle ID 一致。 + +3. 点击 开始编译。 + +4. 编译成功后,你的 iOS 设备上会出现美颜应用。在 iOS 系统设置中将该应用设为信任开发者后你才能打开应用。 + +5. 打开美颜应用,进行体验。 \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/iOS.wsd" "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/iOS.wsd" new file mode 100644 index 00000000000..36f42ca842f --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/iOS.wsd" @@ -0,0 +1,44 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "商汤美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 AgoraRtcEngineKit == +app -> rtc: sharedEngineWithConfig \n创建并初始化 AgoraRtcEngineKit 对象 +== 初始化美颜 SDK == +app -> beauty: 创建并初始化 SenseBeautyRender +== 初始化 Beauty API == +app -> api: 创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +app -> rtc: enableVideo \n开启视频模块 +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: setVideoFrameDelegate \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannelByToken +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: destory \n销毁 Beauty API 对象 +app -> rtc: destroy \n销毁 AgoraRtcEngineKit 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/\345\225\206\346\261\244Androidv1.0.1.1\346\227\266\345\272\217\345\233\276.wsd" "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/\345\225\206\346\261\244Androidv1.0.1.1\346\227\266\345\272\217\345\233\276.wsd" new file mode 100644 index 00000000000..3d52716bbd4 --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/\345\225\206\346\261\244Androidv1.0.1.1\346\227\266\345\272\217\345\233\276.wsd" @@ -0,0 +1,45 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "商汤美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 RtcEngine == +app -> rtc: RtcEngine.create \n创建并初始化 RtcEngine 对象 +== 初始化美颜 SDK == +app -> beauty: 创建并初始化 STRenderKit +== 初始化 Beauty API == +app -> api: createSenseTimeBeautyAPI \n创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +app -> rtc: enableVideo \n开启视频模块 +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: registerVideoFrameObserver \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannel +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: release \n销毁 Beauty API 对象 +app -> beauty: release \n销毁 STRenderKit +app -> rtc: destroy \n销毁 RtcEngine 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/\345\225\206\346\261\244iOSv1.0.1.1\346\227\266\345\272\217\345\233\276.wsd" "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/\345\225\206\346\261\244iOSv1.0.1.1\346\227\266\345\272\217\345\233\276.wsd" new file mode 100644 index 00000000000..36f42ca842f --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.1.1/\345\225\206\346\261\244iOSv1.0.1.1\346\227\266\345\272\217\345\233\276.wsd" @@ -0,0 +1,44 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "商汤美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 AgoraRtcEngineKit == +app -> rtc: sharedEngineWithConfig \n创建并初始化 AgoraRtcEngineKit 对象 +== 初始化美颜 SDK == +app -> beauty: 创建并初始化 SenseBeautyRender +== 初始化 Beauty API == +app -> api: 创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +app -> rtc: enableVideo \n开启视频模块 +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: setVideoFrameDelegate \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannelByToken +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: destory \n销毁 Beauty API 对象 +app -> rtc: destroy \n销毁 AgoraRtcEngineKit 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.2/beauty_integration_sensetime_android.md" "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/beauty_integration_sensetime_android.md" new file mode 100644 index 00000000000..9caec7b5eb6 --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/beauty_integration_sensetime_android.md" @@ -0,0 +1,410 @@ +本文介绍如何通过声网美颜场景化 API (Beauty API) 集成商汤美颜到实时音视频互动中。 + +## 示例项目 + +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main) 示例项目供你参考。 + +## 准备开发环境 + +### 前提条件 + +- [Git](https://git-scm.com/downloads) +- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 11 +- [Android Studio](https://developer.android.com/studio/) 3.5 及以上 +- Android 手机,版本 Android 5.0(API Level 21)及以上 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) +- 已联系商汤技术获取最新的美颜 SDK、美颜资源、美颜证书 +- 已在项目中添加 Kotlin 插件 + +### 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +跑通示例项目时,你需要将**鉴权机制**设置为**调试模式:APP ID**。从头搭建 Android 项目集成美颜功能时,声网推荐你将**鉴权机制**设置为**安全模式:APP ID + Token**,以保障安全性。 + + +### 创建 Android 项目 + +按照以下步骤准备开发环境: + +1. 如需创建新项目,在 **Android Studio** 里,依次选择 **Phone and Tablet > Empty Activity**,创建 [Android 项目](https://developer.android.com/studio/projects/create-project)。 + +
    创建项目后,Android Studio 会自动开始同步 gradle, 稍等片刻至同步成功后再进行下一步操作。
    + +2. 使用 Maven Central 将声网 RTC SDK 集成到你的项目中。 + + a. 在 `/Gradle Scripts/build.gradle(Project: )` 文件中添加如下代码,添加 Maven Central 依赖: + + ```java + buildscript { + repositories { + ... + mavenCentral() + } + ... + } + + allprojects { + repositories { + ... + mavenCentral() + } + } + ``` + +
    如果你的 Android 项目设置了 dependencyResolutionManagement,添加 Maven Central 依赖的方式可能存在差异。
    + + b. 在 `/Gradle Scripts/build.gradle(Module: .app)` 文件中添加如下代码,将声网 RTC SDK 集成到你的 Android 项目中: + + ```java + ... + dependencies { + ... + // x.y.z,请填写具体的 RTC SDK 版本号,如:4.0.0 或 4.1.0-1。 + // 通过互动直播产品发版说明获取最新版本号。 + implementation 'io.agora.rtc:full-sdk:x.y.z' + } + ``` + +3. 将商汤美颜 SDK 集成到你的项目中。请联系商汤技术支持获取美颜 SDK、美颜资源、证书等文件。下载并解压文件,然后添加到美颜项目对应的文件路径下: + + | 文件 | 项目路径 | + |--------------------------------------------------------------------|------------------------------------------------------| + | Android/models | app/src/main/assets/beauty_sensetime/models | + | Android/sample/SenseMeEffects/app/src/main/assets/sticker_face_shape | app/src/main/assets/beauty_sensetime/sticker_face_shape | + | Android/sample/SenseMeEffects/app/src/main/assets/style_lightly | app/src/main/assets/beauty_sensetime/style_lightly | + | Android/sample/SenseMeEffects/app/src/main/assets/makeup_lip | app/src/main/assets/beauty_sensetime/makeup_lip | + | SenseME.lic | app/src/main/assets/beauty_sensetime/license/SenseME.lic | + + +4. 将声网美颜场景化 API 集成到你的项目中。添加 [Android/lib_sensetime/src/main/java/io/agora/beautyapi/sensetime](https://github.com/AgoraIO-Community/BeautyAPI/tree/main/Android/lib_sensetime/src/main/java/io/agora/beautyapi/sensetime) 目录下的文件到项目中,具体文件如下: + - `utils` 文件夹 + - `SenseTimeBeautyAPI.kt` 文件 + - `SenseTimeBeautyAPIImpl.kt` 文件 + +
    为方便后续代码升级,请不要修改你添加的这些文件的名称和路径。
    + +5. 添加网络及设备权限。 + + 在 `/app/Manifests/AndroidManifest.xml` 文件中,在 `` 后面添加如下权限: + + ```xml + + + + + + + + + + + + + ``` + +5. 在 `/Gradle Scripts/proguard-rules.pro` 文件中添加如下行,以防止声网 SDK 的代码被混淆: + + ```java + -keep class io.agora.**{*;} + -dontwarn javax.** + -dontwarn com.google.devtools.build.android.** + ``` + +## 实现美颜 + +本节展示如何在直播间内实现美颜功能,参考 [API 时序图](#api-时序图)可查看总览。声网 RTC SDK 承担实时音视频的业务,商汤美颜 SDK 提供美颜功能,声网 Beauty API 封装了两个 SDK 中的 API 调用逻辑以简化你需要实现的代码逻辑。通过 Beauty API,你可以实现基础美颜功能,但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。 + +### 1. 初始化 RtcEngine + +调用声网 RTC SDK 中的 `create` 创建并初始化 `RtcEngine` 对象。 + +```kotlin +// 初始化声网 RtcEngine +private val mRtcEngine by lazy { + RtcEngine.create(RtcEngineConfig().apply { + mContext = applicationContext + // 传入你从控制台获取的声网项目的 APP ID + mAppId = BuildConfig.AGORA_APP_ID + mEventHandler = object : IRtcEngineEventHandler() {} + }).apply { + // 开启声网 clear_vision 高清视频插件 + enableExtension("agora_video_filters_clear_vision", "clear_vision", true) + } +} +``` + +### 2. 初始化美颜 SDK + +在新线程中调用美颜 SDK 的 `initBeautySDK` 初始化美颜。其中包含如下方法: + +- `checkLicense`:读取本地 `SenseMe.lic` 证书文件,并通过 `generateActiveCodeFromBuffer` 方法生成 `activeCode`。通过 `activeCode` 进行验证,验证成功后才可以使用商汤美颜 SDK。 +- `initHumanAction`:初始化 `STMobileHumanActionNative` 实例,用于人物识别。`STMobileHumanActionNative` 句柄可以全局使用。 + +```kotlin +private val workerThread = Executors.newSingleThreadExecutor() + +// 通过在新线程中调用 checkLicense 和 initHumanAction 来初始化美颜 SDK +fun initBeautySDK(context: Context){ + workerThread.submit { + checkLicense(context) + initHumanAction(context) + } +} +``` + +```kotlin +// 传入 SenseME.lic 文件,通过 generate 方法生成 activeCode 并对其进行验证 +private fun checkLicense(context: Context) { + val license = io.agora.beautyapi.demo.utils.FileUtils.getAssetsString( + context, + "$resourcePath/license/SenseME.lic" + ) + val activeCode = STMobileAuthentificationNative.generateActiveCodeFromBuffer( + context, + license, + license.length + ) + val success = activeCode.isNotEmpty() + if (success) { + Log.d(TAG, "SenseTime >> checkLicense successfully!") + } else { + Log.e(TAG, "SenseTime >> checkLicense failed!") + } +} +``` + +```kotlin +// 初始化 STMobileHumanActionNative,用于进行人物动作识别、躯干分割、人脸网格化识别等 +private fun initHumanAction(context: Context){ + val assets = context.assets + val result = humanActionNative.createInstanceFromAssetFile( + "$resourcePath/$MODEL_106", + humanActionCreateConfig, + assets + ) + Log.d(TAG, "SenseTime >> STMobileHumanActionNative create result : $result") + + if(result != 0){ + return + } + + // 添加一些子模型,用于进行更精细的识别 + humanActionNative.addSubModelFromAssetFile("$resourcePath/$MODEL_HAND", assets) + ... + + // 对背景虚化、人脸网格化识别、躯干分割等功能进行参数配置 + humanActionNative.setParam(STHumanActionParamsType.ST_HUMAN_ACTION_PARAM_BACKGROUND_BLUR_STRENGTH, 0.35f) + ... +} +``` + +调用美颜 SDK 的 `initMobileEffect` 初始化 `STMobileEffectNative` 实例,用于管理视频特效。 + +`STMobileEffectNative` 句柄不能在全局使用,只能在一个 GL 环境里使用。如果切换 GL 环境,你需要在新环境里重新创建一个 `STMobileEffectNative` 实例。 + + +```kotlin +// 初始化 STMobileEffectNative,用于管理视频特效 +// STMobileEffectNative 不能全局使用,只能在一个 GL 环境里使用 +// 切换 GL 环境时需要重新创建一个 STMobileEffectNative +fun initMobileEffect(context: Context){ + val result = + mobileEffectNative.createInstance(context, STMobileEffectNative.EFFECT_CONFIG_NONE) + // 设置视频特效渲染的平滑处理参数 + mobileEffectNative.setParam(STMobileEffectParams.EFFECT_PARAM_QUATERNION_SMOOTH_FRAME, 5f) + Log.d(TAG, "SenseTime >> STMobileEffectNative create result : $result") +} +``` + +### 3. 初始化 Beauty API + +调用 `createSenseTimeBeautyAPI` 创建 Beauty API 对象。Beauty API 对象基于 `STMobileHumanActionNative` 和 `STMobileEffectNative` 对象封装。 + +```kotlin +// 创建 Beauty API 对象 +private val mSenseTimeApi by lazy { + createSenseTimeBeautyAPI() +} +``` + +调用 `initialize` 初始化 Beauty API 对象。你需要在 `config` 参数中传入如下字段: + +- `application`:传入 Android Context(上下文)。 +- `mRtcEngine`:传入之前初始化的 `RtcEngine` 对象。 +- `STHandlers`:商汤美颜 SDK 的句柄,需要传入之前初始化的 `STMobileHumanActionNative` 和 `STMobileEffectNative` 对象。 +- `captureMode`:视频的采集模式: + - 如果你使用声网模块采集视频,请传入 `CaptureMode.Agora`。 + - 如果自定义采集视频,请传入 `CaptureMode.Custom`。 +- `statsEnable`:是否开启美颜统计数据回调。`true` 代表开启,`false` 代表不开启。开启后,会有周期性的 `onBeautyStats` 回调事件。 +- `statsDuration`:美颜统计数据回调的周期。单位为毫秒。 +- `cameraConfig`:设置视频镜像模式。如果在初始化 Beauty API 后你想修改镜像模式,可以调用 Beauty API 的 `updateCameraConfig`。 +- `eventCallback`:你希望监听的回调事件。 + +```kotlin +// 初始化 Beauty API 对象 +mSenseTimeApi.initialize( + Config( + // Android Context(上下文) + application, + // RtcEngine + mRtcEngine, + // 商汤美颜 SDK 的句柄 + STHandlers(SenseTimeBeautySDK.mobileEffectNative, SenseTimeBeautySDK.humanActionNative), + // 设置视频采集模式 + // CaptureMode.Agora 意味着使用声网模块采集视频 + // CaptureMode.Custom 意味着使用开发者自定义采集视频 + captureMode = if (isCustomCaptureMode) CaptureMode.Custom else CaptureMode.Agora, + // 配置视频镜像模式 + cameraConfig = CameraConfig, + // 是否开启美颜统计数据 + // 开启后,会有周期性的 onBeautyStats 回调事件 + statsEnable = true, + // 设置美颜统计数据的统计区间为 1000 毫秒(默认) + statsDuration = 1000, + // 用于监听 Beauty API 的回调事件 + eventCallback = object: IEventCallback{ + override fun onBeautyStats(stats: BeautyStats) { + Log.d(TAG, "BeautyStats stats = $stats") + } + } + ) +) +``` + +### 4. 开启美颜 + +调用 Beauty API 的 `enable` 方法并将参数设为 `true` 开启美颜。 + +```kotlin +mSenseTimeApi.enable(true) +``` + +### 5. 开启视频采集 + +开发者可以使用声网模块采集视频,也可以自定义采集视频。本节介绍在这两种场景下如何开启视频采集。 + +#### 使用声网模块采集视频 + +使用声网模块采集视频视频时,你需要先调用 `RtcEngine` 类的 `enableVideo` 开启声网 SDK 的视频模块,然后调用 Beauty API 的 `setupLocalVideo` 开启本地视图。 + +```kotlin +// 开启视频模块 +mRtcEngine.enableVideo() +// 设置本地视图 +mSenseTimeApi.setupLocalVideo(mBinding.localVideoView, Constants.RENDER_MODE_FIT) +``` + +#### 自定义视频采集 + +自定义视频采集时,你需要先调用 `RtcEngine` 类的 `enableVideo` 开启声网 SDK 的视频模块,然后通过 `RtcEngine` 类的 `registerVideoFrameObserver` 注册原始视频数据观测器并在其中实现 `onCaptureVideoFrame` 函数。 + +通过 Beauty API 的 `onFrame` 函数,你可以将外部自采集的视频数据传入并进行处理。当处理结果不为 `SKIPPED`(忽略)时,用自采集的视频数据替代 `onCaptureVideoFrame` 函数中的 `VideoFrame`,并传入声网 SDK。 + + +```kotlin +// 开启视频模块 +mRtcEngine.enableVideo() +// 注册原始视频数据观测器 +// 自定义视频采集时,即 CaptureMode 为 Custom 时,你需要注册原始视频观测器 +mRtcEngine.registerVideoFrameObserver(object : IVideoFrameObserver { + + override fun onCaptureVideoFrame( + sourceType: Int, + videoFrame: VideoFrame? + ) : Boolean { + return when(mSenseTimeApi.onFrame(videoFrame!!)){ + // 当处理结果为 SKIPPED(忽略)时,代表你丢帧,即外部自采集的视频数据不传入声网 SDK + // 当处理结果为其他时,外部自采集的视频数据传入声网 SDK + ErrorCode.ERROR_FRAME_SKIPPED.value -> false + else -> true + } + } + + // 设置是否对原始视频数据作镜像处理 + override fun getMirrorApplied() = mSenseTimeApi.getMirrorApplied() + + // 设置观测点为本地采集时的视频数据 + override fun getObservedFramePosition() = IVideoFrameObserver.POSITION_POST_CAPTURER + + // override 视频观测器中的其他回调函数 + ... +}) +``` + + +### 6. 加入频道 + +调用 `RtcEngine` 类的 `joinChannel` 加入频道,同时传入如下参数: + +- `token`:用于鉴权的动态密钥。如果在[创建声网项目](#创建声网项目)时启用**调试模式**,那么将 `token` 参数传空。如果启用**安全模式**,那么你先参考[使用 Token 鉴权](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/token_server_android_ng?platform=Android)在你的业务服务端生成 Token,然后将生成的 Token 传入该参数。 +- `channelId`:频道名。 +- `options`:频道媒体设置选项。 + + +```kotlin +mRtcEngine.joinChannel(null, mChannelName, 0, ChannelMediaOptions().apply { + // 设置频道场景为直播 + channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING + // 设置用户角色为主播,主播可以在频道里发布和订阅音视频流 + clientRoleType = Constants.CLIENT_ROLE_BROADCASTER + // 设置是否发布摄像头采集的视频流(适用于使用声网模块采集视频的情况) + publishCameraTrack = true + // 设置是否发布自定义采集的视频流(适用于自定义采集视频的情况) + publishCustomVideoTrack = false + // 设置是否发布麦克风采集的音频流 + publishMicrophoneTrack = false + // 设置进入频道时是否自动订阅频道内其他用户的音频流 + autoSubscribeAudio = false + // 设置进入频道时是否自动订阅频道内其他用户的视频流 + autoSubscribeVideo = true +}) +``` + +### 7. 设置美颜效果 + +调用 Beauty API 中 `setBeautyPreset` 方法设置使用的美颜参数的类型: + +- `DEFAULT`:默认且推荐的美颜参数。 +- `CUSTOM`:开发者自定义的美颜参数。 + +不同的美颜参数会带来不同的美颜效果。如果你没有特殊美颜要求,推荐你使用 `DEFAULT`。 + +```kotlin +mSenseTimeApi.setBeautyPreset(if (enable) BeautyPreset.DEFAULT else BeautyPreset.CUSTOM) +``` + +
    通过 Beauty API 的 setBeautyPreset 方法,你可以实现基础美颜功能。但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。
    + +### 8. 离开频道 + +调用 `RtcEngine` 类的 `leaveChannel` 离开频道。 + +```kotlin +mRtcEngine.leaveChannel() +``` + +### 9. 销毁资源 + +调用 Beauty API 的 `release` 销毁 Beauty API。 + +```kotlin +mSenseTimeApi.release() +``` + +调用美颜 SDK 的 `unInitMobileEffect` 销毁 `STMobileEffectNative`。 + +```kotlin +SenseTimeBeautySDK.unInitMobileEffect() +``` + +调用 `RtcEngine` 的 `destroy` 销毁 `RtcEngine`。 + +```kotlin +RtcEngine.destroy() +``` + + +### API 时序图 + +![](https://web-cdn.agora.io/docs-files/1692947832362) \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.2/beauty_integration_sensetime_ios.md" "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/beauty_integration_sensetime_ios.md" new file mode 100644 index 00000000000..e140ccbf340 --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/beauty_integration_sensetime_ios.md" @@ -0,0 +1,312 @@ +本文介绍如何通过声网美颜场景化 API (Beauty API) 集成商汤美颜到实时音视频互动中。 + +## 示例项目 + +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main) 示例项目供你参考。 + +## 准备开发环境 + +### 前提条件 + +- [Git](https://git-scm.com/downloads) +- [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) +- [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 12.0 及以上 +- iOS 设备,版本 13.0 及以上 +- 有效的苹果开发者账号 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) +- 已联系商汤技术获取最新的美颜 SDK、美颜资源、美颜证书 + + +### 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +跑通示例项目时,你需要将**鉴权机制**设置为**调试模式:APP ID**。从头搭建 Android 项目集成美颜功能时,声网推荐你将**鉴权机制**设置为**安全模式:APP ID + Token**,以保障安全性。 + + +### 创建 iOS 项目 + +在 Xcode 中进行以下操作,在你的 app 中实现场景化美颜功能: + +1. [创建一个新的项目](https://help.apple.com/xcode/mac/current/#/dev07db0e578),**Application** 选择 **App**,**Interface** 选择 **Storyboard**,**Language** 选择 **Swift**。 + +
    如果你没有添加过开发团队信息,会看到 Add account… 按钮。点击该按钮并按照屏幕提示登入 Apple ID,点击 Next,完成后即可选择你的 Apple 账户作为开发团队。
    + +2. 为你的项目设置[自动签名](https://help.apple.com/xcode/mac/current/#/dev23aab79b4)。 + +3. 设置部署你的 app 的[目标设备](https://help.apple.com/xcode/mac/current/#/deve69552ee5)。 + +4. 添加项目的设备权限。在项目导航栏中打开 `info.plist` 文件,编辑[属性列表](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6),添加以下属性: + + | key | type | value | + | -------------------------------------- | ------ | ------------------------------------------------------------ | + | Privacy - Microphone Usage Description | String | 使用麦克风的目的,例如 for a live interactive streaming | + | Privacy - Camera Usage Description | String | 使用摄像头的目的,例如 for a live interactive streaming | + +
    • 如果你的项目中需要添加第三方插件或库(例如第三方摄像头),且该插件或库的签名与项目的签名不一致,你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation
    • 更多注意事项,可以参考 Preparing Your App for Distribution
    + +5. 将商汤美颜 SDK 集成到你的项目中。请联系商汤技术支持获取美颜 SDK、美颜资源、证书等文件。下载并解压文件,然后添加到美颜项目对应的文件路径下: + + | 文件 | 项目路径 | + |------------------|----------------| + | SenseMe/remoteSourcesLib | iOS/SenseLib/remoteSourcesLib | + | SenseMe/st_mobil_sdk | iOS/SenseLib/st_mobile_sdk | + |SenseMe/st_mobil_sdk/license/SENSEME.lic | iOS/SenseLib/SENSEME.lic | + +6. 将声网美颜场景化 API 集成到你的项目中。添加 [iOS/BeautyAPi/BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/1.0.1.1/iOS/BeautyAPi/BeautyAPI) 目录下的文件到项目中,具体文件如下: + + - `Render/SenseRender` 文件夹 + - `SenseRender` 文件夹 + - `BeautyAPI.h` 文件 + - `BeautyAPI.m` 文件 + - `BeautyConfig.h` 文件 + - `BeautyConfig.m` 文件 + +
    为方便后续代码升级,请不要修改你添加的这些文件的名称和路径。
    + +7. 将声网 RTC SDK 和商汤美颜依赖库集成到你的项目。 + + 1. 在终端里进入项目根目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。 + 2. 打开 `Podfile` 文件,修改文件为如下内容。注意将 `Your App` 替换为你的 Target 名称。 + + ```shell + platform :ios, '9.0' + # 替换成你的 target 名称 + target 'Your App' do + # x.y.z 请填写具体的 RTC SDK 版本号,如 4.0.1 或 4.0.0.4 + # 可通过互动直播发版说明获取最新版本号 + pod 'AgoraRtcEngine_iOS', 'x.y.z' + # 配置商汤美颜的依赖库 + pod 'SenseLib', :path => 'sense.podspec' + end + ``` + + +8. 在终端内运行 pod install 命令安装声网 RTC SDK 和商汤美颜依赖。 + +9. 成功安装后,Terminal 中会显示 Pod installation complete!。项目文件夹下会生成一个后缀为 .xcworkspace 的文件,通过 Xcode 打开该文件进行后续操作。 + +## 实现美颜 + +本节展示如何在直播间内实现美颜功能,参考 [API 时序图](#api-时序图)可查看总览。声网 RTC SDK 承担实时音视频的业务,商汤美颜 SDK 提供美颜功能,声网 Beauty API 封装了两个 SDK 中的 API 调用逻辑以简化你需要实现的代码逻辑。通过 Beauty API,你可以实现基础美颜功能,但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。 + +### 1. 初始化 AgoraRtcEngineKit + +调用声网 RTC SDK 中的 `sharedEngineWithConfig` 创建并初始化 `AgoraRtcEngineKit` 对象。调用 `enableVideo` 开启声网 SDK 的视频模块。 + +```swift +// 初始化 AgoraRtcEngineKit +private lazy var rtcEngine: AgoraRtcEngineKit = { + let config = AgoraRtcEngineConfig() + // 传入你从控制台获取的声网项目的 APP ID + config.appId = KeyCenter.AppId + config.channelProfile = .liveBroadcasting + let rtc = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self) + // 设置用户角色为主播,主播可以发送音视频流也可以接收音视频流 + rtc.setClientRole(.broadcaster) + // 开启 SDK 音频模块 + rtc.enableAudio() + // 开启 SDK 视频模块 + rtc.enableVideo() + // 设置默认音频路由为扬声器 + rtc.setDefaultAudioRouteToSpeakerphone(true) + return rtc +}() +``` + +### 2. 初始化美颜和 Beauty API + +创建 SenseBeautyRender 和 Beauty API 对象。Beauty API 对象基于 `SenseBeautyRender` 对象封装。 + + +```swift +private lazy var senseRender = SenseBeautyRender() +private lazy var beautyAPI = BeautyAPI() +``` + + +调用 `initialize` 初始化 Beauty API 对象。你需要在 `config` 参数中传入如下字段: + +- `AgoraRtcEngineKit`:传入之前初始化的 `AgoraRtcEngineKit` 对象。 +- `beautyRender`:传入之前初始化的 `SenseBeautyRender` 对象。 +- `captureMode`:视频的采集模式: + - 如果你使用声网模块采集视频,请传入 `CaptureMode.Agora`。 + - 如果自定义采集视频,请传入 `CaptureMode.Custom`。 +- `statsEnable`:是否开启美颜统计数据回调。`true` 代表开启,`false` 代表不开启。开启后,会有周期性回调事件。 +- `statsDuration`:美颜统计数据回调的周期。单位为秒。 +- `eventCallback`:监听的美颜统计数据回调事件。 + + +```swift +let config = BeautyConfig() +// AgoraRtcEngineKit +config.rtcEngine = rtcEngine +// 设置视频采集模式 +// .agora 意味着使用声网模块采集视频 +// .custom 意味着使用开发者自定义采集视频 +config.captureMode = capture == "Custom" ? .custom : .agora +// SenseBeautyRender +config.beautyRender = senseRender +// 是否开启美颜统计数据 +// 开启后,会有周期性回调事件 +config.statsEnable = false +// 设置美颜统计数据的统计区间为 1 秒(默认) +config.statsDuration = 1 +// Beauty API 的回调事件 +config.eventCallback = { stats in + print("min == \(stats.minCostMs)") + print("max == \(stats.maxCostMs)") + print("averageCostMs == \(stats.averageCostMs)") +} + +// 初始化 Beauty API 对象 +let result = beautyAPI.initialize(config) +if result != 0 { + print("initialize error == \(result)") +} +``` + + +### 3. 开启美颜 + +调用 Beauty API 的 `enable` 方法并将参数设为 `true` 开启美颜。 + +```swift +beautyAPI.enable(true) +``` + +### 4. 开启视频采集 + +开发者可以使用声网模块采集视频,也可以自定义采集视频。本节介绍在这两种场景下如何开启视频采集。 + +#### 使用声网模块采集视频 + +使用声网模块采集视频视频时,调用 Beauty API 的 `setupLocalVideo` 开启本地视图。 + +```swift +beautyAPI.setupLocalVideo(localView, renderMode: .hidden) +``` + + +#### 自定义视频采集 + +自定义视频采集时,你需要通过 `AgoraRtcEngineKit` 类的 `setVideoFrameDelegate` 注册原始视频数据观测器并在其中实现 `onCaptureVideoFrame` 函数。 + +通过 Beauty API 的 `onFrame` 函数,你可以将外部自采集的视频数据传入并进行处理。 + + +```swift +if capture == "Custom" { + // 注册原始视频数据观测器 + // 自定义视频采集时,即 CaptureMode 为 Custom 时,你需要注册原始视频观测器 + rtcEngine.setVideoFrameDelegate(self) +} + +extension BeautyViewController: AgoraVideoFrameDelegate { + func onCapture(_ videoFrame: AgoraOutputVideoFrame, sourceType: AgoraVideoSourceType) -> Bool { + // 将外部自采集的视频数据传入声网 SDK + guard let pixelBuffer = videoFrame.pixelBuffer else { return true } + beautyAPI.onFrame(pixelBuffer) { pixelBuffer in + videoFrame.pixelBuffer = pixelBuffer + } + + return true + } + + // 设置是否对原始视频数据作镜像处理 + func getMirrorApplied() -> Bool { + beautyAPI.getMirrorApplied() + } + + // 设置观测点为本地采集时的视频数据 + func getObservedFramePosition() -> AgoraVideoFramePosition { + .postCapture + } + + // 实现视频观测器中的其他回调函数 + ... +} +``` + + + +### 5. 加入频道 + +调用 `AgoraRtcEngineKit` 类的 `joinChannelByToken` 加入频道,同时传入如下参数: + +- `token`:用于鉴权的动态密钥。如果在[创建声网项目](#创建声网项目)时启用**调试模式**,那么将 `token` 参数传空。如果启用**安全模式**,那么你先参考[使用 Token 鉴权](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/token_server_ios_ng?platform=iOS)在你的业务服务端生成 Token,然后将生成的 Token 传入该参数。 +- `channelId`:频道名。 +- `mediaOptions`:频道媒体设置选项。 + + + +```swift +let mediaOption = AgoraRtcChannelMediaOptions() +mediaOption.clientRoleType = isBroadcast ? .broadcaster : .audience +// 设置进入频道时是否自动订阅频道内其他用户的音频流 +mediaOption.autoSubscribeAudio = true +// 设置进入频道时是否自动订阅频道内其他用户的视频流 +mediaOption.autoSubscribeVideo = true +// 设置是否发布摄像头采集的视频流(适用于使用声网模块采集视频的情况) +// 用户角色为主播时,设置发布 +// 用户角色为观众时,设置不发布 +mediaOption.publishCameraTrack = mediaOption.clientRoleType == .broadcaster +// 设置是否发布自定义采集的视频流(适用于自定义采集视频的情况) +mediaOption.publishCustomVideoTrack = false +// 设置是否发布麦克风采集的音频流 +// 用户角色为主播时,设置发布 +// 用户角色为观众时,设置不发布 +mediaOption.publishMicrophoneTrack = mediaOption.clientRoleType == .broadcaster + +// 加入频道 +let result = rtcEngine.joinChannel(byToken: nil, channelId: channelName ?? "", uid: 0, mediaOptions: mediaOption) +if result != 0 { + print("join failed") +} +``` + + +### 6. 设置美颜效果 + +调用 Beauty API 中 `setBeautyPreset` 方法设置使用的美颜参数的类型: + +- `BeautyPresetModeDefault`:默认且推荐的美颜参数。 +- `BeautyPresetModeCustom`:开发者自定义的美颜参数。 + +不同的美颜参数会带来不同的美颜效果。如果你没有特殊美颜要求,推荐你使用 `BeautyPresetModeDefault`。 + +```swift +beautyAPI.setBeautyPreset(.default) +``` + +
    通过 Beauty API 的 setBeautyPreset 方法,你可以实现基础美颜功能。但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。
    + +### 7. 离开频道 + +调用 `AgoraRtcEngineKit` 类的 `leaveChannel` 离开频道。 + +```swift +rtcEngine.leaveChannel() +``` + + +### 8. 销毁资源 + +调用 Beauty API 的 `destroy` 销毁 Beauty API。 + +```swift +beautyAPI.destroy() +``` + +
    Beauty API 自 1.0.2 版起,已将存在笔误的 destory 方法名修正为 destroy
    + +调用 `AgoraRtcEngineKit` 的 `destroy` 销毁 `AgoraRtcEngineKit`。 + +```swift +AgoraRtcEngineKit.destroy() +``` + + +### API 时序图 + +![](https://web-cdn.agora.io/docs-files/1693990504343) \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.2/iOS.wsd" "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/iOS.wsd" new file mode 100644 index 00000000000..15209225a1c --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/iOS.wsd" @@ -0,0 +1,44 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "商汤美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 AgoraRtcEngineKit == +app -> rtc: sharedEngineWithConfig \n创建并初始化 AgoraRtcEngineKit 对象 +== 初始化美颜 SDK == +app -> beauty: 创建并初始化 SenseBeautyRender +== 初始化 Beauty API == +app -> api: 创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +app -> rtc: enableVideo \n开启视频模块 +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: setVideoFrameDelegate \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannelByToken +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: destroy \n销毁 Beauty API 对象 +app -> rtc: destroy \n销毁 AgoraRtcEngineKit 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.2/\345\225\206\346\261\244Androidv1.0.2\346\227\266\345\272\217\345\233\276.wsd" "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/\345\225\206\346\261\244Androidv1.0.2\346\227\266\345\272\217\345\233\276.wsd" new file mode 100644 index 00000000000..806a1ff3723 --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/\345\225\206\346\261\244Androidv1.0.2\346\227\266\345\272\217\345\233\276.wsd" @@ -0,0 +1,46 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "商汤美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 RtcEngine == +app -> rtc: RtcEngine.create \n创建并初始化 RtcEngine 对象 +== 初始化美颜 SDK == +app -> beauty: initBeautySDK \n验证美颜证书并初始化 STMobileHumanActionNative +app -> beauty: initMobileEffect \n初始化 STMobileEffectNative +== 初始化 Beauty API == +app -> api: createSenseTimeBeautyAPI \n创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +app -> rtc: enableVideo \n开启视频模块 +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: registerVideoFrameObserver \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannel +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: release \n销毁 Beauty API 对象 +app -> beauty: unInitMobileEffect \n销毁 STMobileEffectNative +app -> rtc: destroy \n销毁 RtcEngine 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.2/\345\225\206\346\261\244Android\346\227\266\345\272\217\345\233\276.wsd" "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/\345\225\206\346\261\244Android\346\227\266\345\272\217\345\233\276.wsd" new file mode 100644 index 00000000000..806a1ff3723 --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/\345\225\206\346\261\244Android\346\227\266\345\272\217\345\233\276.wsd" @@ -0,0 +1,46 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "商汤美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 RtcEngine == +app -> rtc: RtcEngine.create \n创建并初始化 RtcEngine 对象 +== 初始化美颜 SDK == +app -> beauty: initBeautySDK \n验证美颜证书并初始化 STMobileHumanActionNative +app -> beauty: initMobileEffect \n初始化 STMobileEffectNative +== 初始化 Beauty API == +app -> api: createSenseTimeBeautyAPI \n创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +app -> rtc: enableVideo \n开启视频模块 +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: registerVideoFrameObserver \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannel +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: release \n销毁 Beauty API 对象 +app -> beauty: unInitMobileEffect \n销毁 STMobileEffectNative +app -> rtc: destroy \n销毁 RtcEngine 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\345\225\206\346\261\244/1.0.2/\345\225\206\346\261\244iOSv1.0.2\346\227\266\345\272\217\345\233\276.wsd" "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/\345\225\206\346\261\244iOSv1.0.2\346\227\266\345\272\217\345\233\276.wsd" new file mode 100644 index 00000000000..15209225a1c --- /dev/null +++ "b/markdown/beauty/\345\225\206\346\261\244/1.0.2/\345\225\206\346\261\244iOSv1.0.2\346\227\266\345\272\217\345\233\276.wsd" @@ -0,0 +1,44 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "商汤美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 AgoraRtcEngineKit == +app -> rtc: sharedEngineWithConfig \n创建并初始化 AgoraRtcEngineKit 对象 +== 初始化美颜 SDK == +app -> beauty: 创建并初始化 SenseBeautyRender +== 初始化 Beauty API == +app -> api: 创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +app -> rtc: enableVideo \n开启视频模块 +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: setVideoFrameDelegate \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannelByToken +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: destroy \n销毁 Beauty API 对象 +app -> rtc: destroy \n销毁 AgoraRtcEngineKit 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\345\255\227\350\212\202/beauty_integration_bytedance_android.md" "b/markdown/beauty/\345\255\227\350\212\202/beauty_integration_bytedance_android.md" new file mode 100644 index 00000000000..65cc42b6fbd --- /dev/null +++ "b/markdown/beauty/\345\255\227\350\212\202/beauty_integration_bytedance_android.md" @@ -0,0 +1,411 @@ +本文介绍如何通过声网美颜场景化 API (Beauty API) 集成字节火山美颜功能到实时音视频互动中。 + +## 示例项目 + +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main) 示例项目供你参考。 + +## 准备开发环境 + +### 前提条件 + +- [Git](https://git-scm.com/downloads) +- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 11 +- [Android Studio](https://developer.android.com/studio/) 3.5 及以上 +- Android 手机,版本 Android 5.0(API Level 21)及以上 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) +- 已联系字节技术获取最新的美颜 SDK、美颜资源、美颜证书 +- 已在项目中添加 Kotlin 插件 + +### 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +跑通示例项目时,你需要将**鉴权机制**设置为**调试模式:APP ID**。从头搭建 Android 项目集成美颜功能时,声网推荐你将**鉴权机制**设置为**安全模式:APP ID + Token**,以保障安全性。 + +### 创建 Android 项目 + +按照以下步骤准备开发环境: + +1. 如需创建新项目,在 **Android Studio** 里,依次选择 **Phone and Tablet > Empty Activity**,创建 [Android 项目](https://developer.android.com/studio/projects/create-project)。 + +
    创建项目后,Android Studio 会自动开始同步 gradle, 稍等片刻至同步成功后再进行下一步操作。
    + +2. 使用 Maven Central 将声网 RTC SDK 集成到你的项目中。 + + a. 在 `/Gradle Scripts/build.gradle(Project: )` 文件中添加如下代码,添加 Maven Central 依赖: + + ```java + buildscript { + repositories { + ... + mavenCentral() + } + ... + } + + allprojects { + repositories { + ... + mavenCentral() + } + } + ``` + +
    如果你的 Android 项目设置了 dependencyResolutionManagement,添加 Maven Central 依赖的方式可能存在差异。
    + + b. 在 `/Gradle Scripts/build.gradle(Module: .app)` 文件中添加如下代码,将声网 RTC SDK 集成到你的 Android 项目中: + + ```java + ... + dependencies { + ... + // x.y.z,请填写具体的 RTC SDK 版本号,如:4.0.0 或 4.1.0-1。 + // 通过互动直播产品发版说明获取最新版本号。 + implementation 'io.agora.rtc:full-sdk:x.y.z' + } + ``` + +3. 将字节火山美颜 SDK 集成到你的项目中。请联系字节技术支持获取美颜 SDK、美颜资源、证书等文件。下载并解压文件,然后添加到美颜项目对应的文件路径下: + + | 文件 | 项目路径 | + |-------------------------------------------------------------------------|----------------------------------| + | Android/models | assets/beauty_sensetime | + | Android/sample/SenseMeEffects/app/src/main/assets/sticker_face_shape | assets/beauty_sensetime | + | Android/sample/SenseMeEffects/app/src/main/assets/style_lightly | assets/beauty_sensetime | + | Android/sample/SenseMeEffects/app/libs/SenseArSourceManager-release.aar | libs | + | Android/sample/SenseMeEffects/app/libs/HardwareBuffer-release.aar | libs | + | Android/aar/STMobileJNI-release.aar | libs | + | SenseME.lic | assets/beauty_sensetime/license | + +4. 将声网美颜场景化 API 集成到你的项目中。添加 [Android/lib_bytedance/src/main/java/io/agora/beautyapi/bytedance](https://github.com/AgoraIO-Community/BeautyAPI/tree/main/Android/lib_bytedance/src/main/java/io/agora/beautyapi/bytedance) 目录下的文件到项目中,具体文件如下: + - `utils` 文件夹 + - `ByteDanceBeautyAPI.kt` 文件 + - `ByteDanceBeautyAPIImpl.kt` 文件 + +
    为方便后续代码升级,请不要修改你添加的这些文件的名称和路径。
    + +5. 添加网络及设备权限。 + + 在 `/app/Manifests/AndroidManifest.xml` 文件中,在 `` 后面添加如下权限: + + ```xml + + + + + + + + + + + + + ``` + +5. 在 `/Gradle Scripts/proguard-rules.pro` 文件中添加如下行,以防止声网 SDK 的代码被混淆: + + ```java + -keep class io.agora.**{*;} + -dontwarn javax.** + -dontwarn com.google.devtools.build.android.** + ``` + +## 实现美颜 + +本节展示如何在直播间内实现美颜功能,参考 [API 时序图](#api-时序图)可查看总览。声网 RTC SDK 承担实时音视频的业务,字节火山美颜 SDK 提供美颜功能,声网 Beauty API 封装了两个 SDK 中的 API 调用逻辑以简化你需要实现的代码逻辑。通过 Beauty API,你可以实现基础美颜功能,但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。 + +### 1. 初始化 RtcEngine + +调用声网 RTC SDK 中的 `create` 创建并初始化 `RtcEngine` 对象。 + +```kotlin +// 初始化声网 RtcEngine +private val mRtcEngine by lazy { + RtcEngine.create(RtcEngineConfig().apply { + mContext = applicationContext + // 传入你从控制台获取的声网项目的 APP ID + mAppId = BuildConfig.AGORA_APP_ID + mEventHandler = object : IRtcEngineEventHandler() {} + }).apply { + // 开启声网 clear_vision 高清视频插件 + enableExtension("agora_video_filters_clear_vision", "clear_vision", true) + } +} +``` + +### 2. 初始化 RenderManager + +复制美颜证书、美颜资源到 `sdcard` 存储中。 + +```kotlin +// 初始化美颜 SDK +fun initBeautySDK(context: Context){ + val storagePath = context.getExternalFilesDir("")?.absolutePath ?: return + val assetsPath = "beauty_bytedance" + + workerThread.execute { + // copy license + licensePath = "$storagePath/beauty_bytedance/LicenseBag.bundle/$LICENSE_NAME" + FileUtils.copyAssets(context, "$assetsPath/LicenseBag.bundle/$LICENSE_NAME", licensePath) + + // copy models + modelsPath = "$storagePath/beauty_bytedance/ModelResource.bundle" + FileUtils.copyAssets(context, "$assetsPath/ModelResource.bundle", modelsPath) + + // copy beauty node + beautyNodePath = "$storagePath/beauty_bytedance/ComposeMakeup.bundle/ComposeMakeup/beauty_Android_lite" + FileUtils.copyAssets(context, "$assetsPath/ComposeMakeup.bundle/ComposeMakeup/beauty_Android_lite", beautyNodePath) + + // copy beauty 4items node + beauty4ItemsNodePath = "$storagePath/beauty_bytedance/ComposeMakeup.bundle/ComposeMakeup/beauty_4Items" + FileUtils.copyAssets(context, "$assetsPath/ComposeMakeup.bundle/ComposeMakeup/beauty_4Items", beauty4ItemsNodePath) + + // copy resharp node + reSharpNodePath = "$storagePath/beauty_bytedance/ComposeMakeup.bundle/ComposeMakeup/reshape_lite" + FileUtils.copyAssets(context, "$assetsPath/ComposeMakeup.bundle/ComposeMakeup/reshape_lite", reSharpNodePath) + + // copy makeup node + makeupTianmeiNodePath = "$storagePath/beauty_bytedance/ComposeMakeup.bundle/ComposeMakeup/style_makeup/tianmei" + FileUtils.copyAssets(context, "$assetsPath/ComposeMakeup.bundle/ComposeMakeup/style_makeup/tianmei", makeupTianmeiNodePath) + + // copy stickers + stickerPath = "$storagePath/beauty_bytedance/StickerResource.bundle/stickers" + FileUtils.copyAssets(context, "$assetsPath/StickerResource.bundle/stickers", stickerPath) + } +} +``` + +在 GL 线程 (Graphics Library Thread) 中通过美颜 SDK 的 `initEffect` 方法初始化 `RenderManager` 实例。 + +```kotlin +// GL 线程中 +// 初始化美颜 SDK 中的 RenderManager 实例 +fun initEffect(context: Context){ + val ret = renderManager.init( + context, + modelsPath, licensePath, false, false, 0 + ) + if(!checkResult("RenderManager init ", ret)){ + return + } + renderManager.useBuiltinSensor(true) + renderManager.set3Buffer(false) + renderManager.appendComposerNodes(arrayOf(beautyNodePath, beauty4ItemsNodePath, reSharpNodePath)) + renderManager.loadResourceWithTimeout(-1) +} +``` + + +### 3. 初始化 Beauty API + +调用 `createByteDanceBeautyAPI` 创建 Beauty API 对象。Beauty API 对象基于 `RenderManager` 对象封装。 + +```kotlin +// 创建 Beauty API 对象 +private val mByteDanceApi by lazy { + createByteDanceBeautyAPI() +} +``` + +调用 `initialize` 初始化 Beauty API 对象。你需要在 `config` 参数中传入如下字段: + +- `applicationContext`:传入 Android Context(上下文)。 +- `mRtcEngine`:传入之前初始化的 `RtcEngine` 对象。 +- `renderManager`:传入之前初始化的 `RenderManager` 对象。 +- `captureMode`:视频的采集模式: + - 如果你使用声网模块采集视频,请传入 `CaptureMode.Agora`。 + - 如果自定义采集视频,请传入 `CaptureMode.Custom`。 +- `statsEnable`:是否开启美颜统计数据回调。`true` 代表开启,`false` 代表不开启。开启后,会有周期性的 `onBeautyStats` 回调事件。 +- `statsDuration`:美颜统计数据回调的周期。单位为毫秒。 +- `cameraConfig`:设置视频镜像模式。如果在初始化 Beauty API 后你想修改镜像模式,可以调用 Beauty API 的 `updateCameraConfig`。 +- `eventCallback`:你希望监听的回调事件。 + +```kotlin +// 初始化 Beauty API 对象 +mByteDanceApi.initialize( + Config( + // Android Context(上下文) + applicationContext, + // RtcEngine + mRtcEngine, + // 美颜特效管理器 + renderManager, + // 设置视频采集模式 + // CaptureMode.Agora 意味着使用声网模块采集视频 + // CaptureMode.Custom 意味着使用开发者自定义采集视频 + captureMode = if (isCustomCaptureMode) CaptureMode.Custom else + CaptureMode.Agora, + // 是否开启美颜统计数据 + // 开启后,会有周期性的 onBeautyStats 回调事件 + statsEnable = true, + // 设置美颜统计数据的统计区间为 1000 毫秒(默认) + statsDuration = 1000, + // 配置视频镜像模式 + cameraConfig = cameraConfig, + // 用于监听 Beauty API 的回调事件 + eventCallback = EventCallback( + // 美颜统计数据回调 + onBeautyStats = {stats -> + Log.d(TAG, "BeautyStats stats = $stats") + }, + // GL 线程中 + // 美颜特效初始化完成回调 + onEffectInitialized = { + ByteDanceBeautySDK.initEffect(applicationContext) + Log.d(TAG, "onEffectInitialized") + }, + // GL 线程中 + // 美颜特效销毁回调 + onEffectDestroyed = { + ByteDanceBeautySDK.unInitEffect() + Log.d(TAG, "onEffectInitialized") + } + ) + )) +``` + +### 4. 开启美颜 + +调用 Beauty API 的 `enable` 方法并将参数设为 `true` 开启美颜。 + +```kotlin +mByteDanceApi.enable(true) +``` + +### 5. 开启视频采集 + +开发者可以使用声网模块采集视频,也可以自定义采集视频。本节介绍在这两种场景下如何开启视频采集。 + +#### 使用声网模块采集视频 + +使用声网模块采集视频视频时,你需要先调用 `RtcEngine` 类的 `enableVideo` 开启声网 SDK 的视频模块,然后调用 Beauty API 的 `setupLocalVideo` 开启本地视图。 + +```kotlin +// 开启视频模块 +mRtcEngine.enableVideo() +// 设置本地视图 +mByteDanceApi.setupLocalVideo(mBinding.localVideoView, Constants.RENDER_MODE_FIT) +``` + +#### 自定义视频采集 + +自定义视频采集时,你需要先调用 `RtcEngine` 类的 `enableVideo` 开启声网 SDK 的视频模块,然后通过 `RtcEngine` 类的 `registerVideoFrameObserver` 注册原始视频数据观测器并在其中实现 `onCaptureVideoFrame` 函数。 + +通过 Beauty API 的 `onFrame` 函数,你可以将外部自采集的视频数据传入并进行处理。当处理结果不为 `SKIPPED`(忽略)时,用自采集的视频数据替代 `onCaptureVideoFrame` 函数中的 `VideoFrame`,并传入声网 SDK。 + + +```kotlin +// 开启视频模块 +mRtcEngine.enableVideo() +// 注册原始视频数据观测器 +// 自定义视频采集时,即 CaptureMode 为 Custom 时,你需要注册原始视频观测器 +mRtcEngine.registerVideoFrameObserver(object : IVideoFrameObserver { + + override fun onCaptureVideoFrame( + sourceType: Int, + videoFrame: VideoFrame? + ) = when (mByteDanceApi.onFrame(videoFrame!!)) { + // 当处理结果为 SKIPPED(忽略)时,代表你丢帧,即外部自采集的视频数据不传入声网 SDK + // 当处理结果为其他时,外部自采集的视频数据传入声网 SDK + ErrorCode.ERROR_FRAME_SKIPPED.value -> false + else -> true + } + + // 设置是否对原始视频数据作镜像处理 + override fun getMirrorApplied() = mByteDanceApi.getMirrorApplied() + + // 设置观测点为本地采集时的视频数据 + override fun getObservedFramePosition() = IVideoFrameObserver.POSITION_POST_CAPTURER + + // override 视频观测器中的其他回调函数 + ... +}) +``` + + +### 6. 加入频道 + +调用 `RtcEngine` 类的 `joinChannel` 加入频道,同时传入如下参数: + +- `token`:用于鉴权的动态密钥。如果在[创建声网项目](#创建声网项目)时启用**调试模式**,那么将 `token` 参数传空。如果启用**安全模式**,那么你先参考[使用 Token 鉴权](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/token_server_android_ng?platform=Android)在你的业务服务端生成 Token,然后将生成的 Token 传入该参数。 +- `channelId`:频道名。 +- `options`:频道媒体设置选项。 + + +```kotlin +mRtcEngine.joinChannel(null, mChannelName, 0, ChannelMediaOptions().apply { + // 设置频道场景为直播 + channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING + // 设置用户角色为主播,主播可以在频道里发布和订阅音视频流 + clientRoleType = Constants.CLIENT_ROLE_BROADCASTER + // 设置是否发布摄像头采集的视频流(适用于使用声网模块采集视频的情况) + publishCameraTrack = true + // 设置是否发布自定义采集的视频流(适用于自定义采集视频的情况) + publishCustomVideoTrack = false + // 设置是否发布麦克风采集的音频流 + publishMicrophoneTrack = false + // 设置进入频道时是否自动订阅频道内其他用户的音频流 + autoSubscribeAudio = false + // 设置进入频道时是否自动订阅频道内其他用户的视频流 + autoSubscribeVideo = true +}) +``` + +### 7. 设置美颜效果 + +调用 Beauty API 中 `setBeautyPreset` 方法设置使用的美颜参数的类型: + +- `DEFAULT`:默认且推荐的美颜参数。 +- `CUSTOM`:开发者自定义的美颜参数。 + +不同的美颜参数会带来不同的美颜效果。如果你没有特殊美颜要求,推荐你使用 `DEFAULT`。 + +```kotlin +mByteDanceApi.setBeautyPreset( + // 设置是否使用默认且推荐的美颜参数 + if (enable) BeautyPreset.DEFAULT else BeautyPreset.CUSTOM, + // 设置美颜、图像识别位点、美妆资源的节点路径 + // 请确保节点路径在你初始化美颜 SDK 时已填写 + ByteDanceBeautySDK.beautyNodePath, + ByteDanceBeautySDK.beauty4ItemsNodePath, + ByteDanceBeautySDK.reSharpNodePath +) +``` + +
    通过 Beauty API 的 setBeautyPreset 方法,你可以实现基础美颜功能。但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。
    + +### 8. 离开频道 + +调用 `RtcEngine` 类的 `leaveChannel` 离开频道。 + +```kotlin +mRtcEngine.leaveChannel() +``` + +### 9. 销毁资源 + +调用 Beauty API 的 `release` 销毁 Beauty API。 + +```kotlin +mByteDanceApi.release() +``` + +在 GL 线程 (Graphics Library Thread) 中调用美颜 SDK 的 `unInitEffect` 销毁 `RenderManager`。 + +```kotlin +fun unInitEffect(){ + renderManager.release() +} +``` + +调用 `RtcEngine` 的 `destroy` 销毁 `RtcEngine`。 + +```kotlin +RtcEngine.destroy() +``` + + +### API 时序图 + +![](https://web-cdn.agora.io/docs-files/1692606491371) \ No newline at end of file diff --git "a/markdown/beauty/\345\255\227\350\212\202/beauty_integration_bytedance_ios.md" "b/markdown/beauty/\345\255\227\350\212\202/beauty_integration_bytedance_ios.md" new file mode 100644 index 00000000000..035598cbc56 --- /dev/null +++ "b/markdown/beauty/\345\255\227\350\212\202/beauty_integration_bytedance_ios.md" @@ -0,0 +1,311 @@ +本文介绍如何通过声网美颜场景化 API (Beauty API) 集成字节火山美颜到实时音视频互动中。 + +## 示例项目 + +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main) 示例项目供你参考。 + +## 准备开发环境 + +### 前提条件 + +- [Git](https://git-scm.com/downloads) +- [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) +- [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 12.0 及以上 +- iOS 设备,版本 13.0 及以上 +- 有效的苹果开发者账号 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) +- 已联系字节火山技术获取最新的美颜 SDK、美颜资源、美颜证书 + + +### 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +跑通示例项目时,你需要将**鉴权机制**设置为**调试模式:APP ID**。从头搭建 Android 项目集成美颜功能时,声网推荐你将**鉴权机制**设置为**安全模式:APP ID + Token**,以保障安全性。 + + +### 创建 iOS 项目 + +在 Xcode 中进行以下操作,在你的 app 中实现场景化美颜功能: + +1. [创建一个新的项目](https://help.apple.com/xcode/mac/current/#/dev07db0e578),**Application** 选择 **App**,**Interface** 选择 **Storyboard**,**Language** 选择 **Swift**。 + +
    如果你没有添加过开发团队信息,会看到 Add account… 按钮。点击该按钮并按照屏幕提示登入 Apple ID,点击 Next,完成后即可选择你的 Apple 账户作为开发团队。
    + +2. 为你的项目设置[自动签名](https://help.apple.com/xcode/mac/current/#/dev23aab79b4)。 + +3. 设置部署你的 app 的[目标设备](https://help.apple.com/xcode/mac/current/#/deve69552ee5)。 + +4. 添加项目的设备权限。在项目导航栏中打开 `info.plist` 文件,编辑[属性列表](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6),添加以下属性: + + | key | type | value | + | -------------------------------------- | ------ | ------------------------------------------------------------ | + | Privacy - Microphone Usage Description | String | 使用麦克风的目的,例如 for a live interactive streaming | + | Privacy - Camera Usage Description | String | 使用摄像头的目的,例如 for a live interactive streaming | + +
    • 如果你的项目中需要添加第三方插件或库(例如第三方摄像头),且该插件或库的签名与项目的签名不一致,你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation
    • 更多注意事项,可以参考 Preparing Your App for Distribution
    + +5. 将字节火山美颜 SDK 集成到你的项目中。请联系字节火山技术支持获取美颜 SDK、美颜资源、证书等文件。下载并解压文件,然后添加到美颜项目对应的文件路径下: + + | 文件 | 项目路径 | + |------------------|----------------| + | BytedEffects/app/Resource | iOS/ByteEffectLib/Resource | + | byted_effect_ios_static/iossample_static/libeffect-sdk.a | iOS/ByteEffectLib/ibeffect-sdk.a | + | byted_effect_ios_static/iossample_static/include/BytedEffectSDK | iOS/ByteEffectLib/BytedEffectSDK | + +6. 将声网美颜场景化 API 集成到你的项目中。添加 [iOS/BeautyAPi/BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main/iOS/BeautyAPi/BeautyAPI) 目录下的文件到项目中,具体文件如下: + + - `Render/BytesRender` 文件夹 + - `BytesRender` 文件夹 + - `BeautyAPI.h` 文件 + - `BeautyAPI.m` 文件 + - `BeautyConfig.h` 文件 + - `BeautyConfig.m` 文件 + +
    为方便后续代码升级,请不要修改你添加的这些文件的名称和路径。
    + +7. 将声网 RTC SDK 和字节火山美颜依赖库集成到你的项目。 + + 1. 在终端里进入项目根目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。 + 2. 打开 `Podfile` 文件,修改文件为如下内容。注意将 `Your App` 替换为你的 Target 名称。 + + ```shell + platform :ios, '9.0' + # 替换成你的 target 名称 + target 'Your App' do + # x.y.z 请填写具体的 RTC SDK 版本号,如 4.0.1 或 4.0.0.4 + # 可通过互动直播发版说明获取最新版本号 + pod 'AgoraRtcEngine_iOS', 'x.y.z' + # 配置字节火山美颜的依赖库 + pod 'bytedEffect', :path => 'bytedEffect.podspec' + end + ``` + +8. 在终端内运行 pod install 命令安装声网 RTC SDK 和字节火山美颜依赖。 + +9. 成功安装后,Terminal 中会显示 Pod installation complete!。项目文件夹下会生成一个后缀为 .xcworkspace 的文件,通过 Xcode 打开该文件进行后续操作。 + +## 实现美颜 + +本节展示如何在直播间内实现美颜功能,参考 [API 时序图](#api-时序图)可查看总览。声网 RTC SDK 承担实时音视频的业务,字节火山美颜 SDK 提供美颜功能,声网 Beauty API 封装了两个 SDK 中的 API 调用逻辑以简化你需要实现的代码逻辑。通过 Beauty API,你可以实现基础美颜功能,但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。 + +### 1. 初始化 AgoraRtcEngineKit + +调用声网 RTC SDK 中的 `sharedEngineWithConfig` 创建并初始化 `AgoraRtcEngineKit` 对象。调用 `enableVideo` 开启声网 SDK 的视频模块。 + +```swift +// 初始化 AgoraRtcEngineKit +private lazy var rtcEngine: AgoraRtcEngineKit = { + let config = AgoraRtcEngineConfig() + // 传入你从控制台获取的声网项目的 APP ID + config.appId = KeyCenter.AppId + config.channelProfile = .liveBroadcasting + let rtc = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self) + // 设置用户角色为主播,主播可以发送音视频流也可以接收音视频流 + rtc.setClientRole(.broadcaster) + // 开启 SDK 音频模块 + rtc.enableAudio() + // 开启 SDK 视频模块 + rtc.enableVideo() + // 设置默认音频路由为扬声器 + rtc.setDefaultAudioRouteToSpeakerphone(true) + return rtc +}() +``` + +### 2. 初始化美颜和 Beauty API + +创建 `BytesBeautyRender` 和 Beauty API 对象。Beauty API 对象基于 `BytesBeautyRender` 对象封装。 + + +```swift +private lazy var bytesRender = BytesBeautyRender() +private lazy var beautyAPI = BeautyAPI() +``` + + +调用 `initialize` 初始化 Beauty API 对象。你需要在 `config` 参数中传入如下字段: + +- `AgoraRtcEngineKit`:传入之前初始化的 `AgoraRtcEngineKit` 对象。 +- `beautyRender`:传入之前初始化的 `BytesBeautyRender` 对象。 +- `captureMode`:视频的采集模式: + - 如果你使用声网模块采集视频,请传入 `CaptureMode.Agora`。 + - 如果自定义采集视频,请传入 `CaptureMode.Custom`。 +- `statsEnable`:是否开启美颜统计数据回调。`true` 代表开启,`false` 代表不开启。开启后,会有周期性回调事件。 +- `statsDuration`:美颜统计数据回调的周期。单位为秒。 +- `eventCallback`:监听的美颜统计数据回调事件。 + + +```swift +let config = BeautyConfig() +// AgoraRtcEngineKit +config.rtcEngine = rtcEngine +// 设置视频采集模式 +// .agora 意味着使用声网模块采集视频 +// .custom 意味着使用开发者自定义采集视频 +config.captureMode = capture == "Custom" ? .custom : .agora +// BytesBeautyRender +config.beautyRender = bytesRender +// 是否开启美颜统计数据 +// 开启后,会有周期性回调事件 +config.statsEnable = false +// 设置美颜统计数据的统计区间为 1 秒(默认) +config.statsDuration = 1 +// Beauty API 的回调事件 +config.eventCallback = { stats in + print("min == \(stats.minCostMs)") + print("max == \(stats.maxCostMs)") + print("averageCostMs == \(stats.averageCostMs)") +} + +// 初始化 Beauty API 对象 +let result = beautyAPI.initialize(config) +if result != 0 { + print("initialize error == \(result)") +} +``` + + +### 3. 开启美颜 + +调用 Beauty API 的 `enable` 方法并将参数设为 `true` 开启美颜。 + +```swift +beautyAPI.enable(true) +``` + +### 4. 开启视频采集 + +开发者可以使用声网模块采集视频,也可以自定义采集视频。本节介绍在这两种场景下如何开启视频采集。 + +#### 使用声网模块采集视频 + +使用声网模块采集视频视频时,调用 Beauty API 的 `setupLocalVideo` 开启本地视图。 + +```swift +beautyAPI.setupLocalVideo(localView, renderMode: .hidden) +``` + + +#### 自定义视频采集 + +自定义视频采集时,你需要通过 `AgoraRtcEngineKit` 类的 `setVideoFrameDelegate` 注册原始视频数据观测器并在其中实现 `onCaptureVideoFrame` 函数。 + +通过 Beauty API 的 `onFrame` 函数,你可以将外部自采集的视频数据传入并进行处理。 + + +```swift +if capture == "Custom" { + // 注册原始视频数据观测器 + // 自定义视频采集时,即 CaptureMode 为 Custom 时,你需要注册原始视频观测器 + rtcEngine.setVideoFrameDelegate(self) +} + +extension BeautyViewController: AgoraVideoFrameDelegate { + func onCapture(_ videoFrame: AgoraOutputVideoFrame, sourceType: AgoraVideoSourceType) -> Bool { + // 将外部自采集的视频数据传入声网 SDK + guard let pixelBuffer = videoFrame.pixelBuffer else { return true } + beautyAPI.onFrame(pixelBuffer) { pixelBuffer in + videoFrame.pixelBuffer = pixelBuffer + } + + return true + } + + // 设置是否对原始视频数据作镜像处理 + func getMirrorApplied() -> Bool { + beautyAPI.getMirrorApplied() + } + + // 设置观测点为本地采集时的视频数据 + func getObservedFramePosition() -> AgoraVideoFramePosition { + .postCapture + } + + // 实现视频观测器中的其他回调函数 + ... +} +``` + + + +### 5. 加入频道 + +调用 `AgoraRtcEngineKit` 类的 `joinChannelByToken` 加入频道,同时传入如下参数: + +- `token`:用于鉴权的动态密钥。如果在[创建声网项目](#创建声网项目)时启用**调试模式**,那么将 `token` 参数传空。如果启用**安全模式**,那么你先参考[使用 Token 鉴权](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/token_server_ios_ng?platform=iOS)在你的业务服务端生成 Token,然后将生成的 Token 传入该参数。 +- `channelId`:频道名。 +- `mediaOptions`:频道媒体设置选项。 + + + +```swift +let mediaOption = AgoraRtcChannelMediaOptions() +mediaOption.clientRoleType = isBroadcast ? .broadcaster : .audience +// 设置进入频道时是否自动订阅频道内其他用户的音频流 +mediaOption.autoSubscribeAudio = true +// 设置进入频道时是否自动订阅频道内其他用户的视频流 +mediaOption.autoSubscribeVideo = true +// 设置是否发布摄像头采集的视频流(适用于使用声网模块采集视频的情况) +// 用户角色为主播时,设置发布 +// 用户角色为观众时,设置不发布 +mediaOption.publishCameraTrack = mediaOption.clientRoleType == .broadcaster +// 设置是否发布自定义采集的视频流(适用于自定义采集视频的情况) +mediaOption.publishCustomVideoTrack = false +// 设置是否发布麦克风采集的音频流 +// 用户角色为主播时,设置发布 +// 用户角色为观众时,设置不发布 +mediaOption.publishMicrophoneTrack = mediaOption.clientRoleType == .broadcaster + +// 加入频道 +let result = rtcEngine.joinChannel(byToken: nil, channelId: channelName ?? "", uid: 0, mediaOptions: mediaOption) +if result != 0 { + print("join failed") +} +``` + + +### 6. 设置美颜效果 + +调用 Beauty API 中 `setBeautyPreset` 方法设置使用的美颜参数的类型: + +- `BeautyPresetModeDefault`:默认且推荐的美颜参数。 +- `BeautyPresetModeCustom`:开发者自定义的美颜参数。 + +不同的美颜参数会带来不同的美颜效果。如果你没有特殊美颜要求,推荐你使用 `BeautyPresetModeDefault`。 + +```swift +beautyAPI.setBeautyPreset(.default) +``` + +
    通过 Beauty API 的 setBeautyPreset 方法,你可以实现基础美颜功能。但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。
    + +### 7. 离开频道 + +调用 `AgoraRtcEngineKit` 类的 `leaveChannel` 离开频道。 + +```swift +rtcEngine.leaveChannel() +``` + + +### 8. 销毁资源 + +调用 Beauty API 的 `destroy` 销毁 Beauty API。 + +```swift +beautyAPI.destroy() +``` + +
    Beauty API 自 1.0.2 版起,已将存在笔误的 destory 方法名修正为 destroy
    + +调用 `AgoraRtcEngineKit` 的 `destroy` 销毁 `AgoraRtcEngineKit`。 + +```swift +AgoraRtcEngineKit.destroy() +``` + + +### API 时序图 + +![](https://web-cdn.agora.io/docs-files/1693995872971) \ No newline at end of file diff --git "a/markdown/beauty/\345\255\227\350\212\202/beauty_run_github_project_bytedance_android.md" "b/markdown/beauty/\345\255\227\350\212\202/beauty_run_github_project_bytedance_android.md" new file mode 100644 index 00000000000..c7d52dbfe6c --- /dev/null +++ "b/markdown/beauty/\345\255\227\350\212\202/beauty_run_github_project_bytedance_android.md" @@ -0,0 +1,101 @@ +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main) 示例项目供你参考。本文介绍如何快速跑通该示例项目,体验字节火山美颜效果。 + +## 前提条件 + +- [Git](https://git-scm.com/downloads) +- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 11 +- [Android Studio](https://developer.android.com/studio/) 3.5 及以上 +- Android 手机,版本 Android 5.0(API Level 21)及以上 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) + +
    声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。
    + + +## 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +跑通示例项目时,你需要将**鉴权机制**设置为**调试模式:APP ID**。从头搭建 Android 项目集成美颜功能时,声网推荐你将**鉴权机制**设置为**安全模式:APP ID + Token**,以保障安全性。 + +## 克隆仓库 + +运行以下命令克隆仓库到本地: + +```shell +git clone git@github.com:AgoraIO-Community/BeautyAPI.git +``` + +## 集成第三方美颜 SDK + +1. 联系字节技术支持获取最新的美颜 SDK、美颜资源、美颜证书。 + +2. 下载并解压美颜 SDK,然后将 SDK 中如下文件添加到美颜示例项目对应的文件路径下: + + + + + + + + + + + + + + + + + + + + + + +
    SDK 文件项目路径
    resource/LicenseBag.bundleapp/src/main/assets/beauty_bytedance
    resource/ModelResource.bundle
    resource/ComposeMakeup.bundle
    resource/StickerResource.bundle
    resource/StickerResource.bundle
    + +3. 在 `app/src/main/java/io/agora/beautyapi/demo/ByteDanceActivity.kt` 文件中,将 `LICENSE_NAME` 设置为申请到的证书文件名。 + + ```kotlin + // 这里的证书文件名只用于声网示例项目测试 + // 请替换成你的证书文件名 + private val LICENSE_NAME = "agora_test_20220805_20230815_io.agora.entfull_4.2.3.licbag" + ``` + +4. 在 `app/build.gradle` 文件中,将 `applicationId` 修改为你的包名,例如 `com.example.app`。包名用于在设备上唯一标识应用程序。在开发应用时,你需要设置包名。在此处设置的包名需要与你申请美颜 SDK 时提供的包名一致。 + + ```java + android { + defaultConfig { + applicationId "io.agora.entfull" + ... + } + } + ``` + +## 配置示例项目 + +运行美颜项目前,你需要在 `local.properties` 文件中添加并设置如下参数: + +```shell +AGORA_APP_ID = "YOUR_APP_ID" +``` + +你可以在[创建声网项目](#create)后,从控制台获取参数的值,详情如下: + +| 参数 | 描述 | 获取方式 | +|----|----|----| +| `AGORA_APP_ID` | 声网项目的 App ID | [获取 App ID](https://docportal.shengwang.cn/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#获取-app-id) | + + +## 编译并运行示例项目 + +1. 开启 Android 设备的开发者选项,打开 USB 调试,通过 USB 连接线将 Android 设备接入电脑。 + +2. 用 Android Studio 打开 `BeautyAPI/Android` 文件夹。 + +3. 在 Android Studio 中,点击 **Sync Project with Gradle Files** 按钮,让项目与 Gradle 文件同步。 + +4. 待同步成功后,点击 `Run 'app'`。片刻后,美颜应用便会安装到你的 Android 设备上。 + +5. 打开美颜应用,进行体验。 diff --git "a/markdown/beauty/\345\255\227\350\212\202/beauty_run_github_project_bytedance_ios.md" "b/markdown/beauty/\345\255\227\350\212\202/beauty_run_github_project_bytedance_ios.md" new file mode 100644 index 00000000000..291c1f55f38 --- /dev/null +++ "b/markdown/beauty/\345\255\227\350\212\202/beauty_run_github_project_bytedance_ios.md" @@ -0,0 +1,70 @@ +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main) 示例项目供你参考。本文介绍如何快速跑通该示例项目,体验字节火山美颜效果。 + +## 前提条件 + +- [Git](https://git-scm.com/downloads) +- [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) +- [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 13.0 及以上 +- iOS 设备,版本 11.0 及以上 +- 有效的苹果开发者账号 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) + +
    声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。
    + + +## 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +## 克隆仓库 + +运行以下命令克隆仓库到本地: + +```shell +git clone git@github.com:AgoraIO-Community/BeautyAPI.git +``` + +## 集成第三方美颜 SDK + +1. 联系字节技术支持获取最新的美颜 SDK、美颜资源、美颜证书。 + +2. 下载并解压美颜 SDK 等文件,然后将如下文件添加到美颜示例项目对应的文件路径下: + + |文件 | 项目路径 | + |-----|-----| + | BytedEffects/app/Resource | iOS/ByteEffectLib/Resource | + | byted_effect_ios_static/iossample_static/libeffect-sdk.a | iOS/ByteEffectLib/ibeffect-sdk.a | + | byted_effect_ios_static/iossample_static/include/BytedEffectSDK | iOS/ByteEffectLib/BytedEffectSDK | + + +## 配置示例项目 + +1. 运行美颜项目前,你需要在 `iOS/BeautyAPi/KeyCenter.swift` 文件中设置如下参数: + + ```swift + static let AppId: String = <#YOUR_APP_ID#> + ``` + + 你可以在[创建声网项目](#create)后,从控制台获取这些参数的值,详情如下: + + | 参数 | 描述 | 获取方式 | + |----|----|----| + | `AppId` | 声网项目的 App ID | [获取 App ID](https://docportal.shengwang.cn/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#获取-app-id) | + + +2. 在 `iOS/` 目录下运行 `pod install`,然后等待依赖库安装完成。 + + +## 编译并运行示例项目 + +![](https://web-cdn.agora.io/docs-files/1690276905446) + +1. 连接上 iOS 设备后,点击 `BeautyAPi.xcodeproj` 文件以通过 Xcode 打开项目,并在 **iOS Device** 选项中勾选上你的 iOS 设备。 + +2. 在项目 **TARGETS** 下的 **Signing & Capabilities** 界面勾选 **Automatically manage signing**,配置你的苹果开发者账号和 **Bundle Identifier**。Bundle ID 是设备上应用程序的唯一标识。在开发应用时,你需要设置 Bundle ID。在此处设置的 Bundle ID 需要与你申请字节火山美颜 SDK 时提供的 Bundle ID 一致。 + +3. 点击 开始编译。 + +4. 编译成功后,你的 iOS 设备上会出现美颜应用。在 iOS 系统设置中将该应用设为信任开发者后你才能打开应用。 + +5. 打开美颜应用,进行体验。 \ No newline at end of file diff --git "a/markdown/beauty/\345\255\227\350\212\202Android\346\227\266\345\272\217\345\233\276.wsd" "b/markdown/beauty/\345\255\227\350\212\202Android\346\227\266\345\272\217\345\233\276.wsd" new file mode 100644 index 00000000000..829e12058cf --- /dev/null +++ "b/markdown/beauty/\345\255\227\350\212\202Android\346\227\266\345\272\217\345\233\276.wsd" @@ -0,0 +1,46 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "字节火山美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 RtcEngine == +app -> rtc: RtcEngine.create \n创建并初始化 RtcEngine 对象 +== 初始化 RenderManager == +app -> beauty: initBeautySDK \n初始化美颜 SDK +app -> beauty: initEffect \n初始化 RenderManager 美颜特效对象 +== 初始化 Beauty API == +app -> api: createByteDanceBeautyAPI \n创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +app -> rtc: enableVideo \n开启视频模块 +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: registerVideoFrameObserver \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannel +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: release \n销毁 Beauty API 对象 +app -> beauty: unInitEffect \n销毁 RenderManager 美颜特效对象 +app -> rtc: destroy \n销毁 RtcEngine 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\345\255\227\350\212\202iOS\346\227\266\345\272\217\345\233\276.wsd" "b/markdown/beauty/\345\255\227\350\212\202iOS\346\227\266\345\272\217\345\233\276.wsd" new file mode 100644 index 00000000000..bcfa094b243 --- /dev/null +++ "b/markdown/beauty/\345\255\227\350\212\202iOS\346\227\266\345\272\217\345\233\276.wsd" @@ -0,0 +1,44 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "字节火山美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 AgoraRtcEngineKit == +app -> rtc: sharedEngineWithConfig \n创建并初始化 AgoraRtcEngineKit 对象 +== 初始化美颜 SDK == +app -> beauty: 创建并初始化 BytesBeautyRender +== 初始化 Beauty API == +app -> api: 创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +app -> rtc: enableVideo \n开启视频模块 +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: setVideoFrameDelegate \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannelByToken +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: destroy \n销毁 Beauty API 对象 +app -> rtc: destroy \n销毁 AgoraRtcEngineKit 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\347\233\270\350\212\257/beauty_integration_faceunity_android.md" "b/markdown/beauty/\347\233\270\350\212\257/beauty_integration_faceunity_android.md" new file mode 100644 index 00000000000..53cc661df7a --- /dev/null +++ "b/markdown/beauty/\347\233\270\350\212\257/beauty_integration_faceunity_android.md" @@ -0,0 +1,397 @@ +本文介绍如何通过声网美颜场景化 API (Beauty API) 集成相芯美颜到实时音视频互动中。 + +## 示例项目 + +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main) 示例项目供你参考。 + +## 准备开发环境 + +### 前提条件 + +- [Git](https://git-scm.com/downloads) +- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 11 +- [Android Studio](https://developer.android.com/studio/) 3.5 及以上 +- Android 手机,版本 Android 5.0(API Level 21)及以上 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) +- 已联系相芯技术获取最新的美颜 SDK、美颜资源、美颜证书 +- 已在项目中添加 Kotlin 插件 + +### 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +跑通示例项目时,你需要将**鉴权机制**设置为**调试模式:APP ID**。从头搭建 Android 项目集成美颜功能时,声网推荐你将**鉴权机制**设置为**安全模式:APP ID + Token**,以保障安全性。 + + +### 创建 Android 项目 + +按照以下步骤准备开发环境: + +1. 如需创建新项目,在 **Android Studio** 里,依次选择 **Phone and Tablet > Empty Activity**,创建 [Android 项目](https://developer.android.com/studio/projects/create-project)。 + +
    创建项目后,Android Studio 会自动开始同步 gradle, 稍等片刻至同步成功后再进行下一步操作。
    + +2. 使用 Maven Central 将声网 RTC SDK 集成到你的项目中。 + + a. 在 `/Gradle Scripts/build.gradle(Project: )` 文件中添加如下代码,添加 Maven Central 依赖: + + ```java + buildscript { + repositories { + ... + mavenCentral() + } + ... + } + + allprojects { + repositories { + ... + mavenCentral() + } + } + ``` + +
    如果你的 Android 项目设置了 dependencyResolutionManagement,添加 Maven Central 依赖的方式可能存在差异。
    + + b. 在 `/Gradle Scripts/build.gradle(Module: .app)` 文件中添加如下代码,将声网 RTC SDK 集成到你的 Android 项目中: + + ```java + // 配置相芯依赖库 + allprojects { + repositories { + maven { + url 'http://maven.faceunity.com/repository/maven-public/' + allowInsecureProtocol = true + } + } + } + + dependencies { + ... + // x.y.z,请填写具体的 RTC SDK 版本号,如:4.0.0 或 4.1.0-1。 + // 通过互动直播产品发版说明获取最新版本号。 + implementation 'io.agora.rtc:full-sdk:x.y.z' + // 集成相芯美颜资源 + implementation 'com.faceunity:core:8.3.0' + implementation 'com.faceunity:model:8.3.0' + } + ``` + +3. 将相芯美颜 SDK 集成到你的项目中。请联系相芯技术支持获取美颜 SDK、美颜资源、证书等文件。下载并解压文件,然后添加到美颜项目对应的文件路径下: + + | 文件 | 项目路径 | + |-----|-----| + | 美妆资源:例如 `naicha.bundle` | app/src/main/assets/beauty_faceunity/makeup | + | 贴纸资源:例如 `fashi.bundle` | app/src/main/assets/beauty_faceunity/sticker | + | 证书:`authpack.java` | app/src/main/java/io/agora/beauty/demo/authpack.java | + + +4. 将声网美颜场景化 API 集成到你的项目中。添加 [Android/lib_faceunity/src/main/java/io/agora/beautyapi/faceunity](https://github.com/AgoraIO-Community/BeautyAPI/tree/main/Android/lib_faceunity/src/main/java/io/agora/beautyapi/faceunity) 目录下的文件到项目中,具体文件如下: + - `utils` 文件夹 + - `FaceUnityBeautyAPI.kt` 文件 + - `FaceUnityBeautyAPIImpl` 文件 + +
    为方便后续代码升级,请不要修改你添加的这些文件的名称和路径。
    + +5. 添加网络及设备权限。 + + 在 `/app/Manifests/AndroidManifest.xml` 文件中,在 `` 后面添加如下权限: + + ```xml + + + + + + + + + + + + + ``` + +5. 在 `/Gradle Scripts/proguard-rules.pro` 文件中添加如下行,以防止声网 SDK 的代码被混淆: + + ```java + -keep class io.agora.**{*;} + -dontwarn javax.** + -dontwarn com.google.devtools.build.android.** + ``` + +## 实现美颜 + +本节展示如何在直播间内实现美颜功能,参考 [API 时序图](#api-时序图)可查看总览。声网 RTC SDK 承担实时音视频的业务,相芯美颜 SDK 提供美颜功能,声网 Beauty API 封装了两个 SDK 中的 API 调用逻辑以简化你需要实现的代码逻辑。通过 Beauty API,你可以实现基础美颜功能,但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。 + + +### 1. 初始化 RtcEngine + +调用声网 RTC SDK 中的 `create` 创建并初始化 `RtcEngine` 对象。 + +```kotlin +// 初始化声网 RtcEngine +private val mRtcEngine by lazy { + RtcEngine.create(RtcEngineConfig().apply { + mContext = applicationContext + // 传入你从控制台获取的声网项目的 APP ID + mAppId = BuildConfig.AGORA_APP_ID + mEventHandler = object : IRtcEngineEventHandler() {} + }).apply { + // 开启声网 clear_vision 高清视频插件 + enableExtension + ("agora_video_filters_clear_vision", "clear_vision", true) + } +} +``` + +### 2. 初始化美颜 SDK + +调用相芯美颜 SDK 的 `registerFURender` 初始化 `FURenderKit` 对象,同时传入如下参数: + +- `context`:Android Context(上下文)。 +- `getAuth()`:`getAuth` 方法返回的鉴权字段,格式为 ByteArray。鉴权字段与本地 `authpack.java` 证书文件相关,只有验证通过后,你才能使用相芯美颜 SDK。 +- `object`:事件回调。 + +初始化美颜 SDK 成功后,在新线程中通过 `loadAIProcessor` 加载 AI 道具。 + +```kotlin +object FaceUnityBeautySDK { + private val TAG = "FaceUnityBeautySDK" + + private val fuAIKit = FUAIKit.getInstance() + val fuRenderKit = FURenderKit.getInstance() + + // AI 道具 + private val BUNDLE_AI_FACE = "model" + File.separator + "ai_face_processor.bundle" + private val BUNDLE_AI_HUMAN = "model" + File.separator + "ai_human_processor.bundle" + + private val workerThread = Executors.newSingleThreadExecutor() + + fun initBeauty(context: Context){ + // 设置美颜 SDK 日志 + FURenderManager.setKitDebug(FULogger.LogLevel.TRACE) + FURenderManager.setCoreDebug(FULogger.LogLevel.ERROR) + // 初始化美颜 SDK + // 需传入美颜 SDK 鉴权字段并设置美颜 SDK 事件监听 + FURenderManager.registerFURender(context, getAuth(), object : OperateCallback { + override fun onSuccess(code: Int, msg: String) { + Log.i(TAG, "FURenderManager onSuccess -- code=$code, msg=$msg") + if (code == OPERATE_SUCCESS_AUTH) { + faceunity.fuSetUseTexAsync(1) + // 如果初始化美颜 SDK 成功,在新线程中加载 AI 道具 + workerThread.submit { + fuAIKit.loadAIProcessor(BUNDLE_AI_FACE, FUAITypeEnum.FUAITYPE_FACEPROCESSOR) + fuAIKit.loadAIProcessor(BUNDLE_AI_HUMAN, FUAITypeEnum.FUAITYPE_HUMAN_PROCESSOR) + } + } + } + + override fun onFail(errCode: Int, errMsg: String) { + Log.e(TAG, "FURenderManager onFail -- code=$errCode, msg=$errMsg") + } + }) + } + + // 获取美颜 SDK 鉴权字段 + private fun getAuth(): ByteArray{ + val authpack = Class.forName("io.agora.beautyapi.demo.authpack") + val aMethod = authpack.getDeclaredMethod("A") + aMethod.isAccessible = true + val authValue = aMethod.invoke(null) as? ByteArray + return authValue ?: ByteArray(0) + } +} +``` + +### 3. 初始化 Beauty API + +调用 `createFaceUnityBeautyAPI` 创建 Beauty API 对象。Beauty API 对象基于 `FuRenderKit` 对象封装。 + + +```kotlin +// 创建 Beauty API 对象 +private val mFaceUnityApi by lazy { + createFaceUnityBeautyAPI() +} +``` + +调用 `initialize` 初始化 Beauty API 对象。你需要在 `config` 参数中传入如下字段: + +- `applicationContext`:传入 Android Context(上下文)。 +- `mRtcEngine`:传入之前初始化的 `RtcEngine` 对象。 +- `fuRenderKit`:传入之前初始化的 `FuRenderKit` 对象。 +- `captureMode`:视频的采集模式: + - 如果你使用声网模块采集视频,请传入 `CaptureMode.Agora`。 + - 如果自定义采集视频,请传入 `CaptureMode.Custom`。 +- `statsEnable`:是否开启美颜统计数据回调。`true` 代表开启,`false` 代表不开启。开启后,会有周期性的 `onBeautyStats` 回调事件。 +- `statsDuration`:美颜统计数据回调的周期。单位为毫秒。 +- `cameraConfig`:设置视频镜像模式。如果在初始化 Beauty API 后你想修改镜像模式,可以调用 Beauty API 的 `updateCameraConfig`。 +- `eventCallback`:你希望监听的回调事件。 + +```kotlin +// 初始化 Beauty API 对象 +mFaceUnityApi.initialize( + Config( + // Android Context(上下文) + applicationContext, + // RtcEngine + mRtcEngine, + // 美颜特效管理器 + fuRenderKit, + // 设置视频采集模式 + // CaptureMode.Agora 意味着使用声网模块采集视频 + // CaptureMode.Custom 意味着使用开发者自定义采集视频 + captureMode = if(isCustomCaptureMode) CaptureMode.Custom else CaptureMode.Agora, + // 配置视频镜像模式 + cameraConfig = this.cameraConfig, + // 是否开启美颜统计数据 + // 开启后,会有周期性的 onBeautyStats 回调事件 + statsEnable = true, + // 设置美颜统计数据的统计区间为 1000 毫秒(默认) + statsDuration = 1000, + // 用于监听 Beauty API 的回调事件 + eventCallback = object: IEventCallback{ + override fun onBeautyStats(stats: BeautyStats) { + Log.d(TAG, "BeautyStats stats = $stats") + } + } + ) +) +``` + +### 4. 开启美颜 + +调用 Beauty API 的 `enable` 方法并将参数设为 `true` 开启美颜。 + +```kotlin +mFaceUnityApi.enable(true) +``` + +### 5. 开启视频采集 + +开发者可以使用声网模块采集视频,也可以自定义采集视频。本节介绍在这两种场景下如何开启视频采集。 + +#### 使用声网模块采集视频 + +使用声网模块采集视频视频时,你需要先调用 `RtcEngine` 类的 `enableVideo` 开启声网 SDK 的视频模块,然后调用 Beauty API 的 `setupLocalVideo` 开启本地视图。 + + +```kotlin +// 开启视频模块 +mRtcEngine.enableVideo() +// 设置本地视图 +mFaceUnityApi.setupLocalVideo(mBinding.localVideoView, Constants.RENDER_MODE_FIT) +``` + +#### 自定义视频采集 + +自定义视频采集时,你需要先调用 `RtcEngine` 类的 `enableVideo` 开启声网 SDK 的视频模块,然后通过 `RtcEngine` 类的 `registerVideoFrameObserver` 注册原始视频数据观测器并在其中实现 `onCaptureVideoFrame` 函数。 + +通过 Beauty API 的 `onFrame` 函数,你可以将外部自采集的视频数据传入并进行处理。当处理结果不为 `SKIPPED`(忽略)时,用自采集的视频数据替代 `onCaptureVideoFrame` 函数中的 `VideoFrame`,并传入声网 SDK。 + + +```kotlin +// 开启视频模块 +mRtcEngine.enableVideo() +// 注册原始视频数据观测器 +// 自定义视频采集时,即 CaptureMode 为 Custom 时,你需要注册原始视频观测器 +mRtcEngine.registerVideoFrameObserver(object : IVideoFrameObserver { + + override fun onCaptureVideoFrame( + sourceType: Int, + videoFrame: VideoFrame? + ) = when (mFaceUnityApi.onFrame(videoFrame!!)) { + // 当处理结果为 SKIPPED(忽略)时,代表你丢帧,即外部自采集的视频数据不传入声网 SDK + // 当处理结果为其他时,外部自采集的视频数据传入声网 SDK + ErrorCode.ERROR_FRAME_SKIPPED.value -> false + else -> true + } + + // 设置是否对原始视频数据作镜像处理 + override fun getMirrorApplied() = mFaceUnityApi.getMirrorApplied() + + // 设置观测点为本地采集时的视频数据 + override fun getObservedFramePosition() = IVideoFrameObserver.POSITION_POST_CAPTURER + + // override 视频观测器中的其他回调函数 + ... +}) +``` + + +### 6. 加入频道 + +调用 `RtcEngine` 类的 `joinChannel` 加入频道,同时传入如下参数: + +- `token`:用于鉴权的动态密钥。如果在[创建声网项目](#创建声网项目)时启用**调试模式**,那么将 `token` 参数传空。如果启用**安全模式**,那么你先参考[使用 Token 鉴权](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/token_server_android_ng?platform=Android)在你的业务服务端生成 Token,然后将生成的 Token 传入该参数。 +- `channelId`:频道名。 +- `options`:频道媒体设置选项。 + +```kotlin +mRtcEngine.joinChannel(null, mChannelName, 0, ChannelMediaOptions().apply { + // 设置频道场景为直播 + channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING + // 设置用户角色为主播,主播可以在频道里发布和订阅音视频流 + clientRoleType = Constants.CLIENT_ROLE_BROADCASTER + // 设置是否发布摄像头采集的视频流(适用于使用声网模块采集视频的情况) + publishCameraTrack = true + // 设置是否发布自定义采集的视频流(适用于自定义采集视频的情况) + publishCustomVideoTrack = false + // 设置是否发布麦克风采集的音频流 + publishMicrophoneTrack = false + // 设置进入频道时是否自动订阅频道内其他用户的音频流 + autoSubscribeAudio = false + // 设置进入频道时是否自动订阅频道内其他用户的视频流 + autoSubscribeVideo = true +}) +``` + + +### 7. 设置美颜效果 + +调用 Beauty API 中 `setBeautyPreset` 方法设置使用的美颜参数的类型: + +- `DEFAULT`:默认且推荐的美颜参数。 +- `CUSTOM`:开发者自定义的美颜参数。 + +不同的美颜参数会带来不同的美颜效果。如果你没有特殊美颜要求,推荐你使用 `DEFAULT`。 + +```kotlin +mFaceUnityApi.setBeautyPreset(if (enable) BeautyPreset.DEFAULT else BeautyPreset.CUSTOM) +``` +
    通过 Beauty API 的 setBeautyPreset 方法,你可以实现基础美颜功能。但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。
    + +### 8. 离开频道 + +调用 `RtcEngine` 类的 `leaveChannel` 离开频道。 + +```kotlin +mRtcEngine.leaveChannel() +``` + +### 9. 销毁资源 + +调用 Beauty API 的 `release` 销毁 Beauty API。 + +```kotlin +mFaceUnityApi.release() +``` + +调用美颜 SDK 的 `destroy` 销毁 `FURenderKit`。 + +```kotlin +FURenderKit.destroy() +``` + +调用 `RtcEngine` 的 `destroy` 销毁 `RtcEngine`。 + +```kotlin +RtcEngine.destroy() +``` + + +### API 时序图 + +![](https://web-cdn.agora.io/docs-files/1692606503301) \ No newline at end of file diff --git "a/markdown/beauty/\347\233\270\350\212\257/beauty_integration_faceunity_ios.md" "b/markdown/beauty/\347\233\270\350\212\257/beauty_integration_faceunity_ios.md" new file mode 100644 index 00000000000..48fc27470d9 --- /dev/null +++ "b/markdown/beauty/\347\233\270\350\212\257/beauty_integration_faceunity_ios.md" @@ -0,0 +1,311 @@ +本文介绍如何通过声网美颜场景化 API (Beauty API) 集成相芯美颜到实时音视频互动中。 + +## 示例项目 + +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main) 示例项目供你参考。 + +## 准备开发环境 + +### 前提条件 + +- [Git](https://git-scm.com/downloads) +- [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) +- [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 12.0 及以上 +- iOS 设备,版本 13.0 及以上 +- 有效的苹果开发者账号 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) +- 已联系相芯技术获取最新的美颜 SDK、美颜资源、美颜证书 + + +### 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +跑通示例项目时,你需要将**鉴权机制**设置为**调试模式:APP ID**。从头搭建 Android 项目集成美颜功能时,声网推荐你将**鉴权机制**设置为**安全模式:APP ID + Token**,以保障安全性。 + + +### 创建 iOS 项目 + +在 Xcode 中进行以下操作,在你的 app 中实现场景化美颜功能: + +1. [创建一个新的项目](https://help.apple.com/xcode/mac/current/#/dev07db0e578),**Application** 选择 **App**,**Interface** 选择 **Storyboard**,**Language** 选择 **Swift**。 + +
    如果你没有添加过开发团队信息,会看到 Add account… 按钮。点击该按钮并按照屏幕提示登入 Apple ID,点击 Next,完成后即可选择你的 Apple 账户作为开发团队。
    + +2. 为你的项目设置[自动签名](https://help.apple.com/xcode/mac/current/#/dev23aab79b4)。 + +3. 设置部署你的 app 的[目标设备](https://help.apple.com/xcode/mac/current/#/deve69552ee5)。 + +4. 添加项目的设备权限。在项目导航栏中打开 `info.plist` 文件,编辑[属性列表](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6),添加以下属性: + + | key | type | value | + | -------------------------------------- | ------ | ------------------------------------------------------------ | + | Privacy - Microphone Usage Description | String | 使用麦克风的目的,例如 for a live interactive streaming | + | Privacy - Camera Usage Description | String | 使用摄像头的目的,例如 for a live interactive streaming | + +
    • 如果你的项目中需要添加第三方插件或库(例如第三方摄像头),且该插件或库的签名与项目的签名不一致,你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation
    • 更多注意事项,可以参考 Preparing Your App for Distribution
    + +5. 将相芯美颜 SDK 集成到你的项目中。请联系相芯技术支持获取美颜 SDK、美颜资源、证书等文件。下载并解压文件,然后添加到美颜项目对应的文件路径下: + + | 文件 | 项目路径 | + |------------------|----------------| + | FaceUnity/Lib/Resources | iOS/FULib | + | 证书:authpack.h | iOS/BeautyAPi/FUBeauty/authpack.h | + +6. 将声网美颜场景化 API 集成到你的项目中。添加 [iOS/BeautyAPi/BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main/iOS/BeautyAPi/BeautyAPI) 目录下的文件到项目中,具体文件如下: + + - `Render/FURender` 文件夹 + - `FURender` 文件夹 + - `BeautyAPI.h` 文件 + - `BeautyAPI.m` 文件 + - `BeautyConfig.h` 文件 + - `BeautyConfig.m` 文件 + +
    为方便后续代码升级,请不要修改你添加的这些文件的名称和路径。
    + +7. 将声网 RTC SDK 和相芯美颜依赖库集成到你的项目。 + + 1. 在终端里进入项目根目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。 + 2. 打开 `Podfile` 文件,修改文件为如下内容。注意将 `Your App` 替换为你的 Target 名称。 + + ```shell + platform :ios, '9.0' + # 替换成你的 target 名称 + target 'Your App' do + # x.y.z 请填写具体的 RTC SDK 版本号,如 4.0.1 或 4.0.0.4 + # 可通过互动直播发版说明获取最新版本号 + pod 'AgoraRtcEngine_iOS', 'x.y.z' + # 配置相芯美颜的依赖库 + pod 'fuLib', :path => 'fu.podspec' + end + ``` + + +8. 在终端内运行 pod install 命令安装声网 RTC SDK 和相芯美颜依赖。 + +9. 成功安装后,Terminal 中会显示 Pod installation complete!。项目文件夹下会生成一个后缀为 .xcworkspace 的文件,通过 Xcode 打开该文件进行后续操作。 + +## 实现美颜 + +本节展示如何在直播间内实现美颜功能,参考 [API 时序图](#api-时序图)可查看总览。声网 RTC SDK 承担实时音视频的业务,相芯美颜 SDK 提供美颜功能,声网 Beauty API 封装了两个 SDK 中的 API 调用逻辑以简化你需要实现的代码逻辑。通过 Beauty API,你可以实现基础美颜功能,但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。 + +### 1. 初始化 AgoraRtcEngineKit + +调用声网 RTC SDK 中的 `sharedEngineWithConfig` 创建并初始化 `AgoraRtcEngineKit` 对象。调用 `enableVideo` 开启声网 SDK 的视频模块。 + +```swift +// 初始化 AgoraRtcEngineKit +private lazy var rtcEngine: AgoraRtcEngineKit = { + let config = AgoraRtcEngineConfig() + // 传入你从控制台获取的声网项目的 APP ID + config.appId = KeyCenter.AppId + config.channelProfile = .liveBroadcasting + let rtc = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self) + // 设置用户角色为主播,主播可以发送音视频流也可以接收音视频流 + rtc.setClientRole(.broadcaster) + // 开启 SDK 音频模块 + rtc.enableAudio() + // 开启 SDK 视频模块 + rtc.enableVideo() + // 设置默认音频路由为扬声器 + rtc.setDefaultAudioRouteToSpeakerphone(true) + return rtc +}() +``` + +### 2. 初始化美颜和 Beauty API + +创建 `FUBeautyRender` 和 Beauty API 对象。Beauty API 对象基于 `FUBeautyRender` 对象封装。 + + +```swift +private lazy var fuRender = FUBeautyRender() +private lazy var beautyAPI = BeautyAPI() +``` + + +调用 `initialize` 初始化 Beauty API 对象。你需要在 `config` 参数中传入如下字段: + +- `AgoraRtcEngineKit`:传入之前初始化的 `AgoraRtcEngineKit` 对象。 +- `beautyRender`:传入之前初始化的 `FUBeautyRender` 对象。 +- `captureMode`:视频的采集模式: + - 如果你使用声网模块采集视频,请传入 `CaptureMode.Agora`。 + - 如果自定义采集视频,请传入 `CaptureMode.Custom`。 +- `statsEnable`:是否开启美颜统计数据回调。`true` 代表开启,`false` 代表不开启。开启后,会有周期性回调事件。 +- `statsDuration`:美颜统计数据回调的周期。单位为秒。 +- `eventCallback`:监听的美颜统计数据回调事件。 + + +```swift +let config = BeautyConfig() +// AgoraRtcEngineKit +config.rtcEngine = rtcEngine +// 设置视频采集模式 +// .agora 意味着使用声网模块采集视频 +// .custom 意味着使用开发者自定义采集视频 +config.captureMode = capture == "Custom" ? .custom : .agora +// FUBeautyRender +config.beautyRender = fuRender +// 是否开启美颜统计数据 +// 开启后,会有周期性回调事件 +config.statsEnable = false +// 设置美颜统计数据的统计区间为 1 秒(默认) +config.statsDuration = 1 +// Beauty API 的回调事件 +config.eventCallback = { stats in + print("min == \(stats.minCostMs)") + print("max == \(stats.maxCostMs)") + print("averageCostMs == \(stats.averageCostMs)") +} + +// 初始化 Beauty API 对象 +let result = beautyAPI.initialize(config) +if result != 0 { + print("initialize error == \(result)") +} +``` + + +### 3. 开启美颜 + +调用 Beauty API 的 `enable` 方法并将参数设为 `true` 开启美颜。 + +```swift +beautyAPI.enable(true) +``` + +### 4. 开启视频采集 + +开发者可以使用声网模块采集视频,也可以自定义采集视频。本节介绍在这两种场景下如何开启视频采集。 + +#### 使用声网模块采集视频 + +使用声网模块采集视频视频时,调用 Beauty API 的 `setupLocalVideo` 开启本地视图。 + +```swift +beautyAPI.setupLocalVideo(localView, renderMode: .hidden) +``` + + +#### 自定义视频采集 + +自定义视频采集时,你需要通过 `AgoraRtcEngineKit` 类的 `setVideoFrameDelegate` 注册原始视频数据观测器并在其中实现 `onCaptureVideoFrame` 函数。 + +通过 Beauty API 的 `onFrame` 函数,你可以将外部自采集的视频数据传入并进行处理。 + + +```swift +if capture == "Custom" { + // 注册原始视频数据观测器 + // 自定义视频采集时,即 CaptureMode 为 Custom 时,你需要注册原始视频观测器 + rtcEngine.setVideoFrameDelegate(self) +} + +extension BeautyViewController: AgoraVideoFrameDelegate { + func onCapture(_ videoFrame: AgoraOutputVideoFrame, sourceType: AgoraVideoSourceType) -> Bool { + // 将外部自采集的视频数据传入声网 SDK + guard let pixelBuffer = videoFrame.pixelBuffer else { return true } + beautyAPI.onFrame(pixelBuffer) { pixelBuffer in + videoFrame.pixelBuffer = pixelBuffer + } + + return true + } + + // 设置是否对原始视频数据作镜像处理 + func getMirrorApplied() -> Bool { + beautyAPI.getMirrorApplied() + } + + // 设置观测点为本地采集时的视频数据 + func getObservedFramePosition() -> AgoraVideoFramePosition { + .postCapture + } + + // 实现视频观测器中的其他回调函数 + ... +} +``` + + + +### 5. 加入频道 + +调用 `AgoraRtcEngineKit` 类的 `joinChannelByToken` 加入频道,同时传入如下参数: + +- `token`:用于鉴权的动态密钥。如果在[创建声网项目](#创建声网项目)时启用**调试模式**,那么将 `token` 参数传空。如果启用**安全模式**,那么你先参考[使用 Token 鉴权](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/token_server_ios_ng?platform=iOS)在你的业务服务端生成 Token,然后将生成的 Token 传入该参数。 +- `channelId`:频道名。 +- `mediaOptions`:频道媒体设置选项。 + + + +```swift +let mediaOption = AgoraRtcChannelMediaOptions() +mediaOption.clientRoleType = isBroadcast ? .broadcaster : .audience +// 设置进入频道时是否自动订阅频道内其他用户的音频流 +mediaOption.autoSubscribeAudio = true +// 设置进入频道时是否自动订阅频道内其他用户的视频流 +mediaOption.autoSubscribeVideo = true +// 设置是否发布摄像头采集的视频流(适用于使用声网模块采集视频的情况) +// 用户角色为主播时,设置发布 +// 用户角色为观众时,设置不发布 +mediaOption.publishCameraTrack = mediaOption.clientRoleType == .broadcaster +// 设置是否发布自定义采集的视频流(适用于自定义采集视频的情况) +mediaOption.publishCustomVideoTrack = false +// 设置是否发布麦克风采集的音频流 +// 用户角色为主播时,设置发布 +// 用户角色为观众时,设置不发布 +mediaOption.publishMicrophoneTrack = mediaOption.clientRoleType == .broadcaster + +// 加入频道 +let result = rtcEngine.joinChannel(byToken: nil, channelId: channelName ?? "", uid: 0, mediaOptions: mediaOption) +if result != 0 { + print("join failed") +} +``` + + +### 6. 设置美颜效果 + +调用 Beauty API 中 `setBeautyPreset` 方法设置使用的美颜参数的类型: + +- `BeautyPresetModeDefault`:默认且推荐的美颜参数。 +- `BeautyPresetModeCustom`:开发者自定义的美颜参数。 + +不同的美颜参数会带来不同的美颜效果。如果你没有特殊美颜要求,推荐你使用 `BeautyPresetModeDefault`。 + +```swift +beautyAPI.setBeautyPreset(.default) +``` + +
    通过 Beauty API 的 setBeautyPreset 方法,你可以实现基础美颜功能。但是如果你还需要更丰富的美颜效果,例如贴纸、美妆风格,你可以直接调用美颜 SDK 中的 API。
    + +### 7. 离开频道 + +调用 `AgoraRtcEngineKit` 类的 `leaveChannel` 离开频道。 + +```swift +rtcEngine.leaveChannel() +``` + + +### 8. 销毁资源 + +调用 Beauty API 的 `destroy` 销毁 Beauty API。 + +```swift +beautyAPI.destroy() +``` + +
    Beauty API 自 1.0.2 版起,已将存在笔误的 destory 方法名修正为 destroy
    + +调用 `AgoraRtcEngineKit` 的 `destroy` 销毁 `AgoraRtcEngineKit`。 + +```swift +AgoraRtcEngineKit.destroy() +``` + + +### API 时序图 + +![](https://web-cdn.agora.io/docs-files/1693995863450) \ No newline at end of file diff --git "a/markdown/beauty/\347\233\270\350\212\257/beauty_run_github_project_faceunity_android.md" "b/markdown/beauty/\347\233\270\350\212\257/beauty_run_github_project_faceunity_android.md" new file mode 100644 index 00000000000..f0fe5e9bf9c --- /dev/null +++ "b/markdown/beauty/\347\233\270\350\212\257/beauty_run_github_project_faceunity_android.md" @@ -0,0 +1,75 @@ +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main) 示例项目供你参考。本文介绍如何快速跑通该示例项目,体验相芯美颜效果。 + +## 前提条件 + +- [Git](https://git-scm.com/downloads) +- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 11 +- [Android Studio](https://developer.android.com/studio/) 3.5 及以上 +- Android 手机,版本 Android 5.0(API Level 21)及以上 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) + +
    声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。
    + + +## 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + + +## 克隆仓库 + +运行以下命令克隆仓库到本地: + +```shell +git clone git@github.com:AgoraIO-Community/BeautyAPI.git +``` + +## 集成第三方美颜 SDK + +1. 联系相芯技术支持获取最新的美颜 SDK、美颜资源、美颜证书。 + +2. 下载并解压美颜资源,然后将资源中如下文件添加到美颜示例项目对应的文件路径下: + + | SDK 文件 | 项目路径 | + |-----|-----| + | 美妆资源:例如 `naicha.bundle` | app/src/main/assets/beauty_faceunity/makeup | + | 贴纸资源:例如 `fashi.bundle` | app/src/main/assets/beauty_faceunity/sticker | + | 证书:`authpack.java` | app/src/main/java/io/agora/beauty/demo/authpack.java | + +3. 在 `app/build.gradle` 文件中,将 `applicationId` 修改为你的包名,例如 `com.example.app`。包名用于在设备上唯一标识应用程序。在开发应用时,你需要设置包名。在此处设置的包名需要与你申请美颜 SDK 时提供的包名一致。 + + ```java + android { + defaultConfig { + applicationId "io.agora.entfull" + ... + } + } + ``` + +## 配置示例项目 + +运行美颜项目前,你需要在 `local.properties` 文件中添加并设置如下参数: + +```shell +AGORA_APP_ID = "YOUR_APP_ID" +``` + +你可以在[创建声网项目](#create)后,从控制台获取参数的值,详情如下: + +| 参数 | 描述 | 获取方式 | +|----|----|----| +| `AGORA_APP_ID` | 声网项目的 App ID | [获取 App ID](https://docportal.shengwang.cn/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#获取-app-id) | + + +## 编译并运行示例项目 + +1. 开启 Android 设备的开发者选项,打开 USB 调试,通过 USB 连接线将 Android 设备接入电脑。 + +2. 用 Android Studio 打开 `BeautyAPI/Android` 文件夹。 + +3. 在 Android Studio 中,点击 **Sync Project with Gradle Files** 按钮,让项目与 Gradle 文件同步。 + +4. 待同步成功后,点击 `Run 'app'`。片刻后,美颜应用便会安装到你的 Android 设备上。 + +5. 打开美颜应用,进行体验。 diff --git "a/markdown/beauty/\347\233\270\350\212\257/beauty_run_github_project_faceunity_ios.md" "b/markdown/beauty/\347\233\270\350\212\257/beauty_run_github_project_faceunity_ios.md" new file mode 100644 index 00000000000..14996f5e884 --- /dev/null +++ "b/markdown/beauty/\347\233\270\350\212\257/beauty_run_github_project_faceunity_ios.md" @@ -0,0 +1,69 @@ +声网在 GitHub 上提供开源 [BeautyAPI](https://github.com/AgoraIO-Community/BeautyAPI/tree/main) 示例项目供你参考。本文介绍如何快速跑通该示例项目,体验相芯美颜效果。 + +## 前提条件 + +- [Git](https://git-scm.com/downloads) +- [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) +- [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 13.0 及以上 +- iOS 设备,版本 11.0 及以上 +- 有效的苹果开发者账号 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora%20Platform/sign_in_and_sign_up) + +
    声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。
    + + +## 创建声网项目 + +~f42d44d0-2ac7-11ee-b391-19a59cc2656e~ + +## 克隆仓库 + +运行以下命令克隆仓库到本地: + +```shell +git clone git@github.com:AgoraIO-Community/BeautyAPI.git +``` + +## 集成第三方美颜 SDK + +1. 联系相芯技术支持获取最新的美颜 SDK、美颜资源、美颜证书。 + +2. 下载并解压美颜资源,然后将如下文件添加到美颜示例项目对应的文件路径下: + + |文件 | 项目路径 | + |-----|-----| + | FaceUnity/Lib/Resources | iOS/FULib | + | 证书:authpack.h | iOS/BeautyAPi/FUBeauty/authpack.h | + + +## 配置示例项目 + +1. 运行美颜项目前,你需要在 `iOS/BeautyAPi/KeyCenter.swift` 文件中设置如下参数: + + ```swift + static let AppId: String = <#YOUR_APP_ID#> + ``` + + 你可以在[创建声网项目](#create)后,从控制台获取这些参数的值,详情如下: + + | 参数 | 描述 | 获取方式 | + |----|----|----| + | `AppId` | 声网项目的 App ID | [获取 App ID](https://docportal.shengwang.cn/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#获取-app-id) | + + +2. 在 `iOS/` 目录下运行 `pod install`,然后等待依赖库安装完成。 + + +## 编译并运行示例项目 + +![](https://web-cdn.agora.io/docs-files/1690276905446) + +1. 连接上 iOS 设备后,点击 `BeautyAPi.xcodeproj` 文件以通过 Xcode 打开项目,并在 **iOS Device** 选项中勾选上你的 iOS 设备。 + +2. 在项目 **TARGETS** 下的 **Signing & Capabilities** 界面勾选 **Automatically manage signing**,配置你的苹果开发者账号和 **Bundle Identifier**。Bundle ID 是设备上应用程序的唯一标识。在开发应用时,你需要设置 Bundle ID。在此处设置的 Bundle ID 需要与你申请相芯美颜 SDK 时提供的 Bundle ID 一致。 + +3. 点击 开始编译。 + +4. 编译成功后,你的 iOS 设备上会出现美颜应用。在 iOS 系统设置中将该应用设为信任开发者后你才能打开应用。 + +5. 打开美颜应用,进行体验。 \ No newline at end of file diff --git "a/markdown/beauty/\347\233\270\350\212\257Android\346\227\266\345\272\217\345\233\276.wsd" "b/markdown/beauty/\347\233\270\350\212\257Android\346\227\266\345\272\217\345\233\276.wsd" new file mode 100644 index 00000000000..633b143d2d2 --- /dev/null +++ "b/markdown/beauty/\347\233\270\350\212\257Android\346\227\266\345\272\217\345\233\276.wsd" @@ -0,0 +1,46 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "相芯美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 RtcEngine == +app -> rtc: RtcEngine.create \n创建并初始化 RtcEngine 对象 +== 初始化美颜 SDK == +app -> beauty: registerFURender \n初始化 FURenderKit +app -> beauty: loadAIProcessor \n加载 AI 道具 +== 初始化 Beauty API == +app -> api: createFaceUnityBeautyAPI \n创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +app -> rtc: enableVideo \n开启视频模块 +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: registerVideoFrameObserver \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannel +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: release \n销毁 Beauty API 对象 +app -> beauty: destroy \n销毁 FURenderKit 对象 +app -> rtc: destroy \n销毁 RtcEngine 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git "a/markdown/beauty/\347\233\270\350\212\257iOS\346\227\266\345\272\217\345\233\276.wsd" "b/markdown/beauty/\347\233\270\350\212\257iOS\346\227\266\345\272\217\345\233\276.wsd" new file mode 100644 index 00000000000..4d4f6b4433f --- /dev/null +++ "b/markdown/beauty/\347\233\270\350\212\257iOS\346\227\266\345\272\217\345\233\276.wsd" @@ -0,0 +1,44 @@ +@startuml +autonumber +title 美颜场景化 API (Beauty API) 时序图 +participant "App" as app +participant "声网 RTC SDK" as rtc +participant "Beauty API" as api +participant "相芯美颜 SDK" as beauty +app -> app: 进入预览和直播间 +== 初始化 AgoraRtcEngineKit == +app -> rtc: sharedEngineWithConfig \n创建并初始化 AgoraRtcEngineKit 对象 +== 初始化美颜 SDK == +app -> beauty: 创建并初始化 FUBeautyRender +== 初始化 Beauty API == +app -> api: 创建 Beauty API 对象 +alt #WhiteSmoke 使用声网模块采集视频 +app -> api: initialize(captureMode.**Agora**) \n初始化 Beauty API 对象 +end +alt #AntiqueWhite 自定义视频采集 +app -> api: initialize(captureMode.**Custom**) \n初始化 Beauty API 对象 +end +app -> rtc: enableVideo \n开启视频模块 +== 开启美颜 == +app -> api: enable +== 开启视频采集 == +alt #WhiteSmoke 使用声网模块采集视频 +app -> rtc: setupLocalVideo \n设置本地视图 +end +alt #AntiqueWhite 开发者自定义视频采集 +app -> rtc: setVideoFrameDelegate \n注册原始视频数据观测器 +api -->> rtc: onFrame \n传递原始视频数据 +rtc -->> app: onCaptureVideoFrame \n传递原始视频数据 +end +== 加入频道 == +app -> rtc: joinChannelByToken +== 设置美颜效果 == +app -> api: setBeautyPreset \n设置是否使用默认且推荐的美颜参数 +app -> beauty: 如需更多美颜效果,例如贴纸、美妆风格,可直接调用美颜 SDK 的 API +== 离开频道 == +app -> rtc: leaveChannel +== 销毁资源 == +app -> api: destroy \n销毁 Beauty API 对象 +app -> rtc: destroy \n销毁 AgoraRtcEngineKit 对象 +app -> app: 退出预览和直播间 +@enduml \ No newline at end of file diff --git a/markdown/showroom/best_practice/showroom_hq_video.md b/markdown/showroom/best_practice/showroom_hq_video.md new file mode 100644 index 00000000000..659e1b7e8ff --- /dev/null +++ b/markdown/showroom/best_practice/showroom_hq_video.md @@ -0,0 +1,103 @@ +在秀场直播中,观众希望观看高清的直播视频。实现高清视频需要考虑用户设备和网络环境等因素。本文介绍声网自适应高清策略在秀场直播解决方案中的最佳实践。 + + +## 单人直播场景 + +单人直播场景下,你需要为主播和观众进行设置,以获得高清视频体验。 + +### 主播设置 + +- 调用 `queryDeviceScore` 查询主播的用户设备等级:高端、中端、低端。在后续步骤中,你需要为不同等级的设备进行不同的视频配置。 + +- 调用 [`setCameraAutoFocusFaceModeEnabled`](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/API%20Reference/java_ng/API/toc_video_device_management.html#api_irtcengine_setcameraautofocusfacemodeenabled) 开启摄像头自动对焦人脸的功能。 + +- 调用 [`setCameraCapturerConfiguration`](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/API%20Reference/java_ng/API/toc_video_device_management.html#api_irtcengine_setcameracapturerconfiguration) 并将 `config` 参数中的 `followEncodeDimensionRatio` 字段设为 `true`,设置本地采集的视频宽高比跟随编码的视频宽高比。 + +- 编码视频属性包含编码视频分辨率、视频帧率、码率。你可以通过 [`setVideoEncoderConfiguration`](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/API%20Reference/java_ng/API/toc_video_process.html#api_irtcengine_setvideoencoderconfiguration) 方法中 `config` 参数中的 `dimensions`、`frameRate`、`bitrate` 字段设置主播端的编码视频属性。 + + | 设备等级 | 视频分辨率 | 视频帧率 (fps) | 视频码率 | + | ---- | ----- | ------ | ------------------- | + | 高端 | 1080P | 24 | `STANDARD_BITRATE(0)` | + | 中端 | 720P | 24 | `STANDARD_BITRATE(0)` | + | 低端 | 720P | 15 | `STANDARD_BITRATE(0)` | + +- 调用 [`enableDualStreamMode`](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/API%20Reference/java_ng/API/toc_stream_management.html#api_irtcengine_enabledualstreammode3) 在主播端开启双流模式。视频大流更加高清,视频小流更加流畅。你可以在 `streamConfig` 参数中将主播发送的视频小流设置为如下值: + + | 设备等级 | 视频分辨率 | 视频帧率 (fps) | 视频码率 (Kbps) | + | ---- |----- | ------ | -------| + | 高端 |540P | 15 | 1100 | + | 中端 |360P | 15 | 680 | + | 低端 |360P | 15 | 680 | + + +### 观众设置 + +主播开启双流模式后,观众端可以通过 [`setRemoteVideoStreamType`](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/API%20Reference/java_ng/API/toc_stream_management.html#api_irtcengine_setremotevideostreamtype) 方法设置接收视频大流或视频小流。视频大流更加高清,视频小流更加流畅,你可以根据观众的设备性能和网络环境进行选择和切换。 + + +## 观众连麦场景 + +观众与主播连麦的场景下,你需要为主播、上麦观众、普通观众进行设置,以获得高清视频体验。 + +### 主播设置 + +主播设置详见[单人直播主播设置](#主播设置)。 + +### 上麦观众设置 + +调用 `setVideoEncoderConfiguration` 并通过 `config` 参数中如下字段设置编码视频属性: + +- `dimensions`:设置分辨率为 180 x 360。 +- `frameRate`:设置帧率为 15 fps。 +- `bitrate`:设置码率为 `STANDARD_BITRATE(0)`。 + + +### 普通观众设置 + +普通观众会接收到主播和上麦观众的视频流。当某个主播(主播或上麦观众)的视频画面在 App 观众端的 UI 界面上占据更大的区域时,可以为这个主播(俗称主屏主播)开启超分功能。详见[注意事项](#注意事项)。 + +## PK 连麦场景 + +主播跨房间 PK 连麦的场景下,你需要为多个房间的主播和观众进行设置,以获得高清视频体验。 + +### 主播设置 + +- 调用 `queryDeviceScore` 查询主播的用户设备等级:高端、中端、低端。在后续步骤中,你需要为不同等级的设备进行不同的视频配置。 + +- 编码视频属性包含编码视频分辨率、视频帧率、码率。你可以通过 `setVideoEncoderConfiguration` 方法中 `config` 参数中的 `dimensions`、`frameRate`、`bitrate` 字段设置主播端的编码视频属性。 + + | 设备等级 | 视频分辨率 | 视频帧率 (fps) | 视频码率 | + | ---- | ----- | ------ | ------------------- | + | 高端 | 720P | 15 | `STANDARD_BITRATE(0)` | + | 中端 | 540P | 15 | `STANDARD_BITRATE(0)` | + | 低端 | 540P | 15 | `STANDARD_BITRATE(0)` | + +- 调用 `enableDualStreamMode` 在主播端开启双流模式。视频大流更加高清,视频小流更加流畅。你可以在 `streamConfig` 参数中将主播发送的视频小流设置为如下值: + + | 设备等级 | 视频分辨率 | 视频帧率 (fps) | 视频码率 (Kbps) | + | ---- |----- | ------ | -------| + | 高端 |360P | 15 | 680 | + | 中端 |360P | 15 | 680 | + | 低端 |360P | 15 | 680 | + +### 观众设置 + +主播开启双流模式后,观众端可以通过 `setRemoteVideoStreamType` 方法设置接收视频大流或视频小流。视频大流更加高清,视频小流更加流畅,你可以根据观众的设备性能和网络环境进行选择和切换。 + +## 伪直播场景 + +伪直播场景下,你需要为视频源和观众进行设置,以获得高清视频体验。 + +//TODO 本期不写 + +## 注意事项 + +- 为达到自适应高清效果,除了按照如上步骤设置代码逻辑外,你还需要联系[声网技术支持](https://docs.agora.io/cn/Agora%20Platform/ticket?platform=All%20Platforms)。声网技术支持会根据你的直播场景、用户角色、设备等级、网络带宽情况,为你配置下发开启一系列功能: + + - **PVC**:PVC(Perceptual Video Coding,视频感知编码)是一种在保障同等画质的前提下降低带宽消耗的视频编码方式。 + - **超分**:超分辨率可以提升本地看到远端视频的画面分辨率。 + - **SVC**:SVC(Scalable Video Coding,可伸缩视频编码)技术能够将视频流分为多个不同的层次,每个层次具有不同的编码质量和码率。这些层次可以独立地解码和传输,因而能够根据用户的网络环境和设备性能自适应调节视频流的编码质量,保证所有用户的观看体验。 + - **H.265**:视频流的一种编解码类型。为了达到高清效果,在某些情况下需要使用 H.265 类型。 + - **硬编硬解**:硬件编码和硬件解码。为了达到高清效果,在某些情况下需要使用硬编硬解。 + +- `queryDeviceScore` 方法仅在部分特殊版 RTC SDK 中提供。请联系声网技术支持获取。 \ No newline at end of file diff --git a/markdown/showroom/guide/showroom_tupu_video_moderation.md b/markdown/showroom/guide/showroom_tupu_video_moderation.md new file mode 100644 index 00000000000..00b9d9e1802 --- /dev/null +++ b/markdown/showroom/guide/showroom_tupu_video_moderation.md @@ -0,0 +1,77 @@ +视频审核功能支持对秀场直播的视频进行内容审核,精准高效过滤违规视频,提高审核效率,降低人工审核成本。 + +## 技术原理 + +集成声网 RTC SDK 后,你可以对声网频道内的视频流使用第三方[图普视频审核](https://shenhe.tuputech.com/video_moderation)服务。当频道内有用户发送视频流时,审核结果会由第三方图普服务器直接返回到你的服务器。具体流程如下: + +![](https://web-cdn.agora.io/docs-files/1673867371709) + +1. 声网 RTC SDK 从频道内的视频流中截取内容,加密传输至声网服务器。 +2. 声网服务器对视频流信息进行封装,然后加密传输至第三方审核服务商。 +3. 第三方审核服务商将声网视频流信息和审核结果返回到你的回调服务器。 +4. 根据审核结果添加业务逻辑。 + +
    你需要自行准备接收审核结果回调的业务服务器。
    + +## 前提条件 + +实现该进阶功能前,请确保你已经实现基础的秀场直播功能,如创建房间、加入房间、设置本地视图等。详见[基础功能](./showroom_integration_android?platform=All%20Platforms)。 + +## 实现步骤 + +### 1. 检查 Token 取值 + +为了保障视频审核过程中,直播间视频的安全性,声网需要你使用最新的 Token 加入频道。因此,开启视频审核时,你需要先检查在实现[基础功能](./showroom_integration_android?platform=All%20Platforms)时,调用 `joinChannel` 或 `joinChannelEx` 时是否将声网 RTC AccessToken2 传入 `token` 参数中。具体步骤如下: + +1. 在[项目管理](https://console.shengwang.cn/projects)页面找到你为秀场直播创建的声网项目,检查**鉴权机制**是否为安全模式: + - 如果为安全模式,进行第 2 步检查。 + - 如果不为安全模式,则点击**配置**。在**项目配置**页面,启用主要证书并删除无证书: + + ![](https://web-cdn.agora.io/docs-files/1692774894211) + ![](https://web-cdn.agora.io/docs-files/1692774903338) + ![](https://web-cdn.agora.io/docs-files/1692774910579) + ![](https://web-cdn.agora.io/docs-files/1692774917077) + +2. 检查你传入的 `token` 参数是否为你在服务端生成 RTC AccessToken2。如果你对 `token` 参数未传值,或者传入在项目管理页面生成的临时 Token,或者传入 RTC AccessToken,那么你需要生成 RTC AccessToken2 并重新传参。生成步骤详见[使用 Token 鉴权](https://docportal.shengwang.cn/cn/live-streaming-premium-4.x/token_server_android_ng?platform=Android)。 + +### 2. 开通视频审核服务 + +联系[声网技术支持](https://docs.agora.io/cn/Agora%20Platform/ticket?platform=All%20Platforms),申请开通视频审核服务。你需要声明你开通的视频审核用于秀场直播场景,并填写视频审核服务的相关信息。部分配置项的说明如下: + +| 配置项 | 说明 | +| ------------ | ------------------------------------------------------------ | +|
    检测间隔
    | 从视频流中截取内容并送审的时间间隔。截取的内容会先加密传输到声网服务器,封装必要的视频流信息,然后加密传输到第三方审核服务商。 | +| 内容保存 | 你可以选择是否存储所有送审内容,以便后期人工复核。默认保存 7 天。 | +| 回调地址 | 你用于接收审核结果的服务器地址,需要支持 HTTPS。
    视频审核在第一个用户加入频道后自动开始,在所有用户都离开频道后自动停止。声网推荐你接收全部审核结果,你也可以联系声网调整为仅接收违规的审核结果。
    | + +### 3. 接收视频审核结果回调 + +审核结果中的 `tag` 字段中包含公共字段和其他字段。 + +#### 公共字段 + +| 字段 | 数据类型 | 字段解释 | +| :------ | :----- | :----------------------------------------------------------- | +| `source` | String | 固定为 `"agora"`,代表审核内容是来自声网频道内的视频流。 | +| `cname` | String | 审核结果对应的频道名。 | +| `uid` | Int | 审核结果对应的用户 ID。 | +| `sid` | String | 审核结果对应的用户会话。用户从加入到退出当前频道视为一次会话。 | +| `requestId` | String | 请求 ID,用于标识声网向第三方服务商发送的审核请求。 | +| `timestamp` | Int | 审核结果对应片段的起始时间点。格式为 UTC 时间,时区为 UTC+0,由年、月、日、小时、分钟、秒和毫秒组成。例如:`20230110080616876` 代表 2023 年 1 月 10 日 8 点 6 分 16 秒 876 毫秒。| + +#### 其他字段 + +其它字段详见[图普异步图片识别](http://cloud.doc.tuputech.com/zh/API/image/asyncImage.html)的《4. 识别结果回调请求》小节。 + +#### 回调示例 + +完整的回调示例如下: + +```json +{ + "json": "{\"54bcfc6c329af61034f7c2fc\":{\"fileList\":[{\"label\":1,\"name\":\"http://cos.ap-guangzhou.myqcloud.com/7-1252177232//cloud-api/storage-0831/2023-01-10/18-1/1673346487085260/276271.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\\u0026X-Amz-Credential=AKIDvc3E8l8D1g4AzXpqZ1TgcHfmcBSTDgso%2F20230110%2Fap-guangzhou%2Fs3%2Faws4_request\\u0026X-Amz-Date=20230110T102807Z\\u0026X-Amz-Expires=86400\\u0026X-Amz-SignedHeaders=host\\u0026X-Amz-Signature=70194025378b808e007b312d49e09f79aec724b6c75f66926c3899808310d2e0\",\"rate\":0.8984967729559958,\"review\":false,\"subLabel\":{\"label\":18,\"rate\":0.21453628821023063,\"review\":false},\"tag\":\"{\\\"callbackData\\\":\\\"test-callbackData\\\",\\\"cname\\\":\\\"test-tupu\\\",\\\"requestId\\\":\\\"B05EE55820AF449EBC007EB1E17A45QQ\\\",\\\"sid\\\":\\\"B05EE55820AF449EBC007EB1E17A4511\\\",\\\"source\\\":\\\"agora\\\",\\\"timestamp\\\":20230110102806386,\\\"uid\\\":123456}\"}],\"reviewCount\":0,\"statistic\":[0,1,0]},\"5b7be1f59b0c77a8c2afb351\":{\"fileList\":[{\"faceId\":\"非政治人物\",\"facePosition\":[[0.30214843,0.1875],[0.50045574,0.1875],[0.50045574,0.36953124],[0.30214843,0.36953124]],\"label\":2,\"name\":\"http://cos.ap-guangzhou.myqcloud.com/7-1252177232//cloud-api/storage-0831/2023-01-10/18-1/1673346487085260/276271.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\\u0026X-Amz-Credential=AKIDvc3E8l8D1g4AzXpqZ1TgcHfmcBSTDgso%2F20230110%2Fap-guangzhou%2Fs3%2Faws4_request\\u0026X-Amz-Date=20230110T102807Z\\u0026X-Amz-Expires=86400\\u0026X-Amz-SignedHeaders=host\\u0026X-Amz-Signature=70194025378b808e007b312d49e09f79aec724b6c75f66926c3899808310d2e0\",\"objects\":[{\"faceId\":\"非政治人物\",\"facePosition\":[[0.30214843,0.1875],[0.50045574,0.1875],[0.50045574,0.36953124],[0.30214843,0.36953124]],\"faceUrl\":\"\",\"label\":2,\"review\":false,\"similarity\":0,\"typeName\":\"非政治人物\"}],\"review\":false,\"similarity\":0,\"tag\":\"{\\\"callbackData\\\":\\\"test-callbackData\\\",\\\"cname\\\":\\\"test-tupu\\\",\\\"requestId\\\":\\\"B05EE55820AF449EBC007EB1E17A45QQ\\\",\\\"sid\\\":\\\"B05EE55820AF449EBC007EB1E17A4511\\\",\\\"source\\\":\\\"agora\\\",\\\"timestamp\\\":20230110102806386,\\\"uid\\\":123456}\",\"typeName\":\"非政治人物\"}]},\"5e1d634d2809c24f6d909bd3\":{\"fileList\":[{\"label\":0,\"name\":\"http://cos.ap-guangzhou.myqcloud.com/7-1252177232//cloud-api/storage-0831/2023-01-10/18-1/1673346487085260/276271.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\\u0026X-Amz-Credential=AKIDvc3E8l8D1g4AzXpqZ1TgcHfmcBSTDgso%2F20230110%2Fap-guangzhou%2Fs3%2Faws4_request\\u0026X-Amz-Date=20230110T102807Z\\u0026X-Amz-Expires=86400\\u0026X-Amz-SignedHeaders=host\\u0026X-Amz-Signature=70194025378b808e007b312d49e09f79aec724b6c75f66926c3899808310d2e0\",\"objects\":[],\"rate\":1,\"review\":false,\"tag\":\"{\\\"callbackData\\\":\\\"test-callbackData\\\",\\\"cname\\\":\\\"test-tupu\\\",\\\"requestId\\\":\\\"B05EE55820AF449EBC007EB1E17A45QQ\\\",\\\"sid\\\":\\\"B05EE55820AF449EBC007EB1E17A4511\\\",\\\"source\\\":\\\"agora\\\",\\\"timestamp\\\":20230110102806386,\\\"uid\\\":123456}\"}]},\"5e1d70adeec2874f7318dc52\":{\"fileList\":[{\"label\":0,\"labels\":[0,10,25,8,13],\"name\":\"http://cos.ap-guangzhou.myqcloud.com/7-1252177232//cloud-api/storage-0831/2023-01-10/18-1/1673346487085260/276271.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\\u0026X-Amz-Credential=AKIDvc3E8l8D1g4AzXpqZ1TgcHfmcBSTDgso%2F20230110%2Fap-guangzhou%2Fs3%2Faws4_request\\u0026X-Amz-Date=20230110T102807Z\\u0026X-Amz-Expires=86400\\u0026X-Amz-SignedHeaders=host\\u0026X-Amz-Signature=70194025378b808e007b312d49e09f79aec724b6c75f66926c3899808310d2e0\",\"rate\":0.9991529339260514,\"rates\":[0.9991529339260514,0.00021821152005362592,0.00014480834910299872,0.00011480319755559418,0.00010425450257236194],\"review\":false,\"tag\":\"{\\\"callbackData\\\":\\\"test-callbackData\\\",\\\"cname\\\":\\\"test-tupu\\\",\\\"requestId\\\":\\\"B05EE55820AF449EBC007EB1E17A45QQ\\\",\\\"sid\\\":\\\"B05EE55820AF449EBC007EB1E17A4511\\\",\\\"source\\\":\\\"agora\\\",\\\"timestamp\\\":20230110102806386,\\\"uid\\\":123456}\"}],\"reviewCount\":0,\"topNStatistic\":[{\"count\":1,\"label\":0}]},\"code\":0,\"message\":\"success\",\"nonce\":0.265046801,\"requestId\":\"73346487-e19a-49ac-944c-cd50081a2e61\",\"summary\":[{\"code\":0,\"name\":\"http://cos.ap-guangzhou.myqcloud.com/7-1252177232//cloud-api/storage-0831/2023-01-10/18-1/1673346487085260/276271.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\\u0026X-Amz-Credential=AKIDvc3E8l8D1g4AzXpqZ1TgcHfmcBSTDgso%2F20230110%2Fap-guangzhou%2Fs3%2Faws4_request\\u0026X-Amz-Date=20230110T102807Z\\u0026X-Amz-Expires=86400\\u0026X-Amz-SignedHeaders=host\\u0026X-Amz-Signature=70194025378b808e007b312d49e09f79aec724b6c75f66926c3899808310d2e0\",\"riskTask\":\"54bcfc6c329af61034f7c2fc\",\"riskType\":2,\"suggestion\":2,\"tag\":\"{\\\"callbackData\\\":\\\"test-callbackData\\\",\\\"cname\\\":\\\"test-tupu\\\",\\\"requestId\\\":\\\"B05EE55820AF449EBC007EB1E17A45QQ\\\",\\\"sid\\\":\\\"B05EE55820AF449EBC007EB1E17A4511\\\",\\\"source\\\":\\\"agora\\\",\\\"timestamp\\\":20230110102806386,\\\"uid\\\":123456}\"}],\"timestamp\":1673346488265}", + "signature": "r1xBiauHLkKdYu/7raB+lro7rlAOAEGYG2yLj/Tq2faGE7A++D1BYepUilknPAh0n8XrSfghS15tYSIdsaEsG8sOj5FQ2FrzbaK7zQmRyKuLDazSJTJdAacUvjIwqVULjEUHMIcGtdJhNeeLgxDovQ5mLG3+DQqxbitonDOnfVc=" +} +``` + +~5d39adb0-964e-11ed-98c1-83ef730c7692~ \ No newline at end of file diff --git a/markdown/showroom/resource_download.md b/markdown/showroom/resource_download.md index 4beb2648680..f13619e3fde 100644 --- a/markdown/showroom/resource_download.md +++ b/markdown/showroom/resource_download.md @@ -5,5 +5,5 @@ |------|-------| | Demo 应用 | [下载声动互娱](/cn/showroom/downloads) | | GitHub 示例项目 |
  • [Android 项目](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/tree/v3.0.0.1-all-Android/Android/scenes/show)
  • [iOS 项目](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/tree/v3.0.0-all-iOS/iOS/AgoraEntScenarios/Scenes/Show) | -| 声网视频 SDK | [下载声网视频 SDK](/cn/live-streaming-premium-4.x/downloads?platform=All%20Platforms) | +| 声网 RTC SDK | [下载声网 RTC SDK](/cn/live-streaming-premium-4.x/downloads?platform=All%20Platforms) | | 第三方美颜 SDK | 联系第三方技术支持获取 | \ No newline at end of file diff --git a/markdown/showroom/integration_android.md b/markdown/showroom/showroom_integration_android.md similarity index 97% rename from markdown/showroom/integration_android.md rename to markdown/showroom/showroom_integration_android.md index f870aadb1c8..23e9afd76c1 100644 --- a/markdown/showroom/integration_android.md +++ b/markdown/showroom/showroom_integration_android.md @@ -28,7 +28,7 @@
    创建项目后,Android Studio 会自动开始同步 gradle, 稍等片刻至同步成功后再进行下一步操作。
    -2. 使用 Maven Central 将声网视频 SDK 集成到你的项目中。 +2. 使用 Maven Central 将声网 RTC SDK 集成到你的项目中。 a. 在 `/Gradle Scripts/build.gradle(Project: )` 文件中添加如下代码,添加 Maven Central 依赖: @@ -51,7 +51,7 @@
    如果你的 Android 项目设置了 dependencyResolutionManagement,添加 Maven Central 依赖的方式可能存在差异。
    - b. 在 `/Gradle Scripts/build.gradle(Module: .app)` 文件中添加如下代码,将声网视频 SDK 集成到你的 Android 项目中: + b. 在 `/Gradle Scripts/build.gradle(Module: .app)` 文件中添加如下代码,将声网 RTC SDK 集成到你的 Android 项目中: ```java ... @@ -93,7 +93,7 @@ ## 实现秀场直播 -如下[时序图](#api-时序图)如何创建直播间、加入直播间、PK 连麦、观众连麦、退出直播间。声网 RTC SDK 承担实时音视频的业务,声网云服务承担信令消息和数据存储的业务。本节会详细介绍如何调用 RTC SDK 的 API 完成这些逻辑,但是信令消息的逻辑需要你参考时序图和[示例项目](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/tree/v3.0.0.1-all-Android/Android/scenes/show)自行实现。 +如下[时序图](#api-时序图)展示如何创建直播间、加入直播间、PK 连麦、观众连麦、退出直播间。声网 RTC SDK 承担实时音视频的业务,声网云服务承担信令消息和数据存储的业务。本节会详细介绍如何调用 RTC SDK 的 API 完成这些逻辑,但是信令消息的逻辑需要你参考时序图和[示例项目](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/tree/v3.0.0.1-all-Android/Android/scenes/show)自行实现。
    声网云服务为内部自研服务,暂不对外提供。你可以调用声网云服务的 API 用于测试,但是对于正式环境,声网建议你参考文档自行实现相似的一套服务。如需协助,请提交工单
    diff --git a/markdown/showroom/integration_ios.md b/markdown/showroom/showroom_integration_ios.md similarity index 96% rename from markdown/showroom/integration_ios.md rename to markdown/showroom/showroom_integration_ios.md index 941b8d7a672..a4f2a2affbc 100644 --- a/markdown/showroom/integration_ios.md +++ b/markdown/showroom/showroom_integration_ios.md @@ -43,7 +43,7 @@
    • 如果你的项目中需要添加第三方插件或库(例如第三方摄像头),且该插件或库的签名与项目的签名不一致,你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation
    • 更多注意事项,可以参考 Preparing Your App for Distribution
    -5. 将声网视频 SDK 集成到你的项目。开始前请确保你已安装 CocoaPods,如尚未安装 CocoaPods,参考 [Getting Started with CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) 安装说明。 +5. 将声网 RTC SDK 集成到你的项目。开始前请确保你已安装 CocoaPods,如尚未安装 CocoaPods,参考 [Getting Started with CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) 安装说明。 1. 在终端里进入项目根目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。 2. 打开 `Podfile` 文件,修改文件为如下内容。注意将 `Your App` 替换为你的 Target 名称。 @@ -65,7 +65,7 @@ ## 实现秀场直播 -如下[时序图](#api-时序图)中展示了如何创建直播间、加入直播间、PK 连麦、观众连麦、退出直播间。声网 RTC SDK 承担实时音视频的业务,声网云服务承担信令消息和数据存储的业务。本节会详细介绍如何调用 RTC SDK 的 API 完成这些逻辑,但是信令消息的逻辑需要你参考时序图和[示例项目](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/tree/v3.0.0-all-iOS/iOS/AgoraEntScenarios/Scenes/Show)自行实现。 +如下[时序图](#api-时序图)展示如何创建直播间、加入直播间、PK 连麦、观众连麦、退出直播间。声网 RTC SDK 承担实时音视频的业务,声网云服务承担信令消息和数据存储的业务。本节会详细介绍如何调用 RTC SDK 的 API 完成这些逻辑,但是信令消息的逻辑需要你参考时序图和[示例项目](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/tree/v3.0.0-all-iOS/iOS/AgoraEntScenarios/Scenes/Show)自行实现。
    声网云服务为内部自研服务,暂不对外提供。你可以调用声网云服务的 API 用于测试,但是对于正式环境,声网建议你参考文档自行实现相似的一套服务。如需协助,请提交工单