Merge pull request #3785 from AgoraIO/4.4.0-bugfix-1010

4.4.0 bugfix 1010
AgoraIO · Oct 11, 2024 · 99d1b2a · 99d1b2a
2 parents 7d90b94 + d20cc62
commit 99d1b2a
Show file tree

Hide file tree

Showing 14 changed files with 68 additions and 51 deletions.
diff --git a/dita/RTC-NG/API/api_imediaengine_registervideoencodedframeobserver.dita b/dita/RTC-NG/API/api_imediaengine_registervideoencodedframeobserver.dita
@@ -30,24 +30,10 @@
  </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p>如果你只想要观测编码后的视频帧 (如 h.264 格式)，而不需要对视频进行解码和渲染，声网推荐你通过该方法注册一个 <xref keyref="IVideoEncodedFrameObserver"/> 类。</p>
-            <p id="mix">如果你想获取一部分远端用户的原始视频数据 (简称为 A 组)、获取另一部分远端用户的编码后视频数据 (简称为 B 组)，可参考以下步骤： 
-
-            <ol>
-            <li>在加入频道前调用 <xref keyref="registerVideoFrameObserver"/> 注册原始视频帧观测器。</li>
-            <li>在加入频道前调用 <xref keyref="registerVideoEncodedFrameObserver"/> 注册编码后的视频帧观测器。</li>
-            <li>加入频道后通过 <xref keyref="onUserJoined"/> 获取 B 组用户的 ID，然后调用 <xref keyref="setRemoteVideoSubscriptionOptions"/> 设置该组用户的 <parmname>encodedFrameOnly</parmname> 为 <codeph><ph keyref="true"/></codeph>。</li>
-            <li>调用 <xref keyref="muteAllRemoteVideoStreams"/><codeph>(<ph keyref="false"/>)</codeph>，开始接收所有远端用户的视频流。此时： 
-
-                <ul>
-                <li>可通过 <xref keyref="IVideoFrameObserver"/> 中的回调获取 A 组用户的原始视频数据，SDK 默认对该数据进行渲染。</li>
-                <li>可通过 <xref keyref="IVideoEncodedFrameObserver"/> 中的回调获取 B 组用户的已编码视频数据。</li>
-                </ul> </li>
-            </ol> </p>
+            <p>如果你只想要观测编码后的视频帧 (如 H.264 格式)，而不需要对视频进行解码和渲染，声网推荐你通过该方法注册一个 <xref keyref="IVideoEncodedFrameObserver"/> 类。<ph props="android cpp apple">有关详细的实现步骤，详见<xref keyref="video-processing"/>。</ph></p>
             <note type="attention">
-            <ul>
-            <li>该方法需要在加入频道前调用。</li>
-            </ul></note> </section>
+            <p>该方法需要在加入频道前调用。</p>
+            </note> </section>
         <section id="parameters">
             <title>参数</title>
             <parml>

diff --git a/dita/RTC-NG/API/api_imediaengine_registervideoframeobserver.dita b/dita/RTC-NG/API/api_imediaengine_registervideoframeobserver.dita
@@ -26,11 +26,10 @@
         <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <p>如果你想要观测原始视频帧 (如 YUV 或 RGBA 格式)，声网推荐你通过该方法注册一个 <xref keyref="IVideoFrameObserver"/> 类。</p>
             <p>调用该方法注册视频观测器时，你可以根据需要注册 <apiname keyref="IVideoFrameObserver"/> 类中的回调。在成功注册视频观测器后，SDK 会在捕捉到每个视频帧时，触发你所注册的上述回调。</p>
-            <p conkeyref="registerVideoEncodedFrameObserver/mix"/>
         </section>
         <section id="scenario" deliveryTarget="details">
             <title>适用场景</title>
-            <p>注册原始视频观测器后，你可以将获取到的原始视频数据应用于各种视频前处理场景，例如自行实现虚拟背景、美颜等场景。</p>
+            <p>注册原始视频观测器后，你可以将获取到的原始视频数据应用于各种视频前处理场景，例如自行实现虚拟背景、美颜等场景。<ph props="android cpp apple">有关详细的实现步骤，详见<xref keyref="video-processing"/>。</ph></p>
             <p props="android ios">声网在 GitHub 上提供了开源的示例项目 <xref keyref="beautyapi-link"/> 供你参考。</p>
         </section>
         <section id="timing" deliveryTarget="details">

