Class AudioStreamPolicy

Definition

Namespace:

Tizen.Multimedia

Assembly:

Tizen.Multimedia.dll

Provides functionalities to control and manage sound streams within an application. The AudioStreamPolicy class enables developers to set policies for playback and recording audio streams, adjusting settings for focus and routing, as well as configuring audio devices and sound effects.

public class AudioStreamPolicy : IDisposable

Inheritance

object

AudioStreamPolicy

Implements

System.IDisposable

Constructors

AudioStreamPolicy(AudioStreamType)

Initializes a new instance of the AudioStreamPolicy class with AudioStreamType.

Declaration

public AudioStreamPolicy(AudioStreamType streamType)

Parameters

Type	Name	Description
AudioStreamType	streamType	The type of the sound stream for which the policy needs to be created.

Remarks

To apply the stream policy according to this stream information, the AudioStreamPolicy should be passed to other APIs related to playback or recording. (For example., Player, WavPlayer , etc.)

Exceptions

Type	Condition
System.ArgumentException	streamType is invalid.

Properties

FocusReacquisitionEnabled

Gets or sets the auto focus reacquisition.

Declaration

public bool FocusReacquisitionEnabled { get; set; }

Property Value

Type	Description
bool	true if the auto focus reacquisition is enabled; otherwise, false. The default is true.

Remarks

If you don't want to reacquire the focus you've lost automatically, disable the focus reacquisition.

Exceptions

Type	Condition
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

PlaybackFocusState

Gets the state of focus for the playback.

Declaration

public AudioStreamFocusState PlaybackFocusState { get; }

Property Value

Type	Description
AudioStreamFocusState	The state of focus for playback.

Exceptions

Type	Condition
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

PreferredInputDevice

Gets or sets the preferred input device.

Declaration

public AudioDevice PreferredInputDevice { get; set; }

Property Value

Type	Description
AudioDevice	The AudioDevice instance. The default is null which means any device is not set on this property.

Remarks

This property is to set a specific built-in device when the system has multiple devices of the same built-in device type. When there's only one device for a built-in device type in the system, nothing will happen even if this property is set successfully.

Exceptions

Type	Condition
System.ArgumentException	A device is not for input.
System.InvalidOperationException	An internal error occurs.
AudioPolicyException	A device is not supported by this AudioStreamPolicy instance.
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

See Also

GetConnectedDevices()

PreferredOutputDevice

Gets or sets the preferred output device.

Declaration

public AudioDevice PreferredOutputDevice { get; set; }

Property Value

Type	Description
AudioDevice	The AudioDevice instance. The default is null which means any device is not set on this property.

Remarks

This property is to set a specific built-in device when the system has multiple devices of the same built-in device type. When there's only one device for a built-in device type in the system, nothing will happen even if this property is set successfully.

Exceptions

Type	Condition
System.ArgumentException	A device is not for output.
System.InvalidOperationException	An internal error occurs.
AudioPolicyException	A device is not supported by this AudioStreamPolicy instance.
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

See Also

GetConnectedDevices()

RecordingFocusState

Gets the state of focus for the recording.

Declaration

public AudioStreamFocusState RecordingFocusState { get; }

Property Value

Type	Description
AudioStreamFocusState	The state of focus for recording.

Exceptions

Type	Condition
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

VolumeType

Gets the AudioVolumeType.

Declaration

public AudioVolumeType VolumeType { get; }

Property Value

Type	Description
AudioVolumeType	The AudioVolumeType of the policy instance.

Remarks

If the AudioStreamType of the current AudioStreamPolicy is Emergency, it returns None.

Exceptions

Type	Condition
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

Methods

AcquireFocus(AudioStreamFocusOptions, AudioStreamBehaviors, string)

Acquires the stream focus.

Declaration

public void AcquireFocus(AudioStreamFocusOptions options, AudioStreamBehaviors behaviors, string extraInfo)

Parameters

Type	Name	Description
AudioStreamFocusOptions	options	The focuses that you want to acquire.
AudioStreamBehaviors	behaviors	The requesting behaviors.
string	extraInfo	The extra information for this request. This value can be null.

Exceptions

Type	Condition
System.ArgumentException	options is zero.
System.ArgumentOutOfRangeException	options contain a invalid bit. -or- behaviors contain a invalid bit.
System.InvalidOperationException	The focus has already been acquired.
AudioPolicyException	Called in FocusStateChanged raised by releasing focus.
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

AddDeviceForStreamRouting(AudioDevice)

Adds a device for the stream routing.

Declaration

public void AddDeviceForStreamRouting(AudioDevice device)

Parameters

Type	Name	Description
AudioDevice	device	The device to add.

Remarks

The available AudioStreamType is Voip and MediaExternalOnly.

Exceptions

Type	Condition
System.InvalidOperationException	The device is not connected. -or- An internal error occurs.
System.ArgumentNullException	device is null.
AudioPolicyException	AudioStreamType of device is unavailable for this.
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

See Also

GetConnectedDevices()

ApplyStreamRouting()

