Audio sample player for Resonant. More...

#include <Resonant/ModuleSamplePlayer.hpp>

Inheritance diagram for Resonant::ModuleSamplePlayer:

Classes
class	NoteInfo
	Note information container. More...

class	NoteParameters
	Parameters for note-on (aka play-sample) events. More...

Public Types
enum	NoteStatus { NOTE_PLAYING, NOTE_FINISHED }
	Possible states of the individual notes. More...

Public Types inherited from Resonant::Module
enum	{ MAX_CYCLE = 1024 }

Public Types inherited from Valuable::Node
typedef container::const_iterator	const_iterator

typedef Radiant::ArrayMap < QByteArray, Attribute * >	container
	Container for attributes, key is the attribute name.

typedef container::iterator	iterator
	Iterator for the container.

typedef std::function< void(Radiant::BinaryData &)>	ListenerFuncBd
	Listener function type that takes a BinaryData reference as a parameter, similar to eventProcess.

typedef std::function< void()>	ListenerFuncVoid
	Default listener function type.

enum	ListenerType { DIRECT =1, AFTER_UPDATE =2, AFTER_UPDATE_ONCE =4 }
	Types of event listeners. More...

typedef int64_t	Uuid
	Unique identifier type.

Public Types inherited from Valuable::Attribute
enum	Layer { DEFAULT = 0, STYLE, USER, STYLE_IMPORTANT, LAYER_COUNT, LAYER_CURRENT }
	Attribute has multiple independent attribute values on LAYER_COUNT different layers. More...

typedef std::function< void()>	ListenerFunc
	Callback function type in the listener API.

enum	ListenerRole { DELETE_ROLE = 1 << 0, CHANGE_ROLE = 1 << 1, ALL_ROLES = (CHANGE_ROLE << 1) -1 }
	Different listener roles, used when adding a new listener.

enum	ValueUnit { VU_UNKNOWN, VU_PXS, VU_PERCENTAGE, VU_EMS, VU_EXS }
	Units of a value. More...

Public Member Functions
size_t	channels () const
	Number of output channels. More...

void	createAmbientBackground (const char *directory, float gain, int fillchannels=1000, float delay=7.0f)
	Adds a few voices that will play an ambient sound background. More...

virtual void	eventProcess (const QByteArray &address, Radiant::BinaryData &)
	Sends a control message to the module. More...

int	locationToChannel (Nimble::Vector2 location)

	ModuleSamplePlayer ()
	Audio sample player module.

NoteInfo	playSample (const char *filename, float gain, float relpitch, int targetChannel, int sampleChannel, bool loop=false, Radiant::TimeStamp time=Radiant::TimeStamp(0))
	Plays an audio sample. More...

NoteInfo	playSample (const NoteParameters &parameters)
	Plays an audio sample. More...

NoteInfo	playSampleAtLocation (const char *filename, float gain, float relpitch, Nimble::Vector2 location, int sampleChannel, bool loop=false, Radiant::TimeStamp time=Radiant::TimeStamp(0))
	Plays an audio sample. More...

virtual bool	prepare (int &channelsIn, int &channelsOut)
	Prepare for signal processing. More...

virtual void	process (float in, float out, int n, const Resonant::CallbackTime &)
	Processes one cycle of audio data. More...

void	setMasterGain (float gain)
	Sets the master gain.

void	setSampleGain (const NoteInfo &info, float gain, float interpolationTimeSeconds=0.02f)

void	setSampleLooping (const NoteInfo &info, bool looping)

void	setSamplePlayHead (const NoteInfo &info, float playHeadTimeSeconds, float interpolationTimeSeconds=0.02f)

void	setSampleRelativePitch (const NoteInfo &info, float relativePitch, float interpolationTimeSeconds=0.02f)

virtual bool	stop ()
	Stops the signal processing, freeing any resources necessary. More...

void	stopSample (int noteId)
	Stops the playback of a given sample.

