Instance handling class. More...

#include <sound4cl.hpp>

Classes
class	CClient

Public Member Functions
	CInstance (CProcessor &dynlib)

	CInstance (CProcessor &dynlib, void *_instance)

	CInstance (const CInstance &)=delete

CInstance &	operator= (const CInstance &)=delete

virtual	~CInstance ()

bool	IsOk () const

void	SetParam (const std::string &name, const std::string &value)

std::string	GetParam (const std::string &name)

void	SetBus (const CBus &bus)

void	SetPresetManager (CPresetLoader *preset_manager)

bool	Create (const std::string &LoginKey, const std::string &RadioName, const std::string &Access_Key_ID, const std::string &Access_Key_Secret, const std::filesystem::path &save_path, int json_port=0, unsigned int frames_per_chunk=0)

unsigned int	GetChunkFrames ()

void	PresetManager_InformChange (const std::filesystem::path &relative_path, PresetChange_Kind change_kind)

void	SetMetadata (const std::string &key, const char *value)

void	SetMetadataMulti (const std::unordered_map< std::string, const char * > &list)

std::vector< std::tuple< std::string, std::string > >	GetMetadataInfos ()

virtual void	OnUpdateThreadStart ()

virtual void	OnUpdateThreadStop ()

bool	StartWebServer (int http_port, int https_port=0)

void	StopWebServer (int timeout_ms=1000)

void	SetWebServerAppHealth (int httpcode, const std::string &contenttype, const std::string &content)

void	GetWebServerAppHealth (int &httpcode, std::string &contenttype, std::string &content)

int	Terminate ()

void	Stop ()

unsigned int	GetEstimatedDelay ()

float *	GetBufferIn ()

float *	GetBufferOut ()

void	ProcessAudio ()

void	ProcessAudio_Planar (float const const input, float const output)

template<typename T >
std::vector< T >	ProcessAnyAudio (const std::vector< T > input)

std::shared_ptr< CClient >	NewClient ()

bool	SaveState ()

Protected Member Functions
template<typename T >
unsigned int	AddAudio (const T *payload, unsigned int nFrame)

template<typename T >
unsigned int	GetAudio (T *payload, unsigned int max_nFrame)

Detailed Description

Holds an instance of processing

Definition at line 873 of file sound4cl.hpp.

Constructor & Destructor Documentation

◆ CInstance() [1/3]

sound4::CInstance::CInstance ( CProcessor & dynlib )

inline

Creates the instance, with default parameters

Parameters

dynlib the processor dynamic library

Definition at line 880 of file sound4cl.hpp.

◆ CInstance() [2/3]

sound4::CInstance::CInstance	(	CProcessor &	dynlib,
		void *	_instance
	)

inline

Wrap an already created C instance.

Note: Stop will not stop the instance.

Parameters

dynlib	the processor dynamic library
_instance	the C instance pointer (No check on the pointer is made.)

Definition at line 895 of file sound4cl.hpp.

◆ CInstance() [3/3]

sound4::CInstance::CInstance ( const CInstance & )

delete

◆ ~CInstance()

virtual sound4::CInstance::~CInstance ( )

inlinevirtual

Destructor, stopping any running tasks

Definition at line 907 of file sound4cl.hpp.

Member Function Documentation

◆ AddAudio()

template<typename T >

unsigned int sound4::CInstance::AddAudio	(	const T *	payload,
		unsigned int	nFrame
	)

inlineprotected

Definition at line 1469 of file sound4cl.hpp.

◆ Create()

bool sound4::CInstance::Create	(	const std::string &	LoginKey,
		const std::string &	RadioName,
		const std::string &	Access_Key_ID,
		const std::string &	Access_Key_Secret,
		const std::filesystem::path &	save_path,
		int	json_port = `0`,
		unsigned int	frames_per_chunk = `0`
	)

inline

Creates and initialize the instance, and starts its update thread

