pytakt.effector module

This module defines classes related to effectors.

class Effector

Bases: ABC

The Effector class is an abstract class on which every effector is based.

An effector is a callable object that performs score transformation. When it is called with a score as an argument, as in the example below, it returns the transformed score.

>>> eff = Transpose('M2')
>>> eff(note(C4))
EventList(duration=480, events=[
    NoteEvent(t=0, n=D4, L=480, v=80, nv=None, tk=1, ch=1)])

Score transformation by effectors has the following properties.

  • The original scores remain unmodified and are not destroyed (although in the case of an EventStream, elements may be consumed during transformation).

  • As a basic rule, events that do not require modification are output without copying. Such events will be shared between the original score and the transformed score.

  • Events in each event list after transformation may not be sorted in chronological order.

Unless otherwise noted, effectors are applicable to EventStream’s (including infinite-length scores). Also, they are applicable to scores containing separated note events (NoteOnEvent and NoteOffEvent) unless otherwise noted.

The constructor of each effector class is also available as a method of the Score class, in which the creation of the effector instance and the score transformation are done in succession (e.g. note(C4).Transpose('M2')).


class EventEffector

Bases: Effector

The EventEffector class is an abstract class of effectors that performs transformations independently for each event.

Effectors of this class can apply transformations not only to scores but also to a single event, as in the example below.

>>> eff = Transpose('M2')
>>> eff(NoteOnEvent(0, C4))
NoteOnEvent(t=0, n=D4, v=80, tk=1, ch=1)

class CompositeEffector(first, second)

Bases: Effector

A class representing an effector that is a composite of two effectors. When this effector is applied, the first effector is applied first, then the second.

Constructor

Parameters:

  • first (Effector) – The object of the first effector.

  • second (Effector) – The object of the second effector.


class Transpose(value, scale=None, transpose_keysig=True)

Bases: EventEffector

Applies a transposition (an operation that raises or lowers the pitch by a certain interval). Applies to all events with the ‘n’ attribute.

If scale is not specified, it does chromatic transposition. The value can be either an Interval object or an integer representing semitones (Interval objects are better for correctly handling enharnomics).

If scale is specified, it performs transposition on the scale (diatonic transposition for a diatonic scale). The value is an integer representing shift amount on the scale. If the original pitch is n it is converted to scale.pitch(scale.tonenum(n) + value).

Constructor

Parameters:

  • value (Interval, str, or int) – Amount of transposition. If this is a string, it is the same as Interval(value).

  • scale (Scale, optional) – Specifies the scale.

  • transpose_keysig – If this argument is Ture (default) and no scale is specified, KeySignatureEvent is also transposed. Otherwise, KeySignatureEvent is output as it is.

Examples

  • mml("CDE").Transpose('M3') generates a score equivalent to mml("EF#G#"). Transpose(E4-C4) has the same meaning.

  • mml("CDE").Transpose(DEG(3), scale=Scale(C4)) generates a score equivalent to mml("EFG").


class Invert(center, scale=None)

Bases: EventEffector

Converts the score to the inverted form. Specifically, given a central pitch center, it converts the pitch of each event having the ‘n’ attribute to the pitch that is shifted in the opposite direction from the center by the interval between the original pitch and center.

Constructor

Parameters:

  • center (Pitch or int) – The pitch at the center of inversion.

  • scale (Scale, optional) – Specifies a scale. If omitted, the effector does chromatic inversion; if specified, it performs inversion on the specified scale (diatonic inversion for a diatonic scale).

Examples

  • mml("EFG*").Invert(E4) generates a score equivalent to mml("ED#C#*").

  • mml("EFG*").Invert(E4, scale=Scale(C4)) generates a score equivalent to mml("EDC*").


class ApplyScale(scale, round_mode='nearestup')

Bases: EventEffector

Converts the pitch of each event having the ‘n’ attribute to a pitch that is on the specified scale and close to the original pitch using Scale.get_near_scale_tone().

Constructor

Parameters:

  • scale (Scale) – scale

  • round_mode (str or function) – Rounding mode passed to takt_roundx().

Examples

  • mml("C C# Db D E").ApplyScale(Scale(C4, 'minor')) generates a score equivalent to mml("C C C D D Eb"). The difference in the results between ‘C#’ and ‘Db’ is due to the effect of enharmonic_delta in Scale.tonenum().


