API References

chartparse.chart module

For representing the data of a .chart file as a object.

This module is the main entrypoint to this package. Typically, a developer needs only to create a Chart object and then inspect its attributes, like so:

Example

Creating a Chart object:

from chartparse.chart import Chart

chart = Chart.from_file("path/to/file.chart")
final class chartparse.chart.Chart(metadata: chartparse.metadata.Metadata, global_events_track: chartparse.globalevents.GlobalEventsTrack, sync_track: chartparse.sync.SyncTrack, instrument_tracks: chartparse.chart.InstrumentTrackMap)

Bases: chartparse.util.DictPropertiesEqMixin, chartparse.util.DictReprTruncatedSequencesMixin

A Clone Hero / Moonscraper chart and its relevant gameplay data.

While it is possible to create this with its initializer, as a user, you will most likely have a .chart file and not the constituent objects necessary to use __init__. To initialize a Chart from a file, you should instead use from_file().

Parameters
Return type

None

metadata: Final[chartparse.metadata.Metadata]

The chart’s metadata, such as song title or charter name.

global_events_track: Final[chartparse.globalevents.GlobalEventsTrack]

Contains the chart’s GlobalEvent objects

sync_track: Final[chartparse.sync.SyncTrack]

Contains the chart’s sync-related events.

instrument_tracks: Final[chartparse.chart.InstrumentTrackMap]

Contains all of the chart’s InstrumentTrack objects.

classmethod from_filepath(path: pathlib.Path, want_tracks: Optional[collections.abc.Sequence[tuple[chartparse.instrument.Instrument, chartparse.instrument.Difficulty]]] = None) → chartparse.chart.Chart

Given a path, parses the contents of its file and returns a new Chart.

Parameters

  • path (pathlib.Path) – A path that points to a .chart file written by Moonscraper. Must have at least a [Song], [SyncTrack], and [Events] track.

  • want_tracks (Optional[collections.abc.Sequence[tuple[chartparse.instrument.Instrument, chartparse.instrument.Difficulty]]]) – If specified, only the specified instruments and difficulties will be parsed from path.

Returns

A Chart object, initialized with data parsed from path.

Return type

chartparse.chart.Chart

classmethod from_file(fp: TextIO, want_tracks: Optional[collections.abc.Sequence[tuple[chartparse.instrument.Instrument, chartparse.instrument.Difficulty]]] = None) → chartparse.chart.Chart

Given a file object, parses its contents and returns a new Chart.

Parameters

  • fp (TextIO) – A file object that allows reading from a .chart file written by Moonscraper. Must have at least a [Song], [SyncTrack], and [Events] track.

  • want_tracks (Optional[collections.abc.Sequence[tuple[chartparse.instrument.Instrument, chartparse.instrument.Difficulty]]]) – If specified, only the specified instruments and difficulties will be parsed from fp.

Returns

A Chart object, initialized with data parsed from fp.

Return type

chartparse.chart.Chart

notes_per_second(instrument: chartparse.instrument.Instrument, difficulty: chartparse.instrument.Difficulty) → float
notes_per_second(instrument: chartparse.instrument.Instrument, difficulty: chartparse.instrument.Difficulty, start: chartparse.time.Timestamp) → float
notes_per_second(instrument: chartparse.instrument.Instrument, difficulty: chartparse.instrument.Difficulty, start: chartparse.time.Timestamp, end: chartparse.time.Timestamp) → float
notes_per_second(instrument: chartparse.instrument.Instrument, difficulty: chartparse.instrument.Difficulty, start: chartparse.tick.Tick) → float
notes_per_second(instrument: chartparse.instrument.Instrument, difficulty: chartparse.instrument.Difficulty, start: chartparse.tick.Tick, end: chartparse.tick.Tick) → float

Returns the average notes per second over the input interval.

More specifically, this calculates the number of NoteEvent objects per second. Chords do not count as multiple “notes” in one instant.

The interval is closed on both ends.

Parameters

  • instrument – The instrument for which the InstrumentTrack should be looked up.

  • difficulty – The difficulty for which the InstrumentTrack should be looked up.

  • start – The beginning of the interval.

  • end – The end of the interval.

Returns

The average notes per second value over the input interval.

Raises

  • ValueError – If there is no InstrumentTrack corresponding to instrument and difficulty.

  • ValueError – If there are no NoteEvent objects on the instrument track in question.

  • ValueError – If the interval in question is not of positive length.

chartparse.metadata module

For representing a chart’s metadata, such as musical artist.

You should not need to create any of this module’s objects manually; please instead create a Chart and inspect its attributes via that object.

class chartparse.metadata.Player2Instrument(value)

Bases: enum.Enum

The instrument type of the co-op guitar chart in Guitar Hero 3.

BASS = 'bass'
RHYTHM = 'rhythm'
final class chartparse.metadata.Metadata(*, resolution: chartparse.tick.Ticks, offset: int = 0, player2: chartparse.metadata.Player2Instrument = Player2Instrument.BASS, difficulty: int = 0, preview_start: int = 0, preview_end: int = 0, genre: str = 'rock', media_type: str = 'cd', name: Optional[str] = None, artist: Optional[str] = None, charter: Optional[str] = None, album: Optional[str] = None, year: Optional[str] = None, music_stream: Optional[str] = None, guitar_stream: Optional[str] = None, rhythm_stream: Optional[str] = None, bass_stream: Optional[str] = None, drum_stream: Optional[str] = None, drum2_stream: Optional[str] = None, drum3_stream: Optional[str] = None, drum4_stream: Optional[str] = None, vocal_stream: Optional[str] = None, keys_stream: Optional[str] = None, crowd_stream: Optional[str] = None)

Bases: chartparse.util.DictPropertiesEqMixin, chartparse.util.DictReprMixin

All of a Chart object’s metadata.

Parameters

  • resolution (chartparse.tick.Ticks) –

  • offset (int) –

  • player2 (chartparse.metadata.Player2Instrument) –

  • difficulty (int) –

  • preview_start (int) –

  • preview_end (int) –

  • genre (str) –

  • media_type (str) –

  • name (str | None) –

  • artist (str | None) –

  • charter (str | None) –

  • album (str | None) –

  • year (str | None) –

  • music_stream (str | None) –

  • guitar_stream (str | None) –

  • rhythm_stream (str | None) –

  • bass_stream (str | None) –

  • drum_stream (str | None) –

  • drum2_stream (str | None) –

  • drum3_stream (str | None) –

  • drum4_stream (str | None) –

  • vocal_stream (str | None) –

  • keys_stream (str | None) –

  • crowd_stream (str | None) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=Metadata)

header_tag: ClassVar[str] = 'Song'

The name of this track’s data section in a .chart file.

resolution: chartparse.tick.Ticks

The number of ticks for which a quarter note lasts.

offset: int = 0

The number of seconds in time before tick 0 is reached.

This is a legacy field and should most likely be ignored.

player2: chartparse.metadata.Player2Instrument = 'bass'

The instrument type of the co-op guitar chart in Guitar Hero 3.

difficulty: int = 0

The perceived difficulty to play the chart.

This is often referred to as “intensity” in modern Guitar Hero.

preview_start: int = 0

The number of seconds into the song at which the song preview should start.

Might not actually be seconds. Typically, preview_start_time in song.ini is respected for Clone Hero instead.

preview_end: int = 0

The number of seconds into the song at which the song preview should end.

Might not actually be seconds. Clone Hero just plays a preview of a particular length starting at preview_start_time in song.ini, so this is unlikely to ever do anything in modern Guitar Hero.

genre: str = 'rock'

The genre of the chart’s song.

media_type: str = 'cd'

The type of media from which the chart’s song originates.

name: str | None = None

The name of the chart’s song.

artist: str | None = None

The name of the chart’s song’s artist.

