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

Summary

Variable Summary Table

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

Actions Summary Table

ActionsDescription
AddTrack()Add a new track to this composition.
Close()Closes all of the resources being used by the Music instance.
Compare(Libraries.Language.Object object)This action compares two object hash codes and returns a CompareResult.
Equals(Libraries.Language.Object object)This action determines if two objects are equal based on their hash code values.
GetHashCode()This action gets the hash code for an object.
GetInstrument(integer index)Returns the requested instrument.
GetInstruments()Returns an iterator containing all available instruments on the system.
GetTempo()Gets the current tempo of the song being created in beats per minute.
GetTicksPerWholeNote()Returns the number of midi "clock ticks" per whole note.
GetTrack(integer index)Gets the track at the specified index.
GetTracks()Get all the tracks from this song.
Play(Libraries.System.File file)Play the given MIDI file.
Play(integer note, number duration)Plays a note for the specified duration at maximum volume.
Play(Libraries.Sound.Chord chord)Plays a chord.
Play(integer note, number duration, number volume)Plays a note for the specified duration, at the given volume.
Play(Libraries.Sound.Note note)Plays a note.
PlaySong()Play the song that was constructed using the AddTrack() method.
SetInstrument(Libraries.Sound.Instrument instrument)Set the default instrument.
SetTempo(integer beatsPerMinute)Set the tempo of this song, specified in beats per minute.
Stop()Stops any currently playing music.

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.

Example Code

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()

Return

Libraries.Sound.Track: a new track

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 Code

use Libraries.Sound.Music
        Music muse
        muse:Close()

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns a CompareResult. The compare result is either larger if this hash code is larger than the object passed as a parameter, smaller, or equal.

Example Code

use Libraries.Language.Support.CompareResult
        Object o
        Object t
        CompareResult result = o:Compare(t)

Parameters

Return

Libraries.Language.Support.CompareResult: The Compare result, Smaller, Equal, or Larger.

Equals(Libraries.Language.Object object)

This action determines if two objects are equal based on their hash code values.

Example Code

use Libraries.Language.Object
        use Libraries.Language.Types.Text
        Object o
        Text t
        boolean result = o:Equals(t)

Parameters

Return

boolean: True if the hash codes are equal and false if they are not equal.

GetHashCode()

This action gets the hash code for an object.

Example Code

Object o
        integer hash = o:GetHashCode()

Return

integer: The integer hash code of the object.

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

Example Code

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()

Parameters

Return

Libraries.Sound.Instrument: the requested instrument

GetInstruments()

Returns an iterator containing all available instruments on the system.

Example Code

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

Return

Libraries.Containers.Iterator: the available instruments.

GetTempo()

Gets the current tempo of the song being created in beats per minute. The default tempo is 120 bpm.

Example Code

use Libraries.Sound.Music
        Music muse
        output "The tempo is " + muse:GetTempo() + " beats per minute."

Return

integer:

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.

Example Code

use Libraries.Sound.Music
        use Libraries.Sound.Track
        Music muse
        Track myTrack = muse:AddTrack()
        Track aCopyOfMyTrack = muse:GetTrack(0)

Parameters

Return

Libraries.Sound.Track: the requested track

GetTracks()

Get all the tracks from this song.

Example Code

use Libraries.Sound.Music
        use Libraries.Sound.Track
        use Libraries.Containers.Iterator
        Music muse
        Iterator<Track> tracks = muse:GetTracks()

Return

Libraries.Containers.Iterator: an iterator containing all tracks (if any).

Play(Libraries.System.File file)

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

Example Code

use Libraries.Sound.Music
        use Libraries.System.File
        Music muse
        File file
        muse:Play(file)

Parameters

Play(integer note, number duration)

Plays a note for the specified duration at maximum volume.

Example Code

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

Parameters

Play(Libraries.Sound.Chord chord)

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

Example Code

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)

Parameters

Play(integer note, number duration, number volume)

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

Example Code

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

Parameters

Play(Libraries.Sound.Note note)

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

Example Code

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

Parameters

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 Code

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.

Example Code

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)

Parameters

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).

Example Code

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

Parameters

Stop()

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