void	stopSample (const NoteInfo &info)

const Radiant::TimeStamp &	time ()
	Current playback time. More...

virtual	~ModuleSamplePlayer ()
	Delete the sample player.

Public Member Functions inherited from Resonant::Module
const QByteArray &	id () const
	ID of the module. More...

	Module ()
	Constructs a new module base object.s.

void	setId (const QByteArray &id)
	Sets the id of the module. More...

Public Member Functions inherited from Valuable::Node
bool	acceptsEvent (const QByteArray &messageId) const
	Returns true if this object accepts event 'id' in eventProcess.

bool	addAttribute (Attribute *const attribute)
	Adds a new Attribute to the list of attribute objects. More...

bool	addAttribute (const QByteArray &name, Attribute *const attribute)
	Adds a new Attribute to the list of attribute objects.

template<typename Widget >
bool	addAttribute (const QByteArray &name, const Radiant::IntrusivePtr< Widget > &attribute)
	Adds a new Attribute to the list of attribute objects. More...

long	addListener (const QByteArray &attribute, v8::Persistent< v8::Function > func, int role=Attribute::CHANGE_ROLE)
	Add a JavaScript attribute listener to attribute belonging this Node. More...

virtual Attribute *	attribute (const QByteArray &name) const
	Gets an Attribute with the given name. More...

template<typename T >
AttributeT< T > *	attribute (const QByteArray &name) const
	Gets an Attribute with the given name. More...

const container &	attributes () const

void	clearValues (Layer layer)
	Clears all Attribute values of the given layer. More...

void	debugDump ()
	Prints the contents of this Attribute to the terminal.

virtual bool	deserialize (const ArchiveElement &element)
	De-serializes this object (and its children) from a DOM node.

void	eventAddDeprecated (const QByteArray &deprecatedId, const QByteArray &newId)
	Register a deprecated event that is automatically converted to new event id and a warning is issued when it is used. More...

void	eventAddIn (const QByteArray &messageId)
	Registers a new event that this class handles in eventProcess.

template<typename Widget >
long	eventAddListener (const QByteArray &eventId, const QByteArray &messageId, Radiant::IntrusivePtr< Widget > &listener, ListenerType listenerType=DIRECT, const Radiant::BinaryData *defaultData=0)
	Add an event listener to this object. More...

long	eventAddListener (const QByteArray &eventId, const QByteArray &messageId, Valuable::Node listener, ListenerType listenerType=DIRECT, const Radiant::BinaryData defaultData=0)
	Add an event listener to this object. More...

long	eventAddListener (const QByteArray &eventId, ListenerFuncVoid func, ListenerType listenerType=DIRECT)
	Add an event listener to this object. More...

long	eventAddListener (const QByteArray &eventId, Node *dstNode, ListenerFuncVoid func, ListenerType listenerType=DIRECT)

long	eventAddListenerBd (const QByteArray &eventId, Node *dstNode, ListenerFuncBd func, ListenerType listenerType=DIRECT)

long	eventAddListenerBd (const QByteArray &eventId, ListenerFuncBd func, ListenerType listenerType=DIRECT)
	Add an event listener to this object. More...

void	eventAddOut (const QByteArray &eventId)
	Registers a new event this class can send with eventSend.

const QSet< QByteArray > &	eventInNames () const
	Returns set of all registered IN events.

unsigned	eventListenerCount () const
	Returns the number of event listeners.

const QSet< QByteArray > &	eventOutNames () const
	Returns set of all registered OUT events.

void	eventPassingEnable (bool enable)
	Control whether events are passed.

template<typename Widget >
int	eventRemoveListener (Radiant::IntrusivePtr< Widget > &listener)
	Removes all events from this object to given listener. More...