charter: str | None = None

The user who made this chart.

album: str | None = None

The name of the chart’s song’s album.

year: str | None = None

The year the chart’s song came out.

This is formatted as, e.g. “, 2018” because it historically saved time when importing into GHTCP (Guitar Hero Three Control Panel).

music_stream: str | None = None

The filename of the main music audio file.

guitar_stream: str | None = None

The filename of the guitar audio file.

rhythm_stream: str | None = None

The filename of the rhythm audio file.

bass_stream: str | None = None

The filename of the bass audio file.

drum_stream: str | None = None

The filename of the drum audio file.

drum2_stream: str | None = None

The filename of the drum2 audio file.

drum3_stream: str | None = None

The filename of the drum3 audio file.

drum4_stream: str | None = None

The filename of the drum4 audio file.

vocal_stream: str | None = None

The filename of the vocal audio file.

keys_stream: str | None = None

The filename of the keys audio file.

crowd_stream: str | None = None

The filename of the crowd audio file.

classmethod from_chart_lines(lines_iter: Iterable[str]) → Self

Initializes instance attributes by parsing an iterable of strings.

Parameters

lines_iter (Iterable[str]) – An iterable of strings obtained from a Moonscraper .chart file.

Return type

Self

chartparse.globalevents module

For representing the data related to lyrics, sections, and more.

You should not need to create any of this module’s objects manually; please instead create a Chart and inspect its attributes via that object.

final class chartparse.globalevents.GlobalEventsTrack(*, header_tag: typ.Final[str] = 'Events', text_events: Sequence[TextEvent], section_events: Sequence[SectionEvent], lyric_events: Sequence[LyricEvent])

Bases: chartparse.util.DictPropertiesEqMixin, chartparse.util.DictReprTruncatedSequencesMixin

A Chart’s GlobalEvents.

Parameters

  • header_tag (typ.Final[str]) –

  • text_events (Sequence[TextEvent]) –

  • section_events (Sequence[SectionEvent]) –

  • lyric_events (Sequence[LyricEvent]) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=GlobalEventsTrack)

header_tag: typ.Final[str] = 'Events'

The name of this track’s data section in a .chart file.

text_events: Sequence[TextEvent]
section_events: Sequence[SectionEvent]
lyric_events: Sequence[LyricEvent]
classmethod from_chart_lines(lines: Iterable[str], bpm_events: BPMEvents) → Self

Initializes instance attributes by parsing an iterable of strings.

Parameters

  • lines (Iterable[str]) – An iterable of strings obtained from a Moonscraper .chart file. bpm_events:

  • BPMEvents. (The chart's wrapped) –

  • bpm_events (BPMEvents) –

Returns

A GlobalEventsTrack parsed from lines.

Return type

Self

class chartparse.globalevents.GlobalEvent(*, tick: Tick, timestamp: Timestamp, _proximal_bpm_event_index: int = 0, value: str)

Bases: chartparse.event.Event

An event in a GlobalEventsTrack.

This is typically used only as a base class for more specialized subclasses. It implements an attractive __str__ representation and supplies a regular expression template for subclasses to fill in.

Subclasses should set _regex_prog and can be instantiated with their from_chart_line method.

Parameters

  • tick (chartparse.tick.Tick) –

  • timestamp (chartparse.time.Timestamp) –

  • _proximal_bpm_event_index (int) –

  • value (str) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=GlobalEvent)

value: str

The data that this event stores.

classmethod from_parsed_data(data: GlobalEvent.ParsedData, prev_event: Self | None, bpm_events: BPMEvents) → Self

Obtain an instance of this object from parsed data.

Parameters

  • data (GlobalEvent.ParsedData) – The data necessary to create an event.

  • prev_event (Self | None) – The event of this type with the greatest tick value less than that of this event. If this is None, then this must be the tick-wise first event of this type.

  • bpm_events (BPMEvents) – The chart’s wrapped BPMEvents.

Returns

An an instance of this object initialized from data.

Return type

Self

class ParsedData(*, tick: Tick, value: str, _regex_template: typ.Final[str] = '^\\s*?(\\d+?) = E \\"{}\\"\\s*?$')

Bases: chartparse.event.Event.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with a GlobalEvent.

Parameters

  • tick (chartparse.tick.Tick) –

  • value (str) –

  • _regex_template (Final[str]) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=GlobalEvent.ParsedData)

value: str
classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Parameters

line (str) – A string, obtained from a Moonscraper .chart file.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Return type

Self

tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

tick: Tick

The tick at which this event occurs.

timestamp: Timestamp

The timestamp when this event occurs.

final class chartparse.globalevents.TextEvent(*, tick: Tick, timestamp: Timestamp, _proximal_bpm_event_index: int = 0, value: str)

Bases: chartparse.globalevents.GlobalEvent

A GlobalEvent that stores freeform text event data.

Parameters

  • tick (Tick) –

  • timestamp (Timestamp) –

  • _proximal_bpm_event_index (int) –

  • value (str) –

Return type

None

final class ParsedData(*, tick: Tick, value: str, _regex_template: typ.Final[str] = '^\\s*?(\\d+?) = E \\"{}\\"\\s*?$')

Bases: chartparse.globalevents.GlobalEvent.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with a TextEvent.

Must not contain quotation marks.

Parameters

  • tick (chartparse.tick.Tick) –

  • value (str) –

  • _regex_template (Final[str]) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=GlobalEvent.ParsedData)

classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Parameters

line (str) – A string, obtained from a Moonscraper .chart file.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Return type

Self

value: str
tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

Self

alias of TypeVar(‘Self’, bound=GlobalEvent)

classmethod from_parsed_data(data: GlobalEvent.ParsedData, prev_event: Self | None, bpm_events: BPMEvents) → Self

Obtain an instance of this object from parsed data.

Parameters

  • data (GlobalEvent.ParsedData) – The data necessary to create an event.

  • prev_event (Self | None) – The event of this type with the greatest tick value less than that of this event. If this is None, then this must be the tick-wise first event of this type.

  • bpm_events (BPMEvents) – The chart’s wrapped BPMEvents.

Returns

An an instance of this object initialized from data.

Return type

Self

value: str

The data that this event stores.

tick: Tick

The tick at which this event occurs.

timestamp: Timestamp

The timestamp when this event occurs.

final class chartparse.globalevents.SectionEvent(*, tick: Tick, timestamp: Timestamp, _proximal_bpm_event_index: int = 0, value: str)

Bases: chartparse.globalevents.GlobalEvent

A GlobalEvent that signifies a new section.

The event’s value attribute contains the section’s name.

Parameters

  • tick (Tick) –

  • timestamp (Timestamp) –

  • _proximal_bpm_event_index (int) –

  • value (str) –

Return type

None

final class ParsedData(*, tick: Tick, value: str, _regex_template: typ.Final[str] = '^\\s*?(\\d+?) = E \\"{}\\"\\s*?$')

Bases: chartparse.globalevents.GlobalEvent.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with a SectionEvent.

Parameters

  • tick (chartparse.tick.Tick) –

  • value (str) –

  • _regex_template (Final[str]) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=GlobalEvent.ParsedData)

classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Parameters

line (str) – A string, obtained from a Moonscraper .chart file.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Return type

Self

value: str
tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

Self

alias of TypeVar(‘Self’, bound=GlobalEvent)

classmethod from_parsed_data(data: GlobalEvent.ParsedData, prev_event: Self | None, bpm_events: BPMEvents) → Self

Obtain an instance of this object from parsed data.

Parameters

  • data (GlobalEvent.ParsedData) – The data necessary to create an event.

  • prev_event (Self | None) – The event of this type with the greatest tick value less than that of this event. If this is None, then this must be the tick-wise first event of this type.

  • bpm_events (BPMEvents) – The chart’s wrapped BPMEvents.

