Score

class paeonia.Score(*, default_tonality=None, tonality_plan=None, tempo=120, time_signature=(4, 4), title=None)[source]

Bases: object

An ordered collection of named staves and global musical metadata.

Score retains dictionary-style voice access for compatibility while storing each voice, clef, name, and MIDI assignment together in a Staff. Score-level tonality is inherited by voices that do not provide a more local tonal context.

Parameters:

  • default_tonality (Tonality | None) – Score-wide fallback tonality.

  • tonality_plan (TonalityPlan | Mapping[int, Tonality] | None) – Score-wide tonal changes keyed by zero-based bar index.

  • tempo (int, default=120) – Tempo in beats per minute.

  • time_signature (tuple[int, int], default=(4, 4)) – Positive numerator and denominator.

  • title (str | None) – Optional score title.

property voices: dict[str, Voice]

Return a compatibility view mapping staff names to voices.

property clefs: dict[str, str]

Return a compatibility view mapping staff names to clefs.

set_clef(voice, clef)[source]

Set the clef of a named staff.

Parameters:

  • voice (str) – Name used to insert the staff into this score.

  • clef (str) – One of "treble", "alto", "tenor", or "bass".

Return type:

None

tonality_at(staff_name, bar_index)[source]

Resolve a staff’s effective tonality at a bar index.

Parameters:

  • staff_name (str)

  • bar_index (int)

Return type:

Tonality | None

copy_structure_without_staves()[source]

Copy score-level metadata into a new score with no staves.

Return type:

Score

copy()[source]

Return a structurally independent score copy.

Return type:

Score

apply_tonality(target, source=None, *, voices=None, chromatic='preserve_alteration')[source]

Reinterpret selected staves in one target tonality.

Source tonality is resolved independently for each original bar. When all staves are selected, the target becomes score-level metadata. For a selective transformation, it becomes local metadata on each changed voice. Staff presentation and MIDI metadata are preserved.

Parameters:

  • target (Tonality) – Tonality in which selected pitches are realized.

  • source (Tonality | None) – Optional source forced across every selected bar.

  • voices (Collection[str] | None) – Staff names to transform, or None for every staff.

  • chromatic (str) – Chromatic analysis policy passed to Bar.apply_tonality.

Returns:

A transformed score; the original is unchanged.

Return type:

Score

apply_tonality_plan(target_plan, source=None, *, voices=None, chromatic='preserve_alteration')[source]

Apply a synchronized target-tonality plan to selected staves.

The target plan must define bar zero. Each selected voice must contain every change index. All-staff transformations store target metadata on the score; selective transformations store equivalent metadata on the transformed voices so unselected voices retain their original score context.

Parameters:

  • target_plan (TonalityPlan | Mapping[int, Tonality]) – Target tonalities keyed by zero-based bar index, including zero.

  • source (Tonality | None) – Optional source forced across every selected bar.

  • voices (Collection[str] | None) – Staff names to transform, or None for every staff.

  • chromatic (str) – Chromatic analysis policy passed to Bar.apply_tonality.

Returns:

A transformed score; the original is unchanged.

Return type:

Score

verticalities(bar_index, *, staves=None)[source]

Return exact time frames containing all pitches sounding in a bar.

Boundaries are derived from every event onset and ending across the selected aligned staves. Rests contribute time but not pitch, sustained notes remain active, and staff insertion order is preserved.

Parameters:

  • bar_index (int)

  • staves (Collection[str] | None)

Return type:

tuple[Verticality, …]

sonority_at(bar_index, offset, *, staves=None)[source]

Return the vertical sonority sounding at a bar-relative offset.

Parameters:

  • bar_index (int)

  • offset (int | Fraction)

  • staves (Collection[str] | None)

Return type:

Verticality

pitch_class_set(bar_index, *, offset=None, staves=None)[source]

Return both written and MIDI pitch-class sets.

With no offset, the result is the union of the complete bar. Pass an offset for the set sounding at one exact point.

Parameters:

  • bar_index (int)

  • offset (int | Fraction | None)

  • staves (Collection[str] | None)

Return type:

PitchClassSet

interval_class_vector(bar_index, *, offset=None, staves=None)[source]

Return the interval-class vector of a pointwise or whole-bar set.

Parameters:

  • bar_index (int)

  • offset (int | Fraction | None)

  • staves (Collection[str] | None)

Return type:

tuple[int, int, int, int, int, int]

prime_form(bar_index, *, offset=None, staves=None)[source]

Return a transposition/inversion-normalized pitch-class form.

Parameters:

  • bar_index (int)

  • offset (int | Fraction | None)

  • staves (Collection[str] | None)

Return type:

tuple[int, …]

scale_degrees(bar_index, *, tonality=None, staves=None)[source]

Analyze every pitch as a time-aware scale position.

When tonality is omitted, all selected staves must resolve to one effective tonality at this bar.

