Merge pull request #3716 from AgoraIO/translation/4.x-api-ref

New YiCAT updates
AgoraIO · Aug 16, 2024 · 5d22cff · 5d22cff
2 parents 1f9afd8 + 9aafc83
commit 5d22cff
Show file tree

Hide file tree

Showing 94 changed files with 1,132 additions and 771 deletions.
diff --git a/en-US/dita/RTC-NG/API/api_ibasespatialaudioengine_setmaxaudiorecvcount.dita b/en-US/dita/RTC-NG/API/api_ibasespatialaudioengine_setmaxaudiorecvcount.dita
@@ -28,7 +28,7 @@
         <section id="detailed_desc">
             <title>Details</title>
             <p>If the number of receivable streams exceeds the set value, the local user receives the <parmname>maxCount</parmname> streams that are closest to the local user.</p>
-            <note type="note" props="hide"><draft-comment author="LuoDan">因为服务端空间音效不发布，所以不能体现 enterRoom。</draft-comment>You can call this method either before or after <xref keyref="enterRoom" />, with the following differences:<ul>
+            <note type="note" props="hide"><draft-comment author="LuoDan">因为服务端空间音频不发布，所以不能体现 enterRoom。</draft-comment>You can call this method either before or after <xref keyref="enterRoom" />, with the following differences:<ul>
                 <li>If you call this method before <apiname keyref="enterRoom" />, this method takes effect when entering the room.</li>
                 <li>If you call this method after <apiname keyref="enterRoom" />, this method takes effect immediately and changes the current maximum number of received streams of the local user.</li>
                 </ul></note> </section>

diff --git a/en-US/dita/RTC-NG/API/api_ibasespatialaudioengine_updateplayerpositioninfo.dita b/en-US/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>Details</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <p>After a successful update, the local user can hear the change in the spatial position of the media player.</p>
         </section>
-        <section id="parameters">
+        <section id="timing" deliveryTarget="details">
+            <title>Call timing</title>
+            <p>This method can be called either before or after joining the channel.</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>Restrictions</title>
+            <p>None.</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>Parameters</title>
             <parml>
             <plentry id="mpkid">

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_adjustplayoutvolume.dita b/en-US/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>Call timing</title>
+            <p>This method can be called either before or after joining the channel.</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>Restrictions</title>
+            <p>None.</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>Parameters</title>
             <parml>
             <plentry>

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_adjustpublishsignalvolume.dita b/en-US/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>Details</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <p>After connected to the Agora server, you can call this method to adjust the volume of the media file heard by the remote user.</p>
         </section>
-        <section id="parameters">
+        <section id="timing" deliveryTarget="details">
+            <title>Call timing</title>
+            <p>This method can be called either before or after joining the channel.</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>Restrictions</title>
+            <p>None.</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>Parameters</title>
             <parml>
             <plentry>

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_getstreaminfo.dita b/en-US/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>Details</title>
-            <note type="attention" id="note">Call this method after calling <xref keyref="getStreamCount" />.</note> </section>
-        <section id="parameters">
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title"/>
+        <section id="timing" deliveryTarget="details">
+            <title>Call timing</title>
+            <p>Call this method after calling <xref keyref="getStreamCount" />.</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>Restrictions</title>
+            <p>None.</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>Parameters</title>
             <parml>
             <plentry>

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_mute.dita b/en-US/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>Call timing</title>
+            <p>You can call this method either before or after joining a channel.</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>Restrictions</title>
+            <p>None.</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>Parameters</title>
             <parml>
             <plentry>

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_open.dita b/en-US/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>Details</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <p props="hide">On the Android platform, if you need to open a file in URI format, use <xref keyref="open2" />.</p>
             <p id="uri" props="android hmos">This method supports playing URI files starting with <codeph>content://</codeph>.</p>
             <p id="format" props="native"><ph props="cn">For supported formats of Agora media player, see <xref keyref="media-player"/>.</ph></p>
             <p props="hide">If you want to choose the CDN route for playing the media resource, you can call the <xref keyref="openWithAgoraCDNSrc" /> method. Agora changes the CDN route through the self-developed scheduling center to improve the viewing user experience. If you do not need to choose the CDN route for playing the media resource, you can call the <xref keyref="open" /> method.</p>
             <note type="attention" id="note">
             <p props="native unreal bp unity electron flutter cs">This method is called asynchronously.</p>
