HephAudio v3.0.6
A cross-platform C++ library for recording, playing, and processing audio on Windows, Android, Linux, iOS, and macOS.
Loading...
Searching...
No Matches
HephAudio::Native::NativeAudio Class Referenceabstract

base class for the classes that interact with the native audio APIs. More...

#include <NativeAudio.h>

Inheritance diagram for HephAudio::Native::NativeAudio:
HephAudio::Native::AndroidAudioBase HephAudio::Native::AppleAudio HephAudio::Native::WinAudioBase HephAudio::Native::AndroidAudioA HephAudio::Native::AndroidAudioSLES HephAudio::Native::WinAudio HephAudio::Native::WinAudioDS HephAudio::Native::WinAudioMME

Public Member Functions

 NativeAudio ()
 
 NativeAudio (const NativeAudio &)=delete
 
NativeAudiooperator= (const NativeAudio &)=delete
 
virtual ~NativeAudio ()=default
 
std::shared_ptr< IAudioDecoderGetAudioDecoder () const
 
void SetAudioDecoder (std::shared_ptr< IAudioDecoder > pNewDecoder)
 
std::shared_ptr< IAudioEncoderGetAudioEncoder () const
 
void SetAudioEncoder (std::shared_ptr< IAudioEncoder > pNewEncoder)
 
AudioObjectPlay (const std::filesystem::path &filePath)
 
AudioObjectPlay (const std::filesystem::path &filePath, uint32_t playCount)
 
AudioObjectPlay (const std::filesystem::path &filePath, uint32_t playCount, bool isPaused)
 
AudioObjectLoad (const std::filesystem::path &filePath)
 
AudioObjectLoad (const std::filesystem::path &filePath, uint32_t playCount)
 
AudioObjectLoad (const std::filesystem::path &filePath, uint32_t playCount, bool isPaused)
 
AudioObjectCreateAudioObject (const std::string &name, size_t bufferFrameCount, AudioChannelLayout channelLayout, uint16_t sampleRate)
 
bool DestroyAudioObject (AudioObject *pAudioObject)
 
bool DestroyAudioObject (const Heph::Guid &audioObjectId)
 
bool AudioObjectExists (AudioObject *pAudioObject) const
 
bool AudioObjectExists (const Heph::Guid &audioObjectId) const
 
AudioObjectGetAudioObject (size_t index)
 
AudioObjectGetAudioObject (const Heph::Guid &audioObjectId)
 
AudioObjectGetAudioObject (const std::string &audioObjectName)
 
size_t GetAudioObjectCount () const
 
void ResumeCapture ()
 
void PauseCapture ()
 
bool IsCapturePaused () const
 
uint32_t GetDeviceEnumerationPeriod () const
 
void SetDeviceEnumerationPeriod (uint32_t deviceEnumerationPeriod_ms)
 
virtual void SetMasterVolume (double volume)=0
 
virtual double GetMasterVolume () const =0
 
const AudioFormatInfoGetRenderFormat () const
 
const AudioFormatInfoGetCaptureFormat () const
 
void InitializeRender ()
 
void InitializeRender (AudioChannelLayout channelLayout, uint32_t sampleRate)
 
void InitializeRender (AudioFormatInfo format)
 
virtual void InitializeRender (AudioDevice *device, AudioFormatInfo format)=0
 
virtual void StopRendering ()=0
 
void InitializeCapture ()
 
void InitializeCapture (AudioChannelLayout channelLayout, uint32_t sampleRate)
 
void InitializeCapture (AudioFormatInfo format)
 
virtual void InitializeCapture (AudioDevice *device, AudioFormatInfo format)=0
 
virtual void StopCapturing ()=0
 
virtual void GetNativeParams (NativeAudioParams &nativeParams) const =0
 
virtual void SetNativeParams (const NativeAudioParams &nativeParams)=0
 
AudioDevice GetAudioDeviceById (const std::string &deviceId) const
 
