Skip to content

Sustain

Functions responsible for applying the sustain pedal effect to a MIDI file.

apply_sustain(df, sustain, sustain_threshold=64)

Apply sustain pedal effects to the notes in a DataFrame.

This function uses a second DataFrame containing sustain pedal events to extend the duration of notes in the original DataFrame. It modifies the end times of notes that are held during the time when the sustain pedal is pressed down.

Parameters:

Name Type Description Default
df DataFrame

The DataFrame containing musical note data. Expected to have columns 'start', 'end', and 'pitch', where 'start' and 'end' represent the start and end times of the notes.

 required
sustain DataFrame

The DataFrame containing sustain pedal events. Expected to have columns 'time' and 'value', where 'time' is the timestamp of the pedal event and 'value' is the intensity of the pedal press.

 required
sustain_threshold int

The threshold value above which the sustain pedal is considered to be pressed down. Defaults to 64.

 64

Returns:

Name Type Description
df DataFrame

The modified DataFrame with updated end times for notes affected by the sustain pedal.
Notes
  • The sustain effect is applied by extending the end time of notes to either the start of the next note with the same pitch or the time when the sustain pedal is released, whichever comes first.
Source code in fortepyan/midi/tools.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def apply_sustain(
    df: pd.DataFrame,
    sustain: pd.DataFrame,
    sustain_threshold: int = 64,
) -> pd.DataFrame:
    """
    Apply sustain pedal effects to the notes in a DataFrame.

    This function uses a second DataFrame containing sustain pedal events to extend
    the duration of notes in the original DataFrame. It modifies the end times of notes
    that are held during the time when the sustain pedal is pressed down.

    Args:
        df (pd.DataFrame):
            The DataFrame containing musical note data. Expected to have columns
            'start', 'end', and 'pitch', where 'start' and 'end' represent the
            start and end times of the notes.
        sustain (pd.DataFrame):
            The DataFrame containing sustain pedal events. Expected to have columns
            'time' and 'value', where 'time' is the timestamp of the pedal event and
            'value' is the intensity of the pedal press.
        sustain_threshold (int, optional):
            The threshold value above which the sustain pedal is considered to be pressed
            down. Defaults to 64.

    Returns:
        df (pd.DataFrame):
            The modified DataFrame with updated end times for notes affected by the
            sustain pedal.

    Notes:
        - The sustain effect is applied by extending the end time of notes to either the
          start of the next note with the same pitch or the time when the sustain pedal is
          released, whichever comes first.
    """
    # Mark sustain pedal as down or up based on threshold value
    sustain["is_down"] = sustain.value >= sustain_threshold

    # Group sustain pedal events by continuous down or up states
    ids = sustain.is_down
    sustain["down_index"] = (ids != ids.shift(1)).cumsum()
    groups = sustain[sustain.is_down].groupby("down_index")

    # Iterate over each group of sustain pedal down events
    for _, gdf in groups:
        # Get start and end times for current sustain pedal down event
        pedal_down = gdf.time.min()
        pedal_up = gdf.time.max()

        # Select notes affected by current sustain pedal down event
        # ids = (df.end >= pedal_down) & (df.end < pedal_up)
        # affeced_notes = df[ids]

        # Modify end times of selected notes based on sustain pedal duration
        df = sustain_notes(
            df=df,
            pedal_down=pedal_down,
            pedal_up=pedal_up,
        )

    # Keep duration consistent
    df["duration"] = df.end - df.start

    return df

note_number_to_name(note_number)

Convert a MIDI note number to its name, in the format '(note)(accidental)(octave number)' (e.g. 'C#4').

Parameters:

Name Type Description Default
note_number int

MIDI note number. If not an int, it will be rounded.

 required

Returns:

Name Type Description
note_name str

Name of the supplied MIDI note number.
Source code in fortepyan/midi/tools.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def note_number_to_name(note_number):
    """
    Convert a MIDI note number to its name, in the format
    ``'(note)(accidental)(octave number)'`` (e.g. ``'C#4'``).

    Parameters:
        note_number (int):
            MIDI note number.  If not an int, it will be rounded.

    Returns:
        note_name (str):
            Name of the supplied MIDI note number.

    """

    # Note names within one octave
    semis = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]

    # Ensure the note is an int
    note_number = int(np.round(note_number))

    # Get the semitone and the octave, and concatenate to create the name
    return semis[note_number % 12] + str(note_number // 12 - 1)

sustain_notes(df, pedal_down, pedal_up)

Extend the end times of notes affected by a sustain pedal down event.

This helper function is called by apply_sustain to process each group of sustain pedal down events. It extends the end times of notes that are playing during the sustain pedal down event.

Parameters:

Name Type Description Default
df DataFrame

The DataFrame containing musical note data. Expected to have columns 'start', 'end', and 'pitch'.

 required
pedal_down float

The start time of the sustain pedal down event.

 required
pedal_up float

The end time of the sustain pedal down event, indicating when the pedal is released.

 required

Returns:

Name Type Description
df DataFrame

The DataFrame with updated end times for the notes affected by the sustain pedal.
Source code in fortepyan/midi/tools.py 
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def sustain_notes(
    df: pd.DataFrame,
    pedal_down: float,
    pedal_up: float,
) -> pd.DataFrame:
    """
    Extend the end times of notes affected by a sustain pedal down event.

    This helper function is called by `apply_sustain` to process each group of sustain
    pedal down events. It extends the end times of notes that are playing during the
    sustain pedal down event.

    Args:
        df (pd.DataFrame):
            The DataFrame containing musical note data. Expected to have columns
            'start', 'end', and 'pitch'.
        pedal_down (float):
            The start time of the sustain pedal down event.
        pedal_up (float):
            The end time of the sustain pedal down event, indicating when the pedal is released.

    Returns:
        df (pd.DataFrame):
            The DataFrame with updated end times for the notes affected by the sustain pedal.
    """
    end_times = []

    # Select notes affected by current sustain pedal down event
    ids = (df.end >= pedal_down) & (df.end < pedal_up)
    affected_notes = df[ids]

    for it, row in affected_notes.iterrows():
        # Get the rows in the DataFrame that correspond to the same pitch
        # as the current row, and that start after the current row
        jds = (df.pitch == row.pitch) & (df.start > row.start)

        if jds.any():
            # If there are any such rows, set the end time
            # to be the start time of the next note of the same pitch
            end_time = min(df[jds].start.min(), pedal_up)
        else:
            # If there are no such rows, set the end time to be the end of the sustain
            # or to be the release of the note, whichever is later
            end_time = max(row.end, pedal_up)

        end_times.append(end_time)

    df.loc[ids, "end"] = end_times

    return df