2.SiON で音を鳴らす．

SiON ActionScript3

現バージョンで音を鳴らす方法は，全部で5種類あります．どの方法であっても，最初に SiONDriver::play() メソッドを呼び出してストリーミングを開始しておく必要があります．

SiONDriver::play(data:*=null, resetEffector:Boolean=true) : SoundChannel

SiONDriverクラスの play() メソッドは，SiON による音声ストリーミングを開始します．SiONで発音する場合，最初に必ずこのメソッドを呼び出しておきます．
第一引数では，SiONData, String または null を渡します．SiONData を渡した場合，ストリーミング開始と同時にそのSiONDataの演奏を開始します．SiONData は楽譜に相当し，通常 SiONDriver::compile() を使ってMML文字列から生成します．String を渡した場合，MML文字列として変換後そのデータが演奏されます．この場合，内部でSiONDataに変換してから演奏するため，同じデータを何度も演奏する場合は SiONDriver::compile() を使って，あらかじめ SiONData に変換しておいた方が効率的です．null を渡した場合，何も演奏せずストリーミングを開始します．ストリーミングを開始していないと，SiON の他メソッドでも音を鳴らす事はできません．
第二引数では，ストリーミング開始時にエフェクタ設定をリセットするかをBoolean値で指定します(default値:true)．SiONData内のエフェクタ設定を使用する場合 true，自前で接続設定を行ったエフェクタを使用する場合 false に設定します．（※現バージョンでは，自前でエフェクタの接続設定を行う場合，ストリーミングを開始する前に設定しておいて使用スロット数を確定する必要があります．差し替えはストリーミング中でも可能です．この仕様は将来変更される可能性があります．）
返値として実際にストリーミングを行う SoundChannel クラスのインスタンスが渡されます．このインスタンスは，ストリーミング中であれば SiONDriver::soundChannel プロパティで参照可能です．
演奏/ストリーミングの停止はSiONDriver::stop()，一時停止はSiONDriver::puse()を使用します．一時停止からの復帰は引数にnullを指定してSiONDriver::play()を呼び出して下さい．
［version0.58以前］SiONDriver::play() を呼び出すと，内部で SiONEvent.START_STREAM, (最初の)SiONEvent.STREAM が呼び出されます．driver::play()後にのみ有効になるメソッド/プロパティを演奏前に使用したい場合は SiONEvent.START_STREAM イベントのハンドラ内で参照してください．

// 実行順序テスト[version0.58以前]
var driver:SiONDriver = new SiONDriver();
driver.addEventListener(SiONEvent.START_STREAM, function():void {trace("START_STREAM");});
driver.addEventListener(SiONEvent.STREAM,       function():void {trace("STREAMING");});
trace("before play()");
driver.play();
trace("after play()");

[flashlog]
before play()
START_STREAM
STREAMING
after play()
STREAMING
STREAMING
STREAMING
...

// 実行順序テスト[version0.60以降]
var driver:SiONDriver = new SiONDriver();
driver.addEventListener(SiONEvent.START_STREAM, function():void {trace("START_STREAM");});
driver.addEventListener(SiONEvent.STREAM,       function():void {trace("STREAMING");});
trace("before play()");
driver.play();
trace("after play()");

[flashlog]
before play()
after play()
START_STREAM
STREAMING
STREAMING
STREAMING
STREAMING
...

SiONDriver::noteOn()/noteOff()/playSound()

SiONDriver::noteOn()は，指定した音階/音色/音長/タイミングで単音を鳴らします．全10引数で出音を設定します．

  • 第1引数;note:int; 音階をMIDIノートナンバーで指定します(0-127)．中心オクターブの"ド"("o5c" in MML)が 60 で半音毎に上下します．ドレミファソラシは60,62,64,65,67,69,71です．
  • 第2引数;voice:SiONVoice = null; 音色を指定します．nullの場合，デフォルトの矩形波で出音します．
  • 第3引数;length:Number = 0; 音長を16分音符単位で指定します．4分音符なら4，全音符なら16，32分音符なら0.5です．0を指定した場合はキーオフされません．持続音の場合noteOff()メソッドで明示的に音を止めるまで発音を続けます．
  • 第4引数;delay:Number = 0; 音が出るまでの遅延を16分音符単位で指定します．第4引数と同様4分音符なら4，全音符なら16，32分音符なら0.5です．
  • 第5引数;quant:Number = 0; 音が出るタイミングをどの拍子にシンクロさせるかを16分音符単位で指定します．例えば4(4分音符)を指定すると4分拍子のタイミングに合わせて音を鳴らします．この時delay=2を指定すると4分拍子の8分音符後(つまり8beatの裏拍)になります．0を指定すると拍に関係なく最速で出音します．
  • 第6引数;trackID:int = 0; 音を鳴らすSiMMLTrackを識別するIDを指定します．noteOff()で出音を止める際に使用します．
  • 第7引数;eventTriggerID:int = 0; ノートオン時に SiONTrackEvent を発行する場合のIDを指定します．(詳細は別記予定)
  • 第8引数;noteOnTrigger:int = 0; SiONTrackEvent.NOTE_ON_FRAME/NOTE_ON_STREAM を発行するかのフラグを指定します．0でイベントを発行しません．(詳細は別記予定)
  • 第9引数;noteOffTrigger:int = 0; SiONTrackEvent.NOTE_OFF_FRAME/NOTE_OFF_STREAM を発行するかのフラグを指定します．0でイベントを発行しません．(詳細は別記予定)
  • 第10引数;isDisposable:Boolean = true; 音を鳴らすトラックが Disposable(使い捨て) かどうかを指定します．Disposableなトラックは発音が終わっているとSiONDriverが次の発音に使用してしまいます．このため，Disposableなトラックを保持しておいて後で参照すると予期しない動作をする可能性があります．(詳細は別記予定)

