Note-Level API

Last modified: Jul 3, 2018 @ 12:02 pm

This page gives a list of important datatypes and functions in Euterpea for working with music at the “note level,” or roughly at the level of a paper score. For more information on the functions, types, and type classes listed here, please see the Haskell School of Music textbook or, from GHCi with Euterpea imported, type the following:

:i nameYouWantToKnowAbout

 

Music Types and Type Classes

Type/ClassDescription
PrimitiveA Note or a Rest.
Music aPolymorphic structure for representing music.
Note1Type Synonym for (Pitch, [NoteAttribute]).
Music1Type synonym for Music1 or Music (Pitch, [NoteAttribute]).
ToMusic1Type class with one function, toMusic1, for converting to Music1. Instances are included for Pitch, (Pitch, Volume), AbsPitch, (AbsPitch, Volume), and Note1. The ToMusic1 type class is required for the play function.
PitchClassRepresentation of pitch classes.
OctaveType synonym for Int.
PitchType synonym for (PitchClass, Octave)
AbsPitchType synonym for Int.
ControlFor use with Music's Modify constructor.
ModeTonality. Currently only Major and Minor are supported.
InstrumentNameFor GM instruments.
PhraseAttributeFor use with Control.
NoteAttributeFor use with Music1.
MEventEvent representation for notes. Used in conversion from Music to MIDI.
PerformanceType synonym for [MEvent]

Playback Functions and Types

FunctionDescription
playPlay a Music value to the default MIDI output device. Supports infinitely long Music values.
playDevPlay a Music value to a custom MIDI output device. Supports infinitely long Music values.
playSPlay a finite Music value to the default MIDI output device with strict timing.
playDevSPlay a finite Music value to a custom MIDI output device with strict timing.
playCCustom playback using the PlayParams data structure.
devicesPrint a list of available MIDI devices and their corresponding device numbers.
PlayParamsRecord type to control playback behavior with playC.

Note: the play function is lazy and does not guarantee correct timing. For more information on the implementation of play and playS, please see this post on the subject.

Music Manipulation

FunctionDescription
noteCreates a single Note.
restCreates a single Rest.
linePut a list of music values together sequentially.
line1Like line but requires a non-empty list and does not add any zero-length rests.
chordPut a list of music values together in parallel.
chord1Like chord but requires a non-empty list and does not add any zero-length rests.
lineToListOpposite of line.
invertInverts (flips upside down) a Music Pitch value around its first pitch.
invert1Like invert but for Music (Pitch, a).
invertAtInverts a Music Pitch value around a specified Pitch.
invertAt1Like invertAt but for Music (Pitch, a).
retroReverses a Music value.
invertRetroPerforms retrograde then inversion.
retroInvertPerforms inversion then retrograde.
offsetDelay a the onset of a Music value.
timesRepeat a Music value sequentially for a fixed number of times.
foreverRepeat a Music value infinitely.
cutTake a finite portion of Music from the front of the value.
removeRemove a finite portion from the front of a Music value.
removeZerosStrip zero-duration constructs from a Music value.
mMapLike map but over Music values. Operates over all "a" portions of a "Music a"
mFoldLike fold but over Music values.
transposeAdds a Transpose modifier.
tempoAdds a Tempo modifier.
instrumentAdds an Instrument modifier.
phraseAdds a Phrase modifier.
keysigAdds a KeySig modifier.
shiftPitchesShifts all pitches in a Music Pitch value by the specified amount.
shiftPitches1Shifts all pitches in a Music(Pitch,x) value by the specified amount.
scaleDurationsAlters the durations of a Music value.
changeInstrumentChanges the instrument of a Music value and Removes any nested Instrument modifiers.
removeInstrumentsStrips all Instrument modifiers from a Music value.
percCreates a note wrapped with the Percussion instrument.

MIDI Conversion Functions

FunctionDescription
performConverts a Music value to a Performance. Requires an instance of ToMusic1.
toMidiConverts a Performance to a Midi value.
exportMidiFileWrites a Midi value to a file.
writeMidiWrites a Music value to a MIDI file. Requites a ToMusic1 instance.
importFileReads a MIDI file to a Midi value.
fromMidiConverts a Midi value to a Music1 value.

Extra MIDI-Related Functions

Function NameModuleDescription
restructureEuterpea.IO.MIDI.FromMidi2Attempts to group musical features by obvious chords, melodies, and so on. The restructure function can be used on Music values that have been read in from MIDI files (the default representation for which is all notes combined in parallel with rests).
writeMidi2Euterpea.IO.MIDI.ToMidi2Allows exporting of MIDI files where more than one track can have the same instrument. To use this, all Instrument assignments must be done using CustomInstrument with a String of the format "GMName UniqueID" (for example: "Flute A")