Melody Engine API

Package Overview

The melody_engine package re-exports the main public classes and functions from the engine submodules. The detailed API reference below documents those submodules directly so the type index stays unambiguous.

Structure Module

class melody_engine.structure.TimeSignature(beats_per_bar: 'int', beat_unit: 'int')

Bases: object

beats_per_bar: int

beat_unit: int

classmethod from_string(value: str) → TimeSignature

property bar_length: float

class melody_engine.structure.NoteEvent(scale_step: 'int', duration: 'float', chromatic_adjustment: 'int' = 0, is_rest: 'bool' = False)

Bases: object

scale_step: int

duration: float

chromatic_adjustment: int = 0

is_rest: bool = False

transpose_diatonic(step_shift: int) → NoteEvent

class melody_engine.structure.NoteCandidate(scale_step: 'int', chromatic_adjustment: 'int' = 0, is_rest: 'bool' = False)

Bases: object

scale_step: int

chromatic_adjustment: int = 0

is_rest: bool = False

class melody_engine.structure.VoiceProfile(name: 'str', range_min: 'int', range_max: 'int', tessitura_min: 'int', tessitura_max: 'int', clef_hint: 'str | None' = None)

Bases: object

name: str

range_min: int

range_max: int

tessitura_min: int

tessitura_max: int

clef_hint: str | None = None

property melodic_span: int

class melody_engine.structure.FormSection(label: 'str', start_bar: 'int', end_bar: 'int', role: 'str', source_bar: 'int | None' = None, transform: 'str' = 'free')

Bases: object

label: str

start_bar: int

end_bar: int

role: str

source_bar: int | None = None

transform: str = 'free'

class melody_engine.structure.FormPlan(kind: 'str', sections: 'tuple[FormSection, ...]' = ())

Bases: object

kind: str

sections: tuple[FormSection, ...] = ()

section_for_bar(bar_number: int) → FormSection | None

class melody_engine.structure.ChoralePlan(voice_profiles: 'tuple[VoiceProfile, ...]' = ())

Bases: object

voice_profiles: tuple[VoiceProfile, ...] = ()

class melody_engine.structure.Motif(events: 'tuple[NoteEvent, ...]', name: 'str' = 'motif')

Bases: object

events: tuple[NoteEvent, ...]

name: str = 'motif'

classmethod from_steps(scale_steps: list[int], durations: list[float], name: str = 'motif') → Motif

property length: float

transpose_diatonic(step_shift: int) → Motif

class melody_engine.structure.HarmonySpan(start_bar: 'int', end_bar: 'int', roman_symbol: 'str', weight: 'float' = 1.0, start_beat: 'float' = 0.0, end_beat: 'float | None' = None)

Bases: object

start_bar: int

end_bar: int

roman_symbol: str

weight: float = 1.0

start_beat: float = 0.0

end_beat: float | None = None

covers(bar_number: int, beat_in_bar: float, bar_length: float) → bool

overlaps_bar(bar_number: int) → bool

class melody_engine.structure.HarmonyPlan(spans: 'tuple[HarmonySpan, ...]' = ())

Bases: object

spans: tuple[HarmonySpan, ...] = ()

chord_for_bar(bar_number: int) → HarmonySpan | None

chord_for_position(bar_number: int, beat_in_bar: float, bar_length: float) → HarmonySpan | None

class melody_engine.structure.Melody(key: 'Key', time_signature: 'TimeSignature', events: 'tuple[NoteEvent, ...]', harmony_plan: 'HarmonyPlan' = HarmonyPlan(spans=()), clef: 'str | None' = None, voice_profile: 'VoiceProfile' = VoiceProfile(name='melody', range_min=0, range_max=9, tessitura_min=1, tessitura_max=8, clef_hint=None), metadata: 'dict[str, object]' = <factory>)

Bases: object

key: Key

time_signature: TimeSignature

events: tuple[NoteEvent, ...]

harmony_plan: HarmonyPlan = HarmonyPlan(spans=())

clef: str | None = None

voice_profile: VoiceProfile = VoiceProfile(name='melody', range_min=0, range_max=9, tessitura_min=1, tessitura_max=8, clef_hint=None)

metadata: dict[str, object]

property pitched_events: tuple[NoteEvent, ...]

transpose_diatonic(step_shift: int) → Melody

transpose_parallel(new_key: Key) → Melody

class melody_engine.structure.ChoraleScore(key: 'Key', time_signature: 'TimeSignature', soprano: 'Melody', alto: 'Melody', tenor: 'Melody', bass: 'Melody', harmony_plan: 'HarmonyPlan' = <factory>, metadata: 'dict[str, object]' = <factory>)