template<typename Widget >
int	eventRemoveListener (const QByteArray &eventId=QByteArray(), const QByteArray &messageId=QByteArray(), Radiant::IntrusivePtr< Widget > &listener=Radiant::IntrusivePtr< Widget >())
	Removes events from this object that match the parameters. More...

int	eventRemoveListener (const QByteArray &eventId=QByteArray(), const QByteArray &messageId=QByteArray(), Valuable::Node *listener=0)
	Removes event listeners from this object. More...

int	eventRemoveListener (Valuable::Node *listener)
	Removes all events from this object to given listener. More...

bool	eventRemoveListener (long listenerId)
	Removes event listener with given id. More...

void	eventSend (const QByteArray &eventId, Radiant::BinaryData &bd)
	Sends an event and bd to all listeners on this eventId.

void	eventSend (const QByteArray &eventId)
	Sends an event to all listeners on this eventId.

template<typename P1 >
void	eventSend (const QByteArray &eventId, const P1 &p1)
	Sends an event to all listeners on this eventId. More...

template<typename P1 , typename P2 >
void	eventSend (const QByteArray &eventId, const P1 &p1, const P2 &p2)
	Sends an event to all listeners on this eventId. More...

template<typename P1 , typename P2 , typename P3 >
void	eventSend (const QByteArray &eventId, const P1 &p1, const P2 &p2, const P3 &p3)
	Sends an event to all listeners on this eventId. More...

template<typename P1 , typename P2 , typename P3 , typename P4 >
void	eventSend (const QByteArray &eventId, const P1 &p1, const P2 &p2, const P3 &p3, const P4 &p4)
	Sends an event to all listeners on this eventId. More...

template<typename P1 , typename P2 , typename P3 , typename P4 , typename P5 >
void	eventSend (const QByteArray &eventId, const P1 &p1, const P2 &p2, const P3 &p3, const P4 &p4, const P5 &p5)
	Sends an event to all listeners on this eventId. More...

unsigned	eventSourceCount () const
	Returns the number of event sources.

Uuid	id () const
	Returns the unique id.

bool	isBeingDestroyed () const
	Returns true if we are about to delete this object. More...

bool	loadFromFileXML (const QString &filename)
	Reads this object (and its children) from an XML file.

bool	loadFromMemoryXML (const QByteArray &buffer)
	Reads this object (and its children) from a memory buffer.

	Node (Node *host, const QByteArray &name="", bool transit=false)
	Constructs a new Node and adds it under the given host. More...

	Node (Node &&node)
	Moves a node, including all its attributes, events etc. More...

Node &	operator= (Node &&node)
	Moves a node, replacing this. More...

virtual bool	readElement (const ArchiveElement &element)
	Handles a serialization element that lacks automatic handlers. More...

void	removeAttribute (Attribute *const attribute)
	Removes an Attribute from the list of attribute objects.

bool	saveToFileXML (const QString &filename, unsigned int opts=SerializationOptions::DEFAULTS) const
	Saves this object (and its children) to an XML file.

bool	saveToMemoryXML (QByteArray &buffer, unsigned int opts=SerializationOptions::DEFAULTS) const
	Saves this object (and its children) to binary data buffer.

virtual ArchiveElement	serialize (Archive &doc) const
	Serializes this object (and its children) to a DOM node.

virtual void	setAsDefaults ()
	Sets the current USER attribute value as the default value and clears the USER value. More...

void	setId (Uuid newId)
	Sets the unique id. More...

template<class T >
bool	setValue (const QByteArray &name, const T &v)
	Uses a query string to find a Attribute, and sets a new value to that if found. More...

bool	setValue (const QByteArray &name, v8::Handle< v8::Value > v)
	Set attribute value from JavaScript. More...

Public Member Functions inherited from Valuable::Attribute
long	addListener (ListenerFunc func, int role=CHANGE_ROLE)
	Adds a listener that is invoked whenever the value is changed. More...

long	addListener (Node *listener, ListenerFunc func, int role=CHANGE_ROLE)
	Adds a listener that is invoked whenever the value is changed. More...