diff --git a/dita/RTC-NG/API/api_imediaplayer_selectaudiotrack.dita b/dita/RTC-NG/API/api_imediaplayer_selectaudiotrack.dita
@@ -27,7 +27,7 @@ int SelectAudioTrack(int index);</codeblock>
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p>获取音频文件的音轨索引后，你可以调用该方法指定任一音轨进行播放。例如，如果一个多音轨文件的不同音轨存放了不同语言的歌曲，则你可以调用该方法设置播放语言。</p>
+            <p>获取音频文件的音轨索引后，你可以调用该方法指定任一音轨进行播放。如果一个多音轨文件的不同音轨存放了不同语言的歌曲，你可以调用该方法设置播放语言。</p>
             <note type="attention" id="note"><ph>你需要在调用 <xref keyref="getStreamInfo" /> 获取音频流索引值后调用该方法。</ph></note> </section>
         <section id="parameters">
             <title>参数</title>

diff --git a/dita/RTC-NG/API/api_irtcengine_joinchannel.dita b/dita/RTC-NG/API/api_irtcengine_joinchannel.dita
@@ -72,7 +72,7 @@
             </plentry>
             <plentry id="uid">
                 <pt>uid</pt>
-                <pd>用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。<ph props="android hmos">该参数为 32 位有符号整数。取值范围为：-2<sup>31</sup>-1 到 2<sup>31</sup>-1。</ph><ph props="cpp apple framework">该参数为 32 位无符号整数。建议设置范围：1 到 2<sup>32</sup>-1。</ph>如果不指定（即设为 0），SDK 会自动分配一个，并在 <apiname keyref="onJoinChannelSuccess" /> 回调中返回， 应用层必须记住该返回值并维护，SDK 不对该返回值进行维护。</pd>
+                <pd>用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。<ph props="android hmos">该参数为 32 位有符号整数。取值范围为：-2<sup>31</sup> 到 2<sup>31</sup>-1。</ph><ph props="cpp apple framework">该参数为 32 位无符号整数。建议设置范围：1 到 2<sup>32</sup>-1。</ph>如果不指定（即设为 0），SDK 会自动分配一个，并在 <apiname keyref="onJoinChannelSuccess" /> 回调中返回， 应用层必须记住该返回值并维护，SDK 不对该返回值进行维护。</pd>
             </plentry>
             <plentry props="ios mac" conkeyref="joinChannel2/joinsuccessblock">
                 <pt />

diff --git a/dita/RTC-NG/API/api_irtcengine_joinchannel2.dita b/dita/RTC-NG/API/api_irtcengine_joinchannel2.dita
@@ -101,7 +101,7 @@
             </plentry>
             <plentry id="uid">
                 <pt>uid</pt>
-                <pd>用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。<ph props="android hmos">该参数为 32 位有符号整数。取值范围为：-2<sup>31</sup>-1 到 2<sup>31</sup>-1。</ph><ph props="cpp apple framework">该参数为 32 位无符号整数。建议设置范围：1 到 2<sup>32</sup>-1。</ph>如果不指定（即设为 0），SDK 会自动分配一个，并在 <apiname keyref="onJoinChannelSuccess" /> 回调中返回， 应用层必须记住该返回值并维护，SDK 不对该返回值进行维护。</pd>
+                <pd>用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。<ph props="android hmos">该参数为 32 位有符号整数。取值范围为：-2<sup>31</sup> 到 2<sup>31</sup>-1。</ph><ph props="cpp apple framework">该参数为 32 位无符号整数。建议设置范围：1 到 2<sup>32</sup>-1。</ph>如果不指定（即设为 0），SDK 会自动分配一个，并在 <apiname keyref="onJoinChannelSuccess" /> 回调中返回， 应用层必须记住该返回值并维护，SDK 不对该返回值进行维护。</pd>
             </plentry>
             <plentry id="options">
                 <pt props="android hmos cpp unreal bp electron unity rn flutter cs">options</pt>

