Instrument (Midica 1.5.4

java.lang.Object
- org.midica.file.Instrument

All Implemented Interfaces:

java.lang.Comparable<Instrument>
```
public class Instrument
extends java.lang.Object
implements java.lang.Comparable<Instrument>
```
Objects of this class represent a specific MIDI channel. They adjust their state according to the commands of the MidicaPLParser while parsing source files - or according to the commands of the MidicaPLExporter while exporting source files.

The following elements of a channel’s state need further explication:
- tickstamp - This is the current position of the parsed/exported file, counted in MIDI ticks.
- velocity - Velocity of key strokes.
- noteLength - Note length string, only used for compact syntax and for ALDA
- naturalLength - Note length without any block tuplets (only used for compact syntax)
- durationRatio - Ratio between key press duration and note length duration.
  Low values result in staccato, high values in legato.
  Minimum: >0.0 (>0%)
  Maximum: infinite (max possible float value)
Author:

Jan Trukenmüller

Field Summary

Fields
Modifier and Type	Field and Description
`boolean`	`autoChannel` Indicates if this channel has been automatically (true) or explicitly (false) defined.
`private int`	`bankLSB` LSB of the bank number (0-127)
`private int`	`bankMSB` MSB of the bank number (0-127)
`private int`	`barLineTolerance` current bar line tolerance
`int`	`channel` Channel number as defined by the MIDI specification.
`private long`	`currentTicks` Current tickstamp
`private static int`	`DEFAULT_BAR_LINE_TOLERANCE` Default tolerance for bar line checks in ticks.
`private static float`	`DEFAULT_DURATION_RATIO` Default duration ratio for this channel unless defined differently.
`private static java.lang.String`	`DEFAULT_NOTE_LENGTH`
`private static byte`	`DEFAULT_OCTAVE`
`private static int`	`DEFAULT_VELOCITY` Default velocity for this channel unless defined differently.
`private float`	`durationRatio` Ratio between key press duration and note length duration
`java.lang.String`	`instrumentName` Instrument name like it is read from the MidicaPL source file.
`int`	`instrumentNumber` Instrument number as defined by the MIDI specification.
`private java.util.HashMap<java.lang.Integer,java.lang.Long>`	`lastNoteOff` key = note; value = tickstamp of the last NOTE-OFF
`private java.util.HashMap<java.lang.Integer,java.lang.Long>`	`lastNoteOn` key = note; value = tickstamp of the last NOTE-ON
`private static int`	`MIN_CURRENT_TICKS` First tickstamp where any action can occur.
`private static long`	`MIN_NOTE_LENGTH` Minimum remaining note length after applying the duration ratio
`private java.lang.String`	`naturalLength` current note length for compact syntax WITHOUT block-tuplets
`private java.lang.String`	`noteLength` current note length for compact syntax or ALDA
`private byte`	`octave`
`private boolean`	`otoMultiple` one-time option for compact syntax: multiple
`private java.lang.Integer`	`otoQuantity` one-time option for compact syntax: quantity
`private java.lang.String`	`otoTremolo` one-time option for compact syntax: tremolo
`private java.lang.Long`	`stopTickForLegatoCorrection` If legato overlappings are detected while adding a note, this is the stop tick of the detected note to be corrected.
`private int`	`velocity` Current velocity

Constructor Summary

Constructors
Constructor and Description
`Instrument(int channel, int instrumentNumber, java.lang.String instrumentName, boolean automatic)` Creates a new Instrument object representing a channel during the parsing or export procedure of a MidicaPL source file.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`long`	`addNote(int note, int duration)` Increments the tickstamp according to the note’s duration in ticks.
`int`	`compareTo(Instrument other)`
`int`	`getBankLSB()` Returns the currently configured bank LSB.
`int`	`getBankMSB()` Returns the currently configured bank MSB.
`int`	`getBarLineTolerance()` Returns the currently configured bar line tolerance.
`long`	`getCurrentTicks()` Returns the current tickstamp.
`float`	`getDurationRatio()` Returns the current duration ratio of the channel.
`static long`	`getMaxCurrentTicks(java.util.ArrayList<Instrument> instruments)` Returns the maximum tickstamp of all the channels.
`java.lang.String`	`getNaturalLength()` Returns the currently configured natural length.
`java.lang.String`	`getNoteLength()` Returns the currently configured note length.
`byte`	`getOctave()` Returns the currently configured octave.
`int`	`getOtoQuantity()` Returns the one-time quantity for compact syntax.
`java.lang.String`	`getOtoTremolo()` Returns the one-time tremolo value for compact syntax, if set.
`java.lang.Long`	`getStopTickToCorrect()` Returns the stop tick of the note to be corrected due to legato overlappings, or null if no overlappings have been detected.
`int`	`getVelocity()` Returns the current velocity of the channel.
`void`	`incrementTicks(int duration)` Increments the tickstamp according to the note length duration.
`boolean`	`isOtoMultiple()` Determins if a one-time multiple option is set for compact syntax.
`void`	`reset()` Resets the current tickstamp and the data structures storing the last pressed notes.
`void`	`resetOto()` Resets all one-time option for compact syntax.
`boolean[]`	`setBank(int msb, int lsb)` Sets the bank.
`void`	`setBarLineTolerance(int barLineTolerance)` Sets the bar line tolerance.
`void`	`setCurrentTicks(long currentTicks)` Sets the current tickstamp.
`void`	`setDurationRatio(float durationRatio)` Sets a new key-press/note-length duration ratio.
`void`	`setNaturalLength(java.lang.String naturalLength)` Sets the natural length of the channel (note length without block tuplets).
`void`	`setNoteLength(java.lang.String noteLength)` Sets the note length of the channel.
`void`	`setOctave(byte octave)` Sets the octave of the channel.
`void`	`setOtoMultiple(boolean multiple)` Sets or resets the one-time multiple option for compact syntax.
`void`	`setOtoQuantity(int quantity)` Sets the one-time quantity for compact syntax.
`void`	`setOtoTremolo(java.lang.String tremolo)` Sets or resets the one-time tremolo value for compact syntax.
`void`	`setVelocity(int velocity)` Sets the velocity of the channel.
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - MIN_CURRENT_TICKS
```
private static final int MIN_CURRENT_TICKS
```
    First tickstamp where any action can occur.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_VELOCITY
```
private static final int DEFAULT_VELOCITY
```
    Default velocity for this channel unless defined differently.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_DURATION_RATIO
```
private static final float DEFAULT_DURATION_RATIO
```
    Default duration ratio for this channel unless defined differently.
    
    See Also:
    
    Constant Field Values
  - MIN_NOTE_LENGTH
```
private static final long MIN_NOTE_LENGTH
```
    Minimum remaining note length after applying the duration ratio
    
    See Also:
    
    Constant Field Values
  - DEFAULT_BAR_LINE_TOLERANCE
```
private static final int DEFAULT_BAR_LINE_TOLERANCE
```
    Default tolerance for bar line checks in ticks.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_OCTAVE
```
private static final byte DEFAULT_OCTAVE
```
    See Also:
    
    Constant Field Values
  - DEFAULT_NOTE_LENGTH
```
private static final java.lang.String DEFAULT_NOTE_LENGTH
```
    See Also:
    
    Constant Field Values
  - channel
```
public final int channel
```
    Channel number as defined by the MIDI specification. Between 0 and 15.
  - instrumentNumber
```
public int instrumentNumber
```
    Instrument number as defined by the MIDI specification. Between 0 and 127.
  - instrumentName
```
public java.lang.String instrumentName
```
    Instrument name like it is read from the MidicaPL source file.
  - autoChannel
```
public boolean autoChannel
```
    Indicates if this channel has been automatically (true) or explicitly (false) defined.
  - bankMSB
```
private int bankMSB
```
    MSB of the bank number (0-127)
  - bankLSB
```
private int bankLSB
```
    LSB of the bank number (0-127)
  - lastNoteOn
```
private java.util.HashMap<java.lang.Integer,java.lang.Long> lastNoteOn
```
    key = note; value = tickstamp of the last NOTE-ON
  - lastNoteOff
```
private java.util.HashMap<java.lang.Integer,java.lang.Long> lastNoteOff
```
    key = note; value = tickstamp of the last NOTE-OFF
  - stopTickForLegatoCorrection
```
private java.lang.Long stopTickForLegatoCorrection
```
    If legato overlappings are detected while adding a note, this is the stop tick of the detected note to be corrected. If no legato overlappings are detected, this is null.
  - velocity
```
private int velocity
```
    Current velocity
  - currentTicks
```
private long currentTicks
```
    Current tickstamp
  - durationRatio
```
private float durationRatio
```
    Ratio between key press duration and note length duration
  - noteLength
```
private java.lang.String noteLength
```
    current note length for compact syntax or ALDA
  - naturalLength
```
private java.lang.String naturalLength
```
    current note length for compact syntax WITHOUT block-tuplets
  - barLineTolerance
```
private int barLineTolerance
```
    current bar line tolerance
  - otoQuantity
```
private java.lang.Integer otoQuantity
```
    one-time option for compact syntax: quantity
  - otoTremolo
```
private java.lang.String otoTremolo
```
    one-time option for compact syntax: tremolo
  - otoMultiple
```
private boolean otoMultiple
```
    one-time option for compact syntax: multiple
  - octave
```
private byte octave
```
- Constructor Detail
  - Instrument
```
public Instrument(int channel,
                  int instrumentNumber,
                  java.lang.String instrumentName,
                  boolean automatic)
```
    Creates a new Instrument object representing a channel during the parsing or export procedure of a MidicaPL source file. While parsing this can be done explicitly inside the first INSTRUMENTS block or (if not defined in this block) when the first INSTRUMENTS block is left.
    
    Parameters:
    
    channel - Channel number as defined by the MIDI specification (0-15)
    
    instrumentNumber - Instrument number as defined by the MIDI specification (0-127)
    
    instrumentName - Instrument name as defined in the INSTRUMENTS command or (if not defined explicitly) the default channel comment (in the parsing procedure) or the pre-configured instrument name (in the export procedure)
    
    automatic - false, as soon as the instrument has been defined explicitly inside an INSTRUMENTS block; otherwise (or until the first definition inside an INSTRUMENTS block): true
- Method Detail
  - compareTo
```
public int compareTo(Instrument other)
```
    Specified by:
    
    compareTo in interface java.lang.Comparable<Instrument>
  - getVelocity
```
public int getVelocity()
```
    Returns the current velocity of the channel.
    
    Returns:
    
    current velocity
  - setVelocity
```
public void setVelocity(int velocity)
```
    Sets the velocity of the channel.
    
    Parameters:
    
    velocity - New velocity of the channel as defined in the MIDI specification. (0-127)
  - getCurrentTicks
```
public long getCurrentTicks()
```
    Returns the current tickstamp. This is the amount of MIDI ticks for which this channel has already been parsed so far.
    
    Returns:
    
    Current tickstamp
  - setCurrentTicks
```
public void setCurrentTicks(long currentTicks)
```
    Sets the current tickstamp. This is the amount of MIDI ticks for which this channel has already been parsed so far.
    
    Parameters:
    
    currentTicks - New tickstamp to be set.
  - reset
```
public void reset()
```
    Resets the current tickstamp and the data structures storing the last pressed notes.
    
    This is done during the initial instruments setup.
  - getDurationRatio
```
public float getDurationRatio()
```
    Returns the current duration ratio of the channel. This is the ratio between key press duration and note length duration. 0.1 means 10% (strong staccato)
    0.5 means 50% (staccato)
    1.0 means 100% (legato)
    more than 1.0 is overlapping legato
    
    Returns:
    
    Current duration ratio
  - setDurationRatio
```
public void setDurationRatio(float durationRatio)
```
    Sets a new key-press/note-length duration ratio.
    
    Parameters:
    
    durationRatio - New duration ratio.
  - addNote
```
public long addNote(int note,
                    int duration)
```
    Increments the tickstamp according to the note’s duration in ticks.
    
    Parameters:
    
    note - Note number.
    
    duration - Note length duration in ticks.
    
    Returns:
    
    Tickstamp for the key release according to note length duration and key press duration ratio.
  - getStopTickToCorrect
```
public java.lang.Long getStopTickToCorrect()
```
    Returns the stop tick of the note to be corrected due to legato overlappings, or null if no overlappings have been detected.
    
    Returns:
    
    the stop tick to be corrected or null.
  - incrementTicks
```
public void incrementTicks(int duration)
```
    Increments the tickstamp according to the note length duration.
    
    Parameters:
    
    duration - duration in ticks
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - getMaxCurrentTicks
```
public static long getMaxCurrentTicks(java.util.ArrayList<Instrument> instruments)
```
    Returns the maximum tickstamp of all the channels.
    
    Parameters:
    
    instruments - List of all Instrument objects.
    
    Returns:
    
    Maximum tickstamp
  - setBank
```
public boolean[] setBank(int msb,
                         int lsb)
```
    Sets the bank.
    
    Returns the following two values.
    - true, if the new MSB is different from the old MSB. false, if the MSB is unchanged.
    - true, if the new LSB is different from the old LSB. false, if the LSB is unchanged.
    Parameters:
    
    msb - bank MSB
    
    lsb - bank LSB
    
    Returns:
    
    What has been changed (see description above).
  - getBankMSB
```
public int getBankMSB()
```
    Returns the currently configured bank MSB.
    
    Returns:
    
    bank MSB
  - getBankLSB
```
public int getBankLSB()
```
    Returns the currently configured bank LSB.
    
    Returns:
    
    bank LSB
  - getOctave
```
public byte getOctave()
```
    Returns the currently configured octave.
    
    Returns:
    
    octave
  - setOctave
```
public void setOctave(byte octave)
```
    Sets the octave of the channel.
    
    Parameters:
    
    octave - New octave of the channel.
  - getNoteLength
```
public java.lang.String getNoteLength()
```
    Returns the currently configured note length.
    
    Returns:
    
    note length
  - setNoteLength
```
public void setNoteLength(java.lang.String noteLength)
```
    Sets the note length of the channel.
    
    Parameters:
    
    noteLength - New note length of the channel.
  - getNaturalLength
```
public java.lang.String getNaturalLength()
```
    Returns the currently configured natural length.
    
    Returns:
    
    note length without block tuplets
  - setNaturalLength
```
public void setNaturalLength(java.lang.String naturalLength)
```
    Sets the natural length of the channel (note length without block tuplets).
    
    Parameters:
    
    naturalLength - note length without block tuplets
  - getBarLineTolerance
```
public int getBarLineTolerance()
```
    Returns the currently configured bar line tolerance.
    
    Returns:
    
    bar line tolerance
  - setBarLineTolerance
```
public void setBarLineTolerance(int barLineTolerance)
```
    Sets the bar line tolerance.
    
    Parameters:
    
    barLineTolerance - bar line tolerance to be set.
  - getOtoQuantity
```
public int getOtoQuantity()
```
    Returns the one-time quantity for compact syntax. The default is 1.
    
    Returns:
    
    one-time quantity
  - setOtoQuantity
```
public void setOtoQuantity(int quantity)
                    throws ParseException
```
    Sets the one-time quantity for compact syntax.
    
    Parameters:
    
    quantity - number to set
    
    Throws:
    
    ParseException - if the option is already set
  - getOtoTremolo
```
public java.lang.String getOtoTremolo()
```
    Returns the one-time tremolo value for compact syntax, if set. Otherwise, returns null.
    
    Parameters:
    
    tremolo - one-time tremolo value or null
  - setOtoTremolo
```
public void setOtoTremolo(java.lang.String tremolo)
                   throws ParseException
```
    Sets or resets the one-time tremolo value for compact syntax.
    
    Parameters:
    
    tremolo - tremolo value to set, or null to reset
    
    Throws:
    
    ParseException - if the option is already set
  - isOtoMultiple
```
public boolean isOtoMultiple()
```
    Determins if a one-time multiple option is set for compact syntax.
    
    Returns:
    
    true or false
  - setOtoMultiple
```
public void setOtoMultiple(boolean multiple)
                    throws ParseException
```
    Sets or resets the one-time multiple option for compact syntax.
    
    Parameters:
    
    multiple - true to set the multiple option, false to reset it.
    
    Throws:
    
    ParseException - if the option is already set
  - resetOto
```
public void resetOto()
```
    Resets all one-time option for compact syntax.

Class Instrument

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MIN_CURRENT_TICKS

DEFAULT_VELOCITY

DEFAULT_DURATION_RATIO

MIN_NOTE_LENGTH

DEFAULT_BAR_LINE_TOLERANCE

DEFAULT_OCTAVE

DEFAULT_NOTE_LENGTH

channel

instrumentNumber

instrumentName

autoChannel

bankMSB

bankLSB

lastNoteOn

lastNoteOff

stopTickForLegatoCorrection

velocity

currentTicks

durationRatio

noteLength

naturalLength

barLineTolerance

otoQuantity

otoTremolo

otoMultiple

octave

Constructor Detail

Instrument

Method Detail

compareTo

getVelocity

setVelocity

getCurrentTicks

setCurrentTicks

reset

getDurationRatio

setDurationRatio

addNote

getStopTickToCorrect

incrementTicks

toString

getMaxCurrentTicks

setBank

getBankMSB

getBankLSB

getOctave

setOctave

getNoteLength

setNoteLength

getNaturalLength

setNaturalLength

getBarLineTolerance

setBarLineTolerance

getOtoQuantity

setOtoQuantity

getOtoTremolo

setOtoTremolo

isOtoMultiple

setOtoMultiple

resetOto