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

VariablesDescription
integer breveA note with two times the duration of a whole note.
integer halfNoteA note with half the duration of a whole note.
integer sixtyFourthNoteA note with a sixty-fourth the duration of a whole note.
integer wholeNoteA whole note.
integer eighthNoteA note with an eighth the duration of a whole note.
integer sixteenthNoteA note with a sixteenth the duration of a whole note.
integer thirtySecondthNoteA note with a thirty-second the duration of a whole note.
integer quarterNoteA note with a quarter the duration of 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

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

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)

Play the given MIDI file. See the "Stop" method to stop playback.

Parameters

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

Play(Libraries.Sound.Chord chord)

Plays a chord. See the "Chord" class for specifics on how to use these objects.

Parameters

Example

use Libraries.Sound.Music
use Libraries.Sound.Chord
Music muse
Chord chord
// Play a major C chord.
chord:Add(60)
chord:Add(64)
chord:Add(72)
chord:SetLength(muse:quarterNote)

muse:Play(chord)

Play(integer note, number duration, number volume)

Plays a note for the specified duration, at the given volume.

Parameters

  • integer note: the note number (0 to 127)
  • number duration: how long to play the note (in seconds)
  • number volume: the volume to play the note at (0 to 1).

Example

use Libraries.Sound.Music
Music muse
muse:Play(60, 1, 0.5) // middle C for 1 second, half volume

Play(Libraries.Sound.Note note)

Plays a note. See the "Note" class for specifics on how to use these objects.

Parameters

Example

use Libraries.Sound.Music
use Libraries.Sound.Note
Music muse
Note note
note:SetPitch(60)
note:SetLength(muse:quarterNote)
muse:Play(note)

PlaySong()

Play the song that was constructed using the AddTrack() method. A "song" consists of one or more tracks of notes and/or chords. If no tracks exist, this method will do nothing. See the "Stop" method to stop playback.

Example

use Libraries.Sound.Music
use Libraries.Sound.Note
use Libraries.Sound.Chord
use Libraries.Sound.Track
// Play a simple C arpeggio followed by a C chord.

Music muse
Track t = muse:AddTrack()

Note n1
Note n2
Note n3
Chord c1
n1:SetPitch(60)
n2:SetPitch(64)
n3:SetPitch(67)
n2:SetStartTime(muse:quarterNote)
n3:SetStartTime(muse:quarterNote)
n1:SetLength(muse:quarterNote)
n2:SetLength(muse:quarterNote)
n3:SetLength(muse:quarterNote)
c1:Add(60)
c1:Add(64)
c1:Add(67)
c1:SetStartTime(muse:quarterNote)
c1:SetLength(muse:breve)
t:Add(n1)
t:Add(n2)
t:Add(n3)
t:Add(c1)
muse:PlaySong()

SetInstrument(Libraries.Sound.Instrument instrument)

Set the default instrument. This will affect any new created track (it will be set to this instrument), and it will also affect the instrument used for the various Play() actions.

Parameters

Example

use Libraries.Sound.Music
use Libraries.Sound.Instrument
Music muse

// Select a different instrument and set it as the default, then play a note.
Instrument i = muse:GetInstrument(10)
muse:SetInstrument(i)
muse:Play(60, 1)

SetTempo(integer beatsPerMinute)

Set the tempo of this song, specified in beats per minute. The default tempo is 120 beats per minute. Note that this will only affect the PlaySong() action and the Play() actions that accept a relative time value (such as quarterNote).

Parameters

  • integer beatsPerMinute: the tempo of the song, in beats per minute.

Example

use Libraries.Sound.Music
Music muse
muse:SetTempo(240) // speed it up

Stop()

Stops any currently playing music. This includes individual notes, individual chords, created songs and MIDI files.