Attribute Controls¶

Attribute Controls are special tokens that allow to train a model in order to control music generation during inference. They work either at the track-level or bar-level and specifies specific attributes they featured. By being placed at the beginning of each bar or track in the token sequence, a causal model will condition the prediction of the next tokens based on them. At inference, these attribute control tokens can strategically be placed at the beginning of nex tracks or bars in order to condition the generated results.

Attribute controls are not compatible with “multi-vocabulary” (e.g. Octuple) or multitrack “one token stream” tokenizers.

To train tokenizers and models with attribute control tokens, you can use the miditok.TokTrainingIterator and miditok.pytorch_data.DatasetMIDI respectively.

Attribute controls module.

class miditok.attribute_controls.AttributeControl(tokens: Sequence[str])¶

Attribute Control class, defining the possible values and their computation.

Note: track-level attribute controls need to return miditok.Events with time attributes set to -1, as they need to be at the very first positions in the token sequence after sorting the list of events. Their times will be set to 0 after sorting in MusicTokenizer._score_to_tokens.

Parameters:: tokens – tokens of the attribute control as a list of tuples specifying their types and values.

abstractmethod compute(track: TrackTick, time_division: int, ticks_bars: Sequence[int], ticks_beats: Sequence[int], bars_idx: Sequence[int]) → list[Event]¶

Compute the attribute control from a symusic.Track.

Parameters:

track – symusic.Track object to compute the attribute from.
time_division – time division in ticks per quarter note of the file.
ticks_bars – ticks indicating the beginning of each bar.
ticks_beats – ticks indicating the beginning of each beat.
bars_idx – sorted indexes of the bars to compute the bar-level control attributes from. If None is provided, the attribute controls are computed on all the bars. (default: None)

Returns:

attribute control values.

class miditok.attribute_controls.BarAttributeControl(tokens: Sequence[str])¶

Base class for bar-level attribute controls.

compute(track: TrackTick, time_division: int, ticks_bars: Sequence[int], ticks_beats: Sequence[int], bars_idx: Sequence[int]) → list[Event]¶

Compute the attribute control from a symusic.Track.

Parameters:

track – symusic.Track object to compute the attribute from.
time_division – time division in ticks per quarter note of the file.
ticks_bars – ticks indicating the beginning of each bar.
ticks_beats – ticks indicating the beginning of each beat.
bars_idx – sorted indexes of the bars to compute the bar-level control attributes from. If None is provided, the attribute controls are computed on all the bars. (default: None)

Returns:

attribute control values.

class miditok.attribute_controls.BarNoteDensity(density_max: int)¶

Bar-level note density attribute control.

It specifies the number of notes per bar. If a bar contains more that the maximum density (density_max), a density_max+ token will be returned.

Parameters:: density_max – maximum note density per bar to consider.

class miditok.attribute_controls.BarNoteDuration¶

Note duration attribute control.

This attribute controls specifies the note durations (whole, half, quarter, eight, sixteenth and thirty-second) present in a bar.

class miditok.attribute_controls.BarOnsetPolyphony(polyphony_min: int, polyphony_max: int)¶

Onset polyphony attribute control at the bar level.

It specifies the minimum and maximum number of notes played simultaneously at a given time onset. It can be enabled with the ac_polyphony_bar argument of miditok.TokenizerConfig.

Parameters:

polyphony_min – minimum number of simultaneous notes to consider.
polyphony_max – maximum number of simultaneous notes to consider.

class miditok.attribute_controls.BarPitchClass¶

Bar-level pitch classes attribute control.

This attribute control specifies which pitch classes are present within a bar.

class miditok.attribute_controls.TrackNoteDensity(density_min: int, density_max: int)¶

Track-level note density attribute control.

It specifies the minimum and maximum number of notes per bar within a track. If a bar contains more that the maximum density (density_max), a density_max+ token will be returned.

Parameters:

density_min – minimum note density per bar to consider.
density_max – maximum note density per bar to consider.

compute(track: TrackTick, time_division: int, ticks_bars: Sequence[int], ticks_beats: Sequence[int], bars_idx: Sequence[int]) → list[Event]¶

Compute the attribute control from a symusic.Track.

Parameters:

track – symusic.Track object to compute the attribute from.
time_division – time division in ticks per quarter note of the file.
ticks_bars – ticks indicating the beginning of each bar.
ticks_beats – ticks indicating the beginning of each beat.
bars_idx – sorted indexes of the bars to compute the bar-level control attributes from. If None is provided, the attribute controls are computed on all the bars. (default: None)

