Audio

Audio

各種オーディオ機能をラップしインターフェイスを共通化する。

new Audio(sourceList, opt_option)

複数のオーディオ・バックエンドから、与えられた音声を再生可能なものを見つけ、音声を再生します。

HTMLAudio の動作・機能がブラウザ毎にバラバラなのに業を煮やし、メソッドやイベントは独自に定義しています。

バックエンドの種類

HTMLAudio, WebAudio, Silverlight, WMP

イベント

X.Event.BACKEND_READY
音声(src リスト)を再生可能なバックエンドが見つかった。
X.Event.BACKEND_NONE
音声を再生可能なバックエンドが見つからなかった。Audio は kill されます。
X.Event.MEDIA_CAN_TOUCH
モバイル端末の制約で音声の再生またはロードに、タッチを必要とする場合、タッチイベント内で play を呼び出す準備が出来たことを通知する。
X.Event.READY
再生可能、実際の状態は canplay から loadeddata まで様々、、、
X.Event.ERROR
  • 1 : ユーザーによってメディアの取得が中断された
  • 2 : ネットワークエラー
  • 3 : メディアのデコードエラー
  • 4 : メディアがサポートされていない
X.Event.MEDIA_PLAYING
再生中に1秒以下のタイミングで発生.currentTime が取れる?
X.Event.MEDIA_LOOP
ループ直前に発生、キャンセル可能
X.Event.MEDIA_LOOPED
ループ時に発生
X.Event.MEDIA_ENDED
再生位置の(音声の)最後についた
X.Event.MEDIA_PAUSED
ポーズした
X.Event.MEDIA_WAITING
再生中に音声が待機状態に。
X.Event.MEDIA_SEEKING
シーク中に音声が待機状態に。

Parameters:
Name Type Argument Description
sourceList array | string
opt_option object optional 
Example
 //
var audio = X.Audio( [ 'etc/special.mp3', 'etc/special.ogg', 'etc/special.wav' ] )
					.listenOnce( X.Event.READY, onReady );

Members

private _listeners :__Listeners__

イベントリスナをイベント名文字列や数値(5以上、フレームワーク内で定義)をキーとするArrayで記憶します。
Arrayには、{cbKind:種類,context:コンテキスト(thisObject),func:コールバック関数,supplement:サプリメントする引数の配列} というハッシュ、または関数が蓄えられています。

private _rawObject :Object

_rawObject には HTMLElement, window, document, XHR といったイベントターゲットオブジェクトを設定します。 _rawObject が設定されていると listen(), unlisten() 時に addEventListener(DOM Level2) や detachEvent(ie5~8), on~(DOM0) 等を操作します。 _rawObject は最初の listen() 前に設定しておかないと addEventListener 等が意図したように行われません。 X.Node では非同期に HTMLElement を生成していますが、要素生成以前に listen, unlisten を呼び出すことができます。これは適宜に X_EventDispatcher_toggleAllEvents を呼んで解決しているためです。

private _rawType :number

EventDispatcher がラップしている EventTarget オブジェクトのタイプです。
X_EventDispatcher_actualAddEvent で使用されます。
OTHER:0(node,window,document,Image,Audio), XHR:1, Silverlight:2

backendName :string

音声再生バックエンドの名前。X.Event.BACKEND_READY で設定される。

source :string

音声の url。X.Event.BACKEND_READY で設定される。

Methods

asyncDispatch(delay, e) → {number}

delay(ミリ秒)後にイベントを dispatch する。戻り値は uid = X.Timer.once() のタイマーID(数値)。X.Timer.remove(uid) でタイマーを解除して dispatch を中止できる。 kill() 時には内部でまだ呼ばれていないタイマーの X.Timer.remove() が行われる。インスタンスが破棄された後にタイマーが呼ばれることがないので神経質にならなくても安全に使える。

Parameters:
Name Type Description
delay number | eventHash | string ms 省略した場合は 0 として扱う asyncDispatch( 'myevent' ) -> asyncDispatch( 0, 'myevent' )
e eventHash | string | number イベントを表す数値、文字列、{ type : XXX, ... } なオブジェクト
Returns:
number X.Timer.add() の戻り値
Example
 this[ 'asyncDispatch' ]( 'myevent' );
// どちらのコードも同じ動作をする。
this.asyncDispatch( 0, 'myevent' );

Constructor(opt_rawObject)

X.EventDispatcher のコンストラクタの実体。
イベントターゲットをラップする場合、通常は new 時に渡します。
アプリケーション独自のイベントをやり取りしたいだけ、という場合イベントターゲットは指定しません。

Parameters:
Name Type Argument Description
opt_rawObject object optional 

currentTime(v) → {Audio}

再生位置のsetter。

Parameters:
Name Type Description
v number msで
Returns:

dispatch(e) → {number}

