com.tagtraum.jipes.audio

Class SelfSimilarity<I extends AudioBuffer>

java.lang.Object

com.tagtraum.jipes.audio.SelfSimilarity<I>

All Implemented Interfaces:

SignalProcessor<I,AudioMatrix>

public class SelfSimilarity<I extends AudioBuffer>
extends Object
implements SignalProcessor<I,AudioMatrix>

Self similarity processor computes a self-similarity matrix from AudioBuffer features. The actual value is produced on flush().

Author:

Hendrik Schreiber

Field Summary

Fields

Modifier and Type	Field and Description
static int	FULL_MATRIX

Constructor Summary

Constructors

Constructor and Description
SelfSimilarity() Self similarity processor using a full matrix (i.e.
SelfSimilarity(int bandwidth) Self similarity processor with a limited bandwidth around the main diagonal.
SelfSimilarity(Object id) Self similarity processor using a full matrix (i.e.
SelfSimilarity(Object id, int bandwidth, DistanceFunction<I> distanceFunction) Self similarity processor with a limited bandwidth around the main diagonal.

Method Summary

Modifier and Type	Method and Description
<O2> SignalProcessor<AudioMatrix,O2>	connectTo(SignalProcessor<AudioMatrix,O2> signalProcessor) Connects this processor to another processor to forward processed data to.
protected MutableMatrix	createMatrix(int previousLength, int length, int bandwidth) By default this creates a symmetric, float-backed, zero-padded Matrix.
<O2> SignalProcessor<AudioMatrix,O2>	disconnectFrom(SignalProcessor<AudioMatrix,O2> signalProcessor) Disconnects a child processor.
void	flush() Asks to complete all pending operations.
int	getBandwidth() Matrix bandwidth for matrices created by createMatrix(int, int, int).
SignalProcessor<AudioMatrix,?>[]	getConnectedProcessors() Lists all connected processors.
Object	getId() Arbitrary object to identify a processor.
AudioMatrix	getOutput() First calls SignalProcessor.flush(), then returns the pending output, should there be any.
boolean	isCopyOnMatrixEnlargement() Indicates whether the similarity matrix should be copied or enlarged (see Matrix.enlarge(com.tagtraum.jipes.math.Matrix)) with a new matrix.
void	process(I input) Asks this processor to work on the provided data and pipe the output to the connected processors' own SignalProcessor.process(Object) method. Implementing methods must not modify or hold on to the provided data.
void	setBandwidth(int bandwidth) Sets the maximal distance between two AudioBuffers that is still compared and computed for the AudioMatrix.
void	setCopyOnMatrixEnlargement(boolean copyOnMatrixEnlargement) Copy the whole matrix, if we need to increase its size?
void	setDistanceFunction(DistanceFunction<I> distanceFunction) Sets the distance function used to compute the self similarity matrix.
void	setId(Object id)

Methods inherited from class java.lang.Object

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

Field Detail

FULL_MATRIX

public static final int FULL_MATRIX

See Also:

Constant Field Values

Constructor Detail

SelfSimilarity

public SelfSimilarity(int bandwidth)

Self similarity processor with a limited bandwidth around the main diagonal.

Parameters:

bandwidth - bandwidth

SelfSimilarity

public SelfSimilarity(Object id,
                      int bandwidth,
                      DistanceFunction<I> distanceFunction)

Self similarity processor with a limited bandwidth around the main diagonal.

Parameters:

id - id

distanceFunction - distance function

SelfSimilarity

public SelfSimilarity(Object id)

Self similarity processor using a full matrix (i.e. getBandwidth() == FULL_MATRIX).

Parameters:

id - id

SelfSimilarity

public SelfSimilarity()

Self similarity processor using a full matrix (i.e. getBandwidth() == FULL_MATRIX).

Method Detail

setId

public void setId(Object id)

setBandwidth

public void setBandwidth(int bandwidth)

Sets the maximal distance between two AudioBuffers that is still compared and computed for the AudioMatrix. If this is set to a positive value, a SymmetricBandMatrix is used internally to preserve memory even when the input is long.

Parameters:

bandwidth - bandwidth, must be odd. Values 0 or less indicate full bandwidth

See Also:

SymmetricBandMatrix, createMatrix(int, int, int)

getBandwidth

public int getBandwidth()

Matrix bandwidth for matrices created by createMatrix(int, int, int).

Returns:

bandwidth or 0 or less for full bandwidth

See Also:

SymmetricBandMatrix

setDistanceFunction

public void setDistanceFunction(DistanceFunction<I> distanceFunction)

Sets the distance function used to compute the self similarity matrix.

Parameters:

distanceFunction - distance function

See Also:

DistanceFunctions.createCosineDistanceFunction()

isCopyOnMatrixEnlargement

public boolean isCopyOnMatrixEnlargement()

Indicates whether the similarity matrix should be copied or enlarged (see Matrix.enlarge(com.tagtraum.jipes.math.Matrix)) with a new matrix.

Returns:

true or false

setCopyOnMatrixEnlargement

public void setCopyOnMatrixEnlargement(boolean copyOnMatrixEnlargement)

Copy the whole matrix, if we need to increase its size?

Parameters:

copyOnMatrixEnlargement - if true, the similarity matrix will be copied, if we need to increase its size

See Also:

isCopyOnMatrixEnlargement()

process

public void process(I input)
             throws IOException

Description copied from interface: SignalProcessor

Asks this processor to work on the provided data and pipe the output to the connected processors' own SignalProcessor.process(Object) method.
Implementing methods must not modify or hold on to the provided data. In other words: the provided object does not belong to you, its values are only guaranteed to be stable for the duration of the call.

If you need to hold on to data, create a copy of the provided data via a copy constructor or the Object.clone() method.

It is the responsibility of implementing classes to call the SignalProcessor.process(Object) method of any connected processors. To manage connected processors classes may want to use a SignalProcessorSupport instance.

Specified by:

process in interface SignalProcessor<I extends AudioBuffer,AudioMatrix>

Parameters:

input - data to process

Throws:

IOException - if a processing error occurs

See Also:

SignalProcessor.getConnectedProcessors()

flush

public void flush()
           throws IOException

Description copied from interface: SignalProcessor

Asks to complete all pending operations. This method may be called multiple times without any adverse effects. It's the implementation's responsibility to call its kids' SignalProcessor.flush() method.

Specified by:

flush in interface SignalProcessor<I extends AudioBuffer,AudioMatrix>

Throws:

IOException - if a processing error occurs

createMatrix

protected MutableMatrix createMatrix(int previousLength,
                                     int length,
                                     int bandwidth)

By default this creates a symmetric, float-backed, zero-padded Matrix. If a positive bandwidth (see getBandwidth()) is set, the matrix may be banded. You may override this method to use a different matrix implementation, e.g. one that is backed by an UnsignedByteBackingBuffer to preserve memory.

Parameters:

previousLength - the length of the previously used matrix, in essence information about the part that does not need to be covered by the new matrix (may be ignored).

length - length

bandwidth - bandwidth

Returns:

mutable matrix

getOutput

public AudioMatrix getOutput()
                      throws IOException

Description copied from interface: SignalProcessor

First calls SignalProcessor.flush(), then returns the pending output, should there be any. Note that this call may only succeed once to preserve memory.

Specified by:

getOutput in interface SignalProcessor<I extends AudioBuffer,AudioMatrix>

Returns:

output, if available. If not, null is returned

Throws:

IOException - if a processing error occurs

getId

public Object getId()

Description copied from interface: SignalProcessor

Arbitrary object to identify a processor. This is useful for associating with results provided by SignalProcessor.getOutput().

Specified by:

getId in interface SignalProcessor<I extends AudioBuffer,AudioMatrix>

Returns:

arbitrary non-null object. If this method returns null, potential results will not be associated with an identifier and potentially dropped

See Also:

SignalPump.pump()

disconnectFrom

public <O2> SignalProcessor<AudioMatrix,O2> disconnectFrom(SignalProcessor<AudioMatrix,O2> signalProcessor)

Description copied from interface: SignalProcessor

Disconnects a child processor.

Specified by:

disconnectFrom in interface SignalProcessor<I extends AudioBuffer,AudioMatrix>

Type Parameters:

O2 - output type of the processor we want to disconnect from

Parameters:

signalProcessor - processor

Returns:

the processor, if it was indeed removed

See Also:

SignalProcessor.connectTo(SignalProcessor), SignalProcessor.getConnectedProcessors()

getConnectedProcessors

public SignalProcessor<AudioMatrix,?>[] getConnectedProcessors()

Description copied from interface: SignalProcessor

Lists all connected processors.

Specified by:

getConnectedProcessors in interface SignalProcessor<I extends AudioBuffer,AudioMatrix>

Returns:

array of registered processors, never null

See Also:

SignalProcessor.disconnectFrom(SignalProcessor), SignalProcessor.connectTo(SignalProcessor)

connectTo

public <O2> SignalProcessor<AudioMatrix,O2> connectTo(SignalProcessor<AudioMatrix,O2> signalProcessor)

Description copied from interface: SignalProcessor

Connects this processor to another processor to forward processed data to. This method returns its parameter and therefore encourages method chaining to build processing chains/pipelines.

Specified by:

connectTo in interface SignalProcessor<I extends AudioBuffer,AudioMatrix>

Type Parameters:

O2 - output type of the processor we want to connect to

Parameters:

signalProcessor - processor

Returns:

the just added processor

See Also:

SignalProcessor.disconnectFrom(SignalProcessor), SignalProcessor.getConnectedProcessors(), SignalPipeline