quicktime.std.music
Class NoteChannel

java.lang.Object
  |
  +--quicktime.QTObject
        |
        +--quicktime.std.music.NoteChannel
All Implemented Interfaces:
quicktime.jdirect.InterfaceLib, quicktime.jdirect.PrimitivesLib, quicktime.jdirect.QuickTimeLib, quicktime.jdirect.SharedLibrary, com.apple.jdirect.SharedLibrary

public final class NoteChannel
extends QTObject
implements quicktime.jdirect.QuickTimeLib

Note channels are used to play notes. The application can either provide the NoteAllocator component for the NoteChanel or can allow the system to create a default one.


Field Summary
static float kMicroControllerResolution
          The smallest step that will effect a change in controller resolution
static float kMicrotonalResolution
          The smallest microtone is a semitone / 128.
 
Fields inherited from interface quicktime.jdirect.QuickTimeLib
JDirect_MacOSX, libraryInstance, name
 
Constructor Summary
NoteChannel(int gmNumber, int poly)
          Creates a new NoteChannel object with the request instrument and polyphony.
NoteChannel(NoteAllocator na, int gmNumber)
          Creates a new NoteChannel object.
NoteChannel(NoteAllocator na, NoteRequest nr)
          Creates a new NoteChannel object.
NoteChannel(NoteRequest nr)
          Creates a new NoteChannel object using the default NoteAllocator

QuickTime::NANewNoteChannel

 
Method Summary
 int findTone(ToneDescription td)
          Locate the best fitting instrument number for the given ToneDescription.
 float getController(int controllerNumber)
          Retrieves the current value for the specified controller The micro controller resolution is 128 steps (kMicroControllerResolution) per semitone.
 int getIndexInfo()
          Returns the index of the NoteAllocator of the MusicComponent that is used by this NoteChannel.
 int getKnob(int knobNumber)
          Returns the value of a knob for the note channel.
 MusicComponent getMusicComponent()
          Returns the Music component in use by the note channel.
 NoteAllocator getNoteAllocator()
          Returns the NoteAllocator that owns this NoteChannel
 NoteRequest getNoteRequest()
          Get the NoteRequest that corresponds to this NoteChannel.
 int getPartInfo()
          Returns the part number within the NoteChannel's MusicComponent that corresponds to this channel.
 void pickEditInstrument(java.lang.String prompt, int flags)
          Presents a user interface for changing the instrument used by the note channel.
 void playNote(float pitch, int velocity)
          Plays a musical note with given pitch and velocity.
 void playNoteCents(int noteNumber, int cents, int velocity)
          Plays a musical note with given pitch and velocity.
 void playNoteRaw(int pitch, int velocity)
          Plays a musical note with given pitch and velocity.
 void preroll()
          Will attempt to re-allocate the note channel if it was invalid previously.
 void reset()
          Turns off all currently sounding notes, and resets all controllers to their default values.
 void sendMIDI(MusicMIDIPacket mp)
          Get the NoteRequest that corresponds to this NoteChannel.
 void setAtomicInstrument(AtomicInstrument instrument, int flags)
          Initialises a note channel with an atomic instrument.
 void setBalance(int balance)
          Modifies the pan controller setting for the note channel.
 void setController(int controllerNumber, float controllerValue)
          Changes the specified controller to the specified value.
 void setControllerRaw(int controllerNumber, int controllerValue)
          Changes the specified controller to the specified value.
 void setInstrumentNumber(int instrumentNumber)
          Change the instrument setting to the specified instrument number.
 void setKnob(int knobNumber, int knobValue)
          Sets the value of a knob for the note channel.
 void setSoundLocalization(SoundLocalization slData)
          Passes sound localization data to a note channel.
 void setVolume(float volume)
          Sets the volume on the note channel.
 void unroll()
          Marks a note channel as available to be stolen.
 
Methods inherited from class quicktime.QTObject
disposeQTObject, equals, ID, toString
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

kMicrotonalResolution