Bases: object

key: Key

time_signature: TimeSignature

soprano: Melody

alto: Melody

tenor: Melody

bass: Melody

harmony_plan: HarmonyPlan

metadata: dict[str, object]

property voices: tuple[Melody, Melody, Melody, Melody]

class melody_engine.structure.GenerationSettings(key: 'Key', time_signature: 'TimeSignature', bars: 'int', allowed_durations: 'tuple[float, ...]' = (0.5, 1.0, 2.0), range_min: 'int' = 0, range_max: 'int' = 9, motif: 'Motif | None' = None, motif_repetition_bar: 'int | None' = None, motif_repetition_shift: 'int' = 1, harmonic_plan: 'HarmonyPlan' = HarmonyPlan(spans=()), phrase_length_bars: 'int' = 4, cadence_duration: 'float' = 2.0, attempts: 'int' = 48, random_seed: 'int' = 7, form_plan: 'FormPlan' = FormPlan(kind='free', sections=()), clef: 'str | None' = None, texture: 'str' = 'melody', voice_profile: 'VoiceProfile' = VoiceProfile(name='melody', range_min=0, range_max=9, tessitura_min=1, tessitura_max=8, clef_hint=None), chorale_plan: 'ChoralePlan' = ChoralePlan(voice_profiles=()))

Bases: object

key: Key

time_signature: TimeSignature

bars: int

allowed_durations: tuple[float, ...] = (0.5, 1.0, 2.0)

range_min: int = 0

range_max: int = 9

motif: Motif | None = None

motif_repetition_bar: int | None = None

motif_repetition_shift: int = 1

harmonic_plan: HarmonyPlan = HarmonyPlan(spans=())

phrase_length_bars: int = 4

cadence_duration: float = 2.0

attempts: int = 48

random_seed: int = 7

form_plan: FormPlan = FormPlan(kind='free', sections=())

clef: str | None = None

texture: str = 'melody'

voice_profile: VoiceProfile = VoiceProfile(name='melody', range_min=0, range_max=9, tessitura_min=1, tessitura_max=8, clef_hint=None)

chorale_plan: ChoralePlan = ChoralePlan(voice_profiles=())

Theory Module

melody_engine.theory.parse_pitch_class(note_name: str) → int

melody_engine.theory.accidental_suffix(accidental: int) → str

melody_engine.theory.accidental_value(symbol: str) → int

melody_engine.theory.lilypond_octave(octave: int) → str

melody_engine.theory.normalize_roman_symbol(symbol: str) → str

melody_engine.theory.roman_symbol_accidental(symbol: str) → int

melody_engine.theory.roman_symbol_quality(symbol: str) → str

melody_engine.theory.split_spelling(spelling: str) → tuple[str, int]

class melody_engine.theory.Key(tonic: 'str', mode: 'str' = 'major', tonic_octave: 'int' = 4)

Bases: object

tonic: str

mode: str = 'major'

tonic_octave: int = 4

property tonic_pitch_class: int

property scale_intervals: tuple[int, ...]

property scale_spellings: tuple[str, ...]

lilypond_pitch(scale_step: int) → str

chromatic_pitch(scale_step: int, chromatic_adjustment: int = 0) → str

absolute_midi(scale_step: int, chromatic_adjustment: int = 0) → int

scale_pitch_class(scale_step: int) → int

chord_tones(roman_symbol: str) → tuple[int, int, int]

chord_pitch_classes(roman_symbol: str) → tuple[int, int, int]

chord_scale_targets(roman_symbol: str) → tuple[tuple[int, int], tuple[int, int], tuple[int, int]]

Constraints Module

class melody_engine.constraints.CandidateContext(key: 'Key', events: 'tuple[NoteEvent, ...]', index: 'int', bar_number: 'int', beat_in_bar: 'float', total_events: 'int', climax_index: 'int', climax_step: 'int', phrase_end_bars: 'frozenset[int]', current_duration: 'float', harmony_span: 'HarmonySpan | None' = None, motif_target_step: 'int | None' = None, section_role: 'str' = 'free', section_transform: 'str' = 'free')

Bases: object

key: Key

events: tuple[NoteEvent, ...]

index: int

bar_number: int

beat_in_bar: float

total_events: int

climax_index: int

climax_step: int

phrase_end_bars: frozenset[int]

current_duration: float

harmony_span: HarmonySpan | None = None

motif_target_step: int | None = None

section_role: str = 'free'

section_transform: str = 'free'

property previous_event: NoteEvent | None

property previous_interval: int | None

