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(op)[source]

Add an operation to this pump.

Parameters:

op : BaseTaskTransformer, FeatureExtractor

The operation to add

Raises:

ParameterError

if op is not of a correct type

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)[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.

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.

Task transformations

BaseTaskTransformer(name, namespace, sr, ...) Base class for task transformer objects
BeatTransformer([name, sr, hop_length]) Task transformation for beat tracking
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.

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
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.

__weakref__

list of weak references to the object (if defined)

data_duration(data)[source]

Compute the valid data duration of a dict

Parameters:

data : dict

As produced by pumpp.transform

Returns:

length : int

The minimum temporal extent of a dynamic observation in data

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
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