AudioDevice GetRenderDevice () const
 
AudioDevice GetCaptureDevice () const
 
AudioDevice GetDefaultAudioDevice (AudioDeviceType deviceType) const
 
std::vector< AudioDeviceGetAudioDevices (AudioDeviceType deviceType) const
 

Public Attributes

Heph::Event OnAudioDeviceAdded
 
Heph::Event OnAudioDeviceRemoved
 
Heph::Event OnCapture
 

Protected Member Functions

virtual bool EnumerateAudioDevices ()=0
 
virtual void CheckAudioDevices ()
 
void JoinRenderThread ()
 
void JoinCaptureThread ()
 
void JoinDeviceThread ()
 
EncodedAudioBuffer Mix (uint32_t frameCount)
 
size_t GetAOCountToMix () const
 
virtual double GetFinalAOVolume (AudioObject *pAudioObject) const
 

Protected Attributes

std::shared_ptr< IAudioDecoderpAudioDecoder
 
std::shared_ptr< IAudioEncoderpAudioEncoder
 
std::vector< AudioObjectaudioObjects
 
std::vector< AudioDeviceaudioDevices
 
std::thread::id mainThreadId
 
std::thread renderThread
 
std::thread captureThread
 
std::thread deviceThread
 
std::string renderDeviceId
 
std::string captureDeviceId
 
AudioFormatInfo renderFormat
 
AudioFormatInfo captureFormat
 
bool disposing
 
bool isRenderInitialized
 
bool isCaptureInitialized
 
bool isCapturePaused
 
uint32_t deviceEnumerationPeriod_ms
 
std::mutex audioDevicesMutex
 
std::recursive_mutex audioObjectsMutex
 

Static Protected Attributes

static constexpr bool DEVICE_ENUMERATION_FAIL = false
 
static constexpr bool DEVICE_ENUMERATION_SUCCESS = true
 

Detailed Description

base class for the classes that interact with the native audio APIs.

Constructor & Destructor Documentation

◆ NativeAudio()

HephAudio::Native::NativeAudio::NativeAudio ( )

creates a new instance and initializes it with default values.

◆ ~NativeAudio()

virtual HephAudio::Native::NativeAudio::~NativeAudio ( )
virtualdefault

releases the resources and destroys the instance.

Member Function Documentation

◆ GetAudioDecoder()

std::shared_ptr< IAudioDecoder > HephAudio::Native::NativeAudio::GetAudioDecoder ( ) const

gets the shared pointer to the audio decoder instance.

◆ SetAudioDecoder()

void HephAudio::Native::NativeAudio::SetAudioDecoder ( std::shared_ptr< IAudioDecoder > pNewDecoder)

sets the decoder.

Parameters
pNewDecodershared pointer to the new decoder.

◆ GetAudioEncoder()

std::shared_ptr< IAudioEncoder > HephAudio::Native::NativeAudio::GetAudioEncoder ( ) const

gets the shared pointer to the audio encoder instance.

◆ SetAudioEncoder()

void HephAudio::Native::NativeAudio::SetAudioEncoder ( std::shared_ptr< IAudioEncoder > pNewEncoder)

sets the encoder.

Parameters
pNewEncodershared pointer to the new encoder.

◆ Play() [1/3]

AudioObject * HephAudio::Native::NativeAudio::Play ( const std::filesystem::path & filePath)

reads the file, then starts playing it.

Parameters
filePathpath of the file which will be played.
Returns
pointer to the audio object instance.

◆ Play() [2/3]

AudioObject * HephAudio::Native::NativeAudio::Play ( const std::filesystem::path & filePath,
uint32_t playCount )

reads the file, then starts playing it.

Parameters
filePathpath of the file which will be played.
playCountnumber of times the file will be played.
Returns
pointer to the audio object instance.

◆ Play() [3/3]

