Merge branch 'master' into convert-oc-api-name

AgoraIO · Aug 16, 2024 · 1dc1039 · 1dc1039
2 parents 0a81c99 + b506344
commit 1dc1039
Show file tree

Hide file tree

Showing 113 changed files with 5,327 additions and 9,332 deletions.
diff --git a/dita/RTC-NG/API/api_ibasespatialaudioengine_updateplayerpositioninfo.dita b/dita/RTC-NG/API/api_ibasespatialaudioengine_updateplayerpositioninfo.dita
@@ -32,11 +32,18 @@
       {required int playerId, required RemoteVoicePositionInfo positionInfo});</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <p>成功更新后，本地用户可以听到媒体播放器空间位置的变化。</p>
         </section>
-        <section id="parameters">
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>加入频道前后均可调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>参数</title>
             <parml>
             <plentry id="mpkid">

diff --git a/dita/RTC-NG/API/api_imediaplayer_adjustplayoutvolume.dita b/dita/RTC-NG/API/api_imediaplayer_adjustplayoutvolume.dita
@@ -25,7 +25,16 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void&gt; adjustPlayoutVolume(int volume);</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="parameters">
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title"/>
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>加入频道前后均可调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>参数</title>
             <parml>
             <plentry>

diff --git a/dita/RTC-NG/API/api_imediaplayer_adjustpublishsignalvolume.dita b/dita/RTC-NG/API/api_imediaplayer_adjustpublishsignalvolume.dita
@@ -25,11 +25,18 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void&gt; adjustPublishSignalVolume(int volume);</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <p>连接到声网服务器后，你可以调用该方法，调节远端用户听到的媒体文件的音量。</p>
         </section>
-        <section id="parameters">
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>加入频道前后均可调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>参数</title>
             <parml>
             <plentry>

diff --git a/dita/RTC-NG/API/api_imediaplayer_getstreaminfo.dita b/dita/RTC-NG/API/api_imediaplayer_getstreaminfo.dita
@@ -25,10 +25,16 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;PlayerStreamInfo&gt; getStreamInfo(int index);</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
-            <note type="attention" id="note">你需要在 <xref keyref="getStreamCount" /> 后调用该方法。</note> </section>
-        <section id="parameters">
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title"/>
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>你需要在 <xref keyref="getStreamCount" /> 后调用该方法。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>参数</title>
             <parml>
             <plentry>

diff --git a/dita/RTC-NG/API/api_imediaplayer_mute.dita b/dita/RTC-NG/API/api_imediaplayer_mute.dita
@@ -25,7 +25,16 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void&gt; mute(bool muted);</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="parameters">
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title"/>
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>该方法在加入频道前后均可调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>参数</title>
             <parml>
             <plentry>

diff --git a/dita/RTC-NG/API/api_imediaplayer_open.dita b/dita/RTC-NG/API/api_imediaplayer_open.dita
@@ -27,17 +27,27 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void&gt; open({required String url, required int startPos});</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <p props="hide">在 Android 平台上，如果你需要打开 URI 格式的文件，请使用 <xref keyref="open2" />。</p>
             <p id="uri" props="android hmos">该方法支持打开以 <codeph>content://</codeph> 开头的 URI 文件。</p>
             <p id="format" props="native"><ph props="cn">媒体播放器支持的格式详见<xref keyref="media-player"/>。</ph></p>
             <p props="hide">如果用户需要自定义播放线路，你可以调用 <xref keyref="openWithAgoraCDNSrc" />。声网会通过自研调度中心支持调度线路，提升观看用户体验。如果用户不需要自定义播放线路，你可以调用 <xref keyref="open" />。</p>
             <note type="attention" id="note">
             <p props="native unreal bp unity electron flutter cs">该方法为异步调用。</p>
-            <p id="open">如需播放媒体文件，请在收到 <xref keyref="onPlayerSourceStateChanged" /> 回调报告播放状态为 <apiname keyref="PLAYER_STATE_OPEN_COMPLETED" /> 后再调用 <xref keyref="play" /> 方法播放媒体文件。</p>
             </note> </section>
-        <section id="parameters">
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>加入频道前后均可调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="related" deliveryTarget="details">
+            <title>相关回调</title>
+            <p id="open">调用该方法后会触发 <xref keyref="onPlayerSourceStateChanged" /> 回调。在收到报告播放状态为 <apiname keyref="PLAYER_STATE_OPEN_COMPLETED" /> 后，你可以调用 <xref keyref="play" /> 方法播放媒体文件。</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>参数</title>
             <parml>
             <plentry>

