`pyxen.Music`

Entity에 컴포넌트로 첨부되는 스트리밍 오디오 트랙입니다.

Music은 주문형으로 디코딩됩니다. 배경 음악과 앰비언스 같은 긴 트랙에 적합합니다.

오디오 개념은 오디오를 참조하세요.

생성자

Music(filename)

필수 위치 인수 하나: 프로젝트 내 음악 에셋의 이름(확장자는 붙이지 않습니다).

매개변수

매개변수	타입	설명
`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

활성화되면 트랙이 끝난 후 자동으로 다시 시작됩니다. 배경 음악에 일반적입니다.

`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)

읽기 전용. 트랙 재생이 완료되면 (loop가 False일 때) True.

형식

음악 에셋은 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).