Merge branch 'release/rtc-ng/4.4.0' of github.com:AgoraIO/agora_doc_s…

…ource into release/rtc-ng/4.4.0
AgoraIO · Jul 26, 2024 · 0e95ef8 · 0e95ef8
2 parents 00f5b1a + 05281d3
commit 0e95ef8
Show file tree

Hide file tree

Showing 120 changed files with 1,474 additions and 564 deletions.
diff --git a/dita/RTC-NG/API/api_ibasespatialaudioengine_muteallremoteaudiostreams.dita b/dita/RTC-NG/API/api_ibasespatialaudioengine_muteallremoteaudiostreams.dita
@@ -31,7 +31,7 @@
             <note>
             <ul>
             <li>该方法需要在 <xref keyref="joinChannel1"/> 或 <xref keyref="joinChannel2"/> 后调用。</li>
-            <li>在使用空间音效时，如需设置是否订阅所有远端用户的音频流，建议调用该方法替代 <xref keyref="IRtcEngine"/> 的 <xref keyref="muteAllRemoteAudioStreams"/> 方法。</li>
+            <li>在使用空间音频时，如需设置是否订阅所有远端用户的音频流，建议调用该方法替代 <xref keyref="IRtcEngine"/> 的 <xref keyref="muteAllRemoteAudioStreams"/> 方法。</li>
                     <li>在调用该方法后，你需要调用 <xref keyref="updateSelfPosition"/> 和 <xref keyref="updateRemotePosition"/> 更新本地用户和远端用户的空间位置，否则该方法中的设置不会生效。</li>
             </ul></note> </section>
         <section id="parameters">

diff --git a/dita/RTC-NG/API/api_ibasespatialaudioengine_mutelocalaudiostream.dita b/dita/RTC-NG/API/api_ibasespatialaudioengine_mutelocalaudiostream.dita
@@ -31,7 +31,7 @@
             <ul>
             <li>该方法不影响音频采集状态，因为没有禁用音频采集设备。</li>
             <li>该方法需要在 <xref keyref="joinChannel1"/> 或 <xref keyref="joinChannel2"/> 后调用。</li>
-            <li>在使用空间音效时，如需设置是否发布本地音频流，建议调用该方法替代 <xref keyref="IRtcEngine"/> 的 <xref keyref="muteLocalAudioStream"/> 方法。</li>
+            <li>在使用空间音频时，如需设置是否发布本地音频流，建议调用该方法替代 <xref keyref="IRtcEngine"/> 的 <xref keyref="muteLocalAudioStream"/> 方法。</li>
             <li>成功调用该方法后，远端会触发 <xref keyref="onUserMuteAudio"/> 回调和 <xref keyref="onRemoteAudioStateChanged"/> 回调。</li>
             </ul></note> </section>
         <section id="parameters">

diff --git a/dita/RTC-NG/API/api_ibasespatialaudioengine_muteremoteaudiostream.dita b/dita/RTC-NG/API/api_ibasespatialaudioengine_muteremoteaudiostream.dita
@@ -36,7 +36,7 @@
             <note>
             <ul>
             <li>该方法需要在 <xref keyref="joinChannel1"/> 或 <xref keyref="joinChannel2"/> 后调用。</li>
-            <li>在使用空间音效时，如需设置是否订阅指定用户的音频流，建议调用该方法替代 <xref keyref="IRtcEngine"/> 的 <xref keyref="muteRemoteAudioStream"/> 方法。</li>
+            <li>在使用空间音频时，如需设置是否订阅指定用户的音频流，建议调用该方法替代 <xref keyref="IRtcEngine"/> 的 <xref keyref="muteRemoteAudioStream"/> 方法。</li>
                     </ul>
                 </note>
             </p>

