Core functionality

Pump(*ops) Top-level pump object.
class pumpp.core.Pump(*ops)[source]

Top-level pump object.

This class is used to collect feature and task transformers

Examples

Create a CQT and chord transformer

>>> p_cqt = pumpp.feature.CQT('cqt', sr=44100, hop_length=1024)
>>> p_chord = pumpp.task.ChordTagTransformer(sr=44100, hop_length=1024)
>>> pump = pumpp.Pump(p_cqt, p_chord)
>>> data = pump.transform(audio_f='/my/audio/file.mp3',
...                       jam='/my/jams/annotation.jams')

Or use the call interface:

>>> data = pump(audio_f='/my/audio/file.mp3',
...             jam='/my/jams/annotation.jams')

Or apply to audio in memory, and without existing annotations:

>>> y, sr = librosa.load('/my/audio/file.mp3')
>>> data = pump(y=y, sr=sr)

Access all the fields produced by this pump:

>>> pump.fields
{'chord/chord': Tensor(shape=(None, 170), dtype=<class 'bool'>),
 'cqt/mag': Tensor(shape=(None, 288), dtype=<class 'numpy.float32'>),
 'cqt/phase': Tensor(shape=(None, 288), dtype=<class 'numpy.float32'>)}

Access a constituent operator by name:

>>> pump['chord'].fields
{'chord/chord': Tensor(shape=(None, 170), dtype=<class 'bool'>)}
Attributes:
ops : list of (BaseTaskTransformer, FeatureExtractor)

The operations to apply

add(operator)[source]

Add an operation to this pump.

Parameters:
operator : BaseTaskTransformer, FeatureExtractor

The operation to add

Raises:
ParameterError

if op is not of a correct type

fields

A dictionary of fields constructed by this pump

layers()[source]

Construct Keras input layers for all feature transformers in the pump.

Returns:
layers : {field: keras.layers.Input}

A dictionary of keras input layers, keyed by the corresponding fields.

sampler(n_samples, duration, random_state=None)[source]

Construct a sampler object for this pump’s operators.

Parameters:
n_samples : None or int > 0

The number of samples to generate

duration : int > 0

The duration (in frames) of each sample patch

random_state : None, int, or np.random.RandomState

If int, random_state is the seed used by the random number generator;

If RandomState instance, random_state is the random number generator;

If None, the random number generator is the RandomState instance used by np.random.

Returns:
sampler : pumpp.Sampler

The sampler object

transform(audio_f=None, jam=None, y=None, sr=None, crop=False)[source]

Apply the transformations to an audio file, and optionally JAMS object.

Parameters:
audio_f : str

Path to audio file

jam : optional, jams.JAMS, str or file-like

Optional JAMS object/path to JAMS file/open file descriptor.

If provided, this will provide data for task transformers.

y : np.ndarray
sr : number > 0

If provided, operate directly on an existing audio buffer y at sampling rate sr rather than load from audio_f.

crop : bool

If True, then data are cropped to a common time index across all fields. Otherwise, data may have different time extents.

Returns:
data : dict

Data dictionary containing the transformed audio (and annotations)

Raises:
ParameterError

At least one of audio_f or (y, sr) must be provided.

Feature extractors

FeatureExtractor(name, sr, hop_length[, conv]) The base feature extractor class.
CQT(name, sr, hop_length[, n_octaves, …]) Constant-Q transform
CQTMag(*args, **kwargs) Magnitude CQT
CQTPhaseDiff(*args, **kwargs) CQT with unwrapped phase differentials
HCQT(name, sr, hop_length[, n_octaves, …]) Harmonic Constant-Q transform
HCQTMag(*args, **kwargs) Magnitude HCQT
HCQTPhaseDiff(*args, **kwargs) HCQT with unwrapped phase differentials
STFT(name, sr, hop_length, n_fft[, log, conv]) Short-time Fourier Transform (STFT) with both magnitude and phase.
STFTMag(*args, **kwargs) STFT with only magnitude.
STFTPhaseDiff(*args, **kwargs) STFT with phase differentials
Mel(name, sr, hop_length, n_fft, n_mels[, …]) Mel spectra feature extraction
Tempogram(name, sr, hop_length, win_length) Tempogram: the short-time autocorrelation of the accent signal
TempoScale(name, sr, hop_length, win_length) Tempogram scale transform.
TimePosition(name, sr, hop_length[, conv]) TimePosition: encode frame position as features.

Task transformations

BaseTaskTransformer(name, namespace, sr, …) Base class for task transformer objects
BeatTransformer([name, sr, hop_length, …]) Task transformation for beat tracking
BeatPositionTransformer(name[, …]) Encode beat- and downbeat-annotations as labeled intervals.
ChordTransformer([name, sr, hop_length, sparse]) Chord annotation transformers.
SimpleChordTransformer([name, sr, hop_length]) Simplified chord transformations.
ChordTagTransformer([name, vocab, sr, …]) Chord transformer that uses a tag-space encoding for chord labels.
VectorTransformer(name, namespace, dimension) Vector regression transformer.
DynamicLabelTransformer(name, namespace[, …]) Time-series label transformer.
StaticLabelTransformer(name, namespace[, labels]) Static label transformer.
StructureTransformer([name, sr, hop_length]) Structure agreement transformer.

