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