com.jblend.media
クラス MediaPlayer　＜Phase2.5＞

java.lang.Object
  |
  +--com.jblend.media.MediaPlayer

直系の既知のサブクラス:

HVscriptPlayer, SmafPlayer

public abstract class MediaPlayer

extends java.lang.Object

このクラスはすべてのメディアプレイヤーの基底となる抽象クラスです。

メディアデータ、およびメディアリソースを総称してメディアと呼びます。 また、MediaPlayerクラスのインスタンスをメディアプレイヤーと呼びます。

メディアプレイヤークラスはメディア種別ごとに定義されます。個々のメディアプレイヤーは必ずMediaPlayerクラスを継承して作成します。

Javaアプリケーションは再生するメディアに対応したプレイヤークラスのインスタンスを生成し、メディアの設定、再生、一時停止、再開などのためのメソッドで使用します。メディアの再生開始、一時停止、再生終了に同期したイベントを待ち受けるためには、MediaPlayerListenerオブジェクトを登録します。

• 1. メディアプレイヤーの使用法
• 2. メディアプレイヤーの生成・メディアの設定
• 3. メディアの再生
• 4. イベントの待ち受け

1. メディアプレイヤーの使用法

メディアプレイヤーはMIDPのCanvasやScreeenなどの画面表示用クラスとは独立に動作します。メディアプレイヤーを生成し再生させると、「現在のDisplayable」とは関係なくメディアの再生画面が表示されます。たとえばCanvasの派生クラスを画面表示している状態でメディアプレイヤーを再生させると、Canvasの派生クラスで描画した画面はメディアの再生画面で上書きされます。逆にメディアプレイヤーを再生開始したのちに、何らかのCanvas派生クラスでの画面描画を行うとメディアプレイヤーの表示領域は上書きされます。メディアが動画であればメディアプレイヤーはさらにその上に動画の画像を上書きします。

したがって、メディアプレイヤーの表示領域以外に何らかのグラフィックスを描画するには、プログラマがメディアプレイヤーの表示領域とCanvas継承クラスでの描画内容について画面上の位置関係を考慮しなくてはなりません。

また、Canvasはメディアプレイヤーの再生とは関係なく、低レベルイベント（キーイベント）やコマンドイベントをMIDletに通知します。メディアプレイヤーを再生させているときに、ユーザ操作によりメニュー画面が表示されるときには、メディアプレイヤーの再生がメニュー表示を阻害しないように配慮しなくてはなりません。具体的には、たとえばCanvasのhideNotify()およびshowNotify()の実装において、メディアプレイヤーの一時停止または再開などの制御が必要となります。

2. メディアプレイヤーの生成・メディアの設定

メディアデータ・メディアプレイヤーの生成

MIDletはメディアプレイヤークラス（MediaPlayer継承クラス）とメディアデータクラス（MediaData継承クラス）のオブジェクトを明示的に生成する必要があります。たとえば再生するメディアデータフォーマットがSMAFであれば、SmafDataオブジェクトとSmafPlayerオブジェクトをコンストラクタで生成します。生成時にはメディアのデータを指定します。MediaData継承クラスのそれぞれのコンストラクタには、メディアのデータをバイト配列で与えるものとリソースファイル名で指定するものの2種類が用意されています。

メディアプレイヤーを生成したら、setData()メソッドでメディアデータを設定します。setData()はバイト配列を設定するものと、メディアの種類に対応したオブジェクトを設定するものの2種類が用意されています。たとえば、SmafPlayerにはSmafDataオブジェクトをパラメータとして指定するsetData()が用意されています。

メディアサイズの取得

画像を含むメディアのメディアデータクラスのオブジェクトは、MediaImageOperatorインタフェースのgetWidth()およびgetHeight()メソッドでそれぞれメディアの幅と高さを取得可能です。また、画像を含むメディアのメディアプレイヤーにメディアデータが設定されていると、getMediaWidth()およびgetMediaHeight()でそれぞれメディアの幅と高さを取得可能です。

メディアが音声データのみからなり、画像データを含んでいない場合は、サイズ取得のためのメソッドは存在しません。再生時は画面上では何も表示されず、音声だけが再生されることになります。

メディア表示位置の設定

画像を表示するメディアプレイヤーは、ソフトキー領域を除いた端末の表示画面の任意の領域に配置できます。MediaPlayerクラスのフィールド値REAL_WIDTH、REAL_HEIGHT は、それぞれこの表示領域の幅と高さを表します。

メディアを表示画面にどのように表示するかをMediaImageOperatorインタフェースのsetOrigin()とsetBounds()で設定します。setOrigin()ではパラメータoffset_xとoffset_yでメディアの左上を原点としたプレイヤー表示領域の切り出し位置を指定します。setBounds()では表示画面中でのプレイヤー表示領域（位置：x,y、幅と高さ：width, height）を指定します 。図1にこの様子を示します。

