#include <CUAudioSynchronizer.h>

Inheritance diagram for cugl::audio::AudioSynchronizer:

Public Member Functions
	AudioSynchronizer ()

	~AudioSynchronizer ()

virtual bool	init () override

virtual bool	init (Uint8 channels, Uint32 rate) override

virtual void	dispose () override

double	getOverhead () const

void	setOverhead (double overhead)

double	getJitter () const

void	clearJitter ()

bool	onBeat ()

bool	attach (const std::shared_ptr< AudioNode > &node, double bpm=0.0)

std::shared_ptr< AudioNode >	detach ()

std::shared_ptr< AudioNode >	getInput () const

virtual void	setReadSize (Uint32 size) override

virtual bool	completed () override

virtual Uint32	read (float *buffer, Uint32 frames) override

virtual bool	mark () override

virtual bool	unmark () override

virtual bool	reset () override

virtual Sint64	advance (Uint32 frames) override

virtual Sint64	getPosition () const override

virtual Sint64	setPosition (Uint32 position) override

virtual double	getElapsed () const override

virtual double	setElapsed (double time) override

virtual double	getRemaining () const override

virtual double	setRemaining (double time) override

Public Member Functions inherited from cugl::audio::AudioNode
	AudioNode ()

virtual	~AudioNode ()

virtual bool	init ()

virtual bool	init (Uint8 channels, Uint32 rate)

virtual void	dispose ()

Uint8	getChannels () const

Uint32	getRate () const

float	getGain ()

virtual void	setGain (float gain)

Uint32	getReadSize () const

virtual void	setReadSize (Uint32 size)

const std::string	getClassName () const

const std::string	getName () const

void	setName (const std::string name)

Sint32	getTag () const

void	setTag (Sint32 tag)

virtual std::string	toString (bool verbose=false) const

	operator std::string () const

Callback	getCallback ()

void	setCallback (Callback callback)

virtual bool	isPaused ()

virtual bool	pause ()

virtual bool	resume ()

virtual bool	completed ()

virtual Uint32	read (float *buffer, Uint32 frames)

virtual bool	mark ()

virtual bool	unmark ()

virtual bool	reset ()

virtual Sint64	advance (Uint32 frames)

virtual Sint64	getPosition () const

virtual Sint64	setPosition (Uint32 position)

virtual double	getElapsed () const

virtual double	setElapsed (double time)

virtual double	getRemaining () const

virtual double	setRemaining (double time)

Static Public Member Functions
static std::shared_ptr< AudioSynchronizer >	alloc ()

static std::shared_ptr< AudioSynchronizer >	alloc (Uint8 channels, Uint32 rate)

Additional Inherited Members
Public Types inherited from cugl::audio::AudioNode
enum	Action : int { COMPLETE = 0 , INTERRUPT = 1 , FADE_OUT = 2 , FADE_IN = 3 , FADE_DIP = 4 , LOOPBACK = 5 }

typedef std::function< void(const std::shared_ptr< AudioNode > &node, Action type)>	Callback

Static Public Attributes inherited from cugl::audio::AudioNode
static const Uint32	DEFAULT_CHANNELS

static const Uint32	DEFAULT_SAMPLING

Protected Member Functions inherited from cugl::audio::AudioNode
void	notify (const std::shared_ptr< AudioNode > &node, Action action)

Protected Attributes inherited from cugl::audio::AudioNode
Uint8	_channels

Uint32	_sampling

bool	_booted

std::atomic< float >	_ndgain

std::atomic< bool >	_paused

std::atomic< bool >	_polling

Callback	_callback

std::atomic< bool >	_calling

Sint32	_tag

Uint32	_readsize

std::string	_localname

std::string	_classname

size_t	_hashOfName

bool	_locked

Detailed Description

A class providing visual synchronization for an audio node.

Because of variable latency issues on mobile platforms, synchronization for rhythm games is always difficult. This EXPERIMENTAL class is attempt to resolve this issue.

To use this class, attach a node with three channels. The first two channels are stereo sound while the third channel represents the "beat". Any non-zero signal in this channel represents a beat window.

