quicktime.std.music
Class TunePlayer

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

public final class TunePlayer
extends Component
implements quicktime.jdirect.QuickTimeLib

Corresponds to the TunePlayer component type.


Fields inherited from interface quicktime.jdirect.QuickTimeLib
JDirect_MacOSX, libraryInstance, name
 
Constructor Summary
TunePlayer()
          Opens the TunePlayer component.
 
Method Summary
static TunePlayer fromMusicMediaHandler(MusicMediaHandler mh, int index)
          Returns the TunePlayer that is responsible for rendering the music data that is contained within a particular music track.
 NoteChannel getIndexedNoteChannel(int index)
          Returns the note channel at the specified index.
 NoteAllocator getNoteAllocator()
          Returns the NoteAllocator that the tune player is using.
 int getNumberOfNoteChannels()
          Returns the number of note channels that the tune player is using.
 MixStateInfo getPartMix(int partNumber)
          Returns the current state of a part in a mix, its volume, balance, and mute/solo state.
 TuneStatus getStatus()
          Returns an initialised structure describing the state of the tune player.
 TimeBase getTimeBase()
          Returns the TunePlayer's current time Base.
 int getTimeScale()
          Returns the current time scale of the tune player, in units-per-second.
 float getVolume()
          Returns the volume of the sequence.
 void instant(TuneStatus tune, int tunePosition)
          Play the sequence of music events at a specified position.
 void preroll()
          Prepares the tune player by attempting to reserve note channels for each part in the sequence.
 void queue(MusicData tune, float tuneRate, int tuneStartPosition, int tuneStopPosition, int queueFlags)
          Places a sequence of music events into a queue to be played.
 void setBalance(int balance)
          Modifies the pan controller setting for a tune player.
 void setHeader(MusicData header)
          Prepares the tune player to accept subsequent music event sequences by defining one or more parts to be used by sequence Note events.
 void setHeaderWithSize(MusicData header, int size)
          Prepares the tune player to accept subsequence music events by defining one or more parts to be used.
 void setNoteChannels(NoteChannel[] noteChannelList)
          Prepares the tune player to accept music event sequences by allocating specified note channels for them.
 void setPartMix(int partNumber, float volume, float balance, int mixFlags)
          Alters the volume and the balance of the specified part, with the flags specifying special conditions.
 void setPartTranspose(int part, float transpose, int velocityShift)
          Modifies the pitch and velocity of every note of the specified part of a tune.
 void setSofter(boolean softer)
          Adjusts the volume to play at a generally softer value that was the normal value for QT 2_1, otherwise sets the volume to a normal level.
 void setSoundLocalization(SoundLocalization data)
          Passes sound localisation data to the tune player.
 void setTimeScale(int scale)
          Sets the time scale used by the tune player.
 void setVolume(float volume)
          Sets the volume for the entire sequence.
 void stop()
          Stops a currently playing sequence.
 void task()
          Call this method periodically to allow the tune player to perform tasks it must perform at foreground task time.
 void unroll()
          Releases any note channels that may have been allocated by previous calls to preroll.
 
Methods inherited from class quicktime.std.comp.Component
count
 
Methods inherited from class quicktime.std.comp.ComponentIdentifier
find, find, getInfo, toString
 
Methods inherited from class quicktime.QTObject
disposeQTObject, equals, ID
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TunePlayer

public TunePlayer()
           throws QTException
Opens the TunePlayer component.

QuickTime::OpenADefaultComponent

Method Detail

fromMusicMediaHandler

public static TunePlayer fromMusicMediaHandler(MusicMediaHandler mh,
                                               int index)
                                        throws StdQTException
Returns the TunePlayer that is responsible for rendering the music data that is contained within a particular music track. If the movie or this media is edited in any way then the returned TunePlayer becomes invalid and must be got again.

QuickTime::MusicMediaGetIndexedTunePlayer()

Parameters:
index - the index within the media.
See Also:
MusicMediaHandler.getIndexedTunePlayer(int)

setHeader

public void setHeader(MusicData header)
               throws StdQTException
Prepares the tune player to accept subsequent music event sequences by defining one or more parts to be used by sequence Note events.

QuickTime::TuneSetHeader

Parameters:
header - the tune header data

getTimeBase

public TimeBase getTimeBase()
                     throws StdQTException
Returns the TunePlayer's current time Base.

QuickTime::TuneGetTimeBase

Returns:
the TimeBase

setTimeScale

public void setTimeScale(int scale)
                  throws StdQTException
Sets the time scale used by the tune player.

QuickTime::TuneSetTimeScale

Parameters:
scale - the new scale

getTimeScale

public int getTimeScale()
                 throws StdQTException
Returns the current time scale of the tune player, in units-per-second.

QuickTime::TuneGetTimeScale

Returns:
the current scale

getNumberOfNoteChannels

public int getNumberOfNoteChannels()
                            throws StdQTException
Returns the number of note channels that the tune player is using.