図1. メディアプレイヤー表示位置設定

メディアのサイズは表示画面サイズに対して大きいことも小さいこともあります。図2にメディアのサイズとプレイヤーのサイズとの大小関係に応じた3種類の設定例を示します。

図2. メディアプレイヤー切り出し位置設定

1. メディアのサイズがプレイヤー表示領域より大きな場合、メディアの部分矩形領域を表示するように指定できます。図の例ではoffset_xおよびoffset_yはともに正の値で指定します。

2. メディアのサイズがプレイヤー表示領域より小さい場合、メディア全体を表示画面の中に配置できます。図の例ではoffset_xおよびoffset_yはともに負の値で指定します。

3. メディアの幅のみがプレイヤー表示領域の幅より大きい場合、図示したようにメディア中の矩形領域を表示する領域として指定できます。図の例ではoffset_xの値は正、offset_yの値は負の値で指定します。メディアの高さのみがプレイヤー表示領域の高さより大きい場合も同様に指定できます。

メディアの配置位置は任意です。図中の2）のような場合でも、メディアの全領域がプレイヤー領域に入るように指定しなくても問題ありません。プレイヤー領域中にあるメディアの部分が表示されます。

プレイヤー表示領域の切り出し位置、および表示画面中でのプレイヤー表示領域の設定値はメディアプレイヤーのメソッドで取得可能です。それぞれのパラメータに対する取得メソッドを表1に示します。

表1. 表示位置取得メソッド

パラメータ	メソッド
プレイヤー表示領域の切り出し位置　offset_x	getOriginX()
プレイヤー表示領域の切り出し位置　offset_y	getOriginY()
プレイヤー表示領域の表示画面中での位置　x	getX()
プレイヤー表示領域の表示画面中での位置　ｙ	getY()
プレイヤー表示領域の表示画面中での幅　width	getWidth()
プレイヤー表示領域の表示画面中での高さ　height	getHeight()

MIDletはデータの内部構造に関して理解する必要はありませんが、MediaPlayerオブジェクトがそのメディアデータを再生できない可能性を考慮する必要があります。再生できない場合は、メディアを設定した時点に例外がスローされます。

3. メディアの再生

再生・停止

メディアプレイヤーにメディアデータが設定されると、メディアの再生が可能な状態になります。ただし、この状態ではメディアはまだ表示されていません。メディアプレイヤーのplay()メソッドを呼び出すと、再生が開始されます。メディア中に画像データが埋め込まれている場合は、画面上に表示されます。play()メソッドでは下記のバージョンが用意されています。

• 一回再生する
• 繰り返し回数を指定して再生する
• 無限に再生を繰り返す

繰り返しを指定した場合は、メディアプレイヤーは、所定の再生を終了するか、停止、または一時停止を指示されるまで再生を繰り返します。ただし、メディアが静止画であった場合は繰り返しを要求しても一度だけの再生となります。

停止はstop()メソッドで、一時停止はpause()メソッドで行います。 再生中もsetOrigin()、およびsetBounds()で表示位置関連の変更が可能です。

一時停止・再開

再生中のメディアプレイヤーに対して、pause()メソッドで一時停止させることができます。再開は、resume()メソッドで行います。 一時停止中のメディアプレイヤーを停止するにはstop()メソッドを呼び出します。

エラー発生の検出

再生中のメディアプレイヤーに何らかのエラーが発生した場合、メディアプレイヤーはイベントを発生してエラー状態に遷移します。MediaPlayerListener（後述）によってイベントを検知して、かつgetState()メソッドによって状態を把握するようにしてください。そして、エラー状態に遷移したことを検出した場合はstop()メソッドによってエラー状態を解消する必要があります。エラー状態を解消すると、メディアプレイヤーは停止状態になり、別のメディアデータを設定するなどの操作が可能になります。

注意事項：

• 再生中、または一時停止中にメディアを設定しなおすと、IllegalStateException例外がスローされます。メディアの設定はメディアの再生を停止してから行ってください。
• 複数のメディアプレイヤーを再生することが可能です。ただし、音声メディアを再生するプレイヤーを複数同時に再生することはできません。この場合は、再生中のメディアプレイヤーを一時停止または停止してから別のプレイヤーを再生開始するようにしなくてはなりません。

4. イベントの待ち受け

MediaPlayerListenerは、メディアプレイヤーが発生するイベントを待ち受けるリスナを実装するためのインタフェースです。MediaPlayerListenerを実装したリスナは、メディアプレイヤークラスのaddMediaPlayerListener()メソッドでメディアプレイヤーに登録します。MediaPlayerListenerリスナのメソッドは下記のように呼び出されます。