public static final float kMicrotonalResolution
The smallest microtone is a semitone / 128. This constant expresses that value (1/128).

kMicroControllerResolution

public static final float kMicroControllerResolution
The smallest step that will effect a change in controller resolution
Constructor Detail

NoteChannel

public NoteChannel(int gmNumber,
                   int poly)
            throws QTException
Creates a new NoteChannel object with the request instrument and polyphony. This constructor will use the system created NoteAllocator, which can be retrieved if required, through the NoteChannel.getNoteAllocator() method once the NoteChannel is created.

QuickTime::NANewNoteChannel

Parameters:
na - the NoteAllocator component instance to use
nr - attributes of note request

NoteChannel

public NoteChannel(NoteRequest nr)
            throws QTException
Creates a new NoteChannel object using the default NoteAllocator

QuickTime::NANewNoteChannel

Parameters:
na - the NoteAllocator component instance to use
nr - attributes of note request

NoteChannel

public NoteChannel(NoteAllocator na,
                   NoteRequest nr)
            throws QTException
Creates a new NoteChannel object.

QuickTime::NANewNoteChannel

Parameters:
na - the NoteAllocator component instance to use
nr - attributes of note request

NoteChannel

public NoteChannel(NoteAllocator na,
                   int gmNumber)
            throws QTException
Creates a new NoteChannel object.

QuickTime::NANewNoteChannel



QuickTime::NAStuffToneDescription

Parameters:
na - the NoteAllocator component instance to use
gmNumber - the general MIDI number for the desired instrument
Method Detail

getNoteAllocator

public final NoteAllocator getNoteAllocator()
Returns the NoteAllocator that owns this NoteChannel

getIndexInfo

public final int getIndexInfo()
                       throws StdQTException
Returns the index of the NoteAllocator of the MusicComponent that is used by this NoteChannel.

QuickTime::NAGetNoteChannelInfo

Returns:
index

getPartInfo

public final int getPartInfo()
                      throws StdQTException
Returns the part number within the NoteChannel's MusicComponent that corresponds to this channel.

QuickTime::NAGetNoteChannelInfo

Returns:
part number

getMusicComponent

public MusicComponent getMusicComponent()
                                 throws StdQTException
Returns the Music component in use by the note channel.

QuickTime::NAGetNoteChannelInfo



QuickTime::NAGetRegisteredMusicDevice

Returns:
index

preroll

public final void preroll()
                   throws StdQTException
Will attempt to re-allocate the note channel if it was invalid previously.

QuickTime::NAPrerollNoteChannel


unroll

public final void unroll()
                  throws StdQTException
Marks a note channel as available to be stolen.

QuickTime::NAUnrollNoteChannel


reset

public final void reset()
                 throws StdQTException
Turns off all currently sounding notes, and resets all controllers to their default values.

QuickTime::NAResetNoteChannel


setVolume

public final void setVolume(float volume)
                     throws StdQTException
Sets the volume on the note channel.

QuickTime::NASetNoteChannelVolume

Parameters:
volume - volume value

setBalance

public final void setBalance(int balance)
                      throws StdQTException
Modifies the pan controller setting for the note channel.

QuickTime::NASetNoteChannelBalance

Parameters:
balance - pan value (-128 left, to 128 right)

playNoteRaw

public final void playNoteRaw(int pitch,
                              int velocity)
                       throws StdQTException
Plays a musical note with given pitch and velocity.

QuickTime::NAPlayNote

Parameters:
pitch - MIDI pitch values (0 to 127, 60 is middle C)
velocity - velocity of note, where 0 = silence - note off.

playNoteCents

public final void playNoteCents(int noteNumber,
                                int cents,
                                int velocity)
                         throws StdQTException
Plays a musical note with given pitch and velocity. The microtone resolution is 128 steps (kMicrotonalResolution) per semitone.

QuickTime::NAPlayNote

