sound — 効果音と音楽の再生

　サウンドモジュールは、iOS上で効果音を発生させたり音声ファイルを再生する関数を備えています。

　レコーダークラスを使ってマイクからの入力を音声ファイルに録音する事もできます。

　注）レコーダークラスを使用するためには、マイクへのアクセスを許可する必要があります。最初に Recorder.record() メソッドを使用する際には自動的にシステムが用意した許可ダイアログが表示されます。その際にマイクへのアクセスを許可しなかった場合でも、「設定」アプリの「プライバシー」画面でアクセスを許可することができます。

関数

sound.play_effect(name[, volume, pitch=1.0, pan=0.0, looping=False])

　引数 name で指定した効果音を発生させます。システム組込の効果音の名前のリストにはツールバーの［＋］ボタンの「アセットピッカー」を使ってアクセスできます。なお、独自の効果音を使用したい場合には、効果音を保存した音声ファイルのファイルパスを指定することができます。

　再生は非同期で行われます。すなわち、音の再生が完了する前に関数は実行を終えて次のスクリプトの実行に進みます。

　戻り値は sound.Effect オブジェクトで、後で再生の設定調整や再生の途中で効果音を停止するために使うことができます。

　あまりに多くの（通常32音が限界です）効果音が既に再生されている場合、None が返されます。

sound.stop_all_effects()

　現在 play_effect() 経由で再生中の全ての効果音を停止します。

sound.stop_effect(effect)

　引数 effect で指定した効果音の再生を停止します。引数 effect には play_effect() の戻り値を使用します。

sound.set_volume(vol)

　全ての効果音についてデフォルトの音量を設定します。（0.0〜1.0の範囲で、デフォルト値は0.5）このメソッドは、既に再生が開始されている効果音には影響を与えません。

sound.set_honors_silent_switch(flag)

　音の再生中にサイレント（消音）スイッチを適用するか否かを設定します。（デフォルトではTrueです。）

エフェクトのクラス

class sound.Effect

　エフェクトのクラスは現在再生中の効果音を示します。直接的にエフェクトオブジェクトを生成することはできません。play_effect() 関数の戻り値として返されます。単純に一回きりのエフェクトの場合、play_effect() の戻り値は無視して問題ありません。一方で、再生中に音量やピッチなどの属性を調整したり、繰り返す効果を止めたりする際に役に立ちます。

エフェクトのメソッド

Effect.stop()

　効果音の再生を止めます。

エフェクトの属性

Effect.looping

　True に設定すると、Effect.stop() メソッドにより再生を停止するまで、効果音が無限に繰り返されます。

Effect.pan

　効果音のステレオ位置です。（-1=左、+1=右、0=センター）

Effect.pitch

　効果音のピッチ（再生速度）です。デフォルト値は1.0です。

Effect.position

　効果音の空間（3D）位置です。値は3要素タプル（x, y, z) です。この値はステレオ位置の Sound.pan 属性を上書きすることに注意してください。

Effect.volume

　効果音の現在の音量です。

プレイヤーのクラス

class sound.Player(file_path)

　プレイヤークラスは、音楽ファイルを簡便に再生するインターフェイスを提供します。このクラスは音楽やその他遅延を気にしない場合にお勧めします。ゲームの効果音には、play_effect() がより適切です。

プレイヤーのメソッド

Player.play()

　音声ファイルの再生を開始します。

Player.stop()

　音声ファイルの再生を止めて、再生位置をリセットします。

Player.pause()

　音声ファイルの再生を止めますが、現在の再生位置を保存します。 Stop playing audio, but keep the current playback position.

プレイヤーの属性

Player.current_time

　現在の再生位置を秒単位で表します。

Player.duration

　音声ファイルの再生所要時間です。（読取専用）

Player.finished_handler

　プレイヤーが再生を終了する際に引数なしで呼び出される関数/コーラブルです。

Player.number_of_loops

　音声ファイルの繰り返し再生回数です。-1 に設定すると永遠に繰り返します。

Player.playing

　音声ファイルを再生中(True)であるか停止中(False)であるかを示すブール値です。

Player.pan

　再生中の音声のステレオ位置です。（-1=左、+1=右、0=センター）

レコーダーのクラス

class sound.Recorder(file_path)

　レコーダークラスは、デバイスのマイクロフォンから音声ファイルを録音するための高度なメソッドを提供します。

　引数の file_path には記憶装置上に生成した音声ファイルを指定します。音声ファイルのフォーマットはファイル名の拡張子で自動的に決定されます。MPEG4 AACの場合は .m4a 、Linear PCM の場合は .wav です。MPEG4 音声ファイルは Wav ファイルよりもかなりコンパクトですが、ウェイブモジュールで生の音声データを処理したい場合には、Wav を使うことになるでしょう。

レコーダーのモジュール

Recorder.record([duration])

　マイクロフォンからの録音を開始します。オプションの引数として duration を設定すると、指定した秒数が経過すると録音は自動的に終了します。さもなければ、Recorder.stop() メソッドを用いて録音を明示的に停止させる必要があります。

Recorder.stop()

　音声の録音を終了します。

Recorder.pause()

　音声の録音を一時停止します。Recorder.record() メソッドを使えば録音を再開できます。

レコーダーの属性

Recorder.current_time

　現在録音中の経過時間です。

Recorder.recording

　現在録音しているか否かを示します。（ブール値）

Recorder.meters

　ピーク音量の現在の平均です。（読取専用）この属性にアクセスすると、自動的に追加の処理を必要とするレコーダーインスタンスを測定します。値は「平均」と「ピーク値」をキー値とするディクショナリー型です。それぞれは左チャンネルと右チャンネルの2つの値のタプルからなっています。例： {'average': (-35.3, -30.1), 'peak': (-5.2, -8.2)}.

MIDIプレイヤーのクラス

class sound.MIDIPlayer(file_path[, sound_bank_path])

　MIDIプレイヤーは、システム組込の「Merlin Silver」や、あなたがオリジナルで設定したサウンドバンクを使用したMIDIファイル（.mid）の簡易な再生を提供します。オリジナルのサウンドバンクを設定する場合には、sf2 フォーマットにする必要があります。

MIDIプレイヤーのメソッド

MIDIPlayer.play()

　再生を開始します。

MIDIPlayer.stop()

　再生を終了します。

MIDIプレイヤーの属性

MIDIPlayer.current_time

　現在の再生位置です。

MIDIPlayer.duration

　読み込んだ MIDI ファイルの所要時間です。

MIDIPlayer.rate

　再生速度です。（1.0が標準の速度です）