Libraries.Sound.Music Documentation
This class generates music from the Music Instrument Digital Interface (MIDI) standard. This class can be used to play invidual notes and individual chords, as well as used to compose multi-track songs. This class abstracts away much of the MIDI interface, greatly simplifying song composition. For song composition, see the Playable and Track classes, as well as the AddTrack() and PlaySong() methods of this class. Throughout this class and its related classes, individual pitches are represented by integers. "Middle C" is note 60. A recommend resource for understanding these numbers is the following page: http://tomscarff.110mb.com/midi_analyser/midi_note_numbers_for_octaves.htm This class also defines some constants that can be used throughout music-related classes. These constants include: breve, wholeNote, halfNote, quarterNote, eighthNote , sixteenthNote, thirtySecondthNote, sixtyFourthNote These constants can all be used to specify note start times and length. In addition, mathematical manipulation of these constants is permitted. For example, if we wanted a double whole note, we could type m:wholeNote*2, as well as m:breve.
Example Code
use Libraries.Sound.Music
Music music
//play me a chromatic scale
integer note = 60
repeat 12 times
music:Play(note, 0.25)
note = note + 1
end
Inherits from: Libraries.Language.Object
Variables Table
Variables | Description |
---|---|
integer halfNote | A note with half the duration of a whole note. |
integer thirtySecondthNote | A note with a thirty-second the duration of a whole note. |
integer eighthNote | A note with an eighth the duration of a whole note. |
integer sixtyFourthNote | A note with a sixty-fourth the duration of a whole note. |
integer quarterNote | A note with a quarter the duration of a whole note. |
integer breve | A note with two times the duration of a whole note. |
integer sixteenthNote | A note with a sixteenth the duration of a whole note. |
integer wholeNote | A whole note. |
Actions Documentation
AddTrack()
Add a new track to this composition. A new track is created (with the appropriate parameters) and returned. Notes can be added to this track to be played. See the PlaySong() action.
Return
Libraries.Sound.Track: a new track
Example
use Libraries.Sound.Music
use Libraries.Sound.Track
Music muse
// Add three tracks to our composition.
Track t1 = muse:AddTrack()
Track t2 = muse:AddTrack()
Track t3 = muse:AddTrack()
Close()
Closes all of the resources being used by the Music instance. This method *must* be called, or the program will not exit properly.
Example
use Libraries.Sound.Music
Music muse
muse:Close()
Compare(Libraries.Language.Object object)
This action compares two object hash codes and returns an integer. The result is larger if this hash code is larger than the object passed as a parameter, smaller, or equal. In this case, -1 means smaller, 0 means equal, and 1 means larger. This action was changed in Quorum 7 to return an integer, instead of a CompareResult object, because the previous implementation was causing efficiency issues.
Parameters
- Libraries.Language.Object: The object to compare to.
Return
integer: The Compare result, Smaller, Equal, or Larger.
Example
Object o
Object t
integer result = o:Compare(t) //1 (larger), 0 (equal), or -1 (smaller)
Equals(Libraries.Language.Object object)
This action determines if two objects are equal based on their hash code values.
Parameters
- Libraries.Language.Object: The to be compared.
Return
boolean: True if the hash codes are equal and false if they are not equal.
Example
use Libraries.Language.Object
use Libraries.Language.Types.Text
Object o
Text t
boolean result = o:Equals(t)
GetHashCode()
This action gets the hash code for an object.
Return
integer: The integer hash code of the object.
Example
Object o
integer hash = o:GetHashCode()
GetInstrument(integer index)
Returns the requested instrument. This instrument can be used to set the instrument of individual tracks, or of this Music object. The General MIDI specification defines a number of instruments which can be expected on most systems. For a complete list, see: http://www.midi.org/techspecs/gm1sound.php
Parameters
- integer index: the requested instrument number (zero based).
Return
Libraries.Sound.Instrument: the requested instrument
Example
use Libraries.Sound.Music
use Libraries.Sound.Instrument
Music muse
Instrument i = muse:GetInstrument(0) // get the default piano specified by the General MIDI standard.
output i:GetName()
GetInstruments()
Returns an iterator containing all available instruments on the system.
Return
Libraries.Containers.Iterator: the available instruments.
Example
use Libraries.Sound.Music
use Libraries.Sound.Instrument
use Libraries.Containers.Iterator
Music muse
Iterator<Instrument> instruments = muse:GetInstruments()
output "Here are all the available instruments:"
repeat while instruments:HasNext()
Instrument i = instruments:Next()
output i:GetName()
end
GetTempo()
Gets the current tempo of the song being created in beats per minute. The default tempo is 120 bpm.
Return
integer:
Example
use Libraries.Sound.Music
Music muse
output "The tempo is " + muse:GetTempo() + " beats per minute."
GetTicksPerWholeNote()
Returns the number of midi "clock ticks" per whole note. The MIDI specification uses clock ticks to keep all MIDI devices synchronized, and MIDI uses Pulses Per Quarter Note (PPQ) to clearly indicate to MIDI devices how long each note should last, based on the tempo and number of clock ticks it spans. In this implementation, Ticks Per Whole Note is used to simplify calculations. To get PPQ (if desired), simply divide the result by four. The default PPQ used by this class is 96, meaning the number of ticks per whole note is likely to be 384.
Return
integer: the number of clock ticks per whole note.
GetTrack(integer index)
Gets the track at the specified index.
Parameters
- integer index: the index of the requested track (zero based).
Return
Libraries.Sound.Track: the requested track
Example
use Libraries.Sound.Music
use Libraries.Sound.Track
Music muse
Track myTrack = muse:AddTrack()
Track aCopyOfMyTrack = muse:GetTrack(0)
GetTracks()
Get all the tracks from this song.
Return
Libraries.Containers.Iterator: an iterator containing all tracks (if any).
Example
use Libraries.Sound.Music
use Libraries.Sound.Track
use Libraries.Containers.Iterator
Music muse
Iterator<Track> tracks = muse:GetTracks()
Play(Libraries.System.File file)
Example
use Libraries.Sound.Music
use Libraries.System.File
Music muse
File file
muse:Play(file)
Play(integer note, number duration)
Plays a note for the specified duration at maximum volume.
Parameters
- integer note: the note number (0 to 127)
- number duration: how long to play the note (in seconds)
Example
use Libraries.Sound.Music
Music muse
muse:Play(60, 1) // middle C, for 1 second, full volume