property previous_pitched_event: NoteEvent | None

property previous_pitched_interval: int | None

property notes_since_last_rest: int

property candidate_is_final: bool

property on_strong_beat: bool

class melody_engine.constraints.SoftConstraint(*args, **kwargs)

Bases: Protocol

name: str

weight: float

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.StepwiseMotionConstraint(weight: 'float' = 1.0, name: 'str' = 'stepwise_motion')

Bases: object

weight: float = 1.0

name: str = 'stepwise_motion'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.LeapRecoveryConstraint(weight: 'float' = 1.0, name: 'str' = 'leap_recovery')

Bases: object

weight: float = 1.0

name: str = 'leap_recovery'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.LeadingToneResolutionConstraint(weight: 'float' = 1.0, name: 'str' = 'leading_tone_resolution')

Bases: object

weight: float = 1.0

name: str = 'leading_tone_resolution'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.ChordTonePreferenceConstraint(weight: 'float' = 1.0, non_chord_tone_penalty: 'float' = -0.35, name: 'str' = 'chord_tone_preference')

Bases: object

weight: float = 1.0

non_chord_tone_penalty: float = -0.35

name: str = 'chord_tone_preference'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.StrongBeatStabilityConstraint(weight: 'float' = 1.0, name: 'str' = 'strong_beat_stability')

Bases: object

weight: float = 1.0

name: str = 'strong_beat_stability'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.PhraseCadenceConstraint(weight: 'float' = 1.0, name: 'str' = 'phrase_cadence')

Bases: object

weight: float = 1.0

name: str = 'phrase_cadence'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.SingleClimaxConstraint(weight: 'float' = 1.0, name: 'str' = 'single_climax')

Bases: object

weight: float = 1.0

name: str = 'single_climax'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.MotifPreferenceConstraint(weight: 'float' = 1.0, name: 'str' = 'motif_preference')

Bases: object

weight: float = 1.0

name: str = 'motif_preference'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.RepeatedPitchConstraint(weight: 'float' = 1.0, name: 'str' = 'repeated_pitch_control')

Bases: object

weight: float = 1.0

name: str = 'repeated_pitch_control'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.DirectionChangeConstraint(weight: 'float' = 1.0, name: 'str' = 'direction_change')

Bases: object

weight: float = 1.0

name: str = 'direction_change'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.LargeLeapConstraint(weight: 'float' = 1.0, name: 'str' = 'large_leap')

Bases: object

weight: float = 1.0

name: str = 'large_leap'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.RestConstraint(weight: 'float' = 1.0, name: 'str' = 'rest_usage')

Bases: object

weight: float = 1.0

name: str = 'rest_usage'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

class melody_engine.constraints.FormSectionConstraint(weight: 'float' = 1.0, name: 'str' = 'form_section')

Bases: object

weight: float = 1.0

name: str = 'form_section'

evaluate(candidate: NoteCandidate, context: CandidateContext) → float

Generator Module

class melody_engine.generator.GenerationAttempt(events: 'tuple[NoteEvent, ...]', score: 'float')

Bases: object

events: tuple[NoteEvent, ...]

score: float

class melody_engine.generator.MelodyGenerator(settings: GenerationSettings, constraints: list[SoftConstraint])

Bases: object

generate() → Melody

LilyPond Module

melody_engine.lilypond.lilypond_duration(duration: float) → str

melody_engine.lilypond.lilypond_key_name(tonic: str) → str

melody_engine.lilypond.choose_clef(melody: Melody) → str

melody_engine.lilypond.melody_to_lilypond_source(melody: Melody) → str

melody_engine.lilypond.note_token(melody: Melody, event) → str

melody_engine.lilypond.voice_music_body(melody: Melody) → str

melody_engine.lilypond.export_melody(melody: Melody, output_path: str | Path) → Path

melody_engine.lilypond.chorale_to_lilypond_source(score: ChoraleScore) → str

melody_engine.lilypond.export_chorale(score: ChoraleScore, output_path: str | Path) → Path

melody_engine.lilypond.render_lilypond_file(source_path: str | Path, output_dir: str | Path | None = None, *, cropped: bool = False, lilypond_bin: str = 'lilypond') → list[Path]

melody_engine.lilypond.render_audio_from_midi(midi_path: str | Path, wav_path: str | Path | None = None, *, timidity_bin: str = 'timidity') → Path

melody_engine.lilypond.render_sources(sources: list[Path], *, output_dir: Path | None = None, pdf: bool = False, wav: bool = False, lilypond_bin: str = 'lilypond', timidity_bin: str = 'timidity') → list[Path]