Merge pull request #3710 from AgoraIO/api-ld-batch4

ld batch4
AgoraIO · Jul 30, 2024 · b9de63c · b9de63c
2 parents 2a555f8 + 16ce4d5
commit b9de63c
Show file tree

Hide file tree

Showing 15 changed files with 161 additions and 103 deletions.
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_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_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>
+        <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>

diff --git a/dita/RTC-NG/API/api_imediaplayer_stop.dita b/dita/RTC-NG/API/api_imediaplayer_stop.dita
@@ -29,6 +29,13 @@
         <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <p>调用该方法停止播放后，如需重新播放，需要调用 <xref keyref="open"/> 或 <xref keyref="openWithMediaSource"/> 再次打开媒体资源。</p>
         </section>
+        <section id="timing" deliveryTarget="details">
+            <title>调用时机</title>
+            <p>该方法需要在 <ph keyref="play" /> 之后调用。</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>调用限制</title>
+            <p>无。</p>
         <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_irtcengine_getaudiomixingduration.dita b/dita/RTC-NG/API/api_irtcengine_getaudiomixingduration.dita
@@ -25,16 +25,21 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;int&gt; getAudioMixingDuration();</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>
-            <note type="attention">
-            <p>你需要在调用 <xref keyref="startAudioMixing2"/> 并收到 <xref keyref="onAudioMixingStateChanged"/><codeph>(<ph keyref="AUDIO_MIXING_STATE_PLAYING"/>)</codeph> 回调后调用该方法。</p>
-            </note> </section>
-        <section id="return_values" props="native unreal bp electron unity rn flutter cs">
+        </section>
+            <section id="timing" deliveryTarget="details">
+                <title>调用时机</title>
+                <p>该方法需要在 <xref keyref="startAudioMixing2" /> 之后，并收到 <xref keyref="onAudioMixingStateChanged" /><codeph>(<ph keyref="AUDIO_MIXING_STATE_PLAYING" />)</codeph> 回调后调用。</p>
+            </section>        
+            <section id="restriction" deliveryTarget="details">
+                <title>调用限制</title>
+                <p>无。</p>
+            </section>
+            <section id="return_values" props="native unreal bp electron unity rn flutter cs">
             <title>返回值</title>
             <ul>
-            <li>≥ 0: 方法调用成功返回音乐文件时长。</li>
+            <li>≥ 0: 方法调用成功则返回音乐文件时长。</li>
             <li>&lt; 0: 方法调用失败。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></li>
             </ul> </section>
     </refbody>

diff --git a/dita/RTC-NG/API/api_irtcengine_getaudiomixingplayoutvolume.dita b/dita/RTC-NG/API/api_irtcengine_getaudiomixingplayoutvolume.dita
@@ -25,13 +25,18 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;int&gt; getAudioMixingPlayoutVolume();</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
-            <p>该方法获取混音的音乐文件本地播放音量，方便排查音量相关问题。</p>
-            <note type="attention">
-            <p>你需要在调用 <xref keyref="startAudioMixing2" /> 并收到<apiname keyref="onAudioMixingStateChanged" /><codeph>(<ph keyref="AUDIO_MIXING_STATE_PLAYING" />)</codeph> 回调后调用该方法。</p>
-            </note> </section>
-        <section id="return_values" props="native unreal bp electron unity rn flutter cs">
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
+            <p>你可以调用该方法获取混音的音乐文件的本地播放音量，方便排查音量相关问题。</p>
+        </section>
+            <section id="timing" deliveryTarget="details">
+                <title>调用时机</title>
+                <p>该方法需要在 <xref keyref="startAudioMixing2" /> 之后，并收到 <xref keyref="onAudioMixingStateChanged" /><codeph>(<ph keyref="AUDIO_MIXING_STATE_PLAYING" />)</codeph> 回调后调用。</p>
+            </section>        
+            <section id="restriction" deliveryTarget="details">
+                <title>调用限制</title>
+                <p>无。</p>
+            </section>
+            <section id="return_values" props="native unreal bp electron unity rn flutter cs">
             <title>返回值</title>
             <ul>
             <li>≥ 0: 方法调用成功则返回音量值，范围为 [0,100]。</li>

diff --git a/dita/RTC-NG/API/api_irtcengine_setaudiomixingdualmonomode.dita b/dita/RTC-NG/API/api_irtcengine_setaudiomixingdualmonomode.dita
@@ -25,16 +25,25 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void&gt; setAudioMixingDualMonoMode(AudioMixingDualMonoMode mode);</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
-            <p>在双声道音频文件中，左声道和右声道可以存储不同的音频数据。根据实际需要，你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如，在 KTV 场景中，音频文件的左声道存储了伴奏，右声道存储了原唱的歌声。如果你只需听伴奏，调用该方法设置音频文件的声道模式为左声道模式；如果你需要同时听伴奏和原唱，调用该方法设置声道模式为混合模式。</p>
-            <note type="attention" id="note">
-            <ul>
-            <li>你需要在调用 <xref keyref="startAudioMixing2" /> 并收到 <xref keyref="onAudioMixingStateChanged" /><codeph>(<ph keyref="AUDIO_MIXING_STATE_PLAYING" />)</codeph> 回调后调用该方法。</li>
-            <li>该方法仅适用于双声道的音频文件。</li>
-            </ul></note> </section>
-        <section id="parameters">
-            <title>参数</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
+            <p>在双声道音频文件中，左声道和右声道可以存储不同的音频数据。根据实际需要，你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。</p>
+        </section>
+            <section id="scenario" deliveryTarget="details">
+                <title>适用场景</title>
+                <p>在 KTV 场景中，音频文件的左声道存储了伴奏，右声道存储了原唱的歌声。你可以根据实际需求进行设置：<ul>
+                    <li>如果你只需听伴奏，则用该方法设置音频文件的声道模式为左声道模式。</li>
+                    <li>如果你需要同时听伴奏和原唱，则调用该方法设置声道模式为混合模式。</li></ul></p>
+            </section>
+            <section id="timing" deliveryTarget="details">
+                <title>调用时机</title>
+                <p>该方法需要在 <xref keyref="startAudioMixing2" /> 之后，并收到 <xref keyref="onAudioMixingStateChanged" /><codeph>(<ph keyref="AUDIO_MIXING_STATE_PLAYING" />)</codeph> 回调后调用。</p>
+            </section>        
+            <section id="restriction" deliveryTarget="details">
+                <title>调用限制</title>
+                <p>该方法仅适用于双声道的音频文件。</p>
+            </section>
+            <section id="parameters" deliveryTarget="details">
+                <title>参数</title>
             <parml>
             <plentry>
                 <pt>mode</pt>