WARNING: This class is largely untested. Use at your own risk.

This class does not support any actions for the AudioNode#setCallback.

Constructor & Destructor Documentation

◆ AudioSynchronizer()

cugl::audio::AudioSynchronizer::AudioSynchronizer ( )

Creates a degenerate audio synchronizer

The node has no channels, so read options will do nothing. The node must be initialized to be used.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate a graph node on the heap, use one of the static constructors instead.

◆ ~AudioSynchronizer()

cugl::audio::AudioSynchronizer::~AudioSynchronizer ( )

inline

Deletes the audio synchronizer, disposing of all resources

Member Function Documentation

◆ advance()

virtual Sint64 cugl::audio::AudioSynchronizer::advance ( Uint32 frames )

overridevirtual

Advances the stream by the given number of frames.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node or if this method is unsupported in that node

This method only advances the read position, it does not actually read data into a buffer. This method is generally not supported for nodes with real-time input like AudioInput.

Parameters

frames The number of frames to advace

Returns: the actual number of frames advanced; -1 if not supported

Reimplemented from cugl::audio::AudioNode.

◆ alloc() [1/2]

static std::shared_ptr< AudioSynchronizer > cugl::audio::AudioSynchronizer::alloc ( )

inlinestatic

Returns a newly allocated synchronizer with default stereo settings

The number of output channels is two, for stereo output. Input nodes must either match this (for no carrier signal) or have one additional channel. The sample rate is the modern standard of 48000 HZ.

Returns: a newly allocated synchronizer with default stereo settings

◆ alloc() [2/2]

static std::shared_ptr< AudioSynchronizer > cugl::audio::AudioSynchronizer::alloc	(	Uint8	channels,
		Uint32	rate
	)

inlinestatic

Returns a newly allocated synchronizer with the given number of channels and sample rate

The channels specifies the number of output channels. Input nodes must either match this (for no carrier signal) or have one additional channel.

Parameters

channels	The number of audio channels
rate	The sample rate (frequency) in HZ

Returns: a newly allocated synchronizer with the given number of channels and sample rate

◆ attach()

bool cugl::audio::AudioSynchronizer::attach	(	const std::shared_ptr< AudioNode > &	node,
		double	bpm = `0.0`
	)

Attaches an audio node to this synchronizer.

The audio node must agree with the sample rate of this synchronizer. If it has a carrier signal, then it should have one more channel than this node, with the extra channel delivering the signal. If it does not have a carrier signal, it must agree with the number of channels of this node.

The optional bpm (beats-per-minute) argument is only applicable if the node does not have a carrier signal. In that case, it will use the timestamps to guess at the synchronization information. If the bpm value is not positive, it will not attempt to synchronize.

Parameters

node	The audio node to synchronize
bpm	The beats-per-minute if a carrier signal is missing

Returns: true if the attachment was successful

◆ clearJitter()

void cugl::audio::AudioSynchronizer::clearJitter ( )

Clears the jitter readings to reset the calculations

◆ completed()

virtual bool cugl::audio::AudioSynchronizer::completed ( )

overridevirtual

Returns true if this audio node has no more data.

An audio node is typically completed if it return 0 (no frames read) on subsequent calls to read(). However, for infinite-running audio threads, it is possible for this method to return true even when data can still be read; in that case the node is notifying that it should be shut down.

Returns: true if this audio node has no more data.

Reimplemented from cugl::audio::AudioNode.

◆ detach()

std::shared_ptr< AudioNode > cugl::audio::AudioSynchronizer::detach ( )

Detaches an audio node from this synchronizer.

If the method succeeds, it returns the audio node that was removed.

Returns: The audio node to detach (or null if failed)

◆ dispose()

virtual void cugl::audio::AudioSynchronizer::dispose ( )

overridevirtual

Disposes any resources allocated for this synchronizer

The state of the node is reset to that of an uninitialized constructor. Unlike the destructor, this method allows the node to be reinitialized.

Reimplemented from cugl::audio::AudioNode.

◆ getElapsed()

virtual double cugl::audio::AudioSynchronizer::getElapsed ( ) const

overridevirtual

Returns the elapsed time in seconds.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node or if this method is unsupported in that node

In some nodes like AudioInput, this method is only supported if mark() is set. In that case, the times will be the number of seconds since the mark. Other nodes like AudioPlayer measure from the start of the stream.

Returns: the elapsed time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ getInput()

std::shared_ptr< AudioNode > cugl::audio::AudioSynchronizer::getInput ( ) const

inline

Returns the input node of this synchronizer.

Returns: the input node of this synchronizer.

◆ getJitter()

double cugl::audio::AudioSynchronizer::getJitter ( ) const

inline

Returns the currently observed jitter

Returns -1 if there is no jitter so far

◆ getOverhead()

double cugl::audio::AudioSynchronizer::getOverhead ( ) const

inline

Returns the (projected) overhead of reading the audio graph

Returns: the (projected) overhead of reading the audio graph

◆ getPosition()

virtual Sint64 cugl::audio::AudioSynchronizer::getPosition ( ) const

overridevirtual

Returns the current frame position of this audio node

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node or if this method is unsupported in that node

In some nodes like AudioInput, this method is only supported if mark() is set. In that case, the position will be the number of frames since the mark. Other nodes like AudioPlayer measure from the start of the stream.

Returns: the current frame position of this audio node.

Reimplemented from cugl::audio::AudioNode.

◆ getRemaining()

virtual double cugl::audio::AudioSynchronizer::getRemaining ( ) const

overridevirtual

Returns the remaining time in seconds.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node or if this method is unsupported in that node

In some nodes like AudioInput, this method is only supported if setRemaining() has been called. In that case, the node will be marked as completed after the given number of seconds. This may or may not actually move the read head. For example, in AudioPlayer it will skip to the end of the sample. However, in AudioInput it will simply time out after the given time.

Returns: the remaining time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ init() [1/2]

virtual bool cugl::audio::AudioSynchronizer::init ( )

overridevirtual

Initializes the synchronizr with default stereo settings

The number of output channels is two, for stereo output. Input nodes must either match this (for no carrier signal) or have one additional channel. The sample rate is the modern standard of 48000 HZ.

Returns: true if initialization was successful

Reimplemented from cugl::audio::AudioNode.

◆ init() [2/2]

virtual bool cugl::audio::AudioSynchronizer::init	(	Uint8	channels,
		Uint32	rate
	)

overridevirtual

Initializes the synchronizer with the given number of channels and sample rate

The channels specifies the number of output channels. Input nodes must either match this (for no carrier signal) or have one additional channel.

Parameters

channels	The number of audio channels
rate	The sample rate (frequency) in HZ

Returns: true if initialization was successful

Reimplemented from cugl::audio::AudioNode.

◆ mark()

virtual bool cugl::audio::AudioSynchronizer::mark ( )

overridevirtual

Marks the current read position in the audio steam.

DELEGATED METHOD: This method delegates its call to the input node. It returns false if there is no input node or if this method is unsupported in that node

This method is typically used by reset() to determine where to restore the read position. For some nodes (like AudioInput), this method may start recording data to a buffer, which will continue until reset() is called.

It is possible for reset() to be supported even if this method is not.

Returns: true if the read position was marked.

Reimplemented from cugl::audio::AudioNode.

◆ onBeat()

bool cugl::audio::AudioSynchronizer::onBeat ( )

Returns true if the music is on the beat

Returns: true if the music is on the beat

◆ read()

virtual Uint32 cugl::audio::AudioSynchronizer::read	(	float *	buffer,
		Uint32	frames
	)

overridevirtual

Reads up to the specified number of frames into the given buffer

AUDIO THREAD ONLY: Users should never access this method directly. The only exception is when the user needs to create a custom subclass of this AudioOutput.

The buffer should have enough room to store frames * channels elements. The channels are interleaved into the output buffer.

This method will always forward the read position.

Parameters

buffer	The read buffer to store the results
frames	The maximum number of frames to read

Returns: the actual number of frames read

Reimplemented from cugl::audio::AudioNode.

◆ reset()

virtual bool cugl::audio::AudioSynchronizer::reset ( )

overridevirtual

Resets the read position to the marked position of the audio stream.

DELEGATED METHOD: This method delegates its call to the input node. It returns false if there is no input node or if this method is unsupported in that node

When no mark() is set, the result of this method is node dependent. Some nodes (such as AudioPlayer) will reset to the beginning of the stream, while others (like AudioInput) only support a rest when a mark is set. Pay attention to the return value of this method to see if the call is successful.

Returns: true if the read position was moved.

Reimplemented from cugl::audio::AudioNode.

◆ setElapsed()

virtual double cugl::audio::AudioSynchronizer::setElapsed ( double time )

overridevirtual

Sets the read position to the elapsed time in seconds.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node or if this method is unsupported in that node

In some nodes like AudioInput, this method is only supported if mark() is set. In that case, the new time will be meaured from the mark. Other nodes like AudioPlayer measure from the start of the stream.

Parameters

time	The elapsed time in seconds.

Returns: the new elapsed time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ setOverhead()

void cugl::audio::AudioSynchronizer::setOverhead ( double overhead )

Sets the projected overhead of reading the audio graph

Parameters

overhead The projected overhead of reading the audio graph

◆ setPosition()

virtual Sint64 cugl::audio::AudioSynchronizer::setPosition ( Uint32 position )

overridevirtual

Sets the current frame position of this audio node.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node or if this method is unsupported in that node

In some nodes like AudioInput, this method is only supported if mark() is set. In that case, the position will be the number of frames since the mark. Other nodes like AudioPlayer measure from the start of the stream.

Parameters

position the current frame position of this audio node.

Returns: the new frame position of this audio node.

Reimplemented from cugl::audio::AudioNode.

◆ setReadSize()

virtual void cugl::audio::AudioSynchronizer::setReadSize ( Uint32 size )

overridevirtual

Sets the typical read size of this node.

Some audio nodes need an internal buffer for operations like mixing or resampling. In that case, it helps to know the requested read size ahead of time. The capacity is the minimal required read amount of the AudioEngine and corresponds to AudioEngine#getReadSize.

It is not actually necessary to set this size. However for nodes with internal buffer, setting this value can optimize performance.

This method is not synchronized because it is assumed that this value will never change while the audio engine in running. The average user should never call this method explicitly. You should always call AudioEngine#setReadSize instead.

Parameters

size	The typical read size of this node.

Reimplemented from cugl::audio::AudioNode.

◆ setRemaining()

virtual double cugl::audio::AudioSynchronizer::setRemaining ( double time )

overridevirtual

Sets the remaining time in seconds.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node or if this method is unsupported in that node

If this method is supported, then the node will be marked as completed after the given number of seconds. This may or may not actually move the read head. For example, in AudioPlayer it will skip to the end of the sample. However, in AudioInput it will simply time out after the given time.

Parameters

time	The remaining time in seconds.

Returns: the new remaining time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ unmark()

virtual bool cugl::audio::AudioSynchronizer::unmark ( )

overridevirtual

Clears the current marked position.

DELEGATED METHOD: This method delegates its call to the input node. It returns false if there is no input node or if this method is unsupported in that node

If the method mark() started recording to a buffer (such as with AudioInput), this method will stop recording and release the buffer. When the mark is cleared, reset() may or may not work depending upon the specific node.

Returns: true if the read position was marked.

Reimplemented from cugl::audio::AudioNode.

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

cugl/include/cugl/audio/graph/CUAudioSynchronizer.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ AudioSynchronizer()

◆ ~AudioSynchronizer()

Member Function Documentation

◆ advance()

◆ alloc() [1/2]

◆ alloc() [2/2]

◆ attach()

◆ clearJitter()

◆ completed()

◆ detach()

◆ dispose()

◆ getElapsed()

◆ getInput()

◆ getJitter()

◆ getOverhead()

◆ getPosition()

◆ getRemaining()

◆ init() [1/2]

◆ init() [2/2]

◆ mark()

◆ onBeat()

◆ read()

◆ reset()

◆ setElapsed()

◆ setOverhead()

◆ setPosition()

◆ setReadSize()

◆ setRemaining()

◆ unmark()