net.charlesames.music.midi
Class MidiFile

java.lang.Object
  net.charlesames.utility.common.Disposable
      net.charlesames.music.midi.MidiEntity
          net.charlesames.music.midi.MidiFile

All Implemented Interfaces:

FileDocument, XmlFileDocument

public class MidiFile
extends MidiEntity
implements XmlFileDocument

The MidiFile class wraps the javax.sound.midi.Sequence class. A MidiFile instance manages a MidiDevice collection and a MidiTrack collection. Each MidiDevice instance manages a MidiChannel collection.

Author:

Charles Ames

Field Summary

static java.lang.String

FILE_EXTENSION Extension for MIDI files.

Constructor Summary

MidiFile()
Constructor for MidiFile instances.

Method Summary

MidiTrack	addMidiTrack(java.lang.String name, int id, javax.sound.midi.Track track) Add an existing Track to the current MidiFile.
MidiDevice	createMidiDevice(java.lang.String midiDeviceName) Create a new MidiDevice instance with the indicated device name.
MidiTrack	createMidiTrack(java.lang.String name) Create a MIDI track.
void	createSequence(float divisionType, int resolution, int fileType) Create an empty MIDI sequence.
void	dispose() Release resources engaged by this object, thus rendering it amenable to garbage collection.
java.util.List<XmlNodeError>	getErrors() Get the collection of errors generated during the most recent file load.
java.io.File	getFile() Get the file associated with this MidiFile.
int	getFileType() Get the MIDI file type.
java.util.Date	getLoadDate() Get the file load date.
MidiDevice	getMidiDevice(java.lang.String midiDeviceName) Search for the MIDI Device with the indicated name.
java.util.SortedMap<java.lang.String,MidiDevice>	getMidiDevices() Get the MIDI devices.
java.util.SortedMap<java.lang.Integer,MidiTrack>	getMidiTracksByID() Get the MIDI tracks in id order.
java.util.SortedMap<java.lang.String,MidiTrack>	getMidiTracksByName() Get the MIDI tracks in name order.
java.lang.String	getName() Get the MidiFile name.
javax.sound.midi.Sequence	getSequence() Get the MIDI data.
java.lang.String	getXmlDefaultNamespace() Get the XML default namespace.
java.lang.String	getXmlSchemaLocation() Get the schema location.
boolean	isDirty() Test if the document or any of its components has experienced a change which justifies saving to file.
boolean	isGeneralMidi() Getter for the GeneralMidi flag.
void	load() Load MIDI file data.
void	logError(org.w3c.dom.Node node, java.lang.String message) Handle an error encountered while loading this document.
void	makeDirty() Signal that the document has experienced a change which should be saved to the associated file.
void	save() Save MIDI file data.
void	setFile(java.io.File file) Associate a file with this MidiFile.
void	setGeneralMidi(boolean generalMidi) Setter for the GeneralMidi flag.

Methods inherited from class net.charlesames.music.midi.MidiEntity

getContainer, getID, setName

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FILE_EXTENSION

public static final java.lang.String FILE_EXTENSION

Extension for MIDI files.

See Also:

Constant Field Values

Constructor Detail

MidiFile

public MidiFile()

Constructor for MidiFile instances.

Throws:

javax.sound.midi.InvalidMidiDataException

Method Detail

getFile

public java.io.File getFile()

Get the file associated with this MidiFile.

Specified by:

getFile in interface FileDocument

Returns:

The current file.

setFile

public void setFile(java.io.File file)

Associate a file with this MidiFile.

Specified by:

setFile in interface FileDocument

Parameters:

file - The intended file.

getXmlDefaultNamespace

public java.lang.String getXmlDefaultNamespace()

Description copied from interface: XmlFileDocument

Get the XML default namespace.

Specified by:

getXmlDefaultNamespace in interface XmlFileDocument

Returns:

The XML default namespace.

getXmlSchemaLocation

public java.lang.String getXmlSchemaLocation()

Description copied from interface: XmlFileDocument

Get the schema location.

Specified by:

getXmlSchemaLocation in interface XmlFileDocument

Returns:

The schema location.

getFileType

public int getFileType()

Get the MIDI file type. There are two MIDI file types: 0 (single track) and 1 (multi-track).

Returns:

The MIDI file type.

load

public void load()

Load MIDI file data. This method calls javax.sound.midi.MidiSystem.getSequence() to acquire a javax.sound.midi.Sequence instance.

Specified by:

load in interface FileDocument

save

public void save()

Save MIDI file data. This method calls javax.sound.midi.MidiSystem.write() to export a javax.sound.midi.Sequence instance to a MIDI file.

Specified by:

save in interface FileDocument

getMidiTracksByName

public java.util.SortedMap<java.lang.String,MidiTrack> getMidiTracksByName()

Get the MIDI tracks in name order.

Returns:

A collection of MidiTrack instances, indexed by name;

getMidiTracksByID

public java.util.SortedMap<java.lang.Integer,MidiTrack> getMidiTracksByID()

Get the MIDI tracks in id order.

Returns:

A collection of MidiTrack instances, indexed by name;

getMidiDevices

public java.util.SortedMap<java.lang.String,MidiDevice> getMidiDevices()

Get the MIDI devices.

Returns:

A collection of MidiDevice instances, indexed by name.

getSequence

public javax.sound.midi.Sequence getSequence()

Get the MIDI data.

Returns:

A javax.sound.midi.Sequence instance.

createSequence

public void createSequence(float divisionType,
                           int resolution,
                           int fileType)
                    throws javax.sound.midi.InvalidMidiDataException

Create an empty MIDI sequence.

Parameters:

divisionType - The timing division type (PPQ or one of the SMPTE types).

resolution - The timing resolution.

fileType - 0 - Single Track; 1 - Multiple Tracks, Synchronous; 2 - Multiple Tracks, Asynchronous.

Throws:

javax.sound.midi.InvalidMidiDataException

createMidiTrack

public MidiTrack createMidiTrack(java.lang.String name)
                          throws javax.sound.midi.InvalidMidiDataException

Create a MIDI track. Uses javax.sound.midi.Sequence.createTrack() to create a javaxsound.midi.Track instance. Wraps the Track in a new MidiTrack instance, and adds the latter to the MidiFile instance's MidiTrack collection.

Parameters:

name - The track name.

Returns:

The newly created MidiTrack instance.

Throws:

javax.sound.midi.InvalidMidiDataException

addMidiTrack

public MidiTrack addMidiTrack(java.lang.String name,
                              int id,
                              javax.sound.midi.Track track)
                       throws javax.sound.midi.InvalidMidiDataException

Add an existing Track to the current MidiFile. Use this method after loading a MIDI file to bring the Sequence's tracks into the MidiFile structure.

Parameters:

name - The track name.

id - The track's unique numeric identifier.

track -

Returns:

A newly created MidiTrack instance which wraps the javax.sound.midi.Track.

Throws:

javax.sound.midi.InvalidMidiDataException

createMidiDevice

public MidiDevice createMidiDevice(java.lang.String midiDeviceName)

Create a new MidiDevice instance with the indicated device name.

Parameters:

midiDeviceName - The device name.

Returns:

The newly created MidiDevice instance.

getMidiDevice

public MidiDevice getMidiDevice(java.lang.String midiDeviceName)
                         throws javax.sound.midi.InvalidMidiDataException

Search for the MIDI Device with the indicated name.

Parameters:

midiDeviceName - The indicated name.

Returns:

A MidiDevice instance with the indicated name.

Throws:

javax.sound.midi.InvalidMidiDataException

dispose

public void dispose()

Description copied from class: Disposable

Release resources engaged by this object, thus rendering it amenable to garbage collection.

Specified by:

dispose in interface FileDocument

Overrides:

dispose in class MidiEntity

getName

public java.lang.String getName()

Get the MidiFile name.

Overrides:

getName in class MidiEntity

Returns:

The name of the associated file with its extension removed.

getLoadDate

public java.util.Date getLoadDate()

Description copied from interface: FileDocument

Get the file load date.

Specified by:

getLoadDate in interface FileDocument

Returns:

The file load date.

makeDirty

public void makeDirty()

Description copied from interface: FileDocument

Signal that the document has experienced a change which should be saved to the associated file.

Specified by:

makeDirty in interface FileDocument

isGeneralMidi

public boolean isGeneralMidi()

Getter for the GeneralMidi flag.

Returns:

The assigned GeneralMidi value.

setGeneralMidi

public void setGeneralMidi(boolean generalMidi)

Setter for the GeneralMidi flag.

Parameters:

generalMidi - The intended GeneralMidi value.

isDirty

public boolean isDirty()

Description copied from interface: FileDocument

Test if the document or any of its components has experienced a change which justifies saving to file.

Specified by:

isDirty in interface FileDocument

Returns:

True if a change has occurred; false otherwise.

getErrors

public java.util.List<XmlNodeError> getErrors()

Description copied from interface: XmlFileDocument

Get the collection of errors generated during the most recent file load.

Specified by:

getErrors in interface XmlFileDocument

Returns:

The collection of errors generated during the most recent file load.

logError

public void logError(org.w3c.dom.Node node,
                     java.lang.String message)

Description copied from interface: XmlFileDocument

Handle an error encountered while loading this document.

Specified by:

logError in interface XmlFileDocument

Parameters:

node - The XML node where this error was detected.

message - A text string describing the error.