AudioObject * HephAudio::Native::NativeAudio::Play ( const std::filesystem::path & filePath,
uint32_t playCount,
bool isPaused )

reads the file, then starts playing it.

Parameters
filePathpath of the file which will be played.
playCountnumber of times the file will be played.
isPausedindicates whether to start playing the audio data after reading it to memory.
Returns
pointer to the audio object instance.

◆ Load() [1/3]

AudioObject * HephAudio::Native::NativeAudio::Load ( const std::filesystem::path & filePath)

reads the file and converts the audio data to the render format but does not start playing it.

Parameters
filePathpath of the file which will be loaded.
Returns
pointer to the audio object instance.

◆ Load() [2/3]

AudioObject * HephAudio::Native::NativeAudio::Load ( const std::filesystem::path & filePath,
uint32_t playCount )

reads the file and converts the audio data to the render format but does not start playing it.

Parameters
filePathpath of the file which will be loaded.
playCountnumber of times the file will be played.
Returns
pointer to the audio object instance.

◆ Load() [3/3]

AudioObject * HephAudio::Native::NativeAudio::Load ( const std::filesystem::path & filePath,
uint32_t playCount,
bool isPaused )

reads the file and converts the audio data to the render format but does not start playing it.

Parameters
filePathpath of the file which will be loaded.
playCountnumber of times the file will be played.
isPausedindicates whether to start playing the audio data after loading it.
Returns
pointer to the audio object instance.

◆ CreateAudioObject()

AudioObject * HephAudio::Native::NativeAudio::CreateAudioObject ( const std::string & name,
size_t bufferFrameCount,
AudioChannelLayout channelLayout,
uint16_t sampleRate )

creates an audio object with the provided buffer info.

Parameters
namename for the audio object.
bufferFrameCountnumber of frames the buffer will have.
channelLayoutchannel layout of the buffer.
sampleRatesample rate of the buffer.
Returns
pointer to the audio object instance.

◆ DestroyAudioObject() [1/2]

bool HephAudio::Native::NativeAudio::DestroyAudioObject ( AudioObject * pAudioObject)

destroys the audio object.

Parameters
pAudioObjectpointer to the object which will be destroyed.
Returns
true if the object is found and destroyed, otherwise false.

◆ DestroyAudioObject() [2/2]

bool HephAudio::Native::NativeAudio::DestroyAudioObject ( const Heph::Guid & audioObjectId)

destroys the audio object.

Parameters
audioObjectIdunique identifier of the object which will be destroyed.
Returns
true if the object is found and destroyed, otherwise false.

◆ AudioObjectExists() [1/2]

bool HephAudio::Native::NativeAudio::AudioObjectExists ( AudioObject * pAudioObject) const

checks whether an audio object exists.

Parameters
pAudioObjectpointer to the object which will checked.
Returns
true if the object is found, otherwise false.

◆ AudioObjectExists() [2/2]

bool HephAudio::Native::NativeAudio::AudioObjectExists ( const Heph::Guid & audioObjectId) const

checks whether an audio object exists.

Parameters
audioObjectIdunique identifier of the object which will be checked.
Returns
true if the object is found, otherwise false.

◆ GetAudioObject() [1/3]

AudioObject * HephAudio::Native::NativeAudio::GetAudioObject ( size_t index)

gets the audio object.

Parameters
indexindex of the audio object.
Returns
pointer to the audio object if found, otherwise nullptr.

◆ GetAudioObject() [2/3]

AudioObject * HephAudio::Native::NativeAudio::GetAudioObject ( const Heph::Guid & audioObjectId)

gets the audio object.

Parameters
audioObjectIdunique identifier of the audio object.
Returns
pointer to the audio object if found, otherwise nullptr.

◆ GetAudioObject() [3/3]

AudioObject * HephAudio::Native::NativeAudio::GetAudioObject ( const std::string & audioObjectName)

gets the first audio object with the provided name.