diff --git a/dita/RTC-NG/API/api_imediaplayer_open2.dita b/dita/RTC-NG/API/api_imediaplayer_open2.dita
@@ -22,11 +22,22 @@
             <codeblock props="rn" outputclass="language-typescript" />
             <codeblock props="flutter" outputclass="language-dart" /> </p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <note type="attention" conkeyref="open/note" />
         </section>
-        <section id="parameters">
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>加入频道前后均可调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="related" deliveryTarget="details">
+            <title>相关回调</title>
+            <p conkeyref="open/open"/>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>参数</title>
             <parml>
             <plentry id="uri">

diff --git a/dita/RTC-NG/API/api_imediaplayer_pause.dita b/dita/RTC-NG/API/api_imediaplayer_pause.dita
@@ -27,6 +27,16 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void&gt; pause();</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title"/>
+
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>该方法在加入频道前后均可调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </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>

diff --git a/dita/RTC-NG/API/api_imediaplayer_play.dita b/dita/RTC-NG/API/api_imediaplayer_play.dita
@@ -25,10 +25,15 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void&gt; play();</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
-            <p>调用 <ph keyref="open"/> 或 <ph keyref="seek" /> 后，你可以调用该方法播放媒体文件。</p>
-            <note type="caution">调用 <ph keyref="open"/> 打开媒体文件后，你需要在收到 <xref keyref="onPlayerSourceStateChanged"/> 回调报告状态为 <ph keyref="PLAYER_STATE_OPEN_COMPLETED"/> 后再调用 <apiname keyref="play"/> 来播放。</note>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title"/>
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <ul><li>在调用 <xref keyref="open" /> 或 <xref keyref="openWithMediaSource"/> 打开媒体文件、且收到 <xref keyref="onPlayerSourceStateChanged"/> 回调报告状态为 <ph keyref="PLAYER_STATE_OPEN_COMPLETED"/> 后，调用该方法。</li>
+                 <li>在调用 <xref keyref="seek" /> 后调用该方法。</li></ul>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
         </section>
         <section id="return_values">
             <title><ph keyref="return-section-title"/></title>

diff --git a/dita/RTC-NG/API/api_imediaplayer_registerplayersourceobserver.dita b/dita/RTC-NG/API/api_imediaplayer_registerplayersourceobserver.dita
@@ -30,7 +30,16 @@
             <codeblock props="flutter" outputclass="language-dart">void registerPlayerSourceObserver(MediaPlayerSourceObserver observer);</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="parameters">
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title"/>
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>加入频道前后均可调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>参数</title>
             <parml>
             <plentry>

diff --git a/dita/RTC-NG/API/api_imediaplayer_seek.dita b/dita/RTC-NG/API/api_imediaplayer_seek.dita
@@ -27,15 +27,24 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void&gt; seek(int newPos);</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
-            <p>成功调用该方法后，你会收到 <xref keyref="onPlayerEvent" /> 回调，报告当前播放器发生的事件，如定位开始、定位成功或定位失败。</p>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <ul>
                 <li>如果你在播放已经完成后（收到 <xref keyref="onPlayerSourceStateChanged"/> 回调报告播放状态为 <ph keyref="PLAYER_STATE_PLAYBACK_COMPLETED"/> 或 <ph keyref="PLAYER_STATE_PLAYBACK_ALL_LOOPS_COMPLETED"/>）再调用 <apiname keyref="seek"/>，方法调用成功后，SDK 会从你指定的位置开始自动播放，此时你会收到 <xref keyref="onPlayerSourceStateChanged"/> 回调报告播放状态为 <ph keyref="PLAYER_STATE_PLAYING"/>。</li>
                 <li>如果你在播放暂停的情况下调用 <apiname keyref="seek"/>，调用成功后 SDK 会定位到你指定位置，如需播放，请调用 <xref keyref="resume"/> 或 <xref keyref="play"/>。</li>
-            </ul>
+            </ul></section>
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>该方法在加入频道前后均可调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="related" deliveryTarget="details">
+            <title>相关回调</title>
+            <p>成功调用该方法后，你会收到 <xref keyref="onPlayerEvent" /> 回调，报告当前播放器发生的事件，如定位开始、定位成功或定位失败。</p>
         </section>
-        <section id="parameters">
+        <section id="parameters" deliveryTarget="details">
             <title>参数</title>
             <parml>
             <plentry>

diff --git a/dita/RTC-NG/API/api_imediaplayer_setplayeroption.dita b/dita/RTC-NG/API/api_imediaplayer_setplayeroption.dita
@@ -2,7 +2,7 @@
 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
 <reference id="api_imediaplayer_setplayeroption">
     <title><ph keyref="setPlayerOption"/></title>