Attention: The save_path must be an existing folder with R/W access, or be NULL (then it uses volatile memory storage) If the save_path is empty or the folder is empty, a default configuration with a default preset will be loaded, unless using SetPresetManager.

If used in a container, we recommend to put a volume for this path, so it will survive updates.

License access: The licenses are retrieved via Internet and access some servers. You may use an alternate server by changing LICENSE_SERVER in the parameters.

Parameters

LoginKey	SOUND4 Login key
RadioName	SOUND4 RadioName
Access_Key_ID	SOUND4 AWS access ID
Access_Key_Secret	SOUND4 AWS access Secret
save_path	Path where we can load/save the configuration
json_port	Optional json listening port
frames_per_chunk	The number of audio frames in each chunk of processing. Must be in the list returned by CProcessor::GetChunkSizeInFrames, or 0 to set default

Returns: false if failed

Definition at line 1011 of file sound4cl.hpp.

◆ GetAudio()

template<typename T >

unsigned int sound4::CInstance::GetAudio	(	T *	payload,
		unsigned int	max_nFrame
	)

inlineprotected

Definition at line 1475 of file sound4cl.hpp.

◆ GetBufferIn()

float * sound4::CInstance::GetBufferIn ( )

inline

Get preallocated aligned buffer for audio input for ProcessAudio

The buffer is a big enough for all supported chunk sizes.

Each sample is a native 32-bit floating-point number where 1.0 is full scale. Channels are interlaced, so the buffers are [L0,R0,L1,R1,...,Ln,Rn] (L=Left, R=Right)

In case of multiple audio input/output, buffer is [aL0,aR0,bL0,bR0,...,aLn,aRn,bLn,bRn]

Returns: An audio input dedicated buffer.

Definition at line 1310 of file sound4cl.hpp.

◆ GetBufferOut()

float * sound4::CInstance::GetBufferOut ( )

inline

Get preallocated aligned buffer for audio output for ProcessAudio

The buffer is a big enough for all supported chunk sizes.

Each sample is a native 32-bit floating-point number where 1.0 is full scale. Channels are interlaced, so the buffers are [L0,R0,L1,R1,...,Ln,Rn] (L=Left, R=Right)

In case of multiple audio input/output, buffer is [aL0,aR0,bL0,bR0,...,aLn,aRn,bLn,bRn]

Returns: An audio output dedicated buffer.

Definition at line 1327 of file sound4cl.hpp.

◆ GetChunkFrames()

unsigned int sound4::CInstance::GetChunkFrames ( )

inline

Get the number of audio frames in each chunk of processing.

The value reflects the frames_per_chunk parameter passed to Create

Returns: the number of audio frames in each chunk of processing

Definition at line 1057 of file sound4cl.hpp.

◆ GetEstimatedDelay()

unsigned int sound4::CInstance::GetEstimatedDelay ( )

inline

Get the delay (estimated) of current processing algorithm

Remarks: This is not very accurate, it does not take into account group delays.; But it is sufficient for file processing adjustements.; Changing the preset and parameters may change the returned value.

Returns: Estimated delay in frames

Definition at line 1292 of file sound4cl.hpp.

◆ GetMetadataInfos()

std::vector< std::tuple< std::string, std::string > > sound4::CInstance::GetMetadataInfos ( )

inline

Get information on known metadata keys.

Returns: a list of {key,description} of known metadata used in process and extensions.

Definition at line 1145 of file sound4cl.hpp.

◆ GetParam()

std::string sound4::CInstance::GetParam ( const std::string & name )

inline

Gets a parameter value

Parameters

name	the parameter name

Returns: the parameter value

Definition at line 936 of file sound4cl.hpp.

◆ GetWebServerAppHealth()

void sound4::CInstance::GetWebServerAppHealth	(	int &	httpcode,
		std::string &	contenttype,
		std::string &	content
	)

inline

Get the web server /apphealth status info

Definition at line 1238 of file sound4cl.hpp.

◆ IsOk()

bool sound4::CInstance::IsOk ( ) const