-            <p id="open">If you need to play a media file, make sure you receive the <xref keyref="onPlayerSourceStateChanged" /> callback reporting <apiname keyref="PLAYER_STATE_OPEN_COMPLETED" /> before calling the <xref keyref="play" /> method to play the file.</p>
             </note> </section>
-        <section id="parameters">
+        <section id="timing" deliveryTarget="details">
+            <title>Call timing</title>
+            <p>This method can be called either before or after joining the channel.</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>Restrictions</title>
+            <p>None.</p>
+        </section>
+        <section id="related" deliveryTarget="details">
+            <title>Related callbacks</title>
+            <p id="open">After calling this method, the SDK triggers the <xref keyref="onPlayerSourceStateChanged" /> callback. After receiving the report of the playback status as <apiname keyref="PLAYER_STATE_OPEN_COMPLETED" />, you can call the <xref keyref="play" /> method to play the media file.</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>Parameters</title>
             <parml>
             <plentry>

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_pause.dita b/en-US/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>Call timing</title>
+            <p>You can call this method either before or after joining a channel.</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>Restrictions</title>
+            <p>None.</p>
+        </section>
         <section id="return_values">
             <title><ph keyref="return-section-title"/></title>
             <p props="flutter">When the method call succeeds, there is no return value; when fails, the <xref keyref="AgoraRtcException"/> exception is thrown. You need to catch the exception and handle it accordingly. <ph props="cn">See <xref keyref="error-code-link"/> for details and resolution suggestions.</ph></p>

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_play.dita b/en-US/dita/RTC-NG/API/api_imediaplayer_play.dita
@@ -25,9 +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>Details</title>
-            <p>After calling <ph keyref="open" /> or <ph keyref="seek" />, you can call this method to play the media file.</p>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title"/>
+        <section id="timing" deliveryTarget="details">
+            <title>Call timing</title>
+            <ul><li>Call this method after calling <xref keyref="open" /> or <xref keyref="openWithMediaSource"/> opening a media file and receiving a <xref keyref="onPlayerSourceStateChanged"/> callback reporting the status as <ph keyref="PLAYER_STATE_OPEN_COMPLETED"/>.</li>
+                 <li>Call the method after calling <xref keyref="seek" />.</li></ul>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>Restrictions</title>
+            <p>None.</p>
         </section>
         <section id="return_values">
             <title><ph keyref="return-section-title"/></title>

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_registerplayersourceobserver.dita b/en-US/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>Call timing</title>
+            <p>This method can be called either before or after joining the channel.</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>Restrictions</title>
+            <p>None.</p>
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>Parameters</title>
             <parml>
             <plentry>

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_seek.dita b/en-US/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>Details</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
+            <ul>
+                <li>If you call <apiname keyref="seek"/> after the playback has completed (upon receiving callback <xref keyref="onPlayerSourceStateChanged"/> reporting playback status as <ph keyref="PLAYER_STATE_PLAYBACK_COMPLETED"/> or <ph keyref="PLAYER_STATE_PLAYBACK_ALL_LOOPS_COMPLETED"/>), the SDK will play the media file from the specified position. At this point, you will receive callback <xref keyref="onPlayerSourceStateChanged"/> reporting playback status as <ph keyref="PLAYER_STATE_PLAYING"/>.</li>
+                <li>If you call <apiname keyref="seek"/> while the playback is paused, upon successful call of this method, the SDK will seek to the specified position. To resume playback, call <xref keyref="resume"/> or<xref keyref="play"/> .</li>
+            </ul></section>
+        <section id="timing" deliveryTarget="details">
+            <title>Call timing</title>
+            <p>You can call this method either before or after joining a channel.</p>
+        </section>        
+        <section id="restriction" deliveryTarget="details">
+            <title>Restrictions</title>
+            <p>None.</p>
+        </section>
+        <section id="related" deliveryTarget="details">
+            <title>Related callbacks</title>
             <p>After successfully calling this method, you will receive the <xref keyref="onPlayerEvent" /> callback, reporting the result of the seek operation to the new playback position.</p>
