`pyxen.Music`

Entityにコンポーネントとしてアタッチされるストリーミングオーディオトラックです。

Musicはオンデマンドでデコードされるため、BGMやアンビエンスなどの長いトラックに適しています。

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

コンストラクタ

Music(filename)

必須の位置引数が1つ：プロジェクト内の音楽アセットの名前（拡張子は付けません）。

パラメータ

パラメータ	型	説明
`filename`	`str`	音楽アセットの名前（拡張子なし）

例

theme = Music("theme")

Musicのアタッチ

生成時：

bgm = world.spawn(music=Music("theme"))

または後から：

entity.music = Music("theme")

ミュージックを割り当てると即座に再生が開始されます。

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

entity.musicでアクセス：

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

`loop`

entity.music.loop = True

有効にすると、トラックは終了後に自動的に再スタートします。BGMでは一般的です。

`volume`

entity.music.volume = 0.5

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

`pan`

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

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

`time`

t = entity.music.time

読み取り専用。現在の再生位置（秒）。

`duration`

d = entity.music.duration

読み取り専用。トラックの全体の長さ（秒）。

`finished`

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

読み取り専用。トラックの再生が完了するとTrue（loopがFalseの場合）。

フォーマット

音楽アセットには、OGG Vorbis（.ogg）、MIDI（.mid、.midi）、またはトラッカーモジュール — ProTracker（.mod）、FastTracker II（.xm）、Impulse Tracker（.it）、Scream Tracker 3（.s3m）— を使用できます。

アセットはベース名で検索されます。Music("theme") は theme.ogg、theme.mod など、プロジェクト内に存在する拡張子のファイルを見つけます。拡張子を渡すのが最もよくある間違いです。Music("theme.ogg") は theme.ogg.ogg を探して例外を送出します。

トラッカーモジュールは、同じ曲のOGGが数メガバイトになるところを数キロバイトで収まることが多く、構造上シームレスにループします — 小さなゲームに最適です。

Sound（WAV、完全にメモリに読み込み）と異なり、Musicはストリーミングされオンデマンドでデコードされます — 長いオーディオにより適しています。

よくあるエラー

ファイル名の指定なし

Music()

ValueError: Music must have a file

無効なアセット

Music("nonexistent")
Music("theme.ogg")     # 拡張子はファイル側に付けます。名前には含めません

ValueError: Music 'nonexistent' not found. Use the asset name without its extension (.ogg, .mid, .mod, .xm, .it, .s3m).