Rendering and playback

MIDI

Convert Paeonia model objects into MIDI messages and files.

paeonia.midi.note_to_midi_messages(note, *, offset=0, tpb=480)[source]

Convert one untied event to MIDI note messages.

For chords, accumulated silence is attached only to the first note_on and sounding duration only to the first note_off. This keeps simultaneous chord pitches simultaneous in MIDI delta time.

Tie interpretation deliberately happens in bar or voice conversion, where adjacent events are available.

Parameters:

  • note (Note)

  • offset (int)

  • tpb (int)

Return type:

list[Message]

paeonia.midi.bar_to_midi_messages(bar, *, offset=0, tpb=480, channel=0)[source]

Convert a bar and return its messages plus trailing silent ticks.

Parameters:

  • bar (Bar)

  • offset (int)

  • tpb (int)

  • channel (int)

Return type:

tuple[list[Message], int]

paeonia.midi.voice_to_midi_messages(voice, *, tpb=480, channel=0)[source]

Convert a voice while preserving timing and ties across its bars.

Parameters:

  • voice (Voice)

  • tpb (int)

  • channel (int)

Return type:

list[Message]

paeonia.midi.tonality_to_midi_key(tonality)[source]

Return a standard MIDI key name when the tonality is representable.

Parameters:

tonality (Tonality | None)

Return type:

str | None

paeonia.midi.score_to_midi(score, *, tpb=480, allow_unaligned=False)[source]

Build a type-1 MIDI file for a score without touching the filesystem.

Parameters:

  • score (Score)

  • tpb (int)

  • allow_unaligned (bool)

Return type:

MidiFile

paeonia.midi.score_to_midi_file(score, *, path, tpb=480, allow_unaligned=False)[source]

Render score and save it to path.

Parameters:

  • score (Score)

  • path (str | Path)

  • tpb (int)

  • allow_unaligned (bool)

Return type:

None

paeonia.midi.messages_to_temporary_midi_file(messages, *, tpb=480)[source]

Write messages to a caller-owned temporary MIDI path.

Parameters:

  • messages (Iterable[Message | MetaMessage])

  • tpb (int)

Return type:

str

LilyPond

Render Paeonia model objects as spelling-aware LilyPond notation.

paeonia.lilypond.pitch_class_to_lilypond(pitch_class)[source]

Render a spelled pitch class, including arbitrary accidentals.

Parameters:

pitch_class (PitchClass)

Return type:

str

paeonia.lilypond.pitch_to_lilypond(pitch)[source]

Render a pitch using its spelling and explicit octave.

Parameters:

pitch (Pitch)

Return type:

str

paeonia.lilypond.duration_to_lilypond(duration)[source]

Render an exact whole-note duration with at most two dots.

Parameters:

duration (Fraction)

Return type:

str

paeonia.lilypond.note_to_lilypond(note)[source]

Render one note, chord, or rest, including an outgoing tie.

Parameters:

note (Note)

Return type:

str

paeonia.lilypond.bar_to_lilypond(bar)[source]

Render all events in a bar in order.

Parameters:

bar (Bar)

Return type:

str

paeonia.lilypond.tonality_to_lilypond(tonality)[source]

Render a LilyPond key command for a supported tonality.

Parameters:

tonality (Tonality)

Return type:

str

paeonia.lilypond.voice_to_lilypond(voice, *, inherited=None, inherited_plan=None)[source]

Render a voice and emit key commands only when tonality changes.

Parameters:
Return type:

str

paeonia.lilypond.score_to_lilypond(score, *, bar_numbers=True, analysis=False)[source]

Render an aligned score as a complete LilyPond score expression.

Bar numbers are shown at every measure by default, including the first measure and measures between system breaks. Pass bar_numbers=False to retain LilyPond’s standard bar-number visibility. analysis=True adds a readable composition-oriented analysis overlay; pass an AnalysisRenderOptions for finer control.

Parameters:
Return type:

str

Playback

External rendering, playback, downloading, and notebook display helpers.

paeonia.playback.download_soundfont()[source]

Return the local GM soundfont, downloading it only when requested.

The user cache directory ~/.paeonia is created lazily by this function, never by importing Paeonia or constructing model objects.

Return type:

Path

paeonia.playback.play_midi(midi, *, autoplay=False)[source]

Render a MIDI object with FluidSynth and display the resulting audio.

Parameters:

  • midi (MidiFile)

  • autoplay (bool)

Return type:

None

paeonia.playback.play_note(note, *, tpb=480, autoplay=False)[source]

Render and play one note or chord.

Parameters:

  • note (Note)

  • tpb (int)

  • autoplay (bool)

Return type:

None

paeonia.playback.play_bar(bar, *, tpb=480, autoplay=False)[source]

Render and play one bar.

Parameters:

  • bar (Bar)

  • tpb (int)

  • autoplay (bool)

Return type:

None

paeonia.playback.play_voice(voice, *, tpb=480, autoplay=False)[source]

Render and play a voice, including ties across bar boundaries.

Parameters:

  • voice (Voice)

  • tpb (int)

  • autoplay (bool)

Return type:

None

paeonia.playback.play_score(score, *, tpb=480, autoplay=False, allow_unaligned=False)[source]

Render and play a complete score.

Parameters:

  • score (Score)

  • tpb (int)

  • autoplay (bool)

  • allow_unaligned (bool)

Return type:

None

paeonia.playback.show_note(note)[source]

Render and display one note or chord with LilyPond.

Parameters:

note (Note)

Return type:

None

paeonia.playback.show_bar(bar)[source]

Render and display one bar with LilyPond.

Parameters:

bar (Bar)

Return type:

None

paeonia.playback.show_voice(voice)[source]

Render and display one voice with LilyPond.

Parameters:

voice (Voice)

Return type:

None

paeonia.playback.show_score(score, *, bar_numbers=True, analysis=False)[source]

Render and display a score with optional analytical annotations.

Parameters:
Return type:

None