Returns

An an instance of this object initialized from data.

Return type

Self

value: str

The data that this event stores.

tick: Tick

The tick at which this event occurs.

timestamp: Timestamp

The timestamp when this event occurs.

final class chartparse.globalevents.LyricEvent(*, tick: Tick, timestamp: Timestamp, _proximal_bpm_event_index: int = 0, value: str)

Bases: chartparse.globalevents.GlobalEvent

A GlobalEvent that stores lyric data.

The event’s value attribute contains the lyric’s text, typically a single syllable’s worth.

Parameters

  • tick (Tick) –

  • timestamp (Timestamp) –

  • _proximal_bpm_event_index (int) –

  • value (str) –

Return type

None

final class ParsedData(*, tick: Tick, value: str, _regex_template: typ.Final[str] = '^\\s*?(\\d+?) = E \\"{}\\"\\s*?$')

Bases: chartparse.globalevents.GlobalEvent.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with a LyricEvent.

Parameters

  • tick (chartparse.tick.Tick) –

  • value (str) –

  • _regex_template (Final[str]) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=GlobalEvent.ParsedData)

classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Parameters

line (str) – A string, obtained from a Moonscraper .chart file.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Return type

Self

value: str
tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

Self

alias of TypeVar(‘Self’, bound=GlobalEvent)

classmethod from_parsed_data(data: GlobalEvent.ParsedData, prev_event: Self | None, bpm_events: BPMEvents) → Self

Obtain an instance of this object from parsed data.

Parameters

  • data (GlobalEvent.ParsedData) – The data necessary to create an event.

  • prev_event (Self | None) – The event of this type with the greatest tick value less than that of this event. If this is None, then this must be the tick-wise first event of this type.

  • bpm_events (BPMEvents) – The chart’s wrapped BPMEvents.

Returns

An an instance of this object initialized from data.

Return type

Self

value: str

The data that this event stores.

tick: Tick

The tick at which this event occurs.

timestamp: Timestamp

The timestamp when this event occurs.

chartparse.sync module

For representing the data related to tempo and meter.

You should not need to create any of this module’s objects manually; please instead create a Chart and inspect its attributes via that object.

final class chartparse.sync.SyncTrack(*, time_signature_events: collections.abc.Sequence[chartparse.sync.TimeSignatureEvent], bpm_events: chartparse.sync.BPMEvents, anchor_events: collections.abc.Sequence[chartparse.sync.AnchorEvent])

Bases: chartparse.util.DictPropertiesEqMixin, chartparse.util.DictReprTruncatedSequencesMixin

All of a Chart object’s tempo-mapping related events.

Parameters
Return type

None

Self

alias of TypeVar(‘Self’, bound=SyncTrack)

header_tag: ClassVar[str] = 'SyncTrack'

The name of this track’s data section in a .chart file.

time_signature_events: collections.abc.Sequence[chartparse.sync.TimeSignatureEvent]
bpm_events: chartparse.sync.BPMEvents
anchor_events: collections.abc.Sequence[chartparse.sync.AnchorEvent]
classmethod from_chart_lines(resolution: Ticks, lines: Iterable[str]) → Self

Initializes instance attributes by parsing an iterable of strings.

Parameters

  • resolution (Ticks) – The number of ticks in a quarter note.

  • lines (Iterable[str]) – An iterable of strings obtained from a Moonscraper .chart file.

Returns

A SyncTrack parsed from lines.

Return type

Self

final class chartparse.sync.TimeSignatureEvent(*, tick: chartparse.tick.Tick, timestamp: chartparse.time.Timestamp, _proximal_bpm_event_index: int = 0, upper_numeral: int, lower_numeral: int)

Bases: chartparse.event.Event

An event representing a time signature change at a particular tick.

The first TimeSignatureEvent sets the initial time signature.

Parameters

  • tick (chartparse.tick.Tick) –

  • timestamp (chartparse.time.Timestamp) –

  • _proximal_bpm_event_index (int) –

  • upper_numeral (int) –

  • lower_numeral (int) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=TimeSignatureEvent)

upper_numeral: int

The number indicating how many beats constitute a bar.

lower_numeral: int

The number indicating the note value that represents one beat.

classmethod from_parsed_data(data: TimeSignatureEvent.ParsedData, prev_event: Self | None, bpm_events: BPMEvents) → Self

Obtain an instance of this object from parsed data.

Parameters

  • data (TimeSignatureEvent.ParsedData) – The data necessary to create an event.

  • prev_event (Self | None) – The event of this type with the greatest tick value less than that of this event. If this is None, then this must be the tick-wise first event of this type.

  • bpm_events (BPMEvents) – An object that can be used to get a timestamp at a particular tick.

Returns

An an instance of this object initialized from data.

Return type

Self

final class ParsedData(*, tick: Tick, upper: int, lower: int | None, _regex: typ.Final[str] = '^\\s*?(\\d+?) = TS (\\d+?)(?: (\\d+?))?\\s*?$', _regex_prog: typ.Final[typ.Pattern[str]] = re.compile('^\\s*?(\\d+?) = TS (\\d+?)(?: (\\d+?))?\\s*?$'))

Bases: chartparse.event.Event.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with a TimeSignatureEvent.

Parameters

  • tick (chartparse.tick.Tick) –

  • upper (int) –

  • lower (int | None) –

  • _regex (Final[str]) –

  • _regex_prog (Final[Pattern[str]]) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=TimeSignatureEvent.ParsedData)

upper: int

The number indicating how many beats constitute a bar.

lower: int | None

The log (base 2) of the number indicating the note value that represents one beat.

classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Parameters

line (str) –

Return type

Self

tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

tick: chartparse.tick.Tick

The tick at which this event occurs.

timestamp: chartparse.time.Timestamp

The timestamp when this event occurs.

final class chartparse.sync.BPMEvent(*, tick: chartparse.tick.Tick, timestamp: chartparse.time.Timestamp, _proximal_bpm_event_index: int = 0, bpm: float)

Bases: chartparse.event.Event

An event representing a BPM (beats per minute) change at a particular tick.

The first BPMEvent sets the initial BPM.

Parameters

  • tick (chartparse.tick.Tick) –

  • timestamp (chartparse.time.Timestamp) –

  • _proximal_bpm_event_index (int) –

  • bpm (float) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=BPMEvent)

bpm: float

The beats per minute value. Must not have more than 3 decimal places.

classmethod from_parsed_data(data: BPMEvent.ParsedData, prev_event: Self | None, resolution: Ticks) → Self

Obtain an instance of this object from parsed data.

Parameters

  • data (BPMEvent.ParsedData) – The data necessary to create an event.

  • prev_event (Self | None) – The event of this type with the greatest tick value less than that of this event. If this is None, then this must be the tick-wise first event of this type.

  • resolution (Ticks) – The number of ticks for which a quarter note lasts.

Returns

An an instance of this object initialized from data.

Raises

ValueError – If prev_event.tick is not less than the tick value parsed from line.

Return type

Self

final class ParsedData(*, tick: Tick, raw_bpm: str, _regex: typ.Final[str] = '^\\s*?(\\d+?) = B (\\d+?)\\s*?$', _regex_prog: typ.Final[typ.Pattern[str]] = re.compile('^\\s*?(\\d+?) = B (\\d+?)\\s*?$'))

Bases: chartparse.event.Event.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with a BPMEvent.

Parameters

  • tick (chartparse.tick.Tick) –

  • raw_bpm (str) –

  • _regex (Final[str]) –

  • _regex_prog (Final[Pattern[str]]) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=BPMEvent.ParsedData)

raw_bpm: str
classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Parameters

line (str) – A string, obtained from a Moonscraper .chart file.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Return type

Self

tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

tick: chartparse.tick.Tick