登録されたイベントリスナを呼び出す。イベントリスナの返り値(数値)を OR したものを返す。イベントハッシュでなく、string|number を渡すと内部でイベントハッシュを作る。 dispatch のコールバック中で kill() が呼ばれた場合、実際の kill は、dispatch の終わりまで待機する。dispatch がネストする場合は全ての dispatch の完了で kill() する。__ClassBase__ も参照。 dispatch のコールバック中で listen() が呼ばれた場合、実際の listen は、dispatch の終わりまで待機する。dispatch がネストする場合は全ての dispatch の完了で listen() する。 dispatch のコールバック中で unlisten() が呼ばれた場合、即座に反映され削除されたイベントリスナーは呼ばれない。

Parameters:
Name Type Description
e eventHash | string | number
Returns:
number X.Callback で定義された数値(ビットフラグ)

instanceOf(klass) → {boolean}

インスタンスのクラスか?またはスーパークラスか?調べる。
instanceof 構文をサポートしない環境(IE5以下)を想定する場合、必ずこのメソッドを使用すること。
クラスのインスタンスか?だけ調べたい場合は this.constructor === klass が高速。

Parameters:
Name Type Description
klass __ClassBase__ クラス定義
Returns:
boolean

isPlaying() → {boolean}

再生中か?

Returns:
boolean

kill()

全ての動的メンバを削除して、インスタンスを破棄する。
インスタンスが X.EventDispatcher とそのサブクラスの場合、次の動作をする。

  1. X.Event.BEFORE_KILL_INSTANCE を発火する。戻り値のビットフラグに X_Callback.PREVENT_DEFAULT が立つ場合、破棄をキャンセルし X.Event.KILL_INSTANCE_CANCELED を発火する。この間に kill() が呼ばれても無視される。
  2. 破棄に進む場合は、X.Event.KILL_INSTANCE を発火する。
  3. dispatch 中は、インスタンスの全ての dispatch が終了するまで実際の破棄を待つ。
  4. 実際の破棄では、インスタンスのメンバの削除に加えて全てのイベントリスナを解除する。

listen() → {EventDispatcher}

イベントリスナを追加する。同一イベントに対して重複するリスナ(context, function, 引数 array が一致)の追加は無視される。 ユーザーが触ることは無いが、システム内部でロックフラグを立てたリスナは、立てられていないフラグとは区別される。 この仕組みによってシステムの登録したリスナを、システム外から不用意に削除されることを回避する。

Returns:
EventDispatcher チェインメソッド
Example
 // 'myEvent' に対して、 this コンテキストを指定して 、コールバック関数を渡す。
this[ 'listen' ]( 'myEvent', context, func );
// 'myEvent' に対して、 this コンテキストを指定して 、コールバック関数と追加の引数を渡す。
args = [ 'arg1', 'arg2', 3 ]; // unlisten( 'myEvent', context, func, args ) で使用するので Array も控えておく。
this[ 'listen' ]( 'myEvent', context, func, args );
// 'myEvent' に対して、 listener オブジェクトを渡す。listener は handleEvent という関数を持つオブジェクトのこと。
listener.handleEvent = function( e ){};
this[ 'listen' ]( 'myEvent', listener );
// 'myEvent' に対して、 listener オブジェクトと追加の引数を渡す。
listener.handleEvent = function( e, arg1, arg2, arg3 ){};
this[ 'listen' ]( 'myEvent', listener, [ arg1, arg2, arg3 ] );
// 'myEvent' に対して、 function を渡す。
this[ 'listen' ]( 'myEvent', onMyEvent );
// 'myEvent' に対して、 function と追加の引数を渡す。
this[ 'listen' ]( 'myEvent', onMyEvent, args );
// 次の二つは同じ動作です。 this コンテキストが与えられなかった場合、コールバックの this は発火元インスタンスになります。
this[ 'listen' ]( 'myEvent', this [, func [, args ] ] );
this[ 'listen' ]( 'myEvent' [, func [, args ] ] );
// 複数のイベントタイプを同時に登録。コールバックは同じ指定が使われる。
this[ 'listen' ]( [ 'open', 'close', 'ready' ], onUpdate );

listening(opt_type, opt_arg1, opt_arg2, opt_arg3) → {number|boolean}

イベントリスナの登録状況を真偽値で返す。戻り値が数値(index)の場合もあるが、これは内部のみで使用。

this.listening(); のように type を省略した場合、一つでも登録があれば true を返す。

this.listening( 'myevent' ); と type だけを与えた場合、その type に登録があれば true を返す。

type と イベントリスナの組み合わせが登録されているかを調べる場合は、listen 時の thisObject や args(Array) も一致させて渡す必要がある。

Parameters:
Name Type Description
opt_type string | number
opt_arg1 listener | function | Array | callbackHash
opt_arg2 function | Array
opt_arg3 Array
Returns:
number | boolean
Example
 
 this.listen( [ 'myevent', 'yourevent' ], this, onMyEvent, args = [ 1, 'a' ] );
 this.listening( 'myevent', this, onMyEvent, args ) === true;