Parameters:

  • bar_index (int)

  • tonality (Tonality | None)

  • staves (Collection[str] | None)

Return type:

tuple[ScaleDegreeSnapshot, …]

chord_candidates(bar_index, *, offset=0, tonality=None, staves=None, limit=5)[source]

Rank common chord interpretations at an exact offset.

Parameters:

  • bar_index (int)

  • offset (int | Fraction)

  • tonality (Tonality | None)

  • staves (Collection[str] | None)

  • limit (int)

Return type:

tuple[ChordCandidate, …]

roman_numerals(bar_index, *, tonality=None, staves=None)[source]

Return contiguous Roman-numeral assignments within a bar.

Parameters:

  • bar_index (int)

  • tonality (Tonality | None)

  • staves (Collection[str] | None)

Return type:

tuple[HarmonicChange, …]

harmonic_context(bar_index, *, tonality=None, staves=None)[source]

Return duration-weighted harmony, changes, and non-chord tones.

Parameters:

  • bar_index (int)

  • tonality (Tonality | None)

  • staves (Collection[str] | None)

Return type:

HarmonicContext

harmonic_rhythm(bar_index, *, tonality=None, staves=None)[source]

Return each contiguous chord assignment and exact duration.

Parameters:

  • bar_index (int)

  • tonality (Tonality | None)

  • staves (Collection[str] | None)

Return type:

tuple[HarmonicChange, …]

interval_matrix(bar_index, *, staves=None, dissonant_classes=frozenset({1, 2, 6}))[source]

Return all cross-staff pitch intervals at every vertical change.

Parameters:

  • bar_index (int)

  • staves (Collection[str] | None)

  • dissonant_classes (Collection[int])

Return type:

tuple[IntervalSnapshot, …]

dissonances(bar_index, *, staves=None, dissonant_classes=frozenset({1, 2, 6}))[source]

Return cross-staff intervals in configurable dissonant classes.

Parameters:

  • bar_index (int)

  • staves (Collection[str] | None)

  • dissonant_classes (Collection[int])

Return type:

tuple[IntervalSnapshot, …]

doublings(bar_index, *, staves=None)[source]

Return duplicated MIDI pitch classes at each vertical change.

Parameters:

  • bar_index (int)

  • staves (Collection[str] | None)

Return type:

tuple[DoublingSnapshot, …]

density(bar_index, *, staves=None)[source]

Return pitch and active-staff density throughout a bar.

Parameters:

  • bar_index (int)

  • staves (Collection[str] | None)

Return type:

tuple[DensityPoint, …]

register_analysis(bar_index, *, staves=None)[source]

Return bass, soprano, ambitus, spacing, crossings, and overlaps.

Parameters:

  • bar_index (int)

  • staves (Collection[str] | None)

Return type:

RegisterAnalysis

bass_motion(bar_index, *, staves=None)[source]

Return motion between successive sounding bass pitches.

Parameters:

  • bar_index (int)

  • staves (Collection[str] | None)

Return type:

tuple[BassMotion, …]

voice_leading_to(bar_index, next_bar_index=None, *, staves=None, leap_threshold=5)[source]

Analyze voice leading from a bar to another bar.

next_bar_index defaults to the following bar. Pitches are matched by minimum motion within each staff; results include common tones, total motion, contrary motion, parallel perfects, and leaps.

Parameters:

  • bar_index (int)

  • next_bar_index (int | None)

  • staves (Collection[str] | None)

  • leap_threshold (int)

Return type:

VoiceLeadingAnalysis

validate_alignment()[source]

Require all voices to have identical bar counts and spans.

Raises:

ValueError – If a voice has a different bar count or if corresponding bars have different total durations. Error messages identify the voice and, for duration mismatches, the bar index.

Return type:

None

to_midi(path, tpb=480, *, allow_unaligned=False)[source]

Delegate MIDI-file export to the score renderer.

Parameters:

  • tpb (int)

  • allow_unaligned (bool)

analysis_annotations(options=None)[source]

Compute fresh renderer-independent annotations for this score.

The analysis is never cached on the score, so editing a voice or a mutable score window cannot leave stale labels behind. With no options, the readable composition-oriented preset is used.

Parameters:

options (AnalysisRenderOptions | None)

Return type:

tuple[ScoreAnnotation, …]

to_lilypond(*, bar_numbers=True, analysis=False)[source]

Render the score with optional bar numbers and analysis labels.

Parameters:
Return type:

str

show(*, bar_numbers=True, analysis=False)[source]

Display the score with optional analysis, then return it.

Parameters:
Return type:

Score

play(tpb=480, autoplay=False, *, allow_unaligned=False)[source]

Render and play this score, then return it.

Parameters:

  • tpb (int)

  • autoplay (bool)

  • allow_unaligned (bool)

Return type:

Score