The tick at which this event occurs.

timestamp: chartparse.time.Timestamp

The timestamp when this event occurs.

final class chartparse.sync.BPMEvents(*, events: collections.abc.Sequence[chartparse.sync.BPMEvent], resolution: chartparse.tick.Ticks)

Bases: collections.abc.Sequence[chartparse.sync.BPMEvent]

The chart’s BPMEvents, wrapped with the chart’s resolution.

This exists solely to allow timestamp_at_tick to be called the moment all requisite data is accessible. If the resolution and BPM events were instead bundled into SyncTrack and timestamp_at_tick were attached to SyncTrack, is would be irksome to call timestamp_at_tick while initializing TimeSignatureEvents.

Parameters
Return type

None

events: collections.abc.Sequence[chartparse.sync.BPMEvent]

The chart’s BPMEvents.

resolution: chartparse.tick.Ticks

The number of ticks in a quarter note.

timestamp_at_tick_no_optimize_return(tick: chartparse.tick.Tick) → chartparse.time.Timestamp

Returns the timestamp at the input tick.

Parameters

tick (chartparse.tick.Tick) – The tick at which the timestamp should be calculated.

Returns

The timestamp at the input tick.

Return type

chartparse.time.Timestamp

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

timestamp_at_tick(tick: chartparse.tick.Tick, *, start_iteration_index: int = 0) → tuple[chartparse.time.Timestamp, int]

Returns the timestamp at the input tick, and an optimizing value.

Parameters

  • tick (chartparse.tick.Tick) – The tick at which the timestamp should be calculated.

  • start_iteration_index (int) –

Return type

tuple[chartparse.time.Timestamp, int]

Kwargs:
start_iteration_index: An optional optimizing input that allows this function to start

iterating over BPM events at a later index. Only pass this if you are certain that the event that should be proximal to tick is _not_ before this index. Not passing this kwarg results only in slower execution.

Returns

The timestamp at the input tick, plus the index of the BPMEvent proximal to the input tick. This index can be passed to successive calls to this function via start_iteration_index as an optimization.

Parameters

  • tick (chartparse.tick.Tick) –

  • start_iteration_index (int) –

Return type

tuple[chartparse.time.Timestamp, int]

final class chartparse.sync.AnchorEvent(*, tick: chartparse.tick.Tick, timestamp: chartparse.time.Timestamp, _proximal_bpm_event_index: int = 0)

Bases: chartparse.event.Event

An event representing a tick “locked” to a particular timestamp.

Parameters

  • tick (chartparse.tick.Tick) –

  • timestamp (chartparse.time.Timestamp) –

  • _proximal_bpm_event_index (int) –

Return type

None

tick: chartparse.tick.Tick

The tick at which this event occurs.

timestamp: chartparse.time.Timestamp

The timestamp when this event occurs.

Self

alias of TypeVar(‘Self’, bound=AnchorEvent)

classmethod from_parsed_data(data: AnchorEvent.ParsedData) → Self

Obtain an instance of this object from parsed data.

Parameters

data (AnchorEvent.ParsedData) – The data necessary to create an event.

Returns

An an instance of this object initialized from data.

Return type

Self

final class ParsedData(*, tick: Tick, microseconds: int, _regex: typ.Final[str] = '^\\s*?(\\d+?) = A (\\d+?)$', _regex_prog: typ.Final[typ.Pattern[str]] = re.compile('^\\s*?(\\d+?) = A (\\d+?)$'))

Bases: chartparse.event.Event.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with an AnchorEvent.

Parameters

  • tick (chartparse.tick.Tick) –

  • microseconds (int) –

  • _regex (Final[str]) –

  • _regex_prog (Final[Pattern[str]]) –

Return type

None

tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

Self

alias of TypeVar(‘Self’, bound=AnchorEvent.ParsedData)

microseconds: int
classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Parameters

line (str) – A string, obtained from a Moonscraper .chart file.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Return type

Self

chartparse.instrument module

For representing the data related instruments and notes.

You should not need to create any of this module’s objects manually; please instead create a Chart and inspect its attributes via that object.

final class chartparse.instrument.Difficulty(value)

Bases: chartparse.util.AllValuesGettableEnum

An InstrumentTrack’s difficulty setting.

Note that this is distinct from the numeric representation of the difficulty of playing a chart. That number is referred to as “intensity”.

Parameters

value (str) –

EASY = 'Easy'
MEDIUM = 'Medium'
HARD = 'Hard'
EXPERT = 'Expert'
final class chartparse.instrument.Instrument(value)

Bases: chartparse.util.AllValuesGettableEnum

The instrument to which a InstrumentTrack corresponds.

Parameters

value (str) –

GUITAR = 'Single'
GUITAR_COOP = 'DoubleGuitar'
BASS = 'DoubleBass'
RHYTHM = 'DoubleRhythm'
KEYS = 'Keyboard'
DRUMS = 'Drums'
GHL_GUITAR = 'GHLGuitar'

Guitar (Guitar Hero Live)

GHL_BASS = 'GHLBass'

Bass (Guitar Hero Live)

GHL_COOP = 'GHLCoop'

Co-op (Guitar Hero Live)

GHL_RHYTHM = 'GHLRhythm'

Rhythm (Guitar Hero Live)

final class chartparse.instrument.Note(value)

Bases: enum.Enum

The note lane(s) to which a NoteEvent corresponds.

Parameters

value (tuple[int, int, int, int, int]) –

Self

alias of TypeVar(‘Self’, bound=Note)

P = (0, 0, 0, 0, 0)
G = (1, 0, 0, 0, 0)
GR = (1, 1, 0, 0, 0)
GY = (1, 0, 1, 0, 0)
GB = (1, 0, 0, 1, 0)
GO = (1, 0, 0, 0, 1)
GRY = (1, 1, 1, 0, 0)
GRB = (1, 1, 0, 1, 0)
GRO = (1, 1, 0, 0, 1)
GYB = (1, 0, 1, 1, 0)
GYO = (1, 0, 1, 0, 1)
GBO = (1, 0, 0, 1, 1)
GRYB = (1, 1, 1, 1, 0)
GRYO = (1, 1, 1, 0, 1)
GRBO = (1, 1, 0, 1, 1)
GYBO = (1, 0, 1, 1, 1)
GRYBO = (1, 1, 1, 1, 1)
R = (0, 1, 0, 0, 0)
RY = (0, 1, 1, 0, 0)
RB = (0, 1, 0, 1, 0)
RO = (0, 1, 0, 0, 1)
RYB = (0, 1, 1, 1, 0)
RYO = (0, 1, 1, 0, 1)
RBO = (0, 1, 0, 1, 1)
RYBO = (0, 1, 1, 1, 1)
Y = (0, 0, 1, 0, 0)
YB = (0, 0, 1, 1, 0)
YO = (0, 0, 1, 0, 1)
YBO = (0, 0, 1, 1, 1)
B = (0, 0, 0, 1, 0)
BO = (0, 0, 0, 1, 1)
O = (0, 0, 0, 0, 1)
OPEN = (0, 0, 0, 0, 0)
GREEN = (1, 0, 0, 0, 0)
GREEN_RED = (1, 1, 0, 0, 0)
GREEN_YELLOW = (1, 0, 1, 0, 0)
GREEN_BLUE = (1, 0, 0, 1, 0)
GREEN_ORANGE = (1, 0, 0, 0, 1)
GREEN_RED_YELLOW = (1, 1, 1, 0, 0)
GREEN_RED_BLUE = (1, 1, 0, 1, 0)
GREEN_RED_ORANGE = (1, 1, 0, 0, 1)
GREEN_YELLOW_BLUE = (1, 0, 1, 1, 0)
GREEN_YELLOW_ORANGE = (1, 0, 1, 0, 1)
GREEN_BLUE_ORANGE = (1, 0, 0, 1, 1)
GREEN_RED_YELLOW_BLUE = (1, 1, 1, 1, 0)
GREEN_RED_YELLOW_ORANGE = (1, 1, 1, 0, 1)
GREEN_RED_BLUE_ORANGE = (1, 1, 0, 1, 1)
GREEN_YELLOW_BLUE_ORANGE = (1, 0, 1, 1, 1)
GREEN_RED_YELLOW_BLUE_ORANGE = (1, 1, 1, 1, 1)
RED = (0, 1, 0, 0, 0)
RED_YELLOW = (0, 1, 1, 0, 0)
RED_BLUE = (0, 1, 0, 1, 0)
RED_ORANGE = (0, 1, 0, 0, 1)
RED_YELLOW_BLUE = (0, 1, 1, 1, 0)
RED_YELLOW_ORANGE = (0, 1, 1, 0, 1)
RED_BLUE_ORANGE = (0, 1, 0, 1, 1)
RED_YELLOW_BLUE_ORANGE = (0, 1, 1, 1, 1)
YELLOW = (0, 0, 1, 0, 0)
YELLOW_BLUE = (0, 0, 1, 1, 0)
YELLOW_ORANGE = (0, 0, 1, 0, 1)
YELLOW_BLUE_ORANGE = (0, 0, 1, 1, 1)
BLUE = (0, 0, 0, 1, 0)
BLUE_ORANGE = (0, 0, 0, 1, 1)
ORANGE = (0, 0, 0, 0, 1)
is_chord() → bool