-            <p>To play the media file from a specific position, do the following:<ul>
-            <li>Call this method to seek to the position you want to begin playback.</li>
-            <li>Call the <xref keyref="play" /> method to play the media file.</li>
-            </ul></p>
         </section>
-        <section id="parameters">
+        <section id="parameters" deliveryTarget="details">
             <title>Parameters</title>
             <parml>
             <plentry>

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_setloopcount.dita b/en-US/dita/RTC-NG/API/api_imediaplayer_setloopcount.dita
@@ -37,7 +37,11 @@
             <parml>
             <plentry>
                 <pt>loopCount</pt>
-                <pd>The number of times the audio effect loops:</pd>
+                <pd>The number of times the audio effect loops:<ul>
+                        <li>≥0: Number of times for playing. For example, setting it to 0 means no loop playback, playing only once; setting it to 1 means loop playback once, playing a total of twice.</li>
+                        <li>-1: Play the audio file in an infinite loop.</li>
+                    </ul>
+                </pd>
             </plentry>
             </parml> </section>
         <section id="return_values">

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_setplayeroption.dita b/en-US/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">Set media player options for providing technical previews or special customization features.</ph></shortdesc>
+    <shortdesc id="short"><ph id="shortdesc">Sets media player options.</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>Details</title>
-            <p id="desc1">The media player supports setting options through <parmname>key</parmname> and <parmname>value</parmname>. In general, you don't need to know about the option settings. You can use the default option settings of the media player.</p>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
+            <p id="desc1">The media player supports setting options through <parmname>key</parmname> and <parmname>value</parmname>.</p>
             <p>The difference between this method and <xref keyref="setPlayerOption2"/> is that the <parmname>value</parmname> parameter of this method is of type Int, while the <parmname>value</parmname> of <apiname keyref="setPlayerOption2"/> is of type String. These two methods cannot be used together.</p>
-            <note type="attention" id="desc2">Ensure that you call this method before <xref keyref="open"/> or <xref keyref="openWithMediaSource"/>.</note> </section>
-        <section id="parameters">
-            <title>Parameters</title>
+            </section>
+            <section id="scenario" deliveryTarget="details">
+                <title>Applicable scenarios</title>
+                <p>Scenarios that require technical previews or special customization features. In general, you do not need to call this method; you can simply use the default options provided by the media player.</p>
+            </section>
+            <section id="timing" deliveryTarget="details">
+                <title>Call timing</title>
+                <p>Call this method before the <xref keyref="open"/> or <xref keyref="openWithMediaSource"/> method.</p>
+            </section>        
+            <section id="restriction" deliveryTarget="details">
+                <title>Restrictions</title>
+                <p>None.</p>
+            </section>
+            <section id="parameters" deliveryTarget="details">
+                <title>Parameters</title>
             <parml>
             <plentry>
                 <pt>key</pt>

diff --git a/en-US/dita/RTC-NG/API/api_imediaplayer_setplayeroption2.dita b/en-US/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">Set media player options for providing technical previews or special customization features.</ph></shortdesc>
+    <shortdesc id="short"><ph id="shortdesc">Sets media player options.</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>Details</title>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
             <p conkeyref="setPlayerOption/desc1"/>
             <p>The difference between this method and <xref keyref="setPlayerOption"/> is that the <parmname>value</parmname> parameter of this method is of type String, while the <parmname>value</parmname> of <apiname keyref="setPlayerOption"/> is of type String. These two methods cannot be used together.</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>Restrictions</title>
+            <p>None.</p>
+        </section>
+        <section id="parameters" conkeyref="setPlayerOption/parameters" deliveryTarget="details"/>
         <section id="return_values">
             <title><ph keyref="return-section-title"/></title>
             <p props="flutter">When the method call succeeds, there is no return value; when fails, the <xref keyref="AgoraRtcException"/> exception is thrown. You need to catch the exception and handle it accordingly. <ph props="cn">See <xref keyref="error-code-link"/> for details and resolution suggestions.</ph></p>