long	addListener (v8::Persistent< v8::Function > func, int role=CHANGE_ROLE)
	Adds a JavaScript listener that is invoked whenever the value is changed. More...

virtual float	asFloat (bool *const ok=0, Layer layer=LAYER_CURRENT) const
	Converts the value object in a floating point number. More...

virtual int	asInt (bool *const ok=0, Layer layer=LAYER_CURRENT) const
	Converts the value object in an integer. More...

virtual QString	asString (bool *const ok=0, Layer layer=LAYER_CURRENT) const
	Converts the value object to a string. More...

	Attribute (const Attribute &o)
	Create a copy of the given Attribute WITHOUT the link to host, listeners, or the attribute name. More...

	Attribute (Node *host, const QByteArray &name, bool transit=false)
	Constructs a new value object and attaches it to its host. More...

virtual void	clearValue (Layer layer)
	Unsets the value from a specific layer. More...

virtual void	emitChange ()
	Invokes the change valueChanged function of all listeners.

void	eventProcessFloat (const char *id, float v)
	Utility function for sending a float message to the object.

void	eventProcessInt (const char *id, int v)
	Utility function for sending an int message to the object.

void	eventProcessString (const char *id, const QString &str)
	Utility function for sending string message to the object.

void	eventProcessString (const char id, const char str)
	Utility function for sending string message to the object.

void	eventProcessVector2 (const char *id, Nimble::Vector2)
	Utility function for sending a Nimble::Vector2f message to the object.

void	eventProcessVector3 (const char *id, Nimble::Vector3)
	Utility function for sending a Vector3 message to the object.

void	eventProcessVector4 (const char *id, Nimble::Vector4)
	Utility function for sending a Vector4 message to the object.

virtual bool	handleShorthand (const Valuable::StyleValue &value, Radiant::ArrayMap< Valuable::Attribute *, Valuable::StyleValue > &expanded)
	If attribute supports shorthand properties, this should be used to parse those. More...

Node *	host () const
	The host object of the value object (is any). More...

virtual bool	isChanged () const

virtual bool	isValueDefinedOnLayer (Layer layer) const
	Check if the given layer defines a value. More...

bool	layerForSerialization (SerializationOptions flags, Layer &layer) const

const QByteArray &	name () const
	Returns the name of the object.

const Attribute &	operator= (const Attribute &)
	Create a copy of the given Attribute WITHOUT the link to host, listeners, or the attribute name. More...

Attribute *	ownerShorthand () const

QByteArray	path () const
	Returns the path (separated by '/'s) from the root.

void	removeHost ()
	Sets the host pointer to zero and removes this object from the host. More...

bool	removeListener (Node *listener, int role=ALL_ROLES)
	Removes a listener from the listener list. More...

bool	removeListener (long id)
	Removes a listener from the listener list. More...

void	removeListeners (int role=ALL_ROLES)
	Removes listeners from the listener list.

virtual bool	set (float v, Layer layer=USER, ValueUnit unit=VU_UNKNOWN)
	Sets the value of the object.

virtual bool	set (int v, Layer layer=USER, ValueUnit unit=VU_UNKNOWN)
	Sets the value of the object.

virtual bool	set (const QString &v, Layer layer=USER, ValueUnit unit=VU_UNKNOWN)
	Sets the value of the object.

virtual bool	set (const Nimble::Vector2f &v, Layer layer=USER, QList< ValueUnit > units=QList< ValueUnit >())
	Sets the value of the object.

virtual bool	set (const Nimble::Vector3f &v, Layer layer=USER, QList< ValueUnit > units=QList< ValueUnit >())
	Sets the value of the object.

virtual bool	set (const Nimble::Vector4f &v, Layer layer=USER, QList< ValueUnit > units=QList< ValueUnit >())
	Sets the value of the object.

