simfile.notes.group

Module Contents

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(, same_beat_notes, join_heads_to_tails, ...)	Group notes that are often considered linked to one another.
ungroup_notes(→ Iterator[simfile.notes.Note])	Convert grouped notes back into a plain note stream.

Attributes

GroupedNotes

A sequence of Note and possibly NoteWithTail objects.

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

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], *, include_note_types: FrozenSet[simfile.notes.NoteType] = frozenset(NoteType), 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]

Group notes that are often considered linked to one another.

There are two kinds of connected notes: notes that occur on the same beat (“jumps”) and hold/roll notes with their corresponding tails. Either or both of these connection types can be opted into using the constructor parameters.

Generators produced by this class yield GroupedNotes objects, rather than Note objects. These are sequences that generally contain Note and NoteWithTail objects, although the output may be more restrained depending on the configuration.

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.