Class CoreAudioPlayer
Provides an audio player based on the Apple's audio HAL framework library,
namely the Core Audio Framework.
The user provides the audio device to perform playback upon,
the audio provider to do playback for, and the rest are managed by this class.
This class does also manage cases where the streams may be invalidated,
or when the selected stream's virtual format has been changed.
There are also several properties that can be configured by the provided AudioDevice
object during construction (applying to all the attached players of the device).
See the AudioDevice properties and methods to see what can be configured.
public sealed class CoreAudioPlayer : IWavePlayer, IDisposable, IWaveLatency, IWavePosition, IAsyncDisposable- Inheritance
-
CoreAudioPlayer
- Implements
- Inherited Members
- Extension Methods
Constructors
CoreAudioPlayer()
Initializes a new Core Audio player instance that renders
audio to the system's default output device.
If a synchronization context is assigned for the thread where this instance
is created to, it is used when a playback stopped event is dispatching.
public CoreAudioPlayer()CoreAudioPlayer(AudioDevice)
Initializes a new Core Audio player instance that renders audio
to the specified Core Audio AudioDevice instance.
If a synchronization context is assigned for the thread where this instance
is created to, it is used when a playback stopped event is dispatching.
public CoreAudioPlayer(AudioDevice device)Parameters
deviceAudioDeviceThe audio device where the audio will be rendered to
Exceptions
- ArgumentNullException
deviceis null.
Properties
AverageLatency
The steady-state latency from a sample being queued for output to it being emitted by the audio hardware, assuming uninterrupted playback. This is a property of the buffer configuration and the driver, not of the current playback state.
public TimeSpan AverageLatency { get; }Property Value
CurrentLatency
The time that has elapsed since the sample currently emerging from the hardware was queued for output. In steady state this is approximately equal to AverageLatency; it differs during start-up, after an underrun, or when the host is filling buffers irregularly. Implementations that cannot meaningfully distinguish from the average are permitted to return AverageLatency.
public TimeSpan CurrentLatency { get; }Property Value
Device
Gets the selected audio device where the player renders data to.
[NotNull]
public AudioDevice Device { get; }Property Value
OutputWaveFormat
Gets the WaveFormat that is the virtual HAL format that the current instance uses to provide audio data to the HAL.
public WaveFormat OutputWaveFormat { get; }Property Value
PlaybackState
Current playback state
public PlaybackState PlaybackState { get; }Property Value
Remarks
Note that this property can only return Stopped or Playing states; See remarks section in Pause() to get an explanation why this happens.
Volume
Modifies the volume of the selected playback device
To individually modify channels, obtain the control list of the
device and modify the value for each of it's volume controls.
public float Volume { get; set; }Property Value
Remarks
Note that modifying the volume of the audio device can be in
general disruptive as the user sets this to a desired value.
If you want to modify the gain of the audio provider that
you use to provide data to the player without modifying this,
inject a VolumeSampleProvider.
When retrieveing the value of this property, the value is deduced by iterating through the device's volume controls and getting the volume value. It has been observed that in some cases the HAL fails to properly update the properties of the device and may return 1 while that is not true. However, assigning this property does the intended result (of changing the device's volume) without any error(s).
Exceptions
- ArgumentOutOfRangeException
When setting the property: The selected volume is less than 0, or more than 1.
Methods
Dispose()
Disposes this CoreAudioPlayer instance.
Thread-safe.
public void Dispose()Remarks
Note that this method will probably throw when the device used to initialize the player is gone; so, expect to catch AggregateException for this particular case.
Exceptions
- AggregateException
One or more native objects were failed to be disposed of.
DisposeAsync()
Disposes this CoreAudioPlayer instance asynchronously.
Disposal is thread-safe, because the returned task puts Dispose() in the thread pool.
public ValueTask DisposeAsync()Returns
GetPosition()
Position (in terms of bytes played - does not necessarily translate directly to the position within the source audio file)
public long GetPosition()Returns
- long
Position in bytes
Init(IWaveProvider)
Initializes this CoreAudioPlayer from the specified audio provider.
public void Init(IWaveProvider waveProvider)Parameters
waveProviderIWaveProviderThe audio provider to initialize from.
Exceptions
- InvalidOperationException
The instance has been successfully initialized before.
Pause()
Pause Playback
public void Pause()Remarks
Note - there is not a 'pause' state in HAL; this is true due to it's I/O procedure model, where the HAL calls each procedure as required. As such, no special pause functionality exists, so this method hardwires to the Stop() method. Also, there is not a Paused state, instead only playing or stopped can be returned from the PlaybackState property.
Play()
Begin playback
public void Play()Stop()
Stop playback
public void Stop()Events
PlaybackStopped
Indicates that playback has gone into a stopped state due to reaching the end of the input stream or an error has been encountered during playback
public event EventHandler<StoppedEventArgs> PlaybackStopped