virtual bool	set (const StyleValue &value, Layer layer=USER)
	Sets the value of the object.

void	setName (const QByteArray &s)
	Sets the name of the object.

void	setOwnerShorthand (Attribute *owner)

virtual QByteArray	type () const
	Get the type id of the attribute. More...

Public Member Functions inherited from Valuable::Serializable
virtual bool	deserializeXML (const DOMElement &element)
	Deserializes (reads) this object from an XML element. More...

bool	isSerializable () const

void	setSerializable (bool v)

Additional Inherited Members
Valuable Attributes inherited from Valuable::Node
Node::Uuid	id = generateId()
	Returns the unique id. More...

Static Public Member Functions inherited from Valuable::Node
static bool	copyValues (const Node &from, Node &to)
	Copies attribute values from one node to another. More...

static void	disableQueue ()
	Disables all AFTER_UPDATE event processing, no new events will be accepted and the current queue will be cleared. More...

static Uuid	generateId ()
	Generates a unique identifier. More...

static void	invokeAfterUpdate (ListenerFuncVoid function)
	Queue function to be called in the main thread after the next update() More...

static int	processQueue ()
	Triggers any pending AFTER_UPDATE-events. More...

static void	reEnableQueue ()
	Enables queue after calling disableQueue. More...

static void	setFatalOnEventMismatch (bool haltApplication)
	Controls what to do when an event mismatch is detected The default behavior is to output a warning to the terminal (haltApplication = false). More...

Protected Member Functions inherited from Valuable::Node
virtual void	attributeAdded (Attribute *attribute)
	This is called when new attribute is added to Node. More...

virtual void	attributeRemoved (Attribute *attribute)
	This is called when attribute is removed from Node. More...

Node *	sender ()
	Get the sender of the event, only valid in DIRECT events. More...

void	setBeingDestroyed ()
	Sets 'isBeginDestroyed' flag to true and removes all event listeners to this object. More...

Detailed Description

Audio sample player for Resonant.

This class implements a basic sample player, which can be used as a minimal synthesizer.

Note management: Playing samples become notes that can be controlled by the user. If you play the same sample many times, each note is treated individually. For this purpose the functions that start sample playback return NoteInfo objects that can be used to query the state of the note.

Memory management: The samples (aka audio files) are read from the disk as they are needed. The samples are loaded when they are first used. To force the loading of a particular sample, you can play the sample with zero volume. Samples are never dropped away from the RAM which may cause memory usage issues if the application is using a lot sound files.

Member Enumeration Documentation

enum Resonant::ModuleSamplePlayer::NoteStatus

Possible states of the individual notes.

Each note has its own id.

Enumerator
NOTE_PLAYING	Note is playing.
NOTE_FINISHED	Note is finished.

Member Function Documentation

size_t Resonant::ModuleSamplePlayer::channels ( ) const

inline

Number of output channels.

Returns: Number of output channels

void Resonant::ModuleSamplePlayer::createAmbientBackground	(	const char *	directory,
		float	gain,
		int	fillchannels = `1000`,
		float	delay = `7.0f`
	)

Adds a few voices that will play an ambient sound background.

All files in the given directory are loaded looped for-ever. In practice one wants to put 3-5 audio files with different lengths in the directory. The length of the files should be usually in the 20-30 second range. The end result will be a nice ambient background that does not sound like it is looping.

The ambient sounds are replicated accross given number of channels, with channel rotation to ensure that each loudspeaker will generate slightly different sounds.

Parameters

directory	Where the files are loaded from.
gain	The gain (volume) to give to the background material.
fillchannels	The number of output channels to fill. This number is limited by the active channel number.
delay	Delay time to wait before starting the playback. Short delay times may lead to poor synchronization between different channels.

virtual void Resonant::ModuleSamplePlayer::eventProcess	(	const QByteArray &	id,
		Radiant::BinaryData &	data
	)

virtual

Sends a control message to the module.