Returns whether this Note has multiple active lanes.

Return type

bool

classmethod from_parsed_datas(datas: Sequence[NoteEvent.ParsedData]) → Self

Returns the Note represented by some number of NoteEvent.ParsedDatas.

Parameters

datas (Sequence[NoteEvent.ParsedData]) – The data whose note track indices should be examined.

Returns

The Note represented by datas.

Return type

Self

final class chartparse.instrument.NoteTrackIndex(value)

Bases: chartparse.util.AllValuesGettableEnum

The integer in a line in a Moonscraper .chart file’s instrument track.

This only specifies one note lane (or a note “flag”) because multiple chart lines coalesce to form chords and/or “flagged” notes.

Parameters

value (int) –

Self

alias of TypeVar(‘Self’, bound=NoteTrackIndex)

G = 0
R = 1
Y = 2
B = 3
O = 4
P = 7
FORCED = 5
TAP = 6
GREEN = 0
RED = 1
YELLOW = 2
BLUE = 3
ORANGE = 4
OPEN = 7
is_5_note() → bool

Returns whether this is one of the five “normal” note indices.

Return type

bool

final class chartparse.instrument.InstrumentTrack(*, instrument: chartparse.instrument.Instrument, difficulty: chartparse.instrument.Difficulty, note_events: collections.abc.Sequence[chartparse.instrument.NoteEvent], star_power_events: collections.abc.Sequence[chartparse.instrument.StarPowerEvent], track_events: collections.abc.Sequence[chartparse.instrument.TrackEvent])

Bases: chartparse.util.DictPropertiesEqMixin, chartparse.util.DictReprTruncatedSequencesMixin

All of the instrument-related events for one (instrument, difficulty) pair.

Parameters
Return type

None

Self

alias of TypeVar(‘Self’, bound=InstrumentTrack)

property header_tag: str

The concatenation of this track’s difficulty and instrument (in that order).

instrument: chartparse.instrument.Instrument

The instrument to which this track corresponds.

difficulty: chartparse.instrument.Difficulty

This track’s difficulty setting.

note_events: collections.abc.Sequence[chartparse.instrument.NoteEvent]

An (instrument, difficulty) pair’s NoteEvent objects.

star_power_events: collections.abc.Sequence[chartparse.instrument.StarPowerEvent]

An (instrument, difficulty) pair’s StarPowerEvent objects.

track_events: collections.abc.Sequence[chartparse.instrument.TrackEvent]

An (instrument, difficulty) pair’s TrackEvent objects.

property last_note_end_timestamp: Optional[chartparse.time.Timestamp]

The timestamp at which the sustain value of the last NoteEvent ends.

This is None iff the track has no notes.

classmethod from_chart_lines(instrument: Instrument, difficulty: Difficulty, lines: Iterable[str], bpm_events: BPMEvents) → Self

Initializes instance attributes by parsing an iterable of strings.

Parameters

  • instrument (Instrument) – The instrument to which this track corresponds.

  • difficulty (Difficulty) – This track’s difficulty setting.

  • lines (Iterable[str]) – An iterable of strings obtained from a Moonscraper .chart file.

  • bpm_events (BPMEvents) – The chart’s wrapped BPMEvents.

Returns

An InstrumentTrack parsed from line.

Return type

Self

final class chartparse.instrument.StarPowerData(*, star_power_event_index: int)

Bases: chartparse.util.DictPropertiesEqMixin

Star power related info for a NoteEvent.

Parameters

star_power_event_index (int) –

Return type

None

star_power_event_index: int
chartparse.instrument.SustainTuple

A 5-element tuple representing the sustain value of each note lane for nonuniform sustains.

An element is None if and only if the corresponding note lane is inactive. If an element is 0, then there will be at least one other non-0, non-None element; this is because that 0 element represents an unsustained (but present) note in unison with a sustained note.

alias of tuple[Optional[chartparse.tick.Ticks], Optional[chartparse.tick.Ticks], Optional[chartparse.tick.Ticks], Optional[chartparse.tick.Ticks], Optional[chartparse.tick.Ticks]]

chartparse.instrument.ComplexSustain

A sustain value representing the possibility for coinciding notes with different sustain values.

If this value is a Ticks, it means that all active note lanes at this tick value are sustained for the same number of ticks.

alias of Union[chartparse.tick.Ticks, chartparse.instrument.SustainTuple]

chartparse.instrument.complex_sustain_from_parsed_datas(datas: collections.abc.Sequence[chartparse.instrument.NoteEvent.ParsedData]) → Union[chartparse.tick.Ticks, chartparse.instrument.SustainTuple]

Returns a ComplexSustain incorporating the sustains of multiple ParsedDatas.

If datas has multiple elements, one or more of which correspond to open notes, this function’s behavior is undefined.

Parameters

datas (collections.abc.Sequence[chartparse.instrument.NoteEvent.ParsedData]) – The datas whose sustain values should be coalesced.

Returns

The sustain values of datas coalesced into a single ComplexSustain.

Return type

Union[chartparse.tick.Ticks, chartparse.instrument.SustainTuple]

final class chartparse.instrument.HOPOState(value)

Bases: enum.Enum

The manner in which a NoteEvent can or must be hit.

STRUM = 0
HOPO = 1
TAP = 2
final class chartparse.instrument.NoteEvent(*, tick: chartparse.tick.Tick, timestamp: chartparse.time.Timestamp, _proximal_bpm_event_index: int = 0, note: chartparse.instrument.Note, sustain: Union[chartparse.tick.Ticks, chartparse.instrument.SustainTuple] = 0, end_timestamp: chartparse.time.Timestamp, hopo_state: chartparse.instrument.HOPOState, star_power_data: Optional[chartparse.instrument.StarPowerData] = None)

Bases: chartparse.event.Event

An event representing all of the active note lanes / flags at a particular tick.

A single NoteEvent is treated as a single “note” in Guitar Hero.

A note event’s str representation looks like this:

NoteEvent(t@0000816 0:00:02.093750): sustain=0: Note.Y [hopo_state=H]

This event occurs at tick 816 and timestamp 0:00:02.093750. It is not sustained. It is yellow. It is a HOPO. Other valid flags are T (for “tap”) and S (for “strum”).

Parameters
Return type

None

Self