diff --git a/dita/RTC-NG/API/api_ibasespatialaudioengine_release.dita b/dita/RTC-NG/API/api_ibasespatialaudioengine_release.dita
@@ -26,7 +26,7 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p>该方法释放 <apiname keyref="IBaseSpatialAudioEngine"/> 下的所有资源。当用户不需要使用空间音效时，你可以调用该方法将资源释放出来用于其他操作。</p>
+            <p>该方法释放 <apiname keyref="IBaseSpatialAudioEngine"/> 下的所有资源。当用户不需要使用空间音频时，你可以调用该方法将资源释放出来用于其他操作。</p>
             <p>调用该方法后，你将无法再使用 <apiname keyref="IBaseSpatialAudioEngine"/> 下的任何 API。
 
 

diff --git a/dita/RTC-NG/API/api_ibasespatialaudioengine_setdistanceunit.dita b/dita/RTC-NG/API/api_ibasespatialaudioengine_setdistanceunit.dita
@@ -27,7 +27,7 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p>游戏引擎里的距离单位是游戏引擎自定义的，而声网空间音效算法的距离单位为米。默认情况下，SDK 会将每单位的游戏引擎距离换算为一米。你可以调用该方法，将游戏引擎里的单位距离换算为指定的米数。</p>
+            <p>游戏引擎里的距离单位是游戏引擎自定义的，而声网空间音频算法的距离单位为米。默认情况下，SDK 会将每单位的游戏引擎距离换算为一米。你可以调用该方法，将游戏引擎里的单位距离换算为指定的米数。</p>
             <note type="note" props="hide">建议在 <xref keyref="enterRoom" /> 前调用该方法。</note> </section>
         <section id="parameters">
             <title>参数</title>

diff --git a/dita/RTC-NG/API/api_ibasespatialaudioengine_setmaxaudiorecvcount.dita b/dita/RTC-NG/API/api_ibasespatialaudioengine_setmaxaudiorecvcount.dita
@@ -28,7 +28,7 @@
         <section id="detailed_desc">
             <title>详情</title>
             <p>如果在音频接收范围内可接收的音频流数超过设置的值，则本地用户会接收音源距离较近的 <parmname>maxCount</parmname> 路音频。</p>
-            <note type="note" props="hide"><draft-comment author="LuoDan">因为服务端空间音效不发布，所以不能体现 enterRoom。</draft-comment>该方法在 <xref keyref="enterRoom" /> 前后均可调用，区别如下： 
+            <note type="note" props="hide"><draft-comment author="LuoDan">因为服务端空间音频不发布，所以不能体现 enterRoom。</draft-comment>该方法在 <xref keyref="enterRoom" /> 前后均可调用，区别如下： 
                 <ul>
                 <li>如果在 <apiname keyref="enterRoom" /> 之前调用，该方法会在进入房间时生效。</li>
                 <li>如果在 <apiname keyref="enterRoom" /> 之后调用，该方法立即生效，即改变当前音频接收范围内最多可接收的音频流数。</li>

diff --git a/dita/RTC-NG/API/api_ibasespatialaudioengine_updateselfposition.dita b/dita/RTC-NG/API/api_ibasespatialaudioengine_updateselfposition.dita
@@ -44,15 +44,15 @@
             <title>详情</title>
             <p id="effect"><ph props="hide">在不同类下调用该方法时，作用不同：</ph>
             <ul>
-            <li props="hide">在 <xref keyref="ICloudSpatialAudioEngine" /> 类下调用该方法时，SDK 会向声网空间音效服务器更新本地用户的空间位置。声网空间音效服务器会根据本地和远端用户的世界坐标和音频接收范围计算用户的空间音效参数。</li>
-            <li>在 <xref keyref="ILocalSpatialAudioEngine" /> 类下，该方法需要和 <xref keyref="updateRemotePosition" /> 搭配使用。SDK 会根据该方法和 <apiname keyref="updateRemotePosition" /> 设置的参数计算本地和远端用户之间的相对位置，从而计算用户的空间音效参数。</li>
+            <li props="hide">在 <xref keyref="ICloudSpatialAudioEngine" /> 类下调用该方法时，SDK 会向声网空间音频服务器更新本地用户的空间位置。声网空间音频服务器会根据本地和远端用户的世界坐标和音频接收范围计算用户的空间音频参数。</li>
+            <li>在 <xref keyref="ILocalSpatialAudioEngine" /> 类下，该方法需要和 <xref keyref="updateRemotePosition" /> 搭配使用。SDK 会根据该方法和 <apiname keyref="updateRemotePosition" /> 设置的参数计算本地和远端用户之间的相对位置，从而计算用户的空间音频参数。</li>
             </ul></p>
             <note type="note" id="note" props="hide">
                 <ul>
                     <li>该方法需要在 <xref keyref="enterRoom" /> 后调用。</li>
                     <li>如果在 <apiname keyref="ICloudSpatialAudioEngine" /> 类下调用该方法，需注意：
                         <ul>