inline

Returns true if an instance has been created and not stopped.

Definition at line 915 of file sound4cl.hpp.

◆ NewClient()

std::shared_ptr< CClient > sound4::CInstance::NewClient ( )

inline

Creates a low-level JSON client

◆ OnUpdateThreadStart()

virtual void sound4::CInstance::OnUpdateThreadStart ( )

inlinevirtual

Can be overloaded, called at start of UpdateThread in the thread

Definition at line 1169 of file sound4cl.hpp.

◆ OnUpdateThreadStop()

virtual void sound4::CInstance::OnUpdateThreadStop ( )

inlinevirtual

Can be overloaded to call at end of UpdateThread in the thread

Definition at line 1173 of file sound4cl.hpp.

◆ operator=()

CInstance & sound4::CInstance::operator= ( const CInstance & )

delete

◆ PresetManager_InformChange()

void sound4::CInstance::PresetManager_InformChange	(	const std::filesystem::path &	relative_path,
		PresetChange_Kind	change_kind
	)

inline

Inform that a change happened in the storage. This must be used only in conjonction with SetPresetManager

Parameters

relative_path	The path which changed, relative to the root storage
change_kind	What happened to this path

Definition at line 1071 of file sound4cl.hpp.

◆ ProcessAnyAudio()

template<typename T >

std::vector< T > sound4::CInstance::ProcessAnyAudio ( const std::vector< T > input )

inline

Process audio (different formats, less optimized)

Supports for int16_t, int32_t and float (32) in native endianness

Attention: the return count is independent from the input count

Template Parameters

T	the C type for one audio sample

Parameters

input audio to process

Returns: processed audio

Definition at line 1369 of file sound4cl.hpp.

◆ ProcessAudio()

void sound4::CInstance::ProcessAudio ( )

inline

Process one audio chunk, from GetBufferIn() to GetBufferOut()

Definition at line 1335 of file sound4cl.hpp.

◆ ProcessAudio_Planar()

void sound4::CInstance::ProcessAudio_Planar	(	float const const	input,
		float const	output
	)

inline

Process one audio chunk, but with planar audio

Each sample is a native 32-bit floating-point number where 1.0 is full scale. Channels are NOT interlaced, so the buffers are arrays of planar audio : [ [L0,L1,...,Ln] , [R0,R1,...,Rn] ] (L=Left, R=Right)

In case of multiple audio input/output, buffer are [ [aL...], [aR...], [bL...], [bR...], ... ]

Parameters

input	has GetAudioInputCount() * GetChannelCount() channels
output	has GetAudioOutputCount() * GetChannelCount() channels

Definition at line 1351 of file sound4cl.hpp.

◆ SaveState()

bool sound4::CInstance::SaveState ( )

inline

Save the current state

Needed when CClient::ProcessJson returned with need_save to true. However it can be postponed as much as wanted.

Remarks: Works only when update thread is running

Returns: true if success

Definition at line 1459 of file sound4cl.hpp.

◆ SetBus()

void sound4::CInstance::SetBus ( const CBus & bus )

inline

Set the instance's bus. It can be used by instances to exchange real-time information if needed.

Attention: The bus should be created with the same library

Parameters

bus	the bus to use

Definition at line 953 of file sound4cl.hpp.

◆ SetMetadata()

void sound4::CInstance::SetMetadata	(	const std::string &	key,
		const char *	value
	)

inline

Adds the specific metadata to the process.

It can come from any thread, and will be used as soon as possible. Setting a null value erase the metadata, which is different from setting an empty string.

Parameters

key	the metadata key If key contains a dot (like wm.KEY), it will be sent only to the matching plugin (ie wm here) without the prefix (ie KEY here) Use empty prefix for routing to main only.
value	the metadata value or nullptr to erase it.

Definition at line 1089 of file sound4cl.hpp.

◆ SetMetadataMulti()

void sound4::CInstance::SetMetadataMulti ( const std::unordered_map< std::string, const char * > & list )