diff --git a/dita/RTC-NG/API/api_irtcengine_setremotevideosubscriptionoptions.dita b/dita/RTC-NG/API/api_irtcengine_setremotevideosubscriptionoptions.dita
@@ -35,21 +35,13 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p>当远端发送双流时，可调用此方法来设置远端视频流的订阅选项。</p>
-            <p>
-            <ul>
-            <li>如果你只注册了 <xref keyref="IVideoFrameObserver"/> 对象，则默认订阅原始视频数据和编码后的视频数据 (效果等同于 <parmname>encodedFrameOnly</parmname> 设置为 <codeph><ph keyref="false"/></codeph>)。</li>
-            <li>如果你只注册了 <xref keyref="IVideoEncodedFrameObserver"/> 对象，则默认只订阅编码后的视频数据 (效果等同于 <parmname>encodedFrameOnly</parmname> 设置为 <codeph><ph keyref="true"/></codeph>)。</li>
-            <li>如果你先后注册了 <apiname keyref="IVideoFrameObserver"/> 和 <apiname keyref="IVideoEncodedFrameObserver"/> 对象，则默认订阅原始视频数据和编码后的视频数据 (效果等同于 <parmname>encodedFrameOnly</parmname> 设置为 <codeph><ph keyref="false"/></codeph>)。</li>
-            <li>如果你先调用该方法设置了 <parmname>options</parmname> 参数、然后再注册 <apiname keyref="IVideoFrameObserver"/> 或 <apiname keyref="IVideoEncodedFrameObserver"/> 对象，则需要再次调用该方法并按照以上两项描述设置 <parmname>options</parmname> 参数，以获得预期的效果。</li>
-            </ul> </p>
-            <note>声网推荐你按照以下步骤调用该方法：
-
-            <ol>
-            <li>调用 <xref keyref="joinChannel2"/> 加入频道时设置 <parmname>autoSubscribeVideo</parmname> 为 <codeph><ph keyref="false"/></codeph>。</li>
-            <li>在收到 <xref keyref="onUserJoined"/> 回调后调用该方法，设置对指定远端用户视频流的订阅选项。</li>
-            <li>调用 <xref keyref="muteRemoteVideoStream"/> 方法，开始恢复订阅指定远端用户的视频流。如果你在上一步中将 <parmname>encodedFrameOnly</parmname> 设置为 <codeph><ph keyref="true"/></codeph>，SDK 会在本地触发 <xref keyref="onEncodedVideoFrameReceived"/> 回调，上报接收到的编码后视频帧信息。</li>
-            </ol> </note> </section>
+            <p>当远端发送双流时，可调用此方法来设置远端视频流的订阅选项。SDK 对远端视频流的默认订阅行为取决于注册的视频观测器类型：<ul>
+                <li>如果注册的是 <xref keyref="IVideoFrameObserver"/> 观测器，则默认订阅原始数据和编码后的数据。</li>
+                <li>如果注册的是 <xref keyref="IVideoEncodedFrameObserver"/> 观测器，则默认仅订阅编码后的数据。</li>
+                <li>如果注册了两种观测器，则默认跟随后注册的视频观测器。举例来说，如果后注册的是 <apiname keyref="IVideoFrameObserver"/> 观测器，则默认订阅原始数据和编码后的数据。</li>
+            </ul>
+            如果你想修改以上默认行为，或者想针对不同 <codeph>uid</codeph> 设置不同的订阅选项，可调用该方法设置。<ph props="android cpp apple">有关详细的实现步骤，详见<xref keyref="video-processing"/>。</ph></p>
+        </section>
         <section id="parameters">
             <title>参数</title>
             <parml>

diff --git a/dita/RTC-NG/API/callback_irtcengineeventhandler_onstreammessage.dita b/dita/RTC-NG/API/callback_irtcengineeventhandler_onstreammessage.dita
@@ -28,16 +28,23 @@
                   }</codeblock>
             <codeblock props="bp" outputclass="language-cpp">UFUNCTION(BlueprintNativeEvent, Category = &quot;Agora|Event&quot;)
 	void OnStreamMessage(int64 uid, int streamId, const FString&amp; data, int length, int64 sentTs);</codeblock>