-                        <li>多次调用该方法时，建议调用时间间隔为 [120,7000) 毫秒，否则 SDK 和声网空间音效服务器会失去同步。</li>
+                        <li>多次调用该方法时，建议调用时间间隔为 [120,7000) 毫秒，否则 SDK 和声网空间音频服务器会失去同步。</li>
                         <li>如果本次更新的空间位置和上次位置间的距离小于 0.2 米或各方向旋转角度小于 15 度，则 SDK 不会更新本次空间位置。</li>
                         </ul></li>
                 </ul>

diff --git a/dita/RTC-NG/API/api_ilocalspatialaudioengine_release.dita b/dita/RTC-NG/API/api_ilocalspatialaudioengine_release.dita
@@ -29,8 +29,8 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p>该方法释放 <apiname keyref="ILocalSpatialAudioEngine" /> 下的所有资源。当用户不需要使用空间音效时，你可以调用该方法将资源释放出来用于其他操作。</p>
-            <p>调用该方法后，你将无法再使用 <apiname keyref="ILocalSpatialAudioEngine" /> 下的任何 API。如需再次使用空间音效，你需要等 <apiname keyref="release_ILocalSpatialAudioEngine" /> 执行结束后再调用 <xref keyref="initialize_ILocalSpatialAudioEngine" /> 创建一个新的 <apiname keyref="ILocalSpatialAudioEngine" />。
+            <p>该方法释放 <apiname keyref="ILocalSpatialAudioEngine" /> 下的所有资源。当用户不需要使用空间音频时，你可以调用该方法将资源释放出来用于其他操作。</p>
+            <p>调用该方法后，你将无法再使用 <apiname keyref="ILocalSpatialAudioEngine" /> 下的任何 API。如需再次使用空间音频，你需要等 <apiname keyref="release_ILocalSpatialAudioEngine" /> 执行结束后再调用 <xref keyref="initialize_ILocalSpatialAudioEngine" /> 创建一个新的 <apiname keyref="ILocalSpatialAudioEngine" />。
 
 
             <note>该方法需要在 <xref keyref="IRtcEngine" /> 的 <xref keyref="release" /> 方法前调用。</note></p>

diff --git a/dita/RTC-NG/API/api_ilocalspatialaudioengine_updateremoteposition.dita b/dita/RTC-NG/API/api_ilocalspatialaudioengine_updateremoteposition.dita
@@ -34,7 +34,7 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p>成功调用该方法后，SDK 会根据本地和远端用户的相对位置计算空间音效参数。</p>
+            <p>成功调用该方法后，SDK 会根据本地和远端用户的相对位置计算空间音频参数。</p>
             <note type="note">该方法需要在 <xref keyref="joinChannel1"/> 或 <xref keyref="joinChannel2"/> 后调用。</note> </section>
         <section id="parameters">
             <title>参数</title>

diff --git a/dita/RTC-NG/API/api_imediaplayer_play.dita b/dita/RTC-NG/API/api_imediaplayer_play.dita
@@ -27,7 +27,8 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p>调用 <ph keyref="open" /> 或 <ph keyref="seek" /> 后，你可以调用该方法播放媒体文件。</p>
+            <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>
         <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