class ConvertScale(src_scale, dst_scale)

Bases: EventEffector

For each event with the ‘n’ attribute, scale conversion is performed. If the original pitch is n, the transformed pitch will be dst_scale.pitch(src_scale.tonenum(n)).

Constructor

Parameters:

  • src_scale (Scale) – The source scale.

  • dst_scale (Scale) – The target scale. The number of its scale constituent tones must be the same as that of src_scale.

Examples

  • mml("C C# D E").ConvertScale(Scale(C4, 'major'), Scale(C4, 'minor')) generates a score equivalent to mml("C C# D Eb").


class ScaleVelocity(value)

Bases: EventEffector

Multiplies the value of velocity (‘v’ attribute) by value.

Constructor

Parameters:

value (float, int, or list) – The velocity multiplier. If it is a float or int, the value is used as a fixed multiplier. If it is a list, the value is passed to the constructor of Interpolator and interpolated values are used as the multipliers.

Examples

  • note(C4, v=80).ScaleVelocity(1.2) generates a score equivalent to note(C4, v=96).

  • mml("v=80 CDEF").ScaleVelocity([1.0, (L1, 0.5)]) produces a score equivalent to mml("C(v=80) D(v=70) E(v=60) F(v=50)").


class Repeat(rep=inf)

Bases: Effector

Converts the input score to a score that repeats the input score rep times.

Constructor

Parameters:

rep (int, optional) – Number of repetitions (default is infinite)


class TimeStretch(stretch)

Bases: Effector

Stretch time by the factor stretch.

Constructor

Parameters:

stretch (float or int) – The stretch factor. Must be a positive value. Less than one means time shrinking.

Examples

mml("CDE*").TimeStretch(2) generates a score equivalent to mml("C*D*E**").


class Retrograde

Bases: Effector

Converts the input score to the time-reversed score.

Time conversion is not performed for events other than NoteEvent.

It cannot be applied to an EventStream.

Examples

  • mml("CDE*").Retrograde() generates a score that is equivalent to mml("E*DC").


class Quantize(tstep, strength=1.0, window=1.0, keepdur=False, saveorg=False)

Bases: Effector

Applies quantization to the time of each event as well as the duration of the score.

Constructor

Parameters:

  • tstep (ticks) – Step time for quantization.

  • strength (float, optional) – Strength of quantization (0-1). If it is 1.0 (default), then each event time is modified to be an integer multiple of tstep. Otherwise, the actual modification amount is a multiple of this value and the modification amount when the value is 1.0.

  • window (float, optional) – The width of the time windows to be quantized, as a ratio to to tstep (0 to 1). Only events within each window centered at the time that is an integer multiple of tstep will be quantized. For example, if window=0.5, the windows are positioned from tstep * (N - 0.25) to tstep * (N + 0.25) (N=0,1,2,…).

  • keepdur (bool, optional) – If True, keeps the value of the L attribute of NoteEvent unchanged and keeps the original note value (has no effect on NoteOffEvent). If False (default), the value of the L attribute is adjusted so that the end time of the note is also quantized.

  • saveorg (bool, optional) – If True, sets the ‘dt’ and ‘du’ attributes so that the original (pre-quantized) time remains as the played time. Values originally stored in the ‘dt’ and ‘du’ attributes will be lost.

Examples

  • note(C4, 450).Quantize(120) generates a score equivalent to note(C4, 480).

  • note(C4, 450).Quantize(120, strength=0.5) generates a score equivalent to note(C4, 465).


class TimeDeform(points, periodic=False, perf_only=False)

Bases: Effector

Converts the time of each event as well as the duration of the score according to a time conversion function described by Interpolator.

Constructor

Parameters:

  • points (list of Points, etc.) – Arguments passed to Interpolator. The time conversion function described the interpolator must be a monotonically non-decreasing function.

  • periodic (bool, optional) – If True, the same pattern of time conversion are repeated with its period of repetition being the time of the last control point among points.

  • perf_only (bool, optional) – If True, the values of the ‘dt’ and ‘du’ attributes are adjusted so that notated time (t and L attributes) is kept unchanged and only played time is converted. If False, notated time is also converted.