-            <codeblock props="electron" outputclass="language-typescript">onStreamMessage?(connection: RtcConnection, remoteUid: number, streamId: number, data: Uint8Array, length: number, sentTs: number): void;</codeblock>
-            <codeblock props="unity cs" outputclass="language-csharp">public virtual void OnStreamMessage(RtcConnection connection, uint remoteUid, int streamId, byte[] data, uint length, UInt64 sentTs) { }</codeblock>
+            <codeblock props="electron" outputclass="language-typescript">onStreamMessage?(
+    connection: RtcConnection,
+    remoteUid: number,
+    streamId: number,
+    data: Uint8Array,
+    length: number,
+    sentTs: number
+  ): void;</codeblock>
+            <codeblock props="unity cs" outputclass="language-csharp">public virtual void OnStreamMessage(RtcConnection connection, uint remoteUid, int streamId, byte[] data, ulong length, ulong sentTs) { }</codeblock>
             <codeblock props="rn" outputclass="language-typescript">onStreamMessage?(
-  connection: RtcConnection,
-  remoteUid: number,
-  streamId: number,
-  data: Uint8Array,
-  length: number,
-  sentTs: number
-): void;</codeblock>
+    connection: RtcConnection,
+    remoteUid: number,
+    streamId: number,
+    data: Uint8Array,
+    length: number,
+    sentTs: number
+  ): void;</codeblock>
             <codeblock props="flutter" outputclass="language-dart">final void Function(RtcConnection connection, int remoteUid, int streamId,
       Uint8List data, int length, int sentTs)? onStreamMessage;</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
@@ -59,7 +66,7 @@
                 <pd />
             </plentry>
             <plentry id="uid">
-                <pt props="android hmos ios mac flutter">uid</pt>
+                <pt props="android hmos ios mac">uid</pt>
                 <pt props="cpp unreal bp">userId</pt>
                 <pt props="unity electron rn flutter cs">remoteUid</pt>
                 <pd>发送消息的用户 ID。</pd>

diff --git a/dita/RTC-NG/API/callback_ivideoframeobserver_getmirrorapplied.dita b/dita/RTC-NG/API/callback_ivideoframeobserver_getmirrorapplied.dita
@@ -27,7 +27,10 @@
             <p>如果你希望获取的视频数据为原始视频的镜像，需要在调用 <xref keyref="registerVideoFrameObserver" /> 方法时注册该回调。成功注册视频数据观测器后，SDK 会在捕捉到每个视频帧时触发该回调，你需要在该回调的返回值中设置是否对原始视频数据作镜像处理。</p>
             <note type="attention">
                 <ul>
-                    <li>该功能仅支持 RGBA 和 YUV420 格式的视频数据。</li>
+                    <li props="android cpp unreal bp">在 Android 平台上，该回调支持的视频数据格式有：I420、RGBA 和 Texture。</li>
+                    <li props="cpp unreal bp">在 Windows 平台上，该回调支持的视频数据格式有：I420、RGBA 和 TextureBuffer。</li>
+                    <li props="ios cpp unreal bp">在 iOS 平台上，该回调支持的视频数据格式有：I420、RGBA 和 CVPixelBuffer。</li>
+                    <li props="mac cpp unreal bp">在 macOS 平台上，该回调支持的视频数据格式有：I420 和 RGBA。</li>
                     <li>该方法和 <xref keyref="setVideoEncoderConfiguration"/> 方法均支持设置镜像效果，声网建议你仅选择一种方法进行设置，同时使用两种方法会导致镜像效果叠加从而造成设置镜像失败。</li>
                 </ul>
             </note> </section>

diff --git a/dita/RTC-NG/API/callback_ivideoframeobserver_getrotationapplied.dita b/dita/RTC-NG/API/callback_ivideoframeobserver_getrotationapplied.dita
@@ -28,8 +28,10 @@
             <p props="ios mac">如果你在采集端已经根据 <xref keyref="VideoFrame" /> 中的旋转信息 <parmname>rotation</parmname> 进行旋转，就无需调用该方法设置视频数据旋转。</p>
             <note type="attention" id="note1">
                 <ul>
-                    <li>该功能仅支持视频处理模式为 <apiname keyref="PROCESS_MODE_READ_ONLY" /> 的场景。</li>
-                    <li>该功能仅支持 RGBA 和 YUV420 格式的视频数据。</li>
+                    <li props="android cpp unreal bp">在 Android 平台上，该回调支持的视频数据格式有：I420、RGBA 和 Texture。</li>
+                    <li props="cpp unreal bp">在 Windows 平台上，该回调支持的视频数据格式有：I420、RGBA 和 TextureBuffer。</li>
+                    <li props="ios cpp unreal bp">在 iOS 平台上，该回调支持的视频数据格式有：I420、RGBA 和 CVPixelBuffer。</li>
+                    <li props="mac cpp unreal bp">在 macOS 平台上，该回调支持的视频数据格式有：I420 和 RGBA。</li>
                 </ul>
             </note> </section>
         <section id="return_values">