alias of TypeVar(‘Self’, bound=NoteEvent)

note: chartparse.instrument.Note

The note lane(s) that are active.

sustain: Union[chartparse.tick.Ticks, chartparse.instrument.SustainTuple] = 0

The duration(s) for which this event’s note lane(s) are sustained.

end_timestamp: chartparse.time.Timestamp

The timestamp at which this note ends.

hopo_state: chartparse.instrument.HOPOState

Whether this note is a strum, a HOPO, or a tap note.

star_power_data: chartparse.instrument.StarPowerData | None = None

Information associated with star power for this note.

If this is None, then the note is not a star power note.

property longest_sustain: chartparse.tick.Ticks

The length of the longest sustained note in this event.

It’s possible for different note lanes to have different sustain values at the same tick.

property end_tick: chartparse.tick.Tick

The tick immediately after this note ends.

classmethod from_parsed_data(datas: Sequence[NoteEvent.ParsedData], prev_event: NoteEvent | None, star_power_events: Sequence[StarPowerEvent], bpm_events: BPMEvents, proximal_bpm_event_index: int = 0, star_power_event_index: int = 0) → tuple[Self, int, int]

Obtain an instance of this object from parsed datas.

This function assumes that all input datas have the same tick value. If they do not, this function’s behavior is undefined.

Parameters

  • datas (Sequence[NoteEvent.ParsedData]) – The data necessary to create an event.

  • prev_event (NoteEvent | None) – The event of this type with the greatest tick value less than that of this event. If this is None, then this must be the tick-wise first event of this type.

  • star_power_events (Sequence[StarPowerEvent]) – All StarPowerEvents.

  • bpm_events (BPMEvents) – The chart’s wrapped BPMEvents.

  • proximal_bpm_event_index (int) – The index of the BPMEvent with the largest tick value smaller than that of this event. For optimization only.

  • star_power_event_index (int) – The index of the StarPowerEvent with the largest tick value smaller than that of this event. For optimization only.

Returns

An instance of this object initialized from the input parsed data, along with the index of the latest BPMEvent and StarPowerEvent not after this event

Return type

tuple[Self, int, int]

class ParsedData(*, tick: Tick, note_track_index: NoteTrackIndex, sustain: Ticks, _regex: typ.Final[str] = '^\\s*?(\\d+?) = N ([0-7]) (\\d+?)\\s*?$', _regex_prog: typ.Final[typ.Pattern[str]] = re.compile('^\\s*?(\\d+?) = N ([0-7]) (\\d+?)\\s*?$'), _unhandled_note_track_index_log_msg_tmpl: typ.Final[str] = 'unhandled note track index {} at tick {}')

Bases: chartparse.event.Event.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with a NoteEvent.

Parameters

  • tick (chartparse.tick.Tick) –

  • note_track_index (chartparse.instrument.NoteTrackIndex) –

  • sustain (chartparse.tick.Ticks) –

  • _regex (Final[str]) –

  • _regex_prog (Final[Pattern[str]]) –

  • _unhandled_note_track_index_log_msg_tmpl (Final[str]) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=NoteEvent.ParsedData)

note_track_index: chartparse.instrument.NoteTrackIndex

The note lane active on this chart line.

sustain: chartparse.tick.Ticks

The duration in ticks of the active lane in the event represented by this data.

classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Parameters

line (str) – A string, obtained from a Moonscraper .chart file.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Return type

Self

tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

tick: chartparse.tick.Tick

The tick at which this event occurs.

timestamp: chartparse.time.Timestamp

The timestamp when this event occurs.

class chartparse.instrument.SpecialEvent(*, tick: chartparse.tick.Tick, timestamp: chartparse.time.Timestamp, _proximal_bpm_event_index: int = 0, sustain: chartparse.tick.Ticks)

Bases: chartparse.event.Event

Provides a regex template for parsing ‘S’ style chart lines.

This is typically used only as a base class for more specialized subclasses.

Parameters

  • tick (chartparse.tick.Tick) –

  • timestamp (chartparse.time.Timestamp) –

  • _proximal_bpm_event_index (int) –

  • sustain (chartparse.tick.Ticks) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=SpecialEvent)

sustain: chartparse.tick.Ticks

The number of ticks for which this event is sustained.

This event does not “cover” events at tick + sustain; it ends immediately before that tick.

property end_tick: chartparse.tick.Tick

The tick immediately after this event ends.

classmethod from_parsed_data(data: SpecialEvent.ParsedData, prev_event: Self | None, bpm_events: BPMEvents) → Self

Obtain an instance of this object from parsed data.

Parameters

  • data (SpecialEvent.ParsedData) – The data necessary to create an event.

  • prev_event (Self | None) – The event of this type with the greatest tick value less than that of this event. If this is None, then this must be the tick-wise first event of this type.

  • bpm_events (BPMEvents) – The chart’s wrapped BPMEvents.

Returns

An an instance of this object initialized from data.

Return type

Self

tick_is_during_event(tick: chartparse.tick.Tick) → bool

Returns whether tick occurs during this event.

This canonicalizes the fact that, in order to be during an event, a tick value must be greater than or equal to the event’s tick value and less than the event’s end_tick value.

Parameters

tick (chartparse.tick.Tick) –

Return type

bool

tick_is_after_event(tick: chartparse.tick.Tick) → bool

Returns whether tick occurs after this event.

This canonicalizes the fact that, in order to be after an event, a tick value must be greater than or equal to the event’s end_tick value.

Parameters

tick (chartparse.tick.Tick) –

Return type

bool

class ParsedData(*, tick: Tick, sustain: Ticks, _regex_template: typ.Final[str] = '^\\s*?(\\d+?) = S {} (\\d+?)\\s*?$')

Bases: chartparse.event.Event.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with a SpecialEvent.

Parameters

  • tick (chartparse.tick.Tick) –

  • sustain (chartparse.tick.Ticks) –

  • _regex_template (Final[str]) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=SpecialEvent.ParsedData)

sustain: chartparse.tick.Ticks

The duration in ticks of the event represented by this data.

tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Parameters

line (str) – A string, obtained from a Moonscraper .chart file.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Return type

Self

tick: chartparse.tick.Tick

The tick at which this event occurs.

timestamp: chartparse.time.Timestamp

The timestamp when this event occurs.

final class chartparse.instrument.StarPowerEvent(*, tick: chartparse.tick.Tick, timestamp: chartparse.time.Timestamp, _proximal_bpm_event_index: int = 0, sustain: chartparse.tick.Ticks)

Bases: chartparse.instrument.SpecialEvent

An event representing star power starting at some tick and lasting for some duration.

Parameters

  • tick (chartparse.tick.Tick) –

  • timestamp (chartparse.time.Timestamp) –

  • _proximal_bpm_event_index (int) –

  • sustain (chartparse.tick.Ticks) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=SpecialEvent)

property end_tick: chartparse.tick.Tick

The tick immediately after this event ends.

classmethod from_parsed_data(data: SpecialEvent.ParsedData, prev_event: Self | None, bpm_events: BPMEvents) → Self

Obtain an instance of this object from parsed data.

Parameters

  • data (SpecialEvent.ParsedData) – The data necessary to create an event.

  • prev_event (Self | None) – The event of this type with the greatest tick value less than that of this event. If this is None, then this must be the tick-wise first event of this type.

  • bpm_events (BPMEvents) – The chart’s wrapped BPMEvents.

Returns

An an instance of this object initialized from data.

Return type

Self

tick_is_after_event(tick: chartparse.tick.Tick) → bool

Returns whether tick occurs after this event.

This canonicalizes the fact that, in order to be after an event, a tick value must be greater than or equal to the event’s end_tick value.

Parameters

tick (chartparse.tick.Tick) –

Return type

bool

tick_is_during_event(tick: chartparse.tick.Tick) → bool