• 再生の繰り返しが発生するとplayerRepeated()メソッドが呼び出されます
• メディアプレイヤーが再生を開始したとき、一時停止したとき、および停止したときplayerStateChanged()メソッドが呼び出されます。停止には、エラー発生による停止も含みます。

MediaPlayerListenerのplayerRepeated()およびplayerStateChanged()にはイベントが発生したメディアプレイヤーのインスタンスが指定されます。playerStateChanged()が呼び出されたときは、指定されたインスタンスのgetState()メソッドによってその時点のメディアプレイヤーの状態を問い合わせることができます。playerStateChanged()が呼び出された時点でgetState()が返す状態を表2に示します。

表2. メディアプレイヤー状態

状態	意味
NO_DATA	データ未設定
PLAYING	再生中
PAUSED	一時停止中
READY	停止中
ERROR	エラー発生により停止中

addMediaPlayerListener()でメディアプレイヤーに設定したリスナは、removeMediaPlayerListener()で登録解除することができます。

注意事項：

下記の場合はイベントは発生されません。

• 一時停止中のメディアプレイヤーに対して、再度pause()が呼び出されたとき
• 既に停止されているメディアプレイヤーに対してstop()メソッドが呼び出されたとき

フィールドの概要

static int	ERROR エラー停止中であることを示します。
static int	NO_DATA 再生データがないことを示します。
static int	PAUSED 一時停止中であることを示します。
static int	PLAYING 再生中であることを示します。
static int	READY 再生可能な状態であることを示します。
protected static int	REAL_HEIGHT 実画面の高さを表します。
protected static int	REAL_WIDTH 実画面の幅を表します。

コンストラクタの概要

MediaPlayer()

メソッドの概要

abstract void	addMediaPlayerListener(MediaPlayerListener l) MediaPlayerListenerを登録します。
protected static void	addNativeMediaEventDispatcher(com.jblend.io.j2me.events.NativeMediaEventDispatcher dispatcher) NativeMediaEventDispatcherを登録します。
abstract int	getState() プレイヤーの状態を返します。
abstract void	pause() 一時停止します。
abstract void	play() 再生します。
abstract void	play(boolean isRepeat) 繰り返し指定つきで再生します。
abstract void	play(int count) 繰り返し再生します。
abstract void	removeMediaPlayerListener(MediaPlayerListener l) MediaPlayerListenerの登録を解除します。
abstract void	resume() 再開します。
abstract void	setData(MediaData data) データを設定します。
abstract void	stop() 停止します。

クラス java.lang.Object から継承したメソッド

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

フィールドの詳細

NO_DATA

public static final int NO_DATA

再生データがないことを示します。定数 0 が割り当てられています。

READY

public static final int READY

再生可能な状態であることを示します。 定数 1 が割り当てられています。

PLAYING

public static final int PLAYING

再生中であることを示します。定数 2 が割り当てられています。

PAUSED

public static final int PAUSED

一時停止中であることを示します。定数 3 が割り当てられています。

ERROR

public static final int ERROR

エラー停止中であることを示します。定数 0x10000 画」割り当てられています。

REAL_WIDTH

protected static final int REAL_WIDTH

実画面の幅を表します。

REAL_HEIGHT

protected static final int REAL_HEIGHT

実画面の高さを表します。

コンストラクタの詳細

MediaPlayer

public MediaPlayer()

メソッドの詳細

setData

public abstract void setData(MediaData data)

データを設定します。

パラメータ:

data - データ

play

public abstract void play()

再生します。

play

public abstract void play(boolean isRepeat)

繰り返し指定つきで再生します。

パラメータ:

isRepeat - 繰り返しの有無

play

public abstract void play(int count)

繰り返し再生します。

パラメータ:

count - 繰り返し回数

stop

public abstract void stop()

停止します。
次にplayした場合、先頭から再生されます。

pause

public abstract void pause()

一時停止します。

resume

public abstract void resume()

再開します。 一時停止している位置から再開します。

getState

public abstract int getState()

プレイヤーの状態を返します。

戻り値:

int 現在の状態

addMediaPlayerListener

public abstract void addMediaPlayerListener(MediaPlayerListener l)

MediaPlayerListenerを登録します。

パラメータ:

l - MediaPlayerListener

removeMediaPlayerListener

public abstract void removeMediaPlayerListener(MediaPlayerListener l)

MediaPlayerListenerの登録を解除します。

パラメータ:

l - MediaPlayerListener

addNativeMediaEventDispatcher

protected static void addNativeMediaEventDispatcher(com.jblend.io.j2me.events.NativeMediaEventDispatcher dispatcher)

NativeMediaEventDispatcherを登録します。

パラメータ:

dispatcher - NativeEventDispatcher