diff --git a/dita/RTC-NG/API/enum_backgroundsourcetype.dita b/dita/RTC-NG/API/enum_backgroundsourcetype.dita
@@ -7,7 +7,7 @@
         <section id="parameters">
             <title>枚举值</title>
             <parml>
-            <plentry>
+            <plentry props="native unity flutter">
                 <pt><ph keyref="BACKGROUND_NONE"/></pt>
                 <pd>0: 将背景处理为 Alpha 数据，不作替换，仅分割人像和背景。设置后，你可以调用 <xref keyref="startLocalVideoTranscoder"/>，实现人像画中画的效果。</pd>
             </plentry>

diff --git a/dita/RTC-NG/config/keys-rtc-ng-links-android.ditamap b/dita/RTC-NG/config/keys-rtc-ng-links-android.ditamap
@@ -101,6 +101,13 @@
                 </keywords>
             </topicmeta>
         </keydef>
+        <keydef keys="video-processing" href="https://doc.shengwang.cn/doc/rtc/android/advanced-features/video-processing" scope="external" format="html">
+            <topicmeta>
+                <keywords>
+                    <keyword>自定义视频数据处理</keyword>
+                </keywords>
+            </topicmeta>
+        </keydef>
     </topichead>
     <topichead navtitle="External">
         <keydef keys="filePath-link" href="https://developer.android.google.cn/guide/topics/media/media-formats?hl=zh-cn" scope="external" format="html"/>

diff --git a/dita/RTC-NG/config/keys-rtc-ng-links-cpp.ditamap b/dita/RTC-NG/config/keys-rtc-ng-links-cpp.ditamap
@@ -88,6 +88,13 @@
                 </keywords>
             </topicmeta>
         </keydef>
+        <keydef keys="video-processing" href="https://doc.shengwang.cn/doc/rtc/windows/advanced-features/video-processing" scope="external" format="html">
+            <topicmeta>
+                <keywords>
+                    <keyword>自定义视频数据处理</keyword>
+                </keywords>
+            </topicmeta>
+        </keydef>
     </topichead>
     <topichead navtitle="External">
         <keydef keys="filePath-link" href="https://docs.microsoft.com/zh-cn/windows/win32/medfound/supported-media-formats-in-media-foundation" scope="external" format="html"/>

diff --git a/dita/RTC-NG/config/keys-rtc-ng-links-ios.ditamap b/dita/RTC-NG/config/keys-rtc-ng-links-ios.ditamap
@@ -102,6 +102,13 @@
             </keywords>
         </topicmeta>
     </keydef>
+    <keydef keys="video-processing" href="https://doc.shengwang.cn/doc/rtc/ios/advanced-features/video-processing" scope="external" format="html">
+        <topicmeta>
+            <keywords>
+                <keyword>自定义视频数据处理</keyword>
+            </keywords>
+        </topicmeta>
+    </keydef>
     <topichead navtitle="External">
         <keydef keys="filePath-link" href="https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/MultimediaPG/UsingAudio/UsingAudio.html#//apple_ref/doc/uid/TP40009767-CH2-SW28" scope="external" format="html"/>
         <keydef keys="rect-link" href="https://developer.apple.com/documentation/corefoundation/cgrect" scope="external" format="html">

diff --git a/dita/RTC-NG/config/keys-rtc-ng-links-macos.ditamap b/dita/RTC-NG/config/keys-rtc-ng-links-macos.ditamap
@@ -74,6 +74,13 @@
                 </keywords>
             </topicmeta>
         </keydef>
+        <keydef keys="video-processing" href="https://doc.shengwang.cn/doc/rtc/macos/advanced-features/video-processing" scope="external" format="html">
+            <topicmeta>
+                <keywords>
+                    <keyword>自定义视频数据处理</keyword>
+                </keywords>
+            </topicmeta>
+        </keydef>
     <topichead navtitle="External">
         <keydef keys="filePath-link" href="https://developer.apple.com/library/archive/documentation/MusicAudio/Conceptual/CoreAudioOverview/SupportedAudioFormatsMacOSX/SupportedAudioFormatsMacOSX.html" scope="external" format="html"/>
         <keydef keys="nsimage-link" href="https://developer.apple.com/documentation/appkit/nsimage?language=objc" scope="external" format="html">