Returns whether tick occurs during this event.

This canonicalizes the fact that, in order to be during an event, a tick value must be greater than or equal to the event’s tick value and less than the event’s end_tick value.

Parameters

tick (chartparse.tick.Tick) –

Return type

bool

sustain: chartparse.tick.Ticks

The number of ticks for which this event is sustained.

This event does not “cover” events at tick + sustain; it ends immediately before that tick.

tick: chartparse.tick.Tick

The tick at which this event occurs.

timestamp: chartparse.time.Timestamp

The timestamp when this event occurs.

final class ParsedData(*, tick: Tick, sustain: Ticks, _regex_template: typ.Final[str] = '^\\s*?(\\d+?) = S {} (\\d+?)\\s*?$')

Bases: chartparse.instrument.SpecialEvent.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with a StarPowerEvent.

Parameters

  • tick (chartparse.tick.Tick) –

  • sustain (chartparse.tick.Ticks) –

  • _regex_template (Final[str]) –

Return type

None

Self

alias of TypeVar(‘Self’, bound=SpecialEvent.ParsedData)

classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Parameters

line (str) – A string, obtained from a Moonscraper .chart file.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Return type

Self

sustain: chartparse.tick.Ticks

The duration in ticks of the event represented by this data.

tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

final class chartparse.instrument.TrackEvent(*, tick: chartparse.tick.Tick, timestamp: chartparse.time.Timestamp, _proximal_bpm_event_index: int = 0, value: str)

Bases: chartparse.event.Event

An event representing arbitrary data at a particular tick.

Parameters

  • tick (chartparse.tick.Tick) –

  • timestamp (chartparse.time.Timestamp) –

  • _proximal_bpm_event_index (int) –

  • value (str) –

Return type

None

tick: chartparse.tick.Tick

The tick at which this event occurs.

timestamp: chartparse.time.Timestamp

The timestamp when this event occurs.

Self

alias of TypeVar(‘Self’, bound=TrackEvent)

classmethod from_parsed_data(data: TrackEvent.ParsedData, prev_event: Self | None, bpm_events: BPMEvents) → Self

Obtain an instance of this object from parsed data.

Parameters

  • data (TrackEvent.ParsedData) – The data necessary to create an event.

  • prev_event (Self | None) – The event of this type with the greatest tick value less than that of this event. If this is None, then this must be the tick-wise first event of this type.

  • bpm_events (BPMEvents) – The chart’s wrapped BPMEvents.

Returns

An an instance of this object initialized from data.

Return type

Self

class ParsedData(*, tick: Tick, value: str, _regex: typ.Final[str] = '^\\s*?(\\d+?) = E ([^ ]*?)\\s*?$', _regex_prog: typ.Final[typ.Pattern[str]] = re.compile('^\\s*?(\\d+?) = E ([^ ]*?)\\s*?$'))

Bases: chartparse.event.Event.ParsedData, chartparse.util.DictReprMixin

The data on a single chart line associated with a TrackEvent.

Parameters

  • tick (chartparse.tick.Tick) –

  • value (str) –

  • _regex (Final[str]) –

  • _regex_prog (Final[Pattern[str]]) –

Return type

None

tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

Self

alias of TypeVar(‘Self’, bound=TrackEvent.ParsedData)

classmethod from_chart_line(line: str) → Self

Attempt to construct this object from a .chart line.

Parameters

line (str) – A string, obtained from a Moonscraper .chart file.

Returns

An an instance of this object initialized from line.

Raises

RegexNotMatchError – If the mixed-into class’ _regex does not match line.

Return type

Self

chartparse.event module

For functionality useful for all event objects.

class chartparse.event.Event(*, tick: chartparse.tick.Tick, timestamp: chartparse.time.Timestamp, _proximal_bpm_event_index: int = 0)

Bases: chartparse.util.DictPropertiesEqMixin, chartparse.util.DictReprMixin

An event that occurs at a tick and timestamp in an event track.

This is typically used only as a base class for more specialized subclasses. It implements an attractive __str__ representation.

Parameters

  • tick (chartparse.tick.Tick) –

  • timestamp (chartparse.time.Timestamp) –

  • _proximal_bpm_event_index (int) –

Return type

None

tick: chartparse.tick.Tick

The tick at which this event occurs.

timestamp: chartparse.time.Timestamp

The timestamp when this event occurs.

class ParsedData(*, tick: chartparse.tick.Tick)

Bases: abc.ABC

The data on a single chart line associated with an Event.

Parameters

tick (chartparse.tick.Tick) –

Return type

None

tick: chartparse.tick.Tick

The tick at which the event represented by this data occurs.

Self

alias of TypeVar(‘Self’, bound=Event.ParsedData)

abstract classmethod from_chart_line(line: str) → Self
Parameters

line (str) –

Return type

Self

chartparse.track module

Functionality useful for all event track objects.

Most notably, InstrumentTrack, SyncTrack, and GlobalEventsTrack are considered to be event tracks.

class chartparse.track.ParsedDataMap

Bases: chartparse.util.DictPropertiesEqMixin, chartparse.util.DictReprTruncatedSequencesMixin

A dict mapping ParsedData subtypes to lists of values of those types.

This type exposes a __getitem__ implementation that is typed such that you can only lookup values of type list[_ParsedDataT] given keys of type type[_ParsedDataT]. This type’s internal dict is a defaultdict(list) and __setitem__ is not exposed, so the only useful things you can do with a ParsedDataMap is lookup/append to that dict’s lists.

Return type

None

chartparse.track.parse_data_from_chart_lines(types: collections.abc.Sequence[type[_ParsedDataT]], lines: collections.abc.Iterable[str]) → chartparse.track.ParsedDataMap

Convert one or more chart lines into parsed data, and partition by type.

Parameters

  • types (collections.abc.Sequence[type[~_ParsedDataT]]) – The types to which we should attempt to map each string in lines. This function is more efficient if the types in types are ordered in descending frequency. That is, because it chooses the first type that matches, users should put the more common ones first.

  • lines (collections.abc.Iterable[str]) – An iterable of strings obtained from a Moonscraper .chart file.

Returns

A dictionary mapping each type in types to a list of datas that were parsed into that type from lines in lines.

Return type

chartparse.track.ParsedDataMap

chartparse.track.build_events_from_data(event_type: type[chartparse.sync.AnchorEvent], datas: collections.abc.Iterable[chartparse.sync.AnchorEvent.ParsedData], /) → list[chartparse.sync.AnchorEvent]
chartparse.track.build_events_from_data(event_type: type[chartparse.sync.BPMEvent], datas: collections.abc.Iterable[chartparse.sync.BPMEvent.ParsedData], resolution: chartparse.tick.Ticks, /) → chartparse.sync.BPMEvents
chartparse.track.build_events_from_data(event_type: type[chartparse.sync.TimeSignatureEvent], datas: collections.abc.Iterable[chartparse.sync.TimeSignatureEvent.ParsedData], bpm_events: chartparse.sync.BPMEvents, /) → list[chartparse.sync.TimeSignatureEvent]
chartparse.track.build_events_from_data(event_type: type[chartparse.globalevents.SectionEvent], datas: collections.abc.Iterable[chartparse.globalevents.SectionEvent.ParsedData], bpm_events: chartparse.sync.BPMEvents, /) → list[chartparse.globalevents.SectionEvent]
chartparse.track.build_events_from_data(event_type: type[chartparse.globalevents.LyricEvent], datas: collections.abc.Iterable[chartparse.globalevents.LyricEvent.ParsedData], bpm_events: chartparse.sync.BPMEvents, /) → list[chartparse.globalevents.LyricEvent]
chartparse.track.build_events_from_data(event_type: type[chartparse.globalevents.TextEvent], datas: collections.abc.Iterable[chartparse.globalevents.TextEvent.ParsedData], bpm_events: chartparse.sync.BPMEvents, /) → list[chartparse.globalevents.TextEvent]
chartparse.track.build_events_from_data(event_type: type[chartparse.instrument.StarPowerEvent], datas: collections.abc.Iterable[chartparse.instrument.StarPowerEvent.ParsedData], bpm_events: chartparse.sync.BPMEvents, /) → list[chartparse.instrument.StarPowerEvent]
chartparse.track.build_events_from_data(event_type: type[chartparse.instrument.TrackEvent], datas: collections.abc.Iterable[chartparse.instrument.TrackEvent.ParsedData], bpm_events: chartparse.sync.BPMEvents, /) → list[chartparse.instrument.TrackEvent]

