src/Tizen.Multimedia.MediaPlayer/Player/AudioOffload.cs

   1 /*
   2  * Copyright (c) 2019 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 using System;
  18 using System.Diagnostics;
  19 using System.Collections.Generic;
  20 using static Interop;
  21
  22 namespace Tizen.Multimedia
  23 {
  24     /// <summary>
  25     /// The class that control the audio offload for <see cref="Multimedia.Player"/>.
  26     /// </summary>
  27     /// <since_tizen> 6 </since_tizen>
  28     public class AudioOffload
  29     {
  30         private IList<MediaFormatAudioMimeType> _supportedFormat;
  31         private Player _player { get; }
  32
  33         /// <summary>
  34         /// Provides a means to retrieve audio offload information.
  35         /// </summary>
  36         /// <since_tizen> 6 </since_tizen>
  37         internal AudioOffload(Player player)
  38         {
  39             Debug.Assert(player != null);
  40             _player = player;
  41         }
  42
  43         private bool _enabled;
  44         internal void CheckDisabled()
  45         {
  46             if (_enabled)
  47             {
  48                 throw new NotAvailableException("the audio offload is enabled.");
  49             }
  50         }
  51
  52         /// <summary>
  53         /// Enables or disables the audio offload.
  54         /// </summary>
  55         /// <value>The value indicating whether or not audio offload is enabled. The default value is false.</value>
  56         /// <remarks><para>The player lets the hardware decode and render the sound if the audio offload is enabled.
  57         /// Audio offload can reduce the power consumption, but disable the ability to handle output PCM.
  58         /// Please check the below list of functions which will not work if offloading is enabled.</para>
  59         /// <para>If audio offload is enabled, the following functions will return <see cref="NotAvailableException"/>: <br/>
  60         /// <see cref="AudioEffect"/><br/>
  61         /// <see cref="EqualizerBand"/><br/>
  62         /// <see cref="PlayerTrackInfo"/><br/>
  63         /// <see cref="Player.EnableExportingAudioData"/><br/>
  64         /// <see cref="Player.AudioLatencyMode"/><br/>
  65         /// <see cref="Player.SetPlaybackRate"/><br/>
  66         /// <see cref="Player.ReplayGain"/><br/>
  67         /// <see cref="Player.AudioPitch"/><br/>
  68         /// <see cref="Player.AudioPitchEnabled"/><br/></para>
  69         /// <para>Although they are called before offload is enabled, they don't work normally.</para>
  70         /// <para>To set, the player must be in the <see cref="PlayerState.Idle"/> state.
  71         /// The sound stream type of the player should be <see cref="AudioStreamType.Media"/>.</para></remarks>
  72         /// <feature>http://tizen.org/feature/multimedia.player.audio_offload</feature>
  73         /// <exception cref="NotSupportedException">The required feature is not supported.</exception>
  74         /// <exception cref="ObjectDisposedException">The player has already been disposed of.</exception>
  75         /// <exception cref="InvalidOperationException">
  76         ///     The player is not in the valid state.<br/>
  77         ///     -or-<br/>
  78         ///     Operation failed; internal error.
  79         /// </exception>
  80         /// <since_tizen> 6 </since_tizen>
  81         public bool IsEnabled
  82         {
  83             get
  84             {
  85                 ValidationUtil.ValidateFeatureSupported(PlayerFeatures.AudioOffload);
  86                 _player.ValidateNotDisposed();
  87
  88                 NativePlayer.IsAudioOffloadEnabled(_player.Handle, out var value).
  89                     ThrowIfFailed(_player, "Failed to get whether the audio offload of the player is enabled or not");
  90                 return value;
  91             }
  92
  93             set
  94             {
  95                 ValidationUtil.ValidateFeatureSupported(PlayerFeatures.AudioOffload);
  96                 _player.ValidateNotDisposed();
  97                 _player.ValidatePlayerState(PlayerState.Idle);
  98
  99                 NativePlayer.SetAudioOffloadEnabled(_player.Handle, value).
 100                     ThrowIfFailed(_player, "Failed to set the audio offload of the player");
 101                 _enabled = value;
 102             }
 103         }
 104
 105         /// <summary>
 106         /// Get a state whether or not the audio offload is activated.
 107         /// </summary>
 108         /// <value>The value indicating whether or not AudioOffload is activated.</value>
 109         /// <remarks>
 110         /// Audio offload could be inactivated depending on the audio device capability even though the audio offload feature is supported.
 111         /// The <see cref="Player"/> that owns this instance must be in the <see cref="PlayerState.Ready"/>,
 112         /// <see cref="PlayerState.Playing"/>, or <see cref="PlayerState.Paused"/> state.
 113         /// </remarks>
 114         /// <feature>http://tizen.org/feature/multimedia.player.audio_offload</feature>
 115         /// <exception cref="NotSupportedException">The required feature is not supported.</exception>
 116         /// <exception cref="ObjectDisposedException">The player has already been disposed of.</exception>
 117         /// <exception cref="InvalidOperationException">
 118         ///     The player is not in the valid state.<br/>
 119         ///     -or-<br/>
 120         ///     Operation failed; internal error.
 121         /// </exception>
 122         /// <since_tizen> 6 </since_tizen>
 123         public bool IsActivated
 124         {
 125             get
 126             {
 127                 ValidationUtil.ValidateFeatureSupported(PlayerFeatures.AudioOffload);
 128                 _player.ValidateNotDisposed();
 129                 _player.ValidatePlayerState(PlayerState.Ready, PlayerState.Playing, PlayerState.Paused);
 130
 131                 NativePlayer.IsAudioOffloadActivated(_player.Handle, out var value).
 132                     ThrowIfFailed(_player, "Failed to get whether the audio offload of the player is enabled or not");
 133                 return value;
 134             }
 135         }
 136
 137         /// <summary>
 138         /// Retrieves the supported audio formats for audio offload.
 139         /// </summary>
 140         /// <returns>
 141         /// It returns a list containing supported audio formats for audio offload.
 142         /// </returns>
 143         /// <remarks>The supported media format can vary depending on the device capabilities.</remarks>
 144         /// <feature>http://tizen.org/feature/multimedia.player.audio_offload</feature>
 145         /// <exception cref="NotSupportedException">The required feature is not supported.</exception>
 146         /// <exception cref="ObjectDisposedException">The <see cref="Player"/> has already been disposed of.</exception>
 147         /// <exception cref="InvalidOperationException">
 148         ///     Operation failed; internal error.
 149         /// </exception>
 150         /// <seealso cref="MediaFormatAudioMimeType"/>
 151         /// <since_tizen> 6 </since_tizen>
 152         public IEnumerable<MediaFormatAudioMimeType> SupportedFormats
 153         {
 154             get
 155             {
 156                 if (_supportedFormat == null)
 157                 {
 158                     _supportedFormat = GetSupportedFormats();
 159                 }
 160
 161                 return _supportedFormat;
 162             }
 163         }
 164
 165         private IList<MediaFormatAudioMimeType> GetSupportedFormats()
 166         {
 167             List<MediaFormatAudioMimeType> audioFormats = new List<MediaFormatAudioMimeType>();
 168
 169             NativePlayer.SupportedMediaFormatCallback callback = (int format, IntPtr userData) =>
 170             {
 171                 if (!Enum.IsDefined(typeof(MediaFormatAudioMimeType), format))
 172                 {
 173                     Log.Warn(PlayerLog.Tag, "not supported : " + format.ToString());
 174                     return false;
 175                 }
 176
 177                 Log.Debug(PlayerLog.Tag, "supported : " + ((MediaFormatAudioMimeType)format).ToString());
 178                 audioFormats.Add((MediaFormatAudioMimeType)format);
 179                 return true;
 180             };
 181
 182             NativePlayer.SupportedAudioOffloadFormat(_player.Handle, callback, IntPtr.Zero).
 183                 ThrowIfFailed(_player, "Failed to get the supported formats for audio offload");
 184
 185             return audioFormats.AsReadOnly();
 186         }
 187     }
 188 }