-    <shortdesc id="short"><ph id="shortdesc">设置媒体播放器选项，用于提供技术预览或特别定制功能。</ph></shortdesc>
+    <shortdesc id="short"><ph id="shortdesc">设置媒体播放器选项。</ph></shortdesc>
     <prolog>
         <metadata>
             <keywords>
@@ -23,13 +23,24 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void> setPlayerOptionInInt({required String key, required int value});</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
-            <p id="desc1">媒体播放器支持通过 <parmname>key</parmname> 和 <parmname>value</parmname> 来设置选项。一般情况下，你无需知晓选项设置，使用媒体播放器默认的选项设置即可。</p>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
+            <p id="desc1">媒体播放器支持通过 <parmname>key</parmname> 和 <parmname>value</parmname> 来设置选项。</p>
             <p>该方法和 <xref keyref="setPlayerOption2"/> 的区别在于，该方法的 <parmname>value</parmname> 是 Int 型，<apiname keyref="setPlayerOption2"/> 的 <parmname>value</parmname> 是 String 型。二者不可混用。</p>
-            <note type="attention" id="desc2">请确保在 <xref keyref="open"/> 或 <xref keyref="openWithMediaSource"/> 之前调用该方法。</note> </section>
-        <section id="parameters">
-            <title>参数</title>
+            </section>
+            <section id="scenario" deliveryTarget="details">
+                <title>适用场景</title>
+                <p>需要提供技术预览或特别定制功能的场景。一般情况下，你无需调用该方法，使用媒体播放器默认的选项设置即可。</p>
+            </section>
+            <section id="timing" deliveryTarget="details">
+                <title>调用时机</title>
+                <p>该方法需要在 <xref keyref="open"/> 或 <xref keyref="openWithMediaSource"/> 之前调用。</p>
+            </section>        
+            <section id="restriction" deliveryTarget="details">
+                <title>调用限制</title>
+                <p>无。</p>
+            </section>
+            <section id="parameters" deliveryTarget="details">
+                <title>参数</title>
             <parml>
             <plentry>
                 <pt>key</pt>

diff --git a/dita/RTC-NG/API/api_imediaplayer_setplayeroption2.dita b/dita/RTC-NG/API/api_imediaplayer_setplayeroption2.dita
@@ -2,7 +2,7 @@
 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
 <reference id="api_imediaplayer_setplayeroption2">
     <title><ph keyref="setPlayerOption2"/></title>
-    <shortdesc id="short"><ph id="shortdesc">设置媒体播放器选项，用于提供技术预览或特别定制功能。</ph></shortdesc>
+    <shortdesc id="short"><ph id="shortdesc">设置媒体播放器选项。</ph></shortdesc>
     <prolog>
         <metadata>
             <keywords>
@@ -24,13 +24,17 @@
     {required String key, required String value});</codeblock> 
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <p conkeyref="setPlayerOption/desc1"/>
             <p>该方法和 <xref keyref="setPlayerOption"/> 的区别在于，该方法的 <parmname>value</parmname> 是 String 型，<apiname keyref="setPlayerOption"/> 的 <parmname>value</parmname> 是 Int 型。二者不可混用。</p>
-            <note type="attention" conkeyref="setPlayerOption/desc2"/></section>
-        <section id="parameters" conkeyref="setPlayerOption/parameters">
-            </section>
+        </section>
+        <section id="scenario" conkeyref="setPlayerOption/scenario" deliveryTarget="details"/>
+        <section id="timing" conkeyref="setPlayerOption/timing" deliveryTarget="details"/>
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="parameters" conkeyref="setPlayerOption/parameters" deliveryTarget="details"/>
         <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>

diff --git a/dita/RTC-NG/API/api_imediaplayer_setview.dita b/dita/RTC-NG/API/api_imediaplayer_setview.dita
@@ -30,9 +30,17 @@
         <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <note type="attention" props="flutter">在 Flutter 中你不需要主动调用该方法，请使用 <xref keyref="AgoraVideoView"/> 渲染本地和远端视图。</note>
         </section>
-        <section id="parameters" props="native flutter unreal bp electron rn">
-            <title>参数</title>
-            <parml>
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>该方法在加入频道前后均可调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
+            <title><ph props="native flutter unreal bp electron rn">参数</ph></title>
+            <parml props="native flutter unreal bp electron rn">
             <plentry>
                 <pt props="android hmos">videoView</pt>
                 <pt props="ios mac cpp unreal bp rn electron flutter">view</pt>