simfile.notes.group

Attributes

GroupedNotes

A sequence of Note and possibly NoteWithTail objects.

Exceptions

OrphanedNoteException

Raised by group_notes() to flag an orphaned head or tail note.

Classes

`NoteWithTail`	A hold/roll head note with its corresponding tail note.
`SameBeatNotes`	Choices for `group_notes()`' same_beat_notes parameter.
`OrphanedNotes`	Choices for `group_notes()`' orphaned_head\|tail parameters.

Functions

`group_notes`(→ Iterator[GroupedNotes])	Join certain notes together: either ones that occur on the same
`ungroup_notes`(→ Iterator[simfile.notes.Note])	Convert grouped notes back into a plain note stream.

Module Contents

class simfile.notes.group.NoteWithTail

Bases: NamedTuple

A hold/roll head note with its corresponding tail note.

beat: simfile.timing.Beat

column: int

note_type: simfile.notes.NoteType

tail_beat: simfile.timing.Beat

player: int = 0: Only used in routine charts. The second player’s note data will have this value set to 1.

keysound_index: int | None = None: Only used in keysounded SSC charts. Notes followed by a number in square brackets will have this value set to the bracketed number.

simfile.notes.group.GroupedNotes: A sequence of Note and possibly NoteWithTail objects.

class simfile.notes.group.SameBeatNotes(*args, **kwds)

Bases: enum.Enum

Choices for group_notes()’ same_beat_notes parameter.

When multiple notes land on the same beat…

KEEP_SEPARATE: each note is emitted separately
JOIN_BY_NOTE_TYPE: notes of the same type are emitted together
JOIN_ALL: all notes are emitted together

KEEP_SEPARATE = 1

JOIN_BY_NOTE_TYPE = 2

JOIN_ALL = 3

exception simfile.notes.group.OrphanedNoteException

Bases: Exception

Raised by group_notes() to flag an orphaned head or tail note.

class simfile.notes.group.OrphanedNotes(*args, **kwds)

Bases: enum.Enum

Choices for group_notes()’ orphaned_head|tail parameters.

When join_heads_to_tails is True and a head or tail note is missing its counterpart…

RAISE_EXCEPTION: raise OrphanedNoteException
KEEP_ORPHAN: emit the orphaned Note
DROP_ORPHAN: do not emit the orphaned note

RAISE_EXCEPTION = 1

KEEP_ORPHAN = 2

DROP_ORPHAN = 3

simfile.notes.group.group_notes(notes: Iterable[simfile.notes.Note], *, same_beat_notes: SameBeatNotes = SameBeatNotes.KEEP_SEPARATE, join_heads_to_tails: bool = False, orphaned_head: OrphanedNotes = OrphanedNotes.RAISE_EXCEPTION, orphaned_tail: OrphanedNotes = OrphanedNotes.RAISE_EXCEPTION) → Iterator[GroupedNotes]

Join certain notes together: either ones that occur on the same beat (“jumps”), hold & roll heads to their tails, or both.

This function yields GroupedNotes objects, which are sequences of Note and NoteWithTail objects. GroupedNotes objects may contain multiple items only if same_beat_notes is set to JOIN_BY_NOTE_TYPE or JOIN_ALL; they may contain NoteWithTail objects only if join_heads_to_tails is set to True.

When join_heads_to_tails is set to True, tail notes are attached to their corresponding hold/roll heads as NoteWithTail objects. The tail itself will not be emitted as a separate note. If a head or tail note is missing its counterpart, orphaned_head and orphaned_tail determine the behavior. (These parameters are ignored if join_heads_to_tails is omitted or False.)

Refer to each enum’s documentation for the other configuration options.

simfile.notes.group.ungroup_notes(grouped_notes: Iterable[GroupedNotes], *, orphaned_notes: OrphanedNotes = OrphanedNotes.RAISE_EXCEPTION) → Iterator[simfile.notes.Note]

Convert grouped notes back into a plain note stream.

If a note falls within a NoteWithTail’s head and tail (on the same column), it would cause the head and tail to be orphaned. orphaned_notes determines how to handle the splitting note: KEEP_ORPHAN will yield the note (allowing the head and tail notes to become orphans) and DROP_ORPHAN will drop the note (preserving the link between the head and tail notes).

Note that this check only applies to heads and tails joined as a NoteAndTail. If group_notes() was called without specifying join_heads_to_tails, specifying orphaned_notes here will have no effect. This mirrors how group_notes()’ orphaned_head and orphaned_tail parameters behave.