listenOnce(type, opt_arg1=, opt_arg2=, opt_arg3=) → {EventDispatcher}

dispatch 時に自動で unlisten されるフラグを立てて listen する。

Parameters:
Name Type Argument Description
type string | number | Array.<string, number> 配列を指定した場合、複数のイベントタイプに対して同じコールバックを登録する。
opt_arg1= listener | function | Array optional 
opt_arg2= function | Array optional 
opt_arg3= Array optional  コールバック時の引数を配列に入れる。引数がひとつでも配列を使用する。省略した場合引数なし。unlisten() に使用するので、配列も適宜に保持しておくこと。
Returns:
EventDispatcher チェインメソッド

loop(v) → {Audio}

ループの setter

Parameters:
Name Type Description
v boolean
Returns:

pause() → {Audio}

ポーズ

Returns:
Audio メソッドチェーン

play(startTime, endTime, endTime, loopStartTime, loopEndTime) → {Audio}

再生。開始位置・終了位置、ループの有無、ループ以降の開始位置、ループ以降の終了位置

Parameters:
Name Type Argument Description
startTime number optional  開始時間を ms で
endTime number optional  終了時間を ms で
endTime boolean optional  に達した際に曲をループさせるか
loopStartTime number optional  ループ以後の開始時間を ms で
loopEndTime number optional  ループ以後の終了時間を ms で
Returns:
Audio メソッドチェーン

seek(seekTime) → {Audio}

シーク、再生中で無い場合は次回再生開始位置の指定のみ

Parameters:
Name Type Description
seekTime number シーク位置を ms で
Returns:
Audio メソッドチェーン

state(obj) → {Audio|object}

状態の getter と setter

Parameters:
Name Type Argument Description
obj object optional  setter の場合、上書きする値を格納したobject
Returns:
Audio | object
Example
audio.setState(
					{
				    	'startTime'     : 0,
				    	'endTime'       : 80000,
				    	'loopStartTime' : 120000,
				    	'loopEndTime'   : 200000,
				    	'currentTime'   : 0,
				        'loop'          : true,
				        'looded'        : false,
				        'volume'        : 1,
				        'autoplay'      : true
					});

Super(var_args) → {*}

関数は Constructor 内で使用します。クラス定義を辿ってスーパークラスのコンストラクタを呼び出します。
内部的には、呼び出したコンストラクタは配列に控え(X_Class_CALLING_SUPER)、呼び出したコンストラクタ内でさらに Super が呼ばれた場合、配列を元にさらにスーパーなコンストラクタを辿ります。

Parameters:
Name Type Argument Description
var_args ? repeatable  親コンストラクタを呼ぶ際に渡す任意の数の引数
Returns:
*
Example
 Constructor : function( arg1, arg2 ){
	this.Super( aeg1, arg2 );
}

superCall(myFunc, var_args) → {*}

myFunc について、スーパークラスで設定されている同名の関数を呼び出す。
低速な関数なので多用されるべきではありません!
第一引数に自身の(自身から参照できる)関数を指定します。内部では関数名を調べた上で prototype チェーンをゴリゴリ辿る、特別なことはしていません。
superCall と Super がネストする場合も現在のクラス階層を X_Class_SUPER_CALLER, X_Class_SUPER_STACKS を使って控えているので、意図した親関数が呼ばれます。
次の理由によって、関数名で辿ることは非推奨です。

  1. closur compiler でメソッド名が変更される
次の場合、意図した動作が得られません。
  1. 2つ以上の異なる名前で同じ関数がメンバーがいた場合
  2. サブクラスの prototype にスーパークラスと同じ関数をコピーしている
  3. 非関数でメンバーを上書きしている
  4. superCall 以外の手段で親関数を呼び、そのなかで superCall を呼んだ
通常の X.Class.create の書き方ではこのような状況は起きませんが、js はなんでもいろいろ出来てしまいますから…
参考:ES5なJavascriptでモダンなクラス的継承&スーパー呼び出し
original:Classical Inheritance in JavaScript

Parameters:
Name Type Argument Description
myFunc function | string オーバーライド済の自身の(自身から参照できる)関数。
var_args * repeatable  オーバーライド元関数に渡す任意の数の引数
Returns:
* オーバーライド元の関数を呼び出した戻り値。
Example
 return this.superCall( this.myFunc, param0, param1, ... );

unlisten() → {EventDispatcher}

イベントリスナの解除を行う。登録時と同じ引数を与える必要がある。kill() で自信に登録されたすべてのイベントが解除されるので、途中で解除されるイベント以外は kill() に任せてしまってよい。
他人に登録したイベントを解除せずに kill するのは NG。

Returns:

volume(v) → {Audio}

ボリュームの setter 実装不十分!

Parameters:
Name Type Description
v number
Returns: