Merge pull request #3425 from AgoraIO/4.2.6-bugfix-1130

4.2.6 bugfix 1130

dita/RTC-NG/API/api_imediaengine_pushvideoframe.dita

@@ -13,8 +13,8 @@
     <refbody>
         <section id="prototype">
             <p outputclass="codeblock">
-            <codeblock props="android" outputclass="language-java">public abstract boolean pushExternalVideoFrame(AgoraVideoFrame frame);</codeblock>
-            <codeblock props="ios mac" outputclass="language-objectivec">- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame * _Nonnull)frame;</codeblock>
+            <codeblock props="android" outputclass="language-java">public abstract int pushExternalVideoFrameEx(AgoraVideoFrame frame, int videoTrackId);</codeblock>
+            <codeblock props="ios mac" outputclass="language-objectivec">- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame * _Nonnull)frame videoTrackId:(NSUInteger)videoTrackId;</codeblock>
             <codeblock props="cpp unreal" outputclass="language-cpp">virtual int pushVideoFrame(base::ExternalVideoFrame* frame, unsigned int videoTrackId = 0) = 0;</codeblock>
             <codeblock props="electron" outputclass="language-typescript">abstract pushVideoFrame(
     frame: ExternalVideoFrame,
@@ -31,14 +31,21 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <dl outputclass="deprecated">
-            <dlentry props="android">
+            <dl outputclass="deprecated" props="android">
+            <dlentry>
                 <dt>弃用：</dt>
-                <dd>如果你需要推送 I422 格式的视频帧，请使用该方法。其他情况下，请改用 <xref keyref="pushVideoFrame2"/>。</dd>
+                <dd>该方法已废弃，请改用 <xref keyref="pushVideoFrameEx2"/>。</dd>
             </dlentry>
             </dl>
-            <p id="desc1"> <ph props="android ios mac">调用 <xref keyref="setExternalVideoSource"/> 方法，设置 <parmname>enabled</parmname> 参数为 <codeph><ph keyref="true"/></codeph>、<parmname>encodedFrame</parmname> 参数为 <codeph><ph keyref="false"/></codeph> 后，你可以调用本方法将未编码的外部视频帧推送到 SDK。</ph> <ph props="unity cpp unreal bp flutter rn electron cs">调用 <xref keyref="createCustomVideoTrack"/> 方法获得视频轨道 ID，在每个频道的 <xref keyref="ChannelMediaOptions"/> 中，将 <parmname>customVideoTrackId</parmname> 参数设置为你想要发布的视频轨道 ID，并将 <parmname>publishCustomVideoTrack</parmname> 设置为 <codeph><ph keyref="true"/></codeph>后，你可以调用本方法将未编码的外部视频帧推送到 SDK。</ph></p>
-            <p props="android">调用该方法或 <xref keyref="pushVideoFrame2"/> 均能将视频帧数据传递给SDK。区别为 <apiname keyref="pushVideoFrame"/> 方法不支持 texture 格式的视频数据。</p>
+            <p id="desc1">推送自定义采集的视频流到频道内，参考如下步骤：<ol>
+            <li>调用 <xref keyref="createCustomVideoTrack"/> 方法获得视频轨道 ID。</li>
+            <li>加入频道时，在每个频道的 <xref keyref="ChannelMediaOptions"/> 中，将 <parmname>customVideoTrackId</parmname> 参数设置为你想要发布的视频轨道 ID，并将 <parmname>publishCustomVideoTrack</parmname> 设置为 <codeph><ph keyref="true"/></codeph>。</li>
+            <li>调用本方法将未编码的外部视频帧推送到 SDK。</li></ol></p>
+            <note type="danger" id="desc2">调用该方法后，即使你停止推送外部视频帧到 SDK，自定义采集的视频流仍然会被计入视频时长用量并产生费用，声网建议你根据实际情况采取相应措施避免此类视频计费：<ul>
+            <li>如果你不再需要采集外部视频数据，可以调用 <xref keyref="destroyCustomVideoTrack"/> 销毁自定义采集的视频轨道。</li>
+            <li>如果你只想将采集到的外部视频数据用于本地预览、而不在频道内发布，可以调用 <xref keyref="muteLocalVideoStream"/> 取消发送视频流，或调用 <xref keyref="updateChannelMediaOptions"/> 将 <parmname>publishCustomVideoTrack</parmname> 设置为 <codeph><ph keyref="false"/></codeph>。</li>
+            </ul></note>
+            <p props="android">调用该方法或 <xref keyref="pushVideoFrameEx2"/> 均能将视频帧数据传递给 SDK。区别为 <apiname keyref="pushVideoFrame"/> 方法不支持 texture 格式的视频数据。</p>
         </section>
         <section props="cpp">
             <title>适用场景</title>
@@ -53,21 +60,22 @@
                     <p>待推送的视频帧。详见 <xref keyref="ExternalVideoFrame" />。</p>
                 </pd>
             </plentry>
-            <plentry id="videotrackid" props="cpp unreal bp electron unity rn flutter cs">
+            <plentry id="videotrackid">
                 <pt>videoTrackId</pt>
-                <pd>调用 <xref keyref="createCustomVideoTrack"/> 方法返回的视频轨道 ID。默认值为 0。</pd>
+                <pd>调用 <apiname keyref="createCustomVideoTrack"/> 方法返回的视频轨道 ID。默认值为 0。</pd>
             </plentry>    
-            </parml> </section>
+            </parml>
+        </section>
         <section id="return_values">
             <title><ph keyref="return-section-title"/></title>
             <p props="flutter">方法成功调用时，无返回值；方法调用失败时，会抛出 <xref keyref="AgoraRtcException"/> 异常，你需要捕获异常并进行处理。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></p>
             <ul props="cpp unreal bp unity rn electron cs">
             <li>0：方法调用成功。</li>
             <li>&lt; 0：方法调用失败。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></li>
             </ul>
-            <ul props="android ios mac">
-            <li><codeph><ph keyref="true"/></codeph>：推送成功。</li>
-            <li><codeph><ph keyref="false"/></codeph>：推送失败。</li>
+            <ul props="apple">
+            <li><codeph><ph keyref="true"/></codeph>：方法调用成功。</li>
+            <li><codeph><ph keyref="false"/></codeph>：方法调用失败。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></li>
             </ul> </section>
     </refbody>
 </reference>

dita/RTC-NG/API/api_irtcengine_createcustomvideotrack.dita

@@ -33,14 +33,14 @@
             <ol>
             <li>调用该方法创建视频轨道并获得视频轨道 ID。</li>
             <li>在每个频道的 <xref keyref="ChannelMediaOptions"/> 中，将 <parmname>customVideoTrackId</parmname> 参数设置为你想要发布的视频轨道 ID，并将 <parmname>publishCustomVideoTrack</parmname> 设置为 <codeph><ph keyref="true"/></codeph>。</li>
-            <li>调用 <xref keyref="pushVideoFrameEx2" props="android"/><xref keyref="pushVideoFrameEx" props="ios mac"/><xref keyref="pushVideoFrame" props="cpp unreal bp electron unity rn flutter"/> 将 <parmname>videoTrackId</parmname> 指定为步骤 2 中指定的视频轨道 ID，即可实现在多个频道中发布对应的自定义视频源。</li>
+            <li>调用 <xref keyref="pushVideoFrame" props="apple cpp framework"/><xref keyref="pushVideoFrameEx2" props="android"/> 将 <parmname>videoTrackId</parmname> 指定为步骤 2 中指定的视频轨道 ID，即可实现在多个频道中发布对应的自定义视频源。</li>
             </ol></p>
         </section>
         <section id="return_values">
             <title>返回值</title>
             <ul>
             <li>方法调用成功，返回视频轨道 ID 作为该视频轨道的唯一标识。</li>
-            <li>方法调用失败，返回负值。</li>
+            <li>方法调用失败，返回负值。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></li>
             </ul> </section>
     </refbody>
 </reference>

dita/RTC-NG/API/api_irtcengine_pushvideoframe2.dita

@@ -24,8 +24,8 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p id="desc1">该方法主动将视频帧数据用 <xref keyref="VideoFrame"/> 类封装后传递给 SDK。请确保在你调用本方法前已调用 <xref keyref="setExternalVideoSource"/>， 并将参数 <parmname>enable</parmname> 设置为 <codeph><ph keyref="true"/></codeph>，不然调用本方法后会一直报错。</p>
-            <p>调用该方法或 <xref keyref="pushVideoFrame"/> 均能将视频帧数据传递给SDK。区别为 <apiname keyref="pushVideoFrame2"/> 方法支持 texture 格式的视频数据。</p>
+            <p conkeyref="pushVideoFrameEx/desc"/>
+            <p>调用该方法或 <xref keyref="pushVideoFrameEx"/> 均能将视频帧数据传递给SDK。区别为 <apiname keyref="pushVideoFrame2"/> 方法支持 texture 格式的视频数据。</p>
         </section>
         <section id="parameters">
             <title>参数</title>
@@ -38,8 +38,8 @@
         <section id="return_values">
             <title>返回值</title>
             <ul>
-            <li><codeph><ph keyref="true"/></codeph>：推送成功。</li>
-            <li><codeph><ph keyref="false"/></codeph>：推送失败。</li>
+            <li><codeph><ph keyref="true"/></codeph>：方法调用成功。</li>
+            <li><codeph><ph keyref="false"/></codeph>：方法调用失败。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></li>
             </ul> </section>
     </refbody>
 </reference>

dita/RTC-NG/API/api_irtcengine_setdualstreammode2.dita

@@ -62,7 +62,9 @@
                 <pt>streamConfig</pt>
                 <pd>
                     <p>视频小流的配置。详见 <xref keyref="SimulcastStreamConfig"/>。</p>
-                    <note>当设置 <parmname>mode</parmname> 为 <apiname keyref="DISABLE_SIMULCAST_STREAM"/> 时，再设置 <parmname>streamConfig</parmname> 不会生效。</note>
+                    <note type="caution"><ul>
+                        <li>当设置 <parmname>mode</parmname> 为 <apiname keyref="DISABLE_SIMULCAST_STREAM"/> 时，再设置 <parmname>streamConfig</parmname> 不会生效。</li>
+                        <li>务必设置 <parmname>streamConfig</parmname> 中的各项参数，否则该方法不会生效。</li></ul></note>
                 </pd>
             </plentry>
             </parml> </section>

dita/RTC-NG/API/api_irtcengine_setuplocalvideo.dita

@@ -33,6 +33,7 @@
             <li props="unity cs">如果你想要在原生窗口上渲染图像，请调用此方法；如果你仅需在 Unity 项目内渲染图像，可直接通过 <xref keyref="AgoraVideoSurface"/> 类来实现。</li>
             <li>该方法在加入频道前后都能调用。</li>
             <li props="native unreal bp unity rn flutter cs">如果你希望在通话中更新本地用户视图的渲染或镜像模式，请使用 <xref keyref="setLocalRenderMode2" /> 方法。</li>
+            <li props="electron">如果想要停止渲染视图，需要将 <parmname>view</parmname> 设为 <ph keyref="NULL" /> 后再次调用该方法，以停止渲染并清理渲染缓存。</li>
             </ul> </note> </section>
         <section id="parameters">
             <title>参数</title>

dita/RTC-NG/API/api_irtcengine_setupremotevideo.dita

@@ -35,6 +35,7 @@
              <li props="unity cs">如果你想要在原生窗口上渲染图像，请调用此方法；如果你仅需在 Unity 项目内渲染图像，可直接通过 <xref keyref="AgoraVideoSurface"/> 类来实现。</li>
             <li props="native unreal bp unity rn flutter cs">如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 <xref keyref="setRemoteRenderMode2"/> 方法。</li>
             <li>如果你使用了录制服务，录制服务会作为一个哑客户端加入频道，因此也会触发 <xref keyref="onUserJoined"/> 回调。由于录制服务不会发送视频流，App 无需为它绑定视图。如果 App 无法识别哑客户端，可以在收到 <xref keyref="onFirstRemoteVideoDecoded"/> 回调时再绑定远端用户视图。</li>
+            <li props="electron">如果想要停止渲染视图，需要将 <parmname>view</parmname> 设为 <ph keyref="NULL" /> 后再次调用该方法，以停止渲染并清理渲染缓存。</li>
             </ul> </note> </section>
         <section id="parameters">
             <title>参数</title>

dita/RTC-NG/API/api_irtcengine_startlastmileprobetest.dita

@@ -33,12 +33,7 @@
                     <li><xref keyref="onLastmileProbeResult" />，视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量，更加客观。</li>
                 </ul>
             </p>
-            <p>该方法主要用于以下两种场景：
-                <ul>
-                    <li>用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。</li>
-                    <li>直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。</li>
-                </ul>
-            </p>
+            <p>该方法需要在加入频道前调用，用于判断和预测目前的上行网络质量是否足够好。</p>
             <note type="attention">
                 <ul>
                     <li>调用该方法后，在收到 <apiname keyref="onLastmileQuality" /> 和 <apiname keyref="onLastmileProbeResult" /> 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行。</li>

dita/RTC-NG/API/api_irtcengineex_pushvideoframeex.dita

@@ -13,8 +13,8 @@
     <refbody>
         <section id="prototype">
             <p outputclass="codeblock">
-            <codeblock props="android" outputclass="language-java">public abstract int pushExternalVideoFrameEx(AgoraVideoFrame frame, int videoTrackId);</codeblock>
-            <codeblock props="ios mac" outputclass="language-objectivec">- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame * _Nonnull)frame videoTrackId:(NSUInteger)videoTrackId;</codeblock>
+            <codeblock props="android" outputclass="language-java">public abstract boolean pushExternalVideoFrame(AgoraVideoFrame frame);</codeblock>
+            <codeblock props="ios mac" outputclass="language-objectivec">- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame * _Nonnull)frame;</codeblock>
             <codeblock props="cpp unreal" outputclass="language-cpp"/>
             <codeblock props="electron" outputclass="language-typescript"/>
             <codeblock props="unity cs" outputclass="language-csharp"/>
@@ -24,14 +24,14 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <dl outputclass="deprecated" props="android">
-            <dlentry>
-                <dt>弃用：</dt>
-                <dd>该方法已废弃，请改用 <xref keyref="pushVideoFrameEx2"/>。</dd>
-            </dlentry>
+            <dl outputclass="deprecated">
+                <dlentry props="android">
+                    <dt>弃用：</dt>
+                    <dd>如果你需要推送 I422 格式的视频帧，请使用该方法。其他情况下，请改用 <xref keyref="pushVideoFrame2"/>。</dd>
+                </dlentry>
             </dl>
-            <p conkeyref="pushVideoFrameEx2/desc1"/>
-            <p props="android">调用该方法或 <xref keyref="pushVideoFrameEx2"/> 均能将视频帧数据传递给 SDK。区别为 <apiname keyref="pushVideoFrameEx"/> 方法不支持 texture 格式的视频数据。</p>
+            <p id="desc">调用 <xref keyref="setExternalVideoSource"/> 方法，设置 <parmname>enabled</parmname> 参数为 <codeph><ph keyref="true"/></codeph>、<parmname>encodedFrame</parmname> 参数为 <codeph><ph keyref="false"/></codeph> 后，你可以调用本方法将未编码的外部视频帧推送到 SDK。</p>
+            <p props="android">调用该方法或 <xref keyref="pushVideoFrame2"/> 均能将视频帧数据传递给 SDK。区别为 <apiname keyref="pushVideoFrameEx"/> 方法不支持 texture 格式的视频数据。</p>
         </section>
         <section id="parameters">
             <title>参数</title>
@@ -40,20 +40,12 @@
                 <pt/>
                 <pd/>
             </plentry>
-            <plentry id="videotrackid">
-                <pt>videoTrackId</pt>
-                <pd>调用 <xref keyref="createCustomVideoTrack"/> 方法返回的视频轨道 ID。默认值为 0。</pd>
-            </plentry>
             </parml> </section>
         <section id="return_values">
             <title>返回值</title>
-            <ul props="android">
-            <li>0：方法调用成功。</li>
-            <li>&lt; 0：方法调用失败。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></li>
-            </ul>
-            <ul props="ios mac">
-                <li><codeph><ph keyref="true"/></codeph>：推送成功。</li>
-                <li><codeph><ph keyref="false"/></codeph>：推送失败。</li>
+            <ul>
+                <li><codeph><ph keyref="true"/></codeph>：方法调用成功。</li>
+                <li><codeph><ph keyref="false"/></codeph>：方法调用失败。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></li>
                 </ul> </section>
     </refbody>
 </reference>

dita/RTC-NG/API/api_irtcengineex_pushvideoframeex2.dita

@@ -24,7 +24,8 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p id="desc1">该方法主动将视频帧数据用 <xref keyref="VideoFrame"/> 类封装后传递给 SDK。请确保在你调用本方法前已调用 <xref keyref="createCustomVideoTrack"/> 获得视频轨道 ID。</p>
+            <p conkeyref="pushVideoFrame/desc1"/>
+            <note conkeyref="pushVideoFrame/desc2"/>
             <p>调用该方法或 <xref keyref="pushVideoFrameEx"/> 均能将视频帧数据传递给 SDK。区别为 <apiname keyref="pushVideoFrameEx2"/> 方法支持 texture 格式的视频数据。</p>
         </section>
         <section id="parameters">
@@ -34,7 +35,7 @@
                 <pt/>
                 <pd/>
             </plentry>
-            <plentry conkeyref="pushVideoFrameEx/videotrackid">
+            <plentry conkeyref="pushVideoFrame/videotrackid">
                 <pt/>
                 <pd/>
             </plentry>
@@ -43,7 +44,7 @@
             <title>返回值</title>
             <ul>
             <li>0: 推送成功。</li>
-            <li>&lt; 0: 推送失败。</li>
+            <li>&lt; 0: 推送失败。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></li>
             </ul> </section>
     </refbody>
 </reference>

dita/RTC-NG/API/api_irtcengineex_startrtmpstreamwithtranscodingex.dita

@@ -71,17 +71,6 @@
                 <pd/>
             </plentry>
             </parml> </section>
-        <section id="return_values">
-            <title><ph keyref="return-section-title"/></title>
-            <p props="flutter">方法成功调用时，无返回值；方法调用失败时，会抛出 <xref keyref="AgoraRtcException"/> 异常，你需要捕获异常并进行处理。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></p>
-            <ul>
-            <li props="native unreal bp unity electron rn cs">0: 方法调用成功。</li>
-            <li>&lt; 0: 方法调用失败。                
-                <ul>
-                <li>-2：url 为空或为长度为 0 的字符串。</li>
-                <li>-7：调用该方法前，未初始化 SDK。</li>
-                <li>-19：该旁路推流 URL 已在使用中，请使用其他旁路推流 URL。</li>
-                </ul> </li>
-            </ul> </section>
+        <section id="return_values" conkeyref="startRtmpStreamWithTranscoding/return_values"></section>
     </refbody>
 </reference>

dita/RTC-NG/config/keys-rtc-ng-api-electron.ditamap

@@ -11990,7 +11990,7 @@
         <keydef keys="NULL">
             <topicmeta>
                 <keywords>
-                    <keyword>NULL</keyword>
+                    <keyword>null</keyword>
                 </keywords>
             </topicmeta>
         </keydef>