chartparse.tick module

For functionality relating to tick arithmetic.

chartparse.tick.Tick

A specific tick-moment in a chart.

alias of int

chartparse.tick.Ticks

A duration measured in ticks.

alias of int

chartparse.tick.add(a: chartparse.tick.Tick, b: chartparse.tick.Ticks) → chartparse.tick.Tick

Returns the tick value at a + b.

Parameters

  • a (chartparse.tick.Tick) – A tick moment.

  • b (chartparse.tick.Ticks) – A number of ticks.

Return type

chartparse.tick.Tick

chartparse.tick.sum(a: chartparse.tick.Ticks, b: chartparse.tick.Ticks) → chartparse.tick.Ticks

Returns the number of ticks in a + b.

Parameters

  • a (chartparse.tick.Ticks) – A number of ticks.

  • b (chartparse.tick.Ticks) – A number of ticks.

Return type

chartparse.tick.Ticks

chartparse.tick.difference(a: chartparse.tick.Ticks, b: chartparse.tick.Ticks) → chartparse.tick.Ticks

Returns the number of ticks in a - b.

Parameters

  • a (chartparse.tick.Ticks) – A number of ticks.

  • b (chartparse.tick.Ticks) – A number of ticks.

Return type

chartparse.tick.Ticks

chartparse.tick.between(a: chartparse.tick.Tick, b: chartparse.tick.Tick) → chartparse.tick.Ticks

Returns the number of ticks in abs(a - b).

Parameters

  • a (chartparse.tick.Tick) – A tick moment.

  • b (chartparse.tick.Tick) – A tick moment.

Return type

chartparse.tick.Ticks

final class chartparse.tick.NoteDuration(value)

Bases: enum.Enum

The note durations supported by Moonscraper.

The enum values are the number of that type of note in one resolution's worth of ticks.

WHOLE = 0.25
HALF = 0.5
QUARTER = 1
EIGHTH = 2
SIXTEENTH = 4
THIRTY_SECOND = 8
SIXTY_FOURTH = 16
HUNDRED_TWENTY_EIGHTH = 32
TWO_HUNDRED_FIFTH_SIXTH = 64
FIVE_HUNDRED_TWELFTH = 128
THIRD = 0.75
SIXTH = 1.5
TWELFTH = 3
TWENTY_FOURTH = 6
FOURTY_EIGHTH = 12
NINETY_SIXTH = 24
HUNDRED_NINETY_SECOND = 48
THREE_HUNDRED_EIGHTY_FOURTH = 96
SEVEN_HUNDRED_SIXTY_EIGHTH = 192
HALF_TRIPLET = 0.75
QUARTER_TRIPLET = 1.5
EIGHTH_TRIPLET = 3
SIXTEENTH_TRIPLET = 6
THIRTY_SECOND_TRIPLET = 12
SIXTY_FOURTH_TRIPLET = 24
HUNDRED_TWENTY_EIGHTH_TRIPLET = 48
TWO_HUNDRED_FIFTH_SIXTH_TRIPLET = 96
FIVE_HUNDRED_TWELFTH_TRIPLET = 192
chartparse.tick.note_duration_to_ticks(resolution: chartparse.tick.Ticks, note_duration: chartparse.tick.NoteDuration) → chartparse.tick.Ticks

Returns the number of ticks between two notes of a particular note value.

I do not know whether Moonscraper rounds or truncates when resolution does not divide evenly. The vast majority of charts have a resolution of exactly 192, so this is mostly a nonissue, because 192 is divided evenly by every note value.

Parameters

  • resolution (chartparse.tick.Ticks) – The number of ticks in a quarter note.

  • note_duration (chartparse.tick.NoteDuration) – The note duration for which the tick interval should be computed.

Return type

chartparse.tick.Ticks

Returns: The number of ticks between two notes of a particular note value.

chartparse.tick.seconds_from_ticks_at_bpm(ticks: chartparse.tick.Ticks, bpm: float, resolution: chartparse.tick.Ticks) → chartparse.time.Seconds

Returns the number of seconds that elapse over some number of ticks at a particular tempo.

Parameters

  • ticks (chartparse.tick.Ticks) – The number of ticks for which the duration should be calculated.

  • bpm (float) – The tempo.

  • resolution (chartparse.tick.Ticks) – The number of ticks in a quarter note.

Return type

chartparse.time.Seconds

Returns: The number of seconds that elapse over ticks ticks at tempo bpm and resolution resolution.

chartparse.exceptions module

For custom exceptions raised in this package.

chartparse.exceptions.raise_(ex: Exception) → None

Raises ex.

Can be used to raise an exception from within a lambda.

Parameters

ex (Exception) –

Return type

None

final exception chartparse.exceptions.MissingRequiredField(field_name: str)

Bases: Exception

Raised when a required Metadata could not be parsed.

Parameters

field_name (Final[str]) –

Return type

None

field_name: Final[str]
message: Final[str]
final exception chartparse.exceptions.RegexNotMatchError(regex: str)
final exception chartparse.exceptions.RegexNotMatchError(regex: str, s: str)
final exception chartparse.exceptions.RegexNotMatchError(regex: str, s: collections.abc.Collection[str])

Bases: Exception

Raised when a regex failed to match.

Parameters

  • regex (Final[str]) –

  • s (typ.Union[None, str, Collection[str]]) –

Return type

None

regex: Final[str]
message: Final[str]
final exception chartparse.exceptions.UnreachableError(reason: str)

Bases: Exception

Raised in branches that should be unreachable.

Oftentimes, these branches must exist to satisfy mypy. If this error is raised, it indicates a fundamental issue with the code that should have been caught during review.

Parameters

reason (str) –

Return type

None

message: Final[str]

chartparse.util module

For various utilities useful throughout chartparse.

class chartparse.util.DictPropertiesEqMixin

Bases: object

A mixin that implements __eq__ via __dict__().__eq__.

An object with this mixed in will equate to other objects that share this mixin and have equal __dict__s.

class chartparse.util.DictReprMixin

Bases: object

A mixin implementing __repr__ by dumping __dict__().

Additionally, this ignores class attributes, since they (typically) do not change and are therefore uninteresting.

class chartparse.util.DictReprTruncatedSequencesMixin

Bases: object

A mixin implementing __repr__ by dumping __dict__() with truncated sequences.

Specifically, any instance attribute of type Sequence with more than 1 element will be represented as such:

["foo", ... 4 more elements]

Additionally, this ignores class attributes, since they (typically) do not change and are therefore uninteresting.

class chartparse.util.AllValuesGettableEnum(value)

Bases: enum.Enum

A wrapper for Enum that adds a method for returning all enum values.

classmethod all_values() → collections.abc.Sequence[chartparse.hints.T]

Returns all Enum values.

Returns

A Sequence containing all Enum values.

Return type

collections.abc.Sequence[chartparse.hints.T]

chartparse.hints module

For type annotation related utilities.

class chartparse.hints.Comparable(*args, **kwargs)

Bases: Protocol

Protocol for annotating comparable types.