Editing Events

Mental Model

Events include BPM changes, time-signature changes, scroll-speed changes, and note-speed changes.

tx.chart has four event lists:

List	What it controls
`tx.chart.bpms`	`BpmEvent` controls song BPM changes.
`tx.chart.beats`	`BeatEvent` controls time-signature changes.
`tx.chart.tils`	`TimelineSpeedEvent` controls scroll speed on a specific TIL.
`tx.chart.speeds`	`NoteSpeedEvent` controls note speed for specific notes.

with m.open_edit() as tx:
    # Read
    for event in tx.chart.bpms:
        print(event.t, event.bpm)

    # Mutate
    tx.chart.bpms[0].bpm = 185.0

    # Filter
    tx.chart.speeds = [
        event for event in tx.chart.speeds if event.t < 7680
    ]

BPM Events

Use BpmEvent(t, bpm) to set BPM from a specific time.

from margrete_rpc.chart.events import BpmEvent

with m.open_edit() as tx:
    tx.chart.bpms.append(BpmEvent(t=0, bpm=180.0))
    tx.chart.bpms.append(BpmEvent(t=(1, 0, 0), bpm=200.0))

If you want to update an existing BPM event, find it and change bpm:

with m.open_edit() as tx:
    for event in tx.chart.bpms:
        if event.t == 0:
            event.bpm = 185.0
            break

Time-Signature Events

Use BeatEvent(bar, beats_per_bar, beat_unit) for time signatures. Unlike most events, a time-signature event is placed by bar number instead of time.

from margrete_rpc.chart.events import BeatEvent

with m.open_edit() as tx:
    tx.chart.beats.append(BeatEvent(0, 4, 4))   # 4/4 from bar 1
    tx.chart.beats.append(BeatEvent(16, 3, 4))  # 3/4 from bar 17

After you add beat events, note positions (Position) in the same open_edit() use the new time signatures automatically. See Time & Musical Position for details.

from margrete_rpc.chart.events import BeatEvent
from margrete_rpc.chart.notes import Tap

with m.open_edit(snapshot=False) as tx:
    tx.chart.beats.append(BeatEvent(0, 3, 4))

    # This means bar 4 in 3/4.
    tx.chart.notes.append(Tap(t=(4, 0), x=4, w=4))

Deleting Events

Event lists are normal Python lists, so deleting events is usually done by filtering the list:

with m.open_edit() as tx:
    # Delete all BPM events after tick 7680.
    tx.chart.bpms = [
        event for event in tx.chart.bpms if event.t <= 7680
    ]

    # Delete all scroll-speed events on TIL 0.
    tx.chart.tils = [
        event for event in tx.chart.tils if event.til != 0
    ]

Deduplicating Events

If two events of the same type are at the same position, the later item in the list wins when the edit is sent:

Event type	Same position
BPM, note speed	The same tick
time signature	The same bar
scroll speed	The same tick and TIL

with m.open_edit() as tx:
    tx.chart.bpms.append(BpmEvent(t=0, bpm=180.0))
    tx.chart.bpms.append(BpmEvent(t=0, bpm=185.0))  # this one wins