Examples

  • TimeDeform([(0, 0), (480, 482), (1920, 1950)]) converts the times 0, 240, 480, 1920, 2000 in the original score to 0, 241, 482, 1950, 1950 respectively.

  • Applying TimeDeform([0, (240, 360), (480, 480)], periodic=True) will convert the times 0, 240, 480, 720, 960 in the original score to 0, 360, 480, 840, 960 respectively. This kind of transformation can be more briefly expressed by the Swing effector below.


class Swing(period, rate=0.6666666666666666, perf_only=True)

Bases: TimeDeform

For each of time spans repeated with the period period, time is transformed so that the time at the center of the span is mapped to the time when period * rate is elapsed from the start of the span.

Constructor

Parameters:

  • period (ticks) – Period

  • rate (float) – Adjustment value of the swing effect (0 to 1, 0.5 means no effect)

  • perf_only (bool, optional) – If True, the values of the ‘dt’ and ‘du’ attributes are adjusted so that notated time (t and L attributes) is kept unchanged and only played time is converted. If False, notated time is also converted.

Examples

mml("CDEF").Swing(L2, 0.75, False) generates a score equivalent to mml("C.D/E.F/").


class ToMilliseconds

Bases: TimeDeform

Converts all times in the score to milliseconds and removes tempo events.

Examples

