FileDocCategorySizeDatePackage
JetPlayer.javaAPI DocAndroid 1.5 API24570Wed May 06 22:42:00 BST 2009android.media

JetPlayer

public class JetPlayer extends Object
JetPlayer provides access to JET content playback and control.

Please refer to the JET Creator User Manual for a presentation of the JET interactive music concept and how to use the JetCreator tool to create content to be player by JetPlayer.

Use of the JetPlayer class is based around the playback of a number of JET segments sequentially added to a playback FIFO queue. The rendering of the MIDI content stored in each segment can be dynamically affected by two mechanisms:

  • tracks in a segment can be muted or unmuted at any moment, individually or through a mask (to change the mute state of multiple tracks at once)
  • parts of tracks in a segment can be played at predefined points in the segment, in order to maintain synchronization with the other tracks in the segment. This is achieved through the notion of "clips", which can be triggered at any time, but that will play only at the right time, as authored in the corresponding JET file.
As a result of the rendering and playback of the JET segments, the user of the JetPlayer instance can receive notifications from the JET engine relative to:
  • the playback state,
  • the number of segments left to play in the queue,
  • application controller events (CC80-83) to mark points in the MIDI segments.
Use {@link #getJetPlayer()} to construct a JetPlayer instance. JetPlayer is a singleton class.

Fields Summary
private static int
MAXTRACKS
The maximum number of simultaneous tracks. Use {@link #getMaxTracks()} to access this value.
private static final int
JET_EVENT
private static final int
JET_USERID_UPDATE
private static final int
JET_NUMQUEUEDSEGMENT_UPDATE
private static final int
JET_PAUSE_UPDATE
private static final int
JET_EVENT_VAL_MASK
private static final int
JET_EVENT_CTRL_MASK
private static final int
JET_EVENT_CHAN_MASK
private static final int
JET_EVENT_TRACK_MASK
private static final int
JET_EVENT_SEG_MASK
private static final int
JET_EVENT_CTRL_SHIFT
private static final int
JET_EVENT_CHAN_SHIFT
private static final int
JET_EVENT_TRACK_SHIFT
private static final int
JET_EVENT_SEG_SHIFT
private static final int
JET_OUTPUT_RATE
private static final int
JET_OUTPUT_CHANNEL_CONFIG
private NativeEventHandler
mEventHandler
Handler for jet events and status updates coming from the native code
private android.os.Looper
mInitializationLooper
Looper associated with the thread that creates the AudioTrack instance
private final Object
mEventListenerLock
Lock to protect the event listener updates against event notifications
private OnJetEventListener
mJetEventListener
private static JetPlayer
singletonRef
private int
mNativePlayerInJavaObj
Accessed by native methods: provides access to C++ JetPlayer object
private static final String
TAG
Constructors Summary
private JetPlayer()


        // remember which looper is associated with the JetPlayer instanciation
        if ((mInitializationLooper = Looper.myLooper()) == null) {
            mInitializationLooper = Looper.getMainLooper();
        }
        
        int buffSizeInBytes = AudioTrack.getMinBufferSize(JET_OUTPUT_RATE,
                JET_OUTPUT_CHANNEL_CONFIG, AudioFormat.ENCODING_PCM_16BIT);
        
        if ((buffSizeInBytes != AudioTrack.ERROR) 
                && (buffSizeInBytes != AudioTrack.ERROR_BAD_VALUE)) {
                            
            native_setup(new WeakReference<JetPlayer>(this),
                    JetPlayer.getMaxTracks(),
                    // bytes to frame conversion: sample format is ENCODING_PCM_16BIT, 2 channels
                    // 1200 == minimum buffer size in frames on generation 1 hardware
                    Math.max(1200, buffSizeInBytes / 4));
        }
Methods Summary
public booleanclearQueue()
Empties the segment queue, and clears all clips that are scheduled for playback.

return
true if the queue was successfully cleared, false otherwise.

        return native_clearQueue();
public java.lang.Objectclone()
Cloning a JetPlayer instance is not supported. Calling clone() will generate an exception.

        // JetPlayer is a singleton class,
        // so you can't clone a JetPlayer instance
        throw new CloneNotSupportedException();
public booleancloseJetFile()
Closes the resource containing the JET content.

return
true if successfully closed, false otherwise.

        return native_closeJetFile();
protected voidfinalize()

 
        native_finalize();
public static android.media.JetPlayergetJetPlayer()
Factory method for the JetPlayer class.

return
the singleton JetPlayer instance

        if (singletonRef == null) {
            singletonRef = new JetPlayer();
        }
        return singletonRef;
public static intgetMaxTracks()
Returns the maximum number of simultaneous MIDI tracks supported by JetPlayer

        return JetPlayer.MAXTRACKS;
public booleanloadJetFile(java.lang.String path)
Loads a .jet file from a given path.

param
path the path to the .jet file, for instance "/sdcard/mygame/music.jet".
return
true if loading the .jet file was successful, false if loading failed.

        return native_loadJetFromFile(path);
public booleanloadJetFile(android.content.res.AssetFileDescriptor afd)
Loads a .jet file from an asset file descriptor.

param
afd the asset file descriptor.
return
true if loading the .jet file was successful, false if loading failed.

        long len = afd.getLength();
        if (len < 0) {
            throw new AndroidRuntimeException("no length for fd");
        }
        return native_loadJetFromFileD(
                afd.getFileDescriptor(), afd.getStartOffset(), len);
private static voidlogd(java.lang.String msg)

    
         
        Log.d(TAG, "[ android.media.JetPlayer ] " + msg);
private static voidloge(java.lang.String msg)

        Log.e(TAG, "[ android.media.JetPlayer ] " + msg);
private final native booleannative_clearQueue()

private final native booleannative_closeJetFile()
private final native voidnative_finalize()
private final native booleannative_loadJetFromFile(java.lang.String pathToJetFile)
private final native booleannative_loadJetFromFileD(java.io.FileDescriptor fd, long offset, long len)
private final native booleannative_pauseJet()
private final native booleannative_playJet()
private final native booleannative_queueJetSegment(int segmentNum, int libNum, int repeatCount, int transpose, int muteFlags, byte userID)
private final native booleannative_queueJetSegmentMuteArray(int segmentNum, int libNum, int repeatCount, int transpose, boolean[] muteArray, byte userID)
private final native voidnative_release()
private final native booleannative_setMuteArray(boolean[] muteArray, boolean sync)
private final native booleannative_setMuteFlag(int trackId, boolean muteFlag, boolean sync)
private final native booleannative_setMuteFlags(int muteFlags, boolean sync)
private final native booleannative_setup(java.lang.Object Jet_this, int maxTracks, int trackBufferSize)
private final native booleannative_triggerClip(int clipId)
public booleanpause()
Pauses the playback of the JET segment queue.
return
true if rendering and playback is successfully paused, false otherwise.
        return native_pauseJet();
    
public booleanplay()
Starts playing the JET segment queue.
return
true if rendering and playback is successfully started, false otherwise.
        return native_playJet();
    
private static voidpostEventFromNative(java.lang.Object jetplayer_ref, int what, int arg1, int arg2)
        //logd("Event posted from the native side: event="+ what + " args="+ arg1+" "+arg2);
        JetPlayer jet = (JetPlayer)((WeakReference)jetplayer_ref).get();

        if ((jet != null) && (jet.mEventHandler != null)) {
            Message m = 
                jet.mEventHandler.obtainMessage(what, arg1, arg2, null);
            jet.mEventHandler.sendMessage(m);
        }
        
    
public booleanqueueJetSegment(int segmentNum, int libNum, int repeatCount, int transpose, int muteFlags, byte userID)
Queues the specified segment in the JET queue.
param
segmentNum the identifier of the segment.
param
libNum the index of the sound bank associated with the segment. Use -1 to indicate
that no sound bank (DLS file) is associated with this segment, in which case JET will use
the General MIDI library.
param
repeatCount the number of times the segment will be repeated. 0 means the segment will
only play once. -1 means the segment will repeat indefinitely.
param
transpose the amount of pitch transposition. Set to 0 for normal playback.
Range is -12 to +12.
param
muteFlags a bitmask to specify which MIDI tracks will be muted during playback. Bit 0
affects track 0, bit 1 affects track 1 etc.
param
userID a value specified by the application that uniquely identifies the segment.
this value is received in the
{@link OnJetEventListener#onJetUserIdUpdate(JetPlayer, int, int)} event listener method.
Normally, the application will keep a byte value that is incremented each time a new
segment is queued up. This can be used to look up any special characteristics of that
track including trigger clips and mute flags.
return
true if the segment was successfully queued, false if the queue is full or if the
parameters are invalid.
        return native_queueJetSegment(segmentNum, libNum, repeatCount, 
                transpose, muteFlags, userID);
    
public booleanqueueJetSegmentMuteArray(int segmentNum, int libNum, int repeatCount, int transpose, boolean[] muteArray, byte userID)
Queues the specified segment in the JET queue.
param
segmentNum the identifier of the segment.
param
libNum the index of the soundbank associated with the segment. Use -1 to indicate that
no sound bank (DLS file) is associated with this segment, in which case JET will use
the General MIDI library.
param
repeatCount the number of times the segment will be repeated. 0 means the segment will
only play once. -1 means the segment will repeat indefinitely.
param
transpose the amount of pitch transposition. Set to 0 for normal playback.
Range is -12 to +12.
param
muteArray an array of booleans to specify which MIDI tracks will be muted during
playback. The value at index 0 affects track 0, value at index 1 affects track 1 etc.
The length of the array must be {@link #getMaxTracks()} for the call to succeed.
param
userID a value specified by the application that uniquely identifies the segment.
this value is received in the
{@link OnJetEventListener#onJetUserIdUpdate(JetPlayer, int, int)} event listener method.
Normally, the application will keep a byte value that is incremented each time a new
segment is queued up. This can be used to look up any special characteristics of that
track including trigger clips and mute flags.
return
true if the segment was successfully queued, false if the queue is full or if the
parameters are invalid.
        if (muteArray.length != JetPlayer.getMaxTracks()) {
            return false;
        }
        return native_queueJetSegmentMuteArray(segmentNum, libNum, repeatCount,
                transpose, muteArray, userID);
    
public voidrelease()
Stops the current JET playback, and releases all associated native resources.
The object can no longer be used and the reference should be set to null
after a call to release().
        native_release();
    
public voidsetEventListener(android.media.JetPlayer$OnJetEventListener listener)
Sets the listener JetPlayer notifies when a JET event is generated by the rendering and
playback engine.
Notifications will be received in the same thread as the one in which the JetPlayer
instance was created.
param
listener
        setEventListener(listener, null);
    
public voidsetEventListener(android.media.JetPlayer$OnJetEventListener listener, android.os.Handler handler)
Sets the listener JetPlayer notifies when a JET event is generated by the rendering and
playback engine.
Use this method to receive JET events in the Handler associated with another
thread than the one in which you created the JetPlayer instance.
param
listener
param
handler the Handler that will receive the event notification messages.
        synchronized(mEventListenerLock) {
            
            mJetEventListener = listener;
            
            if (listener != null) {
                if (handler != null) {
                    mEventHandler = new NativeEventHandler(this, handler.getLooper());
                } else {
                    // no given handler, use the looper the AudioTrack was created in
                    mEventHandler = new NativeEventHandler(this, mInitializationLooper);
                }
            } else {
                mEventHandler = null;
            }
            
        }
    
public booleansetMuteArray(boolean[] muteArray, boolean sync)
Modifies the mute flags for the current active segment.
param
muteArray an array of booleans to specify which MIDI tracks are muted. The value at
index 0 affects track 0, value at index 1 affects track 1 etc.
The length of the array must be {@link #getMaxTracks()} for the call to succeed.
param
sync if false, the new mute flags will be applied as soon as possible by the JET
render and playback engine. If true, the mute flags will be updated at the start of the
next segment. If the segment is repeated, the flags will take effect the next time
segment is repeated.
return
true if the mute flags were successfully updated, false otherwise.
        if(muteArray.length != JetPlayer.getMaxTracks())
            return false;
        return native_setMuteArray(muteArray, sync);
    
public booleansetMuteFlag(int trackId, boolean muteFlag, boolean sync)
Mutes or unmutes a single track.
param
trackId the index of the track to mute.
param
muteFlag set to true to mute, false to unmute.
param
sync if false, the new mute flags will be applied as soon as possible by the JET
render and playback engine. If true, the mute flag will be updated at the start of the
next segment. If the segment is repeated, the flag will take effect the next time
segment is repeated.
return
true if the mute flag was successfully updated, false otherwise.
        return native_setMuteFlag(trackId, muteFlag, sync);
    
public booleansetMuteFlags(int muteFlags, boolean sync)
Modifies the mute flags.
param
muteFlags a bitmask to specify which MIDI tracks are muted. Bit 0 affects track 0,
bit 1 affects track 1 etc.
param
sync if false, the new mute flags will be applied as soon as possible by the JET
render and playback engine. If true, the mute flags will be updated at the start of the
next segment. If the segment is repeated, the flags will take effect the next time
segment is repeated.
return
true if the mute flags were successfully updated, false otherwise.
        return native_setMuteFlags(muteFlags, sync);
    
public booleantriggerClip(int clipId)
Schedules the playback of a clip.
This will automatically update the mute flags in sync with the JET Clip Marker (controller
103). The parameter clipID must be in the range of 0-63. After the call to triggerClip, when
JET next encounters a controller event 103 with bits 0-5 of the value equal to clipID and
bit 6 set to 1, it will automatically unmute the track containing the controller event.
When JET encounters the complementary controller event 103 with bits 0-5 of the value equal
to clipID and bit 6 set to 0, it will mute the track again.
param
clipId the identifier of the clip to trigger.
return
true if the clip was successfully triggered, false otherwise.
        return native_triggerClip(clipId);