Returns:

attribute control values.

class miditok.attribute_controls.TrackNoteDuration¶

Note duration attribute control.

This attribute controls specifies the note durations (whole, half, quarter, eight, sixteenth and thirty-second) present in a track.

compute(track: TrackTick, time_division: int, ticks_bars: Sequence[int], ticks_beats: Sequence[int], bars_idx: Sequence[int]) → list[Event]¶

Compute the attribute control from a symusic.Track.

Parameters:

track – symusic.Track object to compute the attribute from.
time_division – time division in ticks per quarter note of the file.
ticks_bars – ticks indicating the beginning of each bar.
ticks_beats – ticks indicating the beginning of each beat.
bars_idx – sorted indexes of the bars to compute the bar-level control attributes from. If None is provided, the attribute controls are computed on all the bars. (default: None)

Returns:

attribute control values.

class miditok.attribute_controls.TrackOnsetPolyphony(polyphony_min: int, polyphony_max: int)¶

Onset polyphony attribute control at the track level.

It specifies the minimum and maximum number of notes played simultaneously at a given time onset. It can be enabled with the ac_polyphony_track argument of miditok.TokenizerConfig.

Parameters:

polyphony_min – minimum number of simultaneous notes to consider.
polyphony_max – maximum number of simultaneous notes to consider.

compute(track: TrackTick, time_division: int, ticks_bars: Sequence[int], ticks_beats: Sequence[int], bars_idx: Sequence[int]) → list[Event]¶

Compute the attribute control from a symusic.Track.

Parameters:

track – symusic.Track object to compute the attribute from.
time_division – time division in ticks per quarter note of the file.
ticks_bars – ticks indicating the beginning of each bar.
ticks_beats – ticks indicating the beginning of each beat.
bars_idx – sorted indexes of the bars to compute the bar-level control attributes from. If None is provided, the attribute controls are computed on all the bars. (default: None)

Returns:

attribute control values.

class miditok.attribute_controls.TrackRepetition(num_bins: int, num_consecutive_bars: int, pitch_range: tuple[int, int])¶

Track-level repetition level between consecutive bars.

This attribute corresponds to the average similarity between consecutive bars, with the similarity between too bars computed as the ratio of “logical and” positions between their binary pianoroll matrices. For each bar, the module will compute its similarity with the next num_consecutive_bars bars, and return the average of all the similarities.

Parameters:

num_bins – number of levels of repetitions.
num_consecutive_bars – number of successive bars to compare the similarity with each current bar.
pitch_range – pitch range of the tokenizer.

compute(track: TrackTick, time_division: int, ticks_bars: Sequence[int], ticks_beats: Sequence[int], bars_idx: Sequence[int]) → list[Event]¶

Compute the attribute control from a symusic.Track.

Parameters:

track – symusic.Track object to compute the attribute from.
time_division – time division in ticks per quarter note of the file.
ticks_bars – ticks indicating the beginning of each bar.
ticks_beats – ticks indicating the beginning of each beat.
bars_idx – sorted indexes of the bars to compute the bar-level control attributes from. If None is provided, the attribute controls are computed on all the bars. (default: None)

Returns:

attribute control values.

miditok.attribute_controls.create_random_ac_indexes(score: Score, attribute_controls: Sequence[AttributeControl], tracks_idx_ratio: float | tuple[float, float] | None = None, bars_idx_ratio: float | tuple[float, float] | None = None) → Mapping[int, Mapping[int, bool | Sequence[int]]]¶

Randomly create tracks and bars indexes for attribute controls computation.

Parameters:

score – symusic.Score to set the indexes for.
attribute_controls – attribute controls that will be computed. They need to be provided to get their indexes.
tracks_idx_ratio – ratio or range of ratio (between 0 and 1) of track-level attribute controls per track. (default None)
bars_idx_ratio – ratio or range of ratio (between 0 and 1) of track-level attribute controls per track. (default None)

Returns:

indexes of attribute controls to be used when tokenizing a music file.

Using custom attribute controls¶

You can easily add your own attribute controls to an existing tokenizer using the miditok.MusicTokenizer.add_attribute_control() method. You attribute control must subclass either the miditok.attribute_controls.AttributeControl (track-level) or the miditok.attribute_controls.BarAttributeControl classes and implement the attribute computation method.