com.soundhelix.component.arrangementengine.impl

Class SimpleArrangementEngine

java.lang.Object

com.soundhelix.component.arrangementengine.impl.AbstractArrangementEngine

com.soundhelix.component.arrangementengine.impl.SimpleArrangementEngine

All Implemented Interfaces:

ArrangementEngine, Component, RandomSeedable, XMLConfigurable

public class SimpleArrangementEngine
extends AbstractArrangementEngine

Implements a simple ArrangementEngine. The song starts with a configurable "fade-in" of the number of active ActivityVectors and ends with a configurable "fade-out" of the number of active ActivityVectors. For each chord section in between, the number of active AVs is varied in the configured range. ActivityVector activity can be constrained individually to enforce certain properties. All AVs are filled at the same time because there is always the above-mentioned overall song constraint that defines the number of active AVs for each chord section. For each chord section a choice is made whether to activate or deactivate AVs or to leave the number of active AVs unchanged, according to the AVs that should be active. The list of generated AVs are called a song activity matrix. The following constraints are supported for ActivityVectors: - minActive(n): the AV must be active for at least n% of the song; granularity is at chord section level; it is also possible define that the AV may be inactive for the whole song or be active with at least n% of the song - maxActive(n): the AV must be active for at most n% of the song; granularity is at chord section level - startBeforeSection(n): the AV must start before section n - startAfterSection(n): the AV must start after section n - stopBeforeSection(n): the AV must stop before section n, counted from the end (0 is the last chord section) - stopAfterSection(n): the AV must stop after section n, counted from the end (0 is the last chord section) - minSegmentCount(n): the AV must be active for at least n chord section segments - maxSegmentCount(n): the AV must be active for at most n chord section segments - minSegmentLength(n): the minimum AV segment length must be n chord sections - maxSegmentLength(n): the maximum AV segment length must be n chord sections - minPauseLength(n): the minimum AV pause length must be n chord sections - maxPauseLength(n): the maximum AV pause length must be n chord sections A randomized backtracking algorithm is used for finding a song activity matrix that fulfills all constraints of all ActivityVectors at the same time. It works roughly as follows: The song activity matrix is built from left to right (chord section by chord section) by making random selections about which AVs to activate or deactivate. If a constraint violation is detected, a number of different random choices at the same section is tried by reverting the previous choice and choosing another one; if all these fail, the algorithm backtracks to the previous section. To avoid the overhead of recursion, the algorithm is implemented iteratively. The algorithm is able to find a valid song activity matrix pretty quickly (if one exists), much faster than the simpler algorithm used in version 0.1 of SoundHelix and before. The algorithm scales pretty well with increasing numbers of constraints, but keep in mind that every additional constraint increases the complexity level of finding a valid song activity matrix.

Author:

Thomas Schuerger (thomas@schuerger.com)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SimpleArrangementEngine.ConstraintMode The constraint mode for ActivityMatrix generation.

Field Summary

Fields inherited from class com.soundhelix.component.arrangementengine.impl.AbstractArrangementEngine

logger, randomSeed

Constructor Summary

Constructors

Constructor and Description
SimpleArrangementEngine() Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	configure(SongContext songContext, Node node) Configures the instance using the specified XML node.
SimpleArrangementEngine.ConstraintMode	getConstraintMode()
Arrangement	render(SongContext songContext) Renders and returns an Arrangement.
void	setActivityVectorConfiguration(Map<String,com.soundhelix.component.arrangementengine.impl.SimpleArrangementEngine.ActivityVectorConfiguration> activityVectorConfigurationHashMap)
void	setArrangementEntries(com.soundhelix.component.arrangementengine.impl.SimpleArrangementEngine.ArrangementEntry[] arrangementEntries)
void	setConstraintMode(SimpleArrangementEngine.ConstraintMode constraintMode)
void	setMaxActivityChangeCount(int maxActivityChangeCount)
void	setMaxActivityCount(int maxActiveCount)
void	setMaxIterations(int maxIterations)
void	setMinActivityCount(int minActiveCount)
void	setStartActivityCounts(int[] startActivityCounts)
void	setStopActivityCounts(int[] stopActivityCounts)

Methods inherited from class com.soundhelix.component.arrangementengine.impl.AbstractArrangementEngine

getRandomSeed, setRandomSeed

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleArrangementEngine

public SimpleArrangementEngine()

Constructor.

Method Detail

render

public Arrangement render(SongContext songContext)

Description copied from interface: ArrangementEngine

Renders and returns an Arrangement.

Parameters:

songContext - songContext

Returns:

the rendered arrangement

setArrangementEntries

public void setArrangementEntries(com.soundhelix.component.arrangementengine.impl.SimpleArrangementEngine.ArrangementEntry[] arrangementEntries)

configure

public void configure(SongContext songContext,
             Node node)
               throws XPathException

Description copied from interface: XMLConfigurable

Configures the instance using the specified XML node. The method should read all supported configuration tags and should call the corresponding setter methods of the class. All settings of the class that are settable using XML should also be settable by using public methods (for example, if the beats per minute are settable using an XML tag, then the class should also provide a public method setBPM(), which does the same). XML configuration can also be a recursive process, if XML settings contain nodes that require XML configuration themselves, but this is up to the implementation of this method. The method should (but need not) use XPath to access the node's tags. Only the node and its descendant nodes may be used for configuration.

Parameters:

songContext - the song context

node - the parent XML node of the configuration tags

Throws:

XPathException - in case of an XPath problem

setActivityVectorConfiguration

public void setActivityVectorConfiguration(Map<String,com.soundhelix.component.arrangementengine.impl.SimpleArrangementEngine.ActivityVectorConfiguration> activityVectorConfigurationHashMap)

setMinActivityCount

public void setMinActivityCount(int minActiveCount)

setMaxActivityCount

public void setMaxActivityCount(int maxActiveCount)

setMaxActivityChangeCount

public void setMaxActivityChangeCount(int maxActivityChangeCount)

setMaxIterations

public void setMaxIterations(int maxIterations)

getConstraintMode

public SimpleArrangementEngine.ConstraintMode getConstraintMode()

setConstraintMode

public void setConstraintMode(SimpleArrangementEngine.ConstraintMode constraintMode)

setStartActivityCounts

public void setStartActivityCounts(int[] startActivityCounts)

setStopActivityCounts

public void setStopActivityCounts(int[] stopActivityCounts)