Parameters
audioObjectNamename of the audio object.
Returns
pointer to the audio object if found, otherwise nullptr.

◆ GetAudioObjectCount()

size_t HephAudio::Native::NativeAudio::GetAudioObjectCount ( ) const

gets the number of audio objects currently present.

◆ ResumeCapture()

void HephAudio::Native::NativeAudio::ResumeCapture ( )

resumes capturing.

◆ PauseCapture()

void HephAudio::Native::NativeAudio::PauseCapture ( )

pauses capturing.

◆ IsCapturePaused()

bool HephAudio::Native::NativeAudio::IsCapturePaused ( ) const

checks whether the capturing is paused.

Returns
true if paused capturing, otherwise false.

◆ GetDeviceEnumerationPeriod()

uint32_t HephAudio::Native::NativeAudio::GetDeviceEnumerationPeriod ( ) const

◆ SetDeviceEnumerationPeriod()

void HephAudio::Native::NativeAudio::SetDeviceEnumerationPeriod ( uint32_t deviceEnumerationPeriod_ms)

◆ SetMasterVolume()

virtual void HephAudio::Native::NativeAudio::SetMasterVolume ( double volume)
pure virtual

sets the master volume.

Parameters
volumenew master volume.
Important
values above 1 may cause distortion.

Implemented in HephAudio::Native::AndroidAudioA, HephAudio::Native::AndroidAudioSLES, HephAudio::Native::AppleAudio, HephAudio::Native::WinAudio, HephAudio::Native::WinAudioDS, and HephAudio::Native::WinAudioMME.

◆ GetMasterVolume()

virtual double HephAudio::Native::NativeAudio::GetMasterVolume ( ) const
pure virtual

◆ GetRenderFormat()

const AudioFormatInfo & HephAudio::Native::NativeAudio::GetRenderFormat ( ) const

gets the audio format used for rendering.

◆ GetCaptureFormat()

const AudioFormatInfo & HephAudio::Native::NativeAudio::GetCaptureFormat ( ) const

gets the audio format used for capturing.

◆ InitializeRender() [1/4]

void HephAudio::Native::NativeAudio::InitializeRender ( )

initializes rendering with the default device and default format.

◆ InitializeRender() [2/4]

void HephAudio::Native::NativeAudio::InitializeRender ( AudioChannelLayout channelLayout,
uint32_t sampleRate )

initializes rendering with the default device and the provided format.

Parameters
channelLayoutchannel layout of the render format.
sampleRatesample rate of the render format.

◆ InitializeRender() [3/4]

void HephAudio::Native::NativeAudio::InitializeRender ( AudioFormatInfo format)

initializes rendering with the default device and the provided format.

Parameters
formatrender format.

◆ InitializeRender() [4/4]

virtual void HephAudio::Native::NativeAudio::InitializeRender ( AudioDevice * device,
AudioFormatInfo format )
pure virtual

initializes rendering with the provided device and the provided format.

Parameters
devicepointer to the audio render device.
formatrender format.

Implemented in HephAudio::Native::AndroidAudioA, HephAudio::Native::AndroidAudioSLES, HephAudio::Native::AppleAudio, HephAudio::Native::WinAudio, HephAudio::Native::WinAudioDS, and HephAudio::Native::WinAudioMME.

◆ StopRendering()

virtual void HephAudio::Native::NativeAudio::StopRendering ( )
pure virtual

◆ InitializeCapture() [1/4]

void HephAudio::Native::NativeAudio::InitializeCapture ( )

initializes capturing with the default device and default format.

◆ InitializeCapture() [2/4]

void HephAudio::Native::NativeAudio::InitializeCapture ( AudioChannelLayout channelLayout,
uint32_t sampleRate )

initializes capturing with the default device and the provided format.

Parameters
channelLayoutchannel layout of the capture format.
sampleRatesample rate of the capture format.

◆ InitializeCapture() [3/4]