QuickTime::TuneGetIndexedNoteChannel

Returns:
the number of note channels

getIndexedNoteChannel

public NoteChannel getIndexedNoteChannel(int index)
                                  throws StdQTException
Returns the note channel at the specified index.

QuickTime::TuneGetIndexedNoteChannel

Parameters:
index - the part for which you want the note channel
Returns:
the note channel

queue

public void queue(MusicData tune,
                  float tuneRate,
                  int tuneStartPosition,
                  int tuneStopPosition,
                  int queueFlags)
           throws StdQTException
Places a sequence of music events into a queue to be played.

QuickTime::TuneQueue

Parameters:
tune - the events to be played
tuneRate - the playback rate at which to play the events
tuneStartPosition - sequence starting time
tuneStopPosition - sequence ending time
queue - flags with details about how to play the queued tune events.

instant

public void instant(TuneStatus tune,
                    int tunePosition)
             throws StdQTException
Play the sequence of music events at a specified position.

QuickTime::TuneInstant

Parameters:
tune - the tune data is contained within the TuneStatus object
tunePosition - the position within tune sequence data in time units

getStatus

public TuneStatus getStatus()
                     throws StdQTException
Returns an initialised structure describing the state of the tune player.

QuickTime::TuneGetStatus

Returns:
a tune status object

stop

public void stop()
          throws StdQTException
Stops a currently playing sequence.

QuickTime::TuneStop


setVolume

public void setVolume(float volume)
               throws StdQTException
Sets the volume for the entire sequence.

QuickTime::TuneSetVolume

Parameters:
volume - the new volume

getVolume

public float getVolume()
                throws StdQTException
Returns the volume of the sequence.

QuickTime::TuneGetVolume

Returns:
the current volume

preroll

public void preroll()
             throws StdQTException
Prepares the tune player by attempting to reserve note channels for each part in the sequence.

QuickTime::TunePreroll


unroll

public void unroll()
            throws StdQTException
Releases any note channels that may have been allocated by previous calls to preroll.

QuickTime::TuneUnroll


setNoteChannels

public void setNoteChannels(NoteChannel[] noteChannelList)
                     throws StdQTException
Prepares the tune player to accept music event sequences by allocating specified note channels for them.

QuickTime::TuneSetNoteChannels

Parameters:
noteChannelList - the note channels to be set for the tune player

setPartTranspose

public void setPartTranspose(int part,
                             float transpose,
                             int velocityShift)
                      throws StdQTException
Modifies the pitch and velocity of every note of the specified part of a tune.

QuickTime::TuneSetPartTranspose

Parameters:
part - the part number for which you want the pitch and velocity changed
transpose - the value by which to modify the pitch of the note - can specify fractional tuning
velocityShift - a value to add to the velocity of each note played

getNoteAllocator

public NoteAllocator getNoteAllocator()
Returns the NoteAllocator that the tune player is using.

QuickTime::TuneGetNoteAllocator

Returns:
the note allocator

setSofter

public void setSofter(boolean softer)
               throws StdQTException
Adjusts the volume to play at a generally softer value that was the normal value for QT 2_1, otherwise sets the volume to a normal level.

QuickTime::TuneSetSofter

Parameters:
softer - if true it sets the overall volume to a softer level, if false sets it to normal

task

public void task()
          throws StdQTException
Call this method periodically to allow the tune player to perform tasks it must perform at foreground task time.

QuickTime::TuneTask


setBalance

public void setBalance(int balance)
                throws StdQTException
Modifies the pan controller setting for a tune player.

QuickTime::TuneSetBalance

Parameters:
balance - the new balance setting: range is -128 (left) to 127 (right)

setSoundLocalization

public void setSoundLocalization(SoundLocalization data)
                          throws StdQTException
Passes sound localisation data to the tune player.

QuickTime::TuneSetSoundLocalization

Parameters:
data - the sound localisation data

setHeaderWithSize

public void setHeaderWithSize(MusicData header,
                              int size)
                       throws StdQTException
Prepares the tune player to accept subsequence music events by defining one or more parts to be used. You specify the end of the header with the size parameter so that the parsing will not overflow if there is no end marker.

QuickTime::TuneSetHeaderWithSize

Parameters:
header - a list of general events
size - the size of the header in bytes

setPartMix

public void setPartMix(int partNumber,
                       float volume,
                       float balance,
                       int mixFlags)
                throws StdQTException
Alters the volume and the balance of the specified part, with the flags specifying special conditions.

QuickTime::TuneSetPartMix

Parameters:
partNumber - the part to effect
volume - the new volume of the specified part
balance - the new balance of the specified part
mixFlags - the mix flags that will apply to that part - mute or solo part.

getPartMix

public MixStateInfo getPartMix(int partNumber)
                        throws StdQTException
Returns the current state of a part in a mix, its volume, balance, and mute/solo state.

QuickTime::TuneGetPartMix

Parameters:
partNumber - the part number you require information about
Returns:
the mix state of a part