引数が多くて気後れしてしまいそうですが，音階/音色/音長, タイミングx2, ID, イベントx3, 捨フラグ と切り分けると，若干覚えるのが楽になるかと思います．
返値として発音するトラックのインスタンス(SiMMLTrack)を渡します．このインスタンスを通して詳細な操作や情報の取得を行えます．例えば SiMMLTrack::trackStartDelay/44.1 とすると実際に発音するまでの遅延をミリ秒単位で取得する事ができます．また，SiMMLTrack::velocity(0-256)/SiMMLTrack::expression(0-128)/SiMMLTrack::pan(-64-64)/SiMMLTrack::pitchShift()/SiMMLTrack::quantRatio(0-1)などで各パラメータを操作できます．また SiMMLTrack::channel から channel.masterVolume(0-128) や channel.setStreamSend() を操作する事が可能です．SiMMLTrackの詳細は後日別記予定です．
SiONDriver::playSound()は，サンプラーに特化したnoteOn()です．SiONDriver::setSamplerSound()等で登録したSoundオブジェクトを指定した音長/タイミングで鳴らします．サンプラーはMIDIのドラムトラックのように各音階にSoundオブジェクトを割り当てて使用するため音色の設定はありません．noteOn()の第2引数以外の9引数で指定します．
SiONDriver::noteOff()は，音階/trackIDを指定して消音します．noteOn()の第1引数の音階と第6引数のtrackIDが一致するトラックをキーオフします．第1引数を-1に指定すると指定trackIDを持つ全てのトラックを消音します．消音対象のトラックがない場合は，何もせずnullを返します．
noteOn()の第3引数の音長に0を指定した場合はnoteOff()を呼び出して消音を行って下さい．消音しないとトラックが内部に溜まってパフォーマンスが低下する可能性があります（減衰音であれば完全に出力が無くなった時点で消音とみなしますが，聴感よりもかなり長い出力があります）．
現在使用中のトラック数については SiONDriver::trackCount 又は SiONDriver::sequencer.tracks.length で参照できます．

SiONDriver::sequenceOn()/sequenceOff()

SiONDriver::sequenceOn()は，指定した音色/音長/タイミングで SiONData を鳴らします．全6引数で出音を設定します．第1引数にSiONDataを指定する点と第7-10引数が無い以外は noteOn() と同じです．ただし第2引数の音色は SiONData 内で指定されている音色が優先されます．
再生速度もSiONData 内で指定されているテンポが優先されます．SiONData 内で指定がない場合はSiONDriver::play() で演奏されているシーケンスのテンポ，null渡しでplay()を呼び出した場合はSiONDriver::bpm プロパティで指定したテンポで再生されます．
返値としてシーケンスを再生するトラックのリストがVector.型で渡されます(ver0.57以降)．現バージョンでは，sequenceOn()で使用されるトラックは Disposable です．ここで返されるトラックを保持しておいて後で使用するのは，そのトラックが永久ループシーケンス("$"コマンドが指定されているシーケンス)を実行しているなど，演奏が終了していない場合に限定してください．
SiONDriver::sequenceOff()は，指定したtrackIDを持つシーケンスの再生を止めます．sequenceOn()で第3引数=0を指定していても永久ループで無ければシーケンス終了でトラックが開放されます．このため，noteOn()/noteOff()とは異なり，第3引数=0でも永久ループシーケンスで無ければ sequenceOff() を呼び出す必要はありません．

SiMMLTrack.keyOn()/keyOff()

SiMMLTrack.keyOn()/keyOff()は，noteOn()やシーケンス再生でSiONDriver内部から呼び出されている，より低レベルな関数です．通常この関数を呼び出す必要はありませんが，SiONDriver::newUserControlableTrack()やnoteOn()で確保した，Disposableで無いトラックで後から発音する場合に使用します．
keyOn()は，第一引数で音程，第二引数で音長，第三引数で遅延を指定します．音程は1半音=64で指定します("o5c"なら64x60(ノートナンバー)=3840)．また音長/遅延はサンプル数で指定します(44.1kHzでは1秒=44100)．これらの値は SiMMLSequencer::calcSampleLength() や calcSampleDelay() で計算できます(SiMMLTrackの詳細は後日別記予定)．

SoundObject::play()

org.si.sound.* 内のクラスはorg.si.sound.base.SoundObjectを継承しており，そのplay()メソッドを呼び出す事で音を鳴らします．実際には内部で上述の関数を使用して音を鳴らしています．例えば org.si.sound.Arpeggiator クラスでは，生成したSiMMLDataについてSiONDriver::sequenceOn()を使用して演奏しています．