Data subsampling

Sampler(n_samples, duration, *ops, **kwargs) Generate samples uniformly at random from a pumpp data dict.
SequentialSampler(duration, *ops, **kwargs) Sample patches in sequential (temporal) order
VariableLengthSampler(n_samples, …) Sample random patches like a Sampler, but allow for output patches to be less than the target duration when the data is too short.
class pumpp.sampler.Sampler(n_samples, duration, *ops, **kwargs)[source]

Generate samples uniformly at random from a pumpp data dict.

Examples

>>> # Set up the parameters
>>> sr, n_fft, hop_length = 22050, 512, 2048
>>> # Instantiate some transformers
>>> p_stft = pumpp.feature.STFTMag('stft', sr=sr, n_fft=n_fft,
...                                hop_length=hop_length)
>>> p_beat = pumpp.task.BeatTransformer('beat', sr=sr,
...                                     hop_length=hop_length)
>>> # Apply the transformers to the data
>>> data = pumpp.transform('test.ogg', 'test.jams', p_stft, p_beat)
>>> # We'll sample 10 patches of duration = 32 frames
>>> stream = pumpp.Sampler(10, 32, p_stft, p_beat)
>>> # Apply the streamer to the data dict
>>> for example in stream(data):
...     process(data)
Attributes:
n_samples : int or None

the number of samples to generate. If None, generate indefinitely.

duration : int > 0

the duration (in frames) of each sample

random_state : None, int, or np.random.RandomState

If int, random_state is the seed used by the random number generator;

If RandomState instance, random_state is the random number generator;

If None, the random number generator is the RandomState instance used by np.random.

ops : array of pumpp.feature.FeatureExtractor or pumpp.task.BaseTaskTransformer

The operators to include when sampling data.

__call__(data)[source]

Generate samples from a data dict.

Parameters:
data : dict

As produced by pumpp.transform

Yields:
data_sample : dict

A sequence of patch samples from data, as parameterized by the sampler object.

__init__(n_samples, duration, *ops, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

indices(data)[source]

Generate patch indices

Parameters:
data : dict of np.ndarray

As produced by pumpp.transform

Yields:
start : int >= 0

The start index of a sample patch

sample(data, interval)[source]

Sample a patch from the data object

Parameters:
data : dict

A data dict as produced by pumpp.Pump.transform

interval : slice

The time interval to sample

Returns:
data_slice : dict

data restricted to interval.

class pumpp.sampler.SequentialSampler(duration, *ops, **kwargs)[source]

Sample patches in sequential (temporal) order

See also

Sampler

Attributes:
duration : int > 0

the duration (in frames) of each sample

stride : int > 0

The number of frames to advance between samples. By default, matches duration so there is no overlap.

ops : array of pumpp.feature.FeatureExtractor or pumpp.task.BaseTaskTransformer

The operators to include when sampling data.

random_state : None, int, or np.random.RandomState

If int, random_state is the seed used by the random number generator;

If RandomState instance, random_state is the random number generator;

If None, the random number generator is the RandomState instance

__init__(duration, *ops, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

indices(data)[source]

Generate patch start indices

Parameters:
data : dict of np.ndarray

As produced by pumpp.transform

Yields:
start : int >= 0

The start index of a sample patch

class pumpp.sampler.VariableLengthSampler(n_samples, min_duration, max_duration, *ops, **kwargs)[source]

Sample random patches like a Sampler, but allow for output patches to be less than the target duration when the data is too short.

See also

Sampler

Attributes:
n_samples : int or None

the number of samples to generate. If None, generate indefinitely.

min_duration : int > 0

The minimum duration (in frames) of each sample

max_duration : int > 0

the maximum duration (in frames) of each sample

random_state : None, int, or np.random.RandomState

If int, random_state is the seed used by the random number generator;

If RandomState instance, random_state is the random number generator;

If None, the random number generator is the RandomState instance used by np.random.

ops : array of pumpp.feature.FeatureExtractor or pumpp.task.BaseTaskTransformer

The operators to include when sampling data.

__call__(data)[source]

Generate samples from a data dict.

Parameters:
data : dict

As produced by pumpp.transform

Yields:
data_sample : dict

A sequence of patch samples from data, as parameterized by the sampler object.

__init__(n_samples, min_duration, max_duration, *ops, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

indices(data)[source]

Generate patch indices

Parameters:
data : dict of np.ndarray

As produced by pumpp.transform

Yields:
start : int >= 0

The start index of a sample patch