void HephAudio::Native::NativeAudio::InitializeCapture ( AudioFormatInfo format)

initializes capturing with the default device and the provided format.

Parameters
formatcapture format.

◆ InitializeCapture() [4/4]

virtual void HephAudio::Native::NativeAudio::InitializeCapture ( AudioDevice * device,
AudioFormatInfo format )
pure virtual

initializes capturing with the provided device and the provided format.

Parameters
devicepointer to the audio capture device.
formatcapture format.

Implemented in HephAudio::Native::AndroidAudioA, HephAudio::Native::AndroidAudioSLES, HephAudio::Native::AppleAudio, HephAudio::Native::WinAudio, HephAudio::Native::WinAudioDS, and HephAudio::Native::WinAudioMME.

◆ StopCapturing()

virtual void HephAudio::Native::NativeAudio::StopCapturing ( )
pure virtual

◆ GetNativeParams()

virtual void HephAudio::Native::NativeAudio::GetNativeParams ( NativeAudioParams & nativeParams) const
pure virtual

◆ SetNativeParams()

virtual void HephAudio::Native::NativeAudio::SetNativeParams ( const NativeAudioParams & nativeParams)
pure virtual

◆ GetAudioDeviceById()

AudioDevice HephAudio::Native::NativeAudio::GetAudioDeviceById ( const std::string & deviceId) const

gets audio device by id.

◆ GetRenderDevice()

AudioDevice HephAudio::Native::NativeAudio::GetRenderDevice ( ) const

gets the audio device that's currently being used for rendering.

◆ GetCaptureDevice()

AudioDevice HephAudio::Native::NativeAudio::GetCaptureDevice ( ) const

gets the audio device that's currently being used for capturing.

◆ GetDefaultAudioDevice()

AudioDevice HephAudio::Native::NativeAudio::GetDefaultAudioDevice ( AudioDeviceType deviceType) const

gets the system default render/capture device.

Parameters
deviceTypetype of the device. Must be either AudioDeviceType::Render or AudioDeviceType::Capture .
Returns
AudioDevice

◆ GetAudioDevices()

std::vector< AudioDevice > HephAudio::Native::NativeAudio::GetAudioDevices ( AudioDeviceType deviceType) const

gets the available audio devices of the requested type.

Parameters
deviceTypetype of the audio devices.

◆ EnumerateAudioDevices()

virtual bool HephAudio::Native::NativeAudio::EnumerateAudioDevices ( )
protectedpure virtual

enumerates the audio devices.

Returns
DEVICE_ENUMERATION_SUCCESS if succeded, otherwise DEVICE_ENUMERATION_FAIL.

Implemented in HephAudio::Native::AndroidAudioBase.

◆ CheckAudioDevices()

virtual void HephAudio::Native::NativeAudio::CheckAudioDevices ( )
protectedvirtual

enumerates audio devices periodically.

◆ JoinRenderThread()

void HephAudio::Native::NativeAudio::JoinRenderThread ( )
protected

waits for render thread to join.

◆ JoinCaptureThread()

void HephAudio::Native::NativeAudio::JoinCaptureThread ( )
protected

waits for capture thread to join.

◆ JoinDeviceThread()

void HephAudio::Native::NativeAudio::JoinDeviceThread ( )
protected

waits for device thread to join.

◆ Mix()

EncodedAudioBuffer HephAudio::Native::NativeAudio::Mix ( uint32_t frameCount)
protected

mixes the audio objects that are currently playing into one buffer.

Parameters
frameCountnumber of frames the output buffer will have.

◆ GetAOCountToMix()

size_t HephAudio::Native::NativeAudio::GetAOCountToMix ( ) const
protected

gets the number of audio objects that will are currently playing.

◆ GetFinalAOVolume()

virtual double HephAudio::Native::NativeAudio::GetFinalAOVolume ( AudioObject * pAudioObject) const
protectedvirtual

calculates the volume of the audio object.