ApplyStreamRouting()

Applies the stream routing.

Declaration

public void ApplyStreamRouting()

Remarks

If the stream has not been made yet, this will be applied when the stream starts to play.

Exceptions

Type	Condition
System.InvalidOperationException	A device has not been set. -or- An internal error occurs.
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

See Also

AddDeviceForStreamRouting(AudioDevice)

RemoveDeviceForStreamRouting(AudioDevice)

Dispose()

Releases all resources used by the AudioStreamPolicy.

Declaration

public void Dispose()

Dispose(bool)

Releases the unmanaged resources used by the AudioStreamPolicy.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	true to release both managed and unmanaged resources; false to release only unmanaged resources.

GetSoundEffect(bool)

Gets the sound effect.

Declaration

public SoundEffectInfo GetSoundEffect(bool withReference)

Parameters

Type	Name	Description
bool	withReference

Returns

Type	Description
SoundEffectInfo

Remarks

If withReference is false, ReferenceDevice of returned value will be null.

Exceptions

Type	Condition
System.InvalidOperationException	The sound effect is not set yet. or - There's no matched AudioDevice.
System.InvalidOperationException	Sound effect is not set yet.
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed.

HasStreamOnDevice(AudioDevice)

Checks if any stream from the current AudioStreamPolicy is using the device.

Declaration

public bool HasStreamOnDevice(AudioDevice device)

Parameters

Type	Name	Description
AudioDevice	device	The device to be checked.

Returns

Type	Description
bool	true if any audio stream from the current AudioStreamPolicy is using the device; otherwise, false.

Remarks

The AudioStreamPolicy can be applied to each playback or recording stream via other API set. (For example., Player, WavPlayer, AudioPlayback, AudioCapture, etc.) This method returns true only when the device is used for the stream which meets to the two conditions. One is that the current AudioStreamPolicy sets a audio route path to the device and the other is that the playback or recording stream from other API set should have already started to prepare or to play.(It depends on the API set.)

Exceptions

Type	Condition
System.ArgumentNullException	device is null.
System.InvalidOperationException	An internal error occurs.
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

See Also

GetConnectedDevices()

ReleaseFocus(AudioStreamFocusOptions, AudioStreamBehaviors, string)

Releases the acquired focus.

Declaration

public void ReleaseFocus(AudioStreamFocusOptions options, AudioStreamBehaviors behaviors, string extraInfo)

Parameters

Type	Name	Description
AudioStreamFocusOptions	options	The focus mask that you want to release.
AudioStreamBehaviors	behaviors	The requesting behaviors.
string	extraInfo	The extra information for this request. This value can be null.

Exceptions

Type	Condition
System.ArgumentException	options is zero.
System.ArgumentOutOfRangeException	options contain a invalid bit. -or- behaviors contain a invalid bit.
System.InvalidOperationException	The focus has not been acquired.
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

RemoveDeviceForStreamRouting(AudioDevice)

Removes the device for the stream routing.

Declaration

public void RemoveDeviceForStreamRouting(AudioDevice device)

Parameters

Type	Name	Description
AudioDevice	device	The device to remove.

Remarks

The available AudioStreamType is Voip and MediaExternalOnly.

Exceptions

Type	Condition
System.InvalidOperationException	An internal error occurs.
System.ArgumentNullException	device is null.
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed of.

See Also

GetConnectedDevices()

SetSoundEffect(SoundEffectInfo, bool)

Sets the sound effect.

Declaration

public void SetSoundEffect(SoundEffectInfo info, bool withReference)

Parameters

Type	Name	Description
SoundEffectInfo	info	See SoundEffectInfo.
bool	withReference	A reference device for sound effect.

Remarks

If withReference is true, info.Type.Type must be ReferenceCopy or AecSpeex or AecWebrtc. And info.ReferenceDevice.ReferenceDevice must not be null.
If withReference is false, info.Type.Type must be NoiseSuppression or AutoGainControl or NsWithAgc.

Exceptions

Type	Condition
System.ArgumentNullException	When withReference is true, A reference device is null.
AudioPolicyException	The current AudioStreamType is not supported for sound effect with reference.
System.ObjectDisposedException	The AudioStreamPolicy has already been disposed.

Events

FocusStateChanged

Occurs when the state of focus for the current AudioStreamPolicy changes. This event allows subscribers to react to changes in audio focus state, helping to manage audio playback or recording effectively.

Declaration

public event EventHandler<AudioStreamPolicyFocusStateChangedEventArgs> FocusStateChanged

Event Type

Type	Description
System.EventHandler<TEventArgs><AudioStreamPolicyFocusStateChangedEventArgs>

Remarks

The event is raised in the internal thread.

StreamFocusStateChanged

Occurs when the focus state for stream types is changed regardless of the process.

Declaration

public static event EventHandler<StreamFocusStateChangedEventArgs> StreamFocusStateChanged

Event Type

Type	Description
System.EventHandler<TEventArgs><StreamFocusStateChangedEventArgs>

Implements

System.IDisposable