@@ -30,11 +30,10 @@
         <section id="detailed_desc">
             <title>详情</title>
             <p>成功调用该方法后，你会收到 <xref keyref="onPlayerEvent" /> 回调，报告当前播放器发生的事件，如定位开始、定位成功或定位失败。</p>
-            <p>如果你想定位播放，请进行如下操作：
             <ul>
-            <li>调用该方法定位。</li>
-            <li>定位完成后，调用 <xref keyref="play" /> 方法播放。</li>
-            </ul></p>
+                <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>
         <section id="parameters">
             <title>参数</title>

diff --git a/dita/RTC-NG/API/api_imediaplayer_setloopcount.dita b/dita/RTC-NG/API/api_imediaplayer_setloopcount.dita
@@ -37,7 +37,12 @@
             <parml>
             <plentry>
                 <pt>loopCount</pt>
-                <pd>循环播放的次数。</pd>
+                <pd>循环播放的次数。
+                    <ul>
+                        <li>≥0：循环次数。例如，设为 0 表示不循环播放，一共播放一次；设为 1 表示循环播放一次，一共播放 2 次。</li>
+                        <li>-1：无限循环播放。</li>
+                    </ul>
+                </pd>
             </plentry>
             </parml> </section>
         <section id="return_values">

diff --git a/dita/RTC-NG/API/api_imediaplayer_setspatialaudioparams.dita b/dita/RTC-NG/API/api_imediaplayer_setspatialaudioparams.dita
@@ -2,7 +2,7 @@
 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
 <reference id="api_imediaplayer_setspatialaudioparams">
     <title><ph keyref="setSpatialAudioParams" /></title>
-    <shortdesc id="short"><ph id="shortdesc">开启或关闭媒体播放器的空间音效。</ph></shortdesc>
+    <shortdesc id="short"><ph id="shortdesc">开启或关闭媒体播放器的空间音频。</ph></shortdesc>
     <prolog>
         <metadata>
             <keywords>
@@ -27,16 +27,16 @@
         </section>
         <section id="detailed_desc">
             <title>详情</title>
-            <p>成功设置媒体播放器的空间音效参数后，SDK 会开启媒体播放器的空间音效，即本地用户听媒体资源会有空间感。</p>
-            <p>如果需关闭媒体播放器的空间音效，你需要将 <parmname>params</parmname> 参数设为空。</p>
+            <p>成功设置媒体播放器的空间音频参数后，SDK 会开启媒体播放器的空间音频，即本地用户听媒体资源会有空间感。</p>
+            <p>如果需关闭媒体播放器的空间音频，你需要将 <parmname>params</parmname> 参数设为空。</p>
         </section>
         <section id="parameters">
             <title>参数</title>
             <parml>
             <plentry>
                 <pt props="native unreal bp flutter">params</pt>
                 <pt props="unity cs">spatial_audio_params</pt>
-                <pd>媒体播放器的空间音效参数。详见 <xref keyref="SpatialAudioParams" />。</pd>
+                <pd>媒体播放器的空间音频参数。详见 <xref keyref="SpatialAudioParams" />。</pd>
             </plentry>
             </parml> </section>
         <section id="return_values">

diff --git a/dita/RTC-NG/API/api_imediaplayer_stop.dita b/dita/RTC-NG/API/api_imediaplayer_stop.dita
@@ -26,6 +26,9 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void&gt; stop();</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
+            <p>调用该方法停止播放后，如需重新播放，需要调用 <xref keyref="open"/> 或 <xref keyref="openWithMediaSource"/> 再次打开媒体资源。</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_irtcengine_adjustuserplaybacksignalvolume.dita b/dita/RTC-NG/API/api_irtcengine_adjustuserplaybacksignalvolume.dita
@@ -27,7 +27,7 @@
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
         <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
-            <p>你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。</p>
+            <p id="desc">你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。</p>
         </section>
         <section id="timing" deliveryTarget="details">
             <title>调用时机</title>

diff --git a/dita/RTC-NG/API/api_irtcengine_configrhythmplayer.dita b/dita/RTC-NG/API/api_irtcengine_configrhythmplayer.dita
@@ -25,12 +25,26 @@
             <codeblock props="flutter" outputclass="language-dart">Future&lt;void> configRhythmPlayer(AgoraRhythmPlayerConfig config);</codeblock>
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
-        <section id="detailed_desc">
-            <title>详情</title>
-            <p>调用 <xref keyref="startRhythmPlayer"/> 后，你可以调用该方法重新配置虚拟节拍器。</p>
+        <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
+            <ul>
+            <li>调用 <xref keyref="startRhythmPlayer"/> 后，你可以调用该方法重新配置虚拟节拍器。</li>
+            <li>开启虚拟节拍器后，SDK 会从头开始播放指定的音频文件，并根据你在 <xref keyref="AgoraRhythmPlayerConfig"/> 中设置的 <parmname>beatsPerMinute</parmname> 控制每个文件的播放时长。例如，将 <parmname>beatsPerMinute</parmname> 设为 <codeph>60</codeph>，则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长，则 SDK 只播放节拍时长部分的音频。</li>
+            <li>虚拟节拍器的声音默认不会发布至远端，如果你希望远端用户听到虚拟节拍器的声音，你可以在调用该方法后，将 <xref keyref="ChannelMediaOptions"/> 中的 <parmname>publishRhythmPlayerTrack</parmname> 设为 <codeph><ph keyref="true"/></codeph>。</li>
+            </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>成功调用该方法后，SDK 会在本地触发 <xref keyref="onRhythmPlayerStateChanged"/> 回调，报告虚拟节拍器的状态。</p>
-            <note conkeyref="startRhythmPlayer/rhythm_play"/> </section>
-        <section id="parameters">
+        </section>
+        <section id="parameters" deliveryTarget="details">
             <title>参数</title>
             <parml>
             <plentry>

diff --git a/dita/RTC-NG/API/api_irtcengine_createdatastream2.dita b/dita/RTC-NG/API/api_irtcengine_createdatastream2.dita
@@ -31,7 +31,7 @@
         </section>
         <section id="timing" deliveryTarget="details">
             <title>调用时机</title>
-            <p>该方法需要在加入频道后调用。</p>
+            <p>该方法在加入频道前后均可调用。</p>
         </section>
         <section id="restriction" deliveryTarget="details">
             <title>调用限制</title>

diff --git a/dita/RTC-NG/API/api_irtcengine_createmediaplayer.dita b/dita/RTC-NG/API/api_irtcengine_createmediaplayer.dita
@@ -27,7 +27,7 @@
             <codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
         </section>
         <section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
-            <p>在调用 <xref keyref="IMediaPlayer"/> 类下的其他 API 前，你需要先调用该方法创建一个媒体播放器实例。</p>
+            <p>在调用 <xref keyref="IMediaPlayer"/> 类下的其他 API 前，你需要先调用该方法创建一个媒体播放器实例。如果你需要创建多个实例，可以多次调用该方法。</p>
         </section>
         <section id="timing" deliveryTarget="details">
             <title>调用时机</title>
-Original file line number
+Diff line change
@@ Expand Up / @@ -36,7 +36,7 @@ @@
                 <note>
                 <ul>
                 <li>该方法需要在 <xref keyref="joinChannel1"/> 或 <xref keyref="joinChannel2"/> 后调用。</li>
-                <li>在使用空间音效时，如需设置是否订阅指定用户的音频流，建议调用该方法替代 <xref keyref="IRtcEngine"/> 的 <xref keyref="muteRemoteAudioStream"/> 方法。</li>
+                <li>在使用空间音频时，如需设置是否订阅指定用户的音频流，建议调用该方法替代 <xref keyref="IRtcEngine"/> 的 <xref keyref="muteRemoteAudioStream"/> 方法。</li>
                         </ul>
                     </note>
                 </p>
@@ Expand Down @@