The default implementation does nothing. Child classes with dynamic variable will need to override this method.

Parameters

id	Command name
data	Command parameters

Reimplemented from Resonant::Module.

NoteInfo Resonant::ModuleSamplePlayer::playSample	(	const char *	filename,
		float	gain,
		float	relpitch,
		int	targetChannel,
		int	sampleChannel,
		bool	loop = `false`,
		Radiant::TimeStamp	time = `Radiant::TimeStamp(0)`
	)

Plays an audio sample.

This function starts the playback of an audio sample.

Parameters

filename	The name of the audio sample file.
gain	The gain coefficient for playback. Setting gain to one plays the file back at the original volume.
relpitch	The pitch for the playback. If the pitch is set to one, then the file will play back at the original speed. With pitch of 0.5 the file will play back one octave below original pitch, and last twice as long as nominal file duration.
targetChannel	Select the channel where the sound is going to. For example in 8-channel environment, this parameter can range from zero to seven.
sampleChannel	Select the channel of the source file that should be used as the source.
loop	Turns on looping if necessary. With looping the sample will play back for-ever.
time	optional timestamp when to play the sample.

Returns: Returns a handle to the note playback information.

NoteInfo Resonant::ModuleSamplePlayer::playSample ( const NoteParameters & parameters )

Plays an audio sample.

This function starts the playback of an audio sample.

Parameters

parameters An object containing all the parameters for the playback of the sample

NoteInfo Resonant::ModuleSamplePlayer::playSampleAtLocation	(	const char *	filename,
		float	gain,
		float	relpitch,
		Nimble::Vector2	location,
		int	sampleChannel,
		bool	loop = `false`,
		Radiant::TimeStamp	time = `Radiant::TimeStamp(0)`
	)

Plays an audio sample.

This function starts the playback of an audio sample.

Parameters

filename	The name of the audio sample file.
gain	The gain coefficient for playback. Setting gain to one plays the file back at the original volume.
relpitch	The pitch for the playback. If the pitch is set to one, then the file will play back at the original speed. With pitch of 0.5 the file will play back one octave below original pitch, and last twice as long as nominal file duration.
location	The screen location where this sample should be located. Currently the location is used so that the sample player tries to find an audio panning module and if the panner is present uses that to convert the location to one specific audio out channel. The sound is then played out on that channel.
sampleChannel	Select the channel of the source file that should be used as the source.
loop	Turns on looping if necessary. With looping the sample will play back for-ever.
time	optional timestamp when to play the sample.

Returns: Returns a handle to the note playback information.

virtual bool Resonant::ModuleSamplePlayer::prepare	(	int &	channelsIn,
		int &	channelsOut
	)

virtual

Prepare for signal processing.

The default implementation returns true. Most child classes will need to override this method to perform some preparation work.

Parameters

[out]	channelsIn	The number of desired input channels. If necessary, the number of input and output channels is changed (for example if the module is stereo-only, but the host requested mono operation).
[out]	channelsOut	The number of desired output channels.

Returns: Returns true if the module prepared successfully.

Reimplemented from Resonant::Module.

virtual void Resonant::ModuleSamplePlayer::process	(	float **	in,
		float **	out,
		int	n,
		const Resonant::CallbackTime &	time
	)

virtual

Processes one cycle of audio data.

Parameters

in	Input audio data.
out	Output audio data.
n	Number of samples to process. Guaranteed to be between 1 and MAX_CYCLE.

Implements Resonant::Module.

virtual bool Resonant::ModuleSamplePlayer::stop ( )

virtual

Stops the signal processing, freeing any resources necessary.

Returns: True if stopping succeeded (or was already stopped). False on error.

Reimplemented from Resonant::Module.

const Radiant::TimeStamp& Resonant::ModuleSamplePlayer::time ( )

inline

Current playback time.

Returns: Current playback time

Classes

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Member Function Documentation