`pyxen.Sound`

Entityにコンポーネントとしてアタッチされる短いオーディオクリップです。

サウンドは完全にメモリに読み込まれます — ジャンプ、ヒット、アイテム取得などの短いエフェクトに使用してください。

オーディオのコンセプトについてはオーディオを参照してください。

コンストラクタ

Sound(filename, *, volume=1.0, pan=0.0, loop=False, delay=0.0, pitch=1.0)

filename は唯一の位置引数で、プロジェクト内のWAVオーディオアセットの名前です。残りの5つはキーワード専用で、同名のプロパティの初期値を設定します（コンポーネントのプロパティを参照）。

パラメータ

パラメータ	型	説明
`filename`	`str`	WAVアセットの名前（拡張子なし）。サウンドバンク内のサウンドは`bank/sound`
`volume`	`float`	初期ゲイン。デフォルトは `1.0`
`pan`	`float`	初期のステレオ位置（`-1.0`〜`1.0`）。デフォルトは `0.0`
`loop`	`bool`	終了時に最初から再生する。デフォルトは `False`
`delay`	`float`	再生開始までの無音の秒数。デフォルトは `0.0`
`pitch`	`float`	再生速度。`0.25` から `4.0`。デフォルトは `1.0`

例

jump_sound = Sound("jump")
quiet_echo = Sound("jump", volume=0.3, delay=0.15)
high_jump = Sound("jump", pitch=2.0)

Soundのアタッチ

生成時：

sfx = world.spawn(sound=Sound("jump"))

または後から：

entity.sound = Sound("jump")

サウンドを割り当てると即座に再生が開始されます。

コンポーネントのプロパティ

entity.soundでアクセス：

プロパティ	型	R/W	説明
`loop`	`bool`	R/W	ループを有効にする
`volume`	`float`	R/W	ゲイン（0.0以上にクランプ）
`pan`	`float`	R/W	ステレオパンニング（-1.0〜1.0）
`time`	`float`	R/W	現在の再生位置（秒）
`delay`	`float`	R/W	再生が始まるまでの無音の秒数
`pitch`	`float`	R/W	再生速度（0.25〜4.0）
`duration`	`float`	R	全体の長さ（秒）
`finished`	`bool`	R	再生が完了するとTrue

`loop`

entity.sound.loop = True

有効にすると、サウンドは終了後に自動的に再スタートします。

`volume`

entity.sound.volume = 0.5

0.0未満の値は0.0にクランプされます。

`pan`

entity.sound.pan = -1.0  # 完全に左
entity.sound.pan =  1.0  # 完全に右
entity.sound.pan =  0.0  # 中央

-1.0から1.0の範囲にクランプされます。

`time`

t = entity.sound.time
entity.sound.time = 0.25     # 最初の0.25秒を飛ばす

再生位置（秒）。代入するとその位置へシークします。末尾を超える値は末尾に丸められ、再生が終わった音をシークすると再び鳴り始めます。

`delay`

entity.sound.delay = 0.002   # 2ミリ秒後に鳴り始める

音が鳴り始めるまでの無音の秒数です。time と違って何も飛ばしません。音は最初のサンプルから始まり、始まるタイミングだけが遅れます。

同じ効果音を1フレームのうちに何度も鳴らすときに使うものです。 同じ波形のコピーが同じサンプルから始まると位相がそろって加算されます。2つなら1.4倍ではなく2倍の振幅になり、10も重なればどれだけ丁寧に音量を設定していてもミックスはフルスケールを超えます。数ミリ秒ずらすだけで相関は切れますし、その長さが隙間として聞こえることはありません。

ディレイが引き離すのはアタックです。短い打楽器的な音にはよく効きますが、持続音には効果がありません。

`pitch`

entity.sound.pitch = 2.0     # 1オクターブ上
entity.sound.pitch = 0.5     # 1オクターブ下

サウンドを再生する速さです。1.0 は録音どおり、2.0 は1オクターブ高く半分の時間で、 0.5 は1オクターブ低く2倍の長さで再生されます。値は 0.25 から 4.0（上下2オクターブ）に制限されます。同じサウンドのピッチを上げていけば音階になるので、連鎖やストリークには音ごとのサウンドではなく、サウンド1つで足ります：

def on_match(step):
    world.spawn(sound=Sound("match", pitch=1 + 0.12 * step))

time と duration はサウンド自身の秒数のままです。pitch が 2.0 のとき、1秒のサウンドは 0.5秒で鳴り終わり、その間 time は 0.0 から 1.0 まで進みます。

`duration`

d = entity.sound.duration

読み取り専用。録音どおりのサウンドの全体の長さ（秒）。pitch には左右されません。

`finished`

if entity.sound.finished:
    world.destroy(entity)

読み取り専用。サウンドの再生が完了するとTrue（loopがFalseの場合）。

フォーマット

サウンドアセットはWAVファイルでなければなりません。

よくあるエラー

ファイル名の指定なし

Sound()

ValueError: Sound must have a file

無効なアセット

Sound("nonexistent")

ValueError: Sound 'nonexistent' not found. For sounds inside a sound bank, use 'bank/sound'.

ゲームはこのエラーで停止します。アセット名は拡張子 .wav を付けずに指定します。サウンドバンク内のサウンドは bank/sound という名前です。