Parameters:
noteNumber - 0 -> 127 correspond to MIDI note numbers (60 is middle C).
cents - 0 -> 100 correspond to the division of a semitone into 100 logarithmically equal segments.
velocity - velocity of note, where 0 = silence - note off.

playNote

public final void playNote(float pitch,
                           int velocity)
                    throws StdQTException
Plays a musical note with given pitch and velocity. The microtone resolution is 128 steps (kMicrotonalResolution) per semitone.

QuickTime::NAPlayNote

Parameters:
pitch - 1.000 -> 127.999 correspond to MIDI note numbers (60 is middle C).
velocity - velocity of note, where 0 = silence - note off.

getController

public final float getController(int controllerNumber)
                          throws StdQTException
Retrieves the current value for the specified controller The micro controller resolution is 128 steps (kMicroControllerResolution) per semitone.

QuickTime::NAGetController

Parameters:
controllerNumber - which controller
controllerValue - the new controller value, range -128.000 to 127.999

setControllerRaw

public final void setControllerRaw(int controllerNumber,
                                   int controllerValue)
                            throws StdQTException
Changes the specified controller to the specified value.

QuickTime::NASetController

Parameters:
controllerNumber - which controller
controllerValue - the new controller value, dealing with raw controller values, which have the full range of a short (-32768 to 32767)

setController

public final void setController(int controllerNumber,
                                float controllerValue)
                         throws StdQTException
Changes the specified controller to the specified value. The micro controller resolution is 128 steps (kMicroControllerResolution) per semitone.

QuickTime::NASetController

Parameters:
controllerNumber - which controller
controllerValue - the new controller value, range -128.000 to 127.999

getKnob

public final int getKnob(int knobNumber)
                  throws StdQTException
Returns the value of a knob for the note channel.

QuickTime::NAGetKnob

Parameters:
knobNumber - index or ID of the knob
Returns:
the value of the knob

setKnob

public final void setKnob(int knobNumber,
                          int knobValue)
                   throws StdQTException
Sets the value of a knob for the note channel.

QuickTime::NASetKnob

Parameters:
knobNumber - index or ID of the knob
knobValue - the value of the knob

findTone

public final int findTone(ToneDescription td)
                   throws StdQTException
Locate the best fitting instrument number for the given ToneDescription.

QuickTime::NAFindNoteChannelTone

Parameters:
td - description for instrument fit
Returns:
the instrument index of fit

setAtomicInstrument

public final void setAtomicInstrument(AtomicInstrument instrument,
                                      int flags)
                               throws StdQTException
Initialises a note channel with an atomic instrument.

QuickTime::NASetAtomicInstrument

Parameters:
instrument - the AtomicInstrument to set the channel to.
flags - use the set flags from Atomic instrument.

setInstrumentNumber

public final void setInstrumentNumber(int instrumentNumber)
                               throws StdQTException
Change the instrument setting to the specified instrument number.

QuickTime::NASetInstrumentNumber

Parameters:
instrumentNumber - instrument number to apply

getNoteRequest

public final NoteRequest getNoteRequest()
                                 throws QTException
Get the NoteRequest that corresponds to this NoteChannel.

QuickTime::NAGetNoteRequest

Returns:
a new NoteRequest class with the parameters of this NoteChannel

pickEditInstrument

public final void pickEditInstrument(java.lang.String prompt,
                                     int flags)
                              throws StdQTException
Presents a user interface for changing the instrument used by the note channel.

QuickTime::NAPickEditInstrument

Parameters:
prompt - Dialog box prompt "New Instrument..."
flags - flags to limit user options

sendMIDI

public final void sendMIDI(MusicMIDIPacket mp)
                    throws StdQTException
Get the NoteRequest that corresponds to this NoteChannel.

QuickTime::NASendMIDI


setSoundLocalization

public final void setSoundLocalization(SoundLocalization slData)
                                throws StdQTException
Passes sound localization data to a note channel.

QuickTime::NASetNoteChannelSoundLocalization

Parameters:
slData - sound localization data