Member Data Documentation

◆ DEVICE_ENUMERATION_FAIL

bool HephAudio::Native::NativeAudio::DEVICE_ENUMERATION_FAIL = false
staticconstexprprotected

indicates the device enumeration has failed.

◆ DEVICE_ENUMERATION_SUCCESS

bool HephAudio::Native::NativeAudio::DEVICE_ENUMERATION_SUCCESS = true
staticconstexprprotected

indicates the device enumeration has succeeded.

◆ pAudioDecoder

std::shared_ptr<IAudioDecoder> HephAudio::Native::NativeAudio::pAudioDecoder
protected

shared pointer to the decoder instance that's used internally.

◆ pAudioEncoder

std::shared_ptr<IAudioEncoder> HephAudio::Native::NativeAudio::pAudioEncoder
protected

shared pointer to the encoder instance that's used internally.

◆ audioObjects

std::vector<AudioObject> HephAudio::Native::NativeAudio::audioObjects
protected

a list of audio objects.

◆ audioDevices

std::vector<AudioDevice> HephAudio::Native::NativeAudio::audioDevices
protected

a list of audio devices present in the system.

◆ mainThreadId

std::thread::id HephAudio::Native::NativeAudio::mainThreadId
protected

unique identifier of the thread that created the current isntance.

◆ renderThread

std::thread HephAudio::Native::NativeAudio::renderThread
protected

the thread that's used for rendering audio data.

◆ captureThread

std::thread HephAudio::Native::NativeAudio::captureThread
protected

the thread that's used for capturing audio data.

◆ deviceThread

std::thread HephAudio::Native::NativeAudio::deviceThread
protected

the thread that's used for enumerating audio devices periodically.

◆ renderDeviceId

std::string HephAudio::Native::NativeAudio::renderDeviceId
protected

unique identifier of the audio device that's currently being used for rendering.

◆ captureDeviceId

std::string HephAudio::Native::NativeAudio::captureDeviceId
protected

unique identifier of the audio device that's currently being used for capturing.

◆ renderFormat

AudioFormatInfo HephAudio::Native::NativeAudio::renderFormat
protected

render format.

◆ captureFormat

AudioFormatInfo HephAudio::Native::NativeAudio::captureFormat
protected

capture format.

◆ disposing

bool HephAudio::Native::NativeAudio::disposing
protected

indicates whether the current instance is being destroyed.

◆ isRenderInitialized

bool HephAudio::Native::NativeAudio::isRenderInitialized
protected

indicates whether the current instance is ready for rendering.

◆ isCaptureInitialized

bool HephAudio::Native::NativeAudio::isCaptureInitialized
protected

indicates whether the current instance is ready for capturing.

◆ isCapturePaused

bool HephAudio::Native::NativeAudio::isCapturePaused
protected

indicates whether the capture is paused.

◆ deviceEnumerationPeriod_ms

uint32_t HephAudio::Native::NativeAudio::deviceEnumerationPeriod_ms
protected

time, in milliseconds, between each device enumeration.

◆ audioDevicesMutex

std::mutex HephAudio::Native::NativeAudio::audioDevicesMutex
mutableprotected

to prevent race condition when accessing/enumerating audio devices.

◆ audioObjectsMutex

std::recursive_mutex HephAudio::Native::NativeAudio::audioObjectsMutex
mutableprotected

to prevent race condition when creating/accessing audio objects.

◆ OnAudioDeviceAdded

Heph::Event HephAudio::Native::NativeAudio::OnAudioDeviceAdded

raised when an audio device is connected to the device or activated.

◆ OnAudioDeviceRemoved

Heph::Event HephAudio::Native::NativeAudio::OnAudioDeviceRemoved

raised when an audio device is disconnected from the device or deactivated.

◆ OnCapture

Heph::Event HephAudio::Native::NativeAudio::OnCapture

raised when sufficient amount (typically 10 ms) audio data is captured.