>>> mml("$tempo(120) c $tempo(240) d").ToMilliseconds()
EventList(duration=750.0, events=[
    NoteEvent(t=0.0, n=C4, L=500.0, v=80, nv=None, tk=1, ch=1),
    NoteEvent(t=500.0, n=D4, L=250.0, v=80, nv=None, tk=1, ch=1)]

class Randomize(time=10, veloc=10, adjust_ctrl=True)

Bases: Effector

For each note, this effector adds a random value to its played time (more specifically to the ‘dt’ attribute value) and velocity. By default, it uses random numbers with the Gaussian distribution with mean 0 and standard deviation specified by the arguments.

Constructor

Parameters:

  • time (int, float or function, optional) – If int or float, specifies the standard deviation (in ticks) of the random values to be added to time. If the absolute value of the generated random value exceeds 3 times the standard deviation, it will be adjusted to within 3 times. If this argument is a function, the random values are generated by that function.

  • veloc (int, float or function, optional) – If int or float, specifies the standard deviation of the random values to be added to velocity. If this argument is a function, the random values are generated by that function.

  • adjust_ctrl (bool, optional) – If True, the played time of CtrlEvent is adjusted to the same value as the played time of NoteEvent or NoteOnEvent, if the random value added to the played time of the note event is negative, and if the CtrlEvent has the same track, same channel, and same pitch (applicable only for a KeyPressureEvent) as the note event and lies in the interval between the modified played time and the original played time of the note event.


class Clip(start, end=inf, initializer=True, split_notes=True)

Bases: Effector

Cut out only those parts of the score whose time is greater than or equal to start and less than end. The structure of the score is preserved.

Constructor

Parameters:

  • start (ticks or str) – Start time. It can be a number representing ticks from the beginning of the score, or a string recognized by TimeSignatureMap.mbt2ticks().

  • end (ticks or str, optional) – End time. It can be a number representing ticks from the beginning of the score, or a string recognized by TimeSignatureMap.mbt2ticks(). When only the measure number is given in the string, it means up to the end of the measure.

  • initializer (bool, optional) – If True, all CtrlEvent’s, TempoEvent’s, KeySignatureEvent’s, and TimeSignatureEvent’s that are active (see active_events_at()) at the time of start are output at the beginning.

  • split_notes (bool, optional) – If True, notes that span start and/or end boundaries are split and the result will contain the fragments of the notes. If False, no splitting is done and only notes whose onset time (the t attribute value) is within the range of clipping are stored in the result. This feature is valid only for NoteEvent’s and is not valid for NoteOnEvent’s or NoteOffEvent’s.

Examples

Clip(960)

Clips scores after 960 ticks.

Clip('3:2', '7')

Clips the score from Measure 3, Beat 2 to the end of Measure 7. Note that the beat number starts from 0.


class Arpeggio(delay=60)

Bases: Effector

For each chord in the score (a group of notes started simultaneously), this effector adds a value to the ‘dt’ attribute for each note in the chord, according to its pitch order so that an arpeggio is played. Also, the value of the ‘du’ attribute is adjusted so that the note-off time remains the same. By default, the arpeggio is played from the lowest to highest note.

Constructor

Parameters:

delay (ticks) – Specifies the amount of time delay between the notes in the chord. Negative numbers result in arpeggios from high to low.


class Filter(*conds, negate=False, globals=None, locals=None)

Bases: Effector

Converts the input score to a score containing only events that meet (or do not meet) specified condition. The structure of the score is preserved, and thus empty event lists may remain in the output. Each event is not copied.

Constructor

Parameters:

  • conds (class, str, or function, each) –

    Each argument represents a primary condition, and the logical OR of all of them is the final condition. Each argument is one of the followings.

    • An event class – True if the event belongs to that class or its subclass.

    • A string that can be evaluated by eval() – The condition is specified by a string containing a Python expression that gives a bool value. In the string, ‘ev’ represents the event itself, and ‘t’, ‘tk’, ‘dt’, ‘n’, ‘v’, ‘nv’, ‘ch’, ‘L’, ‘du’, ‘ctrlnum’, ‘mtype’, ‘xtype’, and ‘value’ are constants representing attribute values of the event. For attributes that the event does not have, the value of these constants will be None (except for ‘du’ for NoteEvent, which will have the same value as ‘L’). If a TypeError exception is raised while evaluating the expression, the expression value is assumed to be False and processing continues.

    • A function that returns a bool value – Called with the event as an argument, and the return value becomes the value of the condition.

  • negate (bool, optional) – If False (default), a score consisting of events that satisfy the condition is output; if True, a score consisting of events that do not satisfy the condition (i.e., events not output in the default case) is output.

  • globals (dict, optional) – Specifies a dictionary of the global symbol table used when conds is a string. By default, this is the value of globals() at the time when the constructor is called.

  • locals (dict, optional) – Specifies a dictionary of the local symbol table used when conds is a string, By default, this is the value of locals() at the time when the constructor is called.

Examples

Filter(NoteEventClass, TempoEvent)

Extracts events belonging to NoteEventClass (i.e., NoteEvent, NoteOnEvent, and NoteOffEvent) and tempo events.

Filter('ctrlnum == 7')

Extracts No. 7 control change events.

Filter(lambda ev: hasattr(ev, 'ctrlnum') and ev.ctrlnum == 7)

The previous example can be rewritten using a function as this example.

Filter('ctrlnum == C_PROG', negate=True)

Removes program change events. Filter('ctrlnum ! = C_PROG') or Reject('ctrlnum == C_PROG') has the same meaning.

Filter('n >= C4')

Extracts NoteEventClass and KeyPressureEvent events whose pitch is C4 or higher (events without the ‘n’ attribute will result in TypeError and will not be output as a result).

Filter('n < C4', negate=True)

Removes NoteEventClass and KeyPressureEvent events whose pitch is lower than C4 (i.e., extracts those events with a pitch of C4 or higher and other events without the ‘n’ attribute). Can also be written as Reject('n < C4'). Note that, in cases where a TypeError exception occurs as in this example, Filter('...') and Reject('not ...') are not equivalent.

Filter('n >= C5 and L == L4')

Extracts NoteEvent’s with a pitch equal to or higher than C5 and a note value equal to a quarter note.

Filter('ch in (1,2,4)', MetaEvent)

Extract events whose MIDI channel is 1, 2, or 4, and all MetaEvent’s.

Filter('isinstance(ev, SysExEvent) and value[0] ! = 0xf0')

Extracts events for system-exclusive messages whose first byte is not 0xf0.


class Reject(*conds, globals=None, locals=None)

Bases: Filter

Converts the input score to a score containing only events that do not satisfy the condition. Reject(…) is equivalent to Filter(… , negate=True).


class Cond(cond, effector, globals=None, locals=None)

Bases: Effector

Applies the specified effector only to events that satisfy the condition. Events that do not satisfy the condition are output as is.

If there are simultaneous events with and without effectors applied in the output, the events with effectors applied will always be placed later.

Constructor

Parameters:

  • cond (class, str, or function) – Specifies the condition in the same format as the conds argument of Filter (but only one primary condition is allowed).

  • effector (Effector) – The effector object to apply.

  • globals (dict, optional) – Same meaning as the globals argument of Filter.

  • locals (dict, optional) – Same meaning as the locals argument of Filter.

Examples

Cond('n >= C5', ScaleVelocity(1.2))

For NoteEvent’s and NoteOnEvent’s with a pitch of C5 or higher, the velocity is scaled by 1.2.


class Modify(operation, globals=None, locals=None)

Bases: EventEffector

For each event, the effector executes the sequence of statements specified by operation and outputs an updated event according to it. This provides a handy way for updating events as an alternative to Score.mapev().

Events are always copied before being updated (use Score.mapev() if you want to avoid copying).

Constructor

Parameters:

  • operation (str) – Specifies a string that is evaluated by exec(). In the string, ‘ev’ represents the event itself. Also, ‘t’, ‘tk’, ‘dt’, ‘n’, ‘v’, ‘nv’, ‘ch’, ‘L’, ‘du’, ‘ctrlnum’, ‘mtype’, ‘xtype’, and ‘value’ can be used as variables representing the attribute values of the event, and by assigning values to them the attribute values of the event can be changed. It is also possible to add or change attributes through ‘ev’; however, for the aforementioned variables, those values take precedence over the attribute values set to ‘ev’. If a TypeError exception occurs while evaluating the string, no update is made for that event.

  • globals (dict, optional) – Dictionary of the global symbol table used when operation is evaluated. By default, this is the value of globals() at the time when the constructor is called.

  • locals (dict, optional) – Dictionary of the local symbol table used when operation is evaluated. By default, this is the value of locals() at the time when the constructor is called.

Examples

Modify('ch=3')

Outputs events in which all MIDI channel numbers are changed to 3. For events that do not have a ‘ch’ attribute, nothing is changed.

Modify('v*=0.8; nv=30')

Outputs NoteEventClass events with velocity multiplied by 0.8 and note-off velocity set to 30. All other events are output unchanged.

Modify('if tk==2: v*=1.1')

For NoteEvent’s and NoteOnEvent’s with track number 2, velocity is multiplied by 1.1. All other events are output unchanged.

Modify('ev.voice=2')

For all events, sets the value of the ‘voice’ attribute to 2 (newly added if such an attribute does not exist).


class Product(pattern, *, tail=None, scale=None)

Bases: Effector

Replaces each note in the input score with a score that serves as a pattern. This can be applied to octave playing, rolls, ornaments, trills, and many other purposes. The pattern can be given in the form of an MML string (see mml()) or a function that returns a score.

By default, the pitch of each output note is the pitch in the input score with added the interval from C4 to the pitch in the pattern. For example, mml('CD').Product('[CE]') would mean to replace each of the original notes with a chord consisting of a root and its major third, resulting in a score equivalent to mml('[CE][DF#]').

The start time of each pattern in the output is always the same as the start time of the note in the input score. Also, the overall duration of the score remains the same. If the duration of the pattern corresponding to a note is longer than the note’s length (i.e., the L attribute value), the pattern is terminated with that length, except that, if the pattern is an EventList or Tracks with zero duration (as in Product('{CDEF}&')), the termination is not performed, which would allow overlap between the pattern and the pattern for the next note.

This effector can also be applied to a RealTimeStream from input devices.

Constructor

Parameters:

  • pattern (str or function) – Specifies how pattern scores are generated by either an MML string or a function that returns a score. The score may have infinite length. The context in which the MML string or the function is evaluated is set up for each NoteEvent or NoteOnEvent in the input score, allowing the pattern to reflect the parameters of the notes. The v, nv, L, tk, ch, and dt context attributes are set to the values of the same name attributes (if any) in the input event. If the input event is a NoteOnEvent, the L attribute is set to infinity. The ‘dr’ pseudo attribute in the context is set so that the played duration is unchanged if the input event is a NoteEvent. The ‘o’ attribute is always set to 4.

  • tail (str or function, optional) – Specifies how scores at the end of the pattern are generated by either an MML string or a function that returns a score. The score from pattern is shortened by the duration of the score from tail. This can be used, for example, to insert ornaments at the end of a trill performance. Scores generated by tail must not have infinite length. Also, it cannot be used if the event contained in the input score is NoteOnEvent. The context is set in the same way as for pattern.

  • scale (Scale, optional) – If a scale is specified with this argument, the pitch of the output notes is determined based on the tone number on that scale (see Scale). Specifically, the tone number of the output note is the tone number of the note in the input score plus the tone number of the pitch in the pattern.

Examples

Product("[C ^C]").

Adds a note one octave higher for each note.

Product(lambda: note(C4) & note(C5))

Equivalent to the above, written using a function.

Product("[[v*=0.9 CE]G]")

Converts each note to a major triad chord rooted with that note. Velocity is multiplied by 0.9 for all but the highest note.

Product("{CDEF}//", scale=Scale(C4))

For each note, plays four consecutive notes on the C major scale with a note value of 1/4 of the original. For example, mml("CDE").Product("{CDEF}//", scale=Scale(C4)) produces a score equivalent to mml("{CDEF DEFG EFGA}//").

Product("{L16 CDEFGAB^C}&")

For each note, plays a one-octave major scale with sixteenth notes where the tonic of the scale is the input note. The scale is always played to the end, regardless of the note value of the original note. (If there were no trailing ‘&’ in the MML, the scale would be truncated to a length corresponding to the note value of the original note.)

Product("G(L32)F", scale=Scale(F4, 'minor'))

For each note, adds an appoggiatura one degree higher in the F natural minor scale. The note value of the following note will be decreased by the length of a 32nd note.

Product("L32 C@@")

Repeats 32nd notes of the same pitch for each note (like a drum roll).

Product("L32 {CD}@@", tail="L=L8/5 CDC_BC")

Performs each note as a sequence of 32nd notes alternating with the original pitch and the pitch a whole note higher (i.e., a trill). The performance specified by tail is inserted at the end of the trill.


class Apply(pattern)

Bases: Effector

Applies rhythm and expressive information in another score (called a pattern) to the input score. This is especially useful for describing music in which phrases with different pitches but common rhythms and expressions appear frequently.

The conversion is performed as follows. The notes of the input score are matched against the notes of the pattern, and for each note in the input score, the corresponding note information in the pattern is applied with the following rules:

  • Only pitches in the input score are valid and those of the pattern are ignored.

  • The resulting ‘dt’ attribute value is the sum of those in the input and pattern scores.

  • The resulting ‘v’ attribute value is that of the pattern plus the difference between that of the input score and the value in the context.

  • All other attributes, including ‘t’ and ‘L’, are taken from the pattern.

The matching is performed on groups of simultaneously starting notes (hereafter called chords, including the case of single notes). Notes in each chord are matched in order of appearance. If a chord in the input score has less notes than the pattern, first notes in the pattern are ignored. If a chord in the input score has more notes than the pattern, the first note of the pattern is used duplicatedly.

If the input score is shorter (fewer chords) than the pattern, the extra chords in the pattern are discarded. If the input score has more chords than the pattern, an exception is raised.

If the input score contains a NoteEvent whose ‘n’ attribute is None, it is also matched as a note, but is not output.

Non-note events in the pattern are output as is. On the other hand, events other than NoteEvent in the input score are ignored; this effector is not available for input scores containing NoteOnEvent and NoteOffEvent.

Constructor

Parameters:

pattern (Score or str) – Specifies a score to be used as the pattern. If it is a string, it is assumed to be MML. May be infinite in length.

Examples

mml("CDEF`").Apply("{C!C`>C/C/}")

Produces a score equivalent to mml("C!D`>E/F`/").

mml("CDEF").Apply("{C.C/}@@")

Applies a dotted rhythm and produces a score equivalent to mml("C.D/E.F/").

mml("[CE] [EG] [EGB]").Apply("C [C? C] [C? C]")

Generates a score equivalent to mml("[CE] [E? G] [E? G? B]").


class ToTracks(set_tk_by_ch=False, limit=2000000.0)

Bases: Effector

Converts the input score to a structure classified by track number (the value of the ‘tk’ attribute). The output score is a Tracks object where each EventList indexed by i contains events with track number i (i >= 0). The events for each track are sorted by time.

Constructor

Parameters:

  • set_tk_by_ch (bool) – If True, the value of the ‘ch’ attribute is assigned to the ‘tk’ attribute for each event before the classification, and events are effectively classified by MIDI channel number. The track number of events without the ‘ch’ attribute will be 0.

  • limit (ticks) – Limits the length of the score. See the same name argument of Score.stream() for details.


class Render(swap=False)

Bases: Effector

Converts to a score where notated time is replaced by played time. Specifically, it adds the value of the ‘dt’ attribute to the ‘t’ attribute and assigns the value of the ‘du’ attribute (if any) to the ‘L’ attribute. The ‘dt’ attribute is then reset to 0 and the ‘du’ attribute is removed, unless swap is True.

The transformation can be applied to a single event as well as a score.

Constructor

Parameters:

swap (bool, optional) – If True, the notated time and the performed time are swapped. When applied twice, times are returned to the orignal state.


class Tie

Bases: EventEffector

Adds an attribute indicating the start of a tie to each NoteEvent in the score.


class EndTie

Bases: EventEffector

Adds an attribute indicating the end of a tie to each NoteEvent in the score. For notes at which a tie ends and another tie starts, apply both the Tie() end EndTie() effectors.


class ConnectTies(errhdr='')

Bases: Effector

Merges each set of NoteEvent’s tied together in the score into a single NoteEvent. In order to be correctly tied, the end time (sum of the t and L attribute values) of a NoteEvent must match the start time (the t attribute value) of the next NoteEvent in the tied set.

Constructor

Parameters:

errhdr (str, optional) – header string for error and warning messages


class Dump

Bases: EventEffector


class Voice(voice)

Bases: EventEffector

Adds a ‘voice’ attribute to each event belonging to NoteEventClass in the score. The ‘voice’ attribute is used in Score.music21().

Constructor

Parameters:

voice (int) – value of the ‘voice’ attribute


class Mark(mark)

Bases: EventEffector

Adds a ‘mark’ attribute (or appends a value to the ‘mark’ attribute if it already exists) to each event belonging to NoteEventClass in the score. The ‘mark’ attribute is used in Score.music21().

Constructor

Parameters:

mark (str or tuple of str) – a string or a tuple of strings to be added as the ‘mark’ attribute


class PairNoteEvents(ref_links=False, errhdr='')

Bases: Effector

Converts each pair of NoteOnEvent and NoteOffEvent in the score into a NoteEvent. After this effector is applied, it is guaranteed that NoteOnEvent and NoteOffEvent are not included.

The mapping between NoteOnEvent and NoteOffEvent is done between those whose tk, ch, and n attributes all match, but if there are multiple possibilities, the mapping is done in the FIFO manner, that is, the NoteOnEvent at the earlier time is preferentially paired with the NoteOffEvent. Pairing across different EventList’s or EventStream’s is not performed.

If there is a NoteOffEvent that has no corresponding NoteOnEvent, it will be deleted with a warning. If there is a NoteOnEvent without a corresponding NoteOffEvent, a warning is issued and a NoteEvent is generated as a note that lasts up to the duration of the score.

Constructor

Parameters:

  • ref_links (bool) – If True, for each generated NoteEvent, references to the original NoteOnEvent and NoteOffEvent are added as the ‘noteonev’ and ‘noteoffev’ attributes, respectively.

  • errhdr (str, optional) – header string for error and warning messages


class UnpairNoteEvents(ref_links=False)

Bases: Effector

Converts each NoteEvent in the score into a pair of NoteOnEvent and NoteOffEvent, where the time of the NoteOffEvent is the t attribute value plus the L attribute value of the original NoteEvent.

Constructor

Parameters:

ref_links (bool) – If True, for each NoteOnEvent and NoteOffEvent generated, a reference to the original NoteEvent is added as the ‘noteev’ attribute.


class RetriggerNotes

Bases: Effector

Applies retrigger processing to avoid note collisions. A note collision is a situation where the sounding period (a period of the length of the L attribute value starting from the t attribute value of NoteEvent or a period from NoteOnEvent to NoteOffEvent) of two or more notes overlap for the same pitch, track and MIDI channel. When a note collision occurs, the sound duration may be shorter than expected for some synthesizers. The retrigger process avoids the collision by reducing the sounding period of preceding notes appropriately.