inline

Adds multiple metadata to the process.

This works like SetMetadata but with multiple metadata at once.

See also: CInstance::SetMetadata

Parameters

list	a map of key/value pair.

Definition at line 1109 of file sound4cl.hpp.

◆ SetParam()

void sound4::CInstance::SetParam	(	const std::string &	name,
		const std::string &	value
	)

inline

Set a parameter value

Must be done before Create See also Environment variables and parameters

Parameters

name	the parameter name
value	the parameter value

Definition at line 925 of file sound4cl.hpp.

◆ SetPresetManager()

void sound4::CInstance::SetPresetManager ( CPresetLoader * preset_manager )

inline

Sets a custom preset manager Optional, this overrides the save_path in Create

To dynamically update when storage change, see PresetManager_InformChange

Must be done before Create

Parameters

preset_manager The custom preset manager

Definition at line 970 of file sound4cl.hpp.

◆ SetWebServerAppHealth()

void sound4::CInstance::SetWebServerAppHealth	(	int	httpcode,
		const std::string &	contenttype,
		const std::string &	content
	)

inline

Set the web server /apphealth status info

Definition at line 1229 of file sound4cl.hpp.

◆ StartWebServer()

bool sound4::CInstance::StartWebServer	(	int	http_port,
		int	https_port = `0`
	)

inline

Starts a Web server on requested ports

For secure connection, it will use privatekey.pem and certificate.pem from current directory. Environment variables SSL_PRIVATE_PATH and SSL_CERTIFICATE_PATH can override those (see Environment variables and parameters). If none is valid, it will try also /etc/ssl/certs/server.key and /etc/ssl/certs/server.crt.

Warning: On Windows, calling this from Go<1.20 code will crash.

Parameters

http_port	The port to listen for HTTP connections (0 to disable)
https_port	The port to listen for HTTPS connections (0 to disable)

Returns: true if ports were opened successfully.

Definition at line 1189 of file sound4cl.hpp.

◆ Stop()

void sound4::CInstance::Stop ( )

inline

Stops the instance, its web server and its update thread.

Note: Stop will not stop a wrapped C instance

Definition at line 1269 of file sound4cl.hpp.

◆ StopWebServer()

void sound4::CInstance::StopWebServer ( int timeout_ms = 1000 )

inline

Stop a web server started with StartWebServer

Warning: On Windows, calling this from Go<1.20 code will crash.

Parameters

timeout_ms The timeout to wait gracefull shutdown

Definition at line 1217 of file sound4cl.hpp.

◆ Terminate()

int sound4::CInstance::Terminate ( )

inline

Terminate the processing.

This is useful only with file processing, to get the final status. For some plugins, this is mandatory

Returns: 0 is success, <0 if error, >0 if some status

Definition at line 1258 of file sound4cl.hpp.

The documentation for this class was generated from the following file:

sound4cl.hpp

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CInstance() [1/3]

◆ CInstance() [2/3]

◆ CInstance() [3/3]

◆ ~CInstance()

Member Function Documentation

◆ AddAudio()

◆ Create()

◆ GetAudio()

◆ GetBufferIn()

◆ GetBufferOut()

◆ GetChunkFrames()

◆ GetEstimatedDelay()

◆ GetMetadataInfos()

◆ GetParam()

◆ GetWebServerAppHealth()

◆ IsOk()

◆ NewClient()

◆ OnUpdateThreadStart()

◆ OnUpdateThreadStop()

◆ operator=()

◆ PresetManager_InformChange()

◆ ProcessAnyAudio()

◆ ProcessAudio()

◆ ProcessAudio_Planar()

◆ SaveState()

◆ SetBus()

◆ SetMetadata()

◆ SetMetadataMulti()

◆ SetParam()

◆ SetPresetManager()

◆ SetWebServerAppHealth()

◆ StartWebServer()

◆ Stop()

◆ StopWebServer()

◆ Terminate()