[MediaPlayer] Change documentation for streaming APIs (#826)

[platform/core/csapi/tizenfx.git] / src / Tizen.Multimedia.MediaPlayer / Player / Player.Properties.cs

diff --git a/src/Tizen.Multimedia.MediaPlayer/Player/Player.Properties.cs b/src/Tizen.Multimedia.MediaPlayer/Player/Player.Properties.cs
index 058f56a..2af4ce9 100644 (file)
--- a/src/Tizen.Multimedia.MediaPlayer/Player/Player.Properties.cs
+++ b/src/Tizen.Multimedia.MediaPlayer/Player/Player.Properties.cs
@@ -40,11 +40,10 @@ namespace Tizen.Multimedia
         /// <param name="reBufferMillisecond">A duration of buffering data that must be prerolled to resume playback,
         /// when player is internally paused for buffering.
         /// Except 0 and -1, setting at least 1000 milliseconds is recommended to ensure the normal buffering operation.
-        /// 0 : use platform default value which could be different depending on the streaming type and network status. (the initial value)
-        /// -1 : use current value. (since 5.5)
-        /// <para>0 means platform default value which could be different depending on the streaming type and network status.
+        /// 0 : use platform default value, which depends on the streaming type and network status. It is set as the initial value of this parameter.
         /// If the player state is <see cref="PlayerState.Playing"/> or <see cref="PlayerState.Paused"/>,
-        /// this function will return correct time value instead of 0. (since 5.5)</para></param>
+        /// this function will return correct time value instead of 0. (since 5.5)
+        /// -1 : use current value. (since 5.5)</param>
         /// <since_tizen> 5 </since_tizen>
         public PlayerBufferingTime(int preBufferMillisecond = -1, int reBufferMillisecond = -1)
         {
@@ -560,6 +559,86 @@ namespace Tizen.Multimedia
             }
         }
 
+        /// <summary>
+        /// Gets or sets the audio pitch.
+        /// </summary>
+        /// <value>The value indicating whether or not AudioPitch is enabled. The default is false.</value>
+        /// <remarks>This function is used for audio content only.
+        /// To set, the player must be in the <see cref="PlayerState.Idle"/> state.</remarks>
+        /// <exception cref="InvalidOperationException">The player is not in the valid state.</exception>
+        /// <exception cref="ObjectDisposedException">The player has already been disposed of.</exception>
+        /// <seealso cref="AudioPitch"/>
+        /// <since_tizen> 6 </since_tizen>
+        public bool AudioPitchEnabled
+        {
+            get
+            {
+                ValidateNotDisposed();
+                NativePlayer.IsAudioPitchEnabled(Handle, out var value).
+                    ThrowIfFailed(this, "Failed to get whether the audio pitch is enabled or not");
+                return value;
+            }
+
+            set
+            {
+                ValidateNotDisposed();
+                ValidatePlayerState(PlayerState.Idle);
+
+                NativePlayer.SetAudioPitchEnabled(Handle, value).
+                    ThrowIfFailed(this, "Failed to enable the audio pitch of the player");
+            }
+        }
+
+        /// <summary>
+        /// Gets or sets the audio pitch value.
+        /// </summary>
+        /// <value>The audio stream pitch value. The default is 1.</value>
+        /// <remarks>Enabling pitch control could increase the CPU usage on some devices.
+        /// This function is used for audio content only.</remarks>
+        /// <exception cref="InvalidOperationException">A pitch is not enabled.</exception>
+        /// <exception cref="ObjectDisposedException">The player has already been disposed of.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">
+        ///     value is less than 0.5.
+        ///     -or-<br/>
+        ///     value is greater than 2.0.<br/>
+        /// </exception>
+        /// <seealso cref="AudioPitchEnabled"/>
+        /// <since_tizen> 6 </since_tizen>
+        public float AudioPitch
+        {
+            get
+            {
+                ValidateNotDisposed();
+
+                if (AudioPitchEnabled == false)
+                {
+                    throw new InvalidOperationException("An audio pitch is not enabled.");
+                }
+
+                NativePlayer.GetAudioPitch(Handle, out var value).
+                    ThrowIfFailed(this, "Failed to get the audio pitch");
+
+                return value;
+            }
+
+            set
+            {
+                ValidateNotDisposed();
+
+                if (AudioPitchEnabled == false)
+                {
+                    throw new InvalidOperationException("An audio pitch is not enabled.");
+                }
+
+                if (value < 0.5F || 2.0F < value)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), value, "Valid value is 0.5 to 2.0");
+                }
+
+                NativePlayer.SetAudioPitch(Handle, value).ThrowIfFailed(this, "Failed to set the audio pitch");
+            }
+        }
+
         private SphericalVideo _sphericalVideo;
 
         /// <summary>