MucomDotNET Extensions ko

MUCOMSX mucomDotNET 확장 명령 안내

문서 갱신일: 2026-10-03. MAKOTO 한 대의 YM2608을 사용하는 MUCOMSX 확장 빌드용입니다. 기존 MUCOM88 문법에 무엇이 더해졌는지, 실제 악보에 어떻게 쓰는지 정리했습니다. 모든 mucomDotNET 악보와 모든 칩을 그대로 지원한다는 뜻은 아닙니다.

빌드 구분과 검증 범위도 함께 읽어 주세요. MucoMSX_261003.zip에는 다중 페이지·120 KiB DATA·아래 음악 명령 확장이 들어 있습니다. CPU 자동 가속과 /N은 별도로 검증한 10월 3일 CPU 가속 빌드에만 있습니다. 문서 ZIP을 교체해도 실행파일은 바뀌지 않습니다.

입력과 출력 크기

구분	한도와 의미
MUC2MUB·MUCPLAY의 MUC 입력	파일 전체 65,536바이트. 태그·주석·개행 포함
MUCEDIT 편집	개행 정규화 후 60,000바이트. 전용 16 KiB 뱅크 4개
컴파일 음악 DATA 전체	122,880바이트, 즉 120 KiB. 구조·음색 데이터도 포함
한 페이지의 음악 스트림	최대 59,546바이트. 전체 120 KiB와 별개의 한도
파트와 페이지	A–K 11파트, 각 0–9의 10페이지, 최대 110개 소프트웨어 페이지
최소 매퍼	512 KiB. CPU 가속을 위한 추가 뱅크는 없음
MUB 파일 전체	DATA 외에 헤더·태그·PCM이 있으므로 120 KiB보다 클 수 있음

120 KiB는 120,000바이트가 아닙니다. 한 페이지에 모든 음표를 몰아 넣으면 전체 DATA가 작아도 페이지 한도에 먼저 닿습니다. 페이지를 나눈다고 물리 음원 채널 수가 늘어나지는 않습니다. 또한 512 KiB가 장착되어 있다는 사실만으로 모든 대용량 곡과 편집 세션을 동시에 유지할 수 있는 것은 아닙니다.

컴파일은 MUC를 행 경계를 보존하여 매퍼에 적재한 뒤 일괄 처리합니다. 음악 DATA를 메모리에서 빌드·검사하고, 저장할 때 컨테이너를 작성합니다. ADPCM 은행은 컴파일된 음악 DATA에 상주하지 않으며, MUB export 단계에서 지정 PCM 파일을 읽어 붙입니다. WAV를 그 자리에서 ADPCM으로 변환하는 기능은 아닙니다.

출력 형식과 호환성

확장이 필요 없는 곡은 MUB8을 유지합니다. 확장 사용이나 대용량 출력이 필요한 경우에는 muPb 0100 경로를 사용하며 export 시 필요한 mucomDotNET 드라이버 태그를 기록합니다. 파일 확장자는 둘 다 .MUB입니다. 확장자를 보고 구분하거나 헤더의 이름만 바꾸어 변환하지 마세요.

일반 주석·제목이나 호출하지 않은 매크로 안의 명령만으로 확장 사용을 판단하지 않습니다. 숫자 페이지나 실제 확장 명령을 사용하는 경로가 기준입니다. 레거시 4바이트 FM3 S 명령과 확장 16비트 S 표현을 섞어 조용히 잘못 연주하는 대신 오류로 중단하는 경로가 있습니다. 확장 곡은 처음부터 다음 태그를 명시하는 편이 이해하기 쉽습니다.

#driver mucomDotNET

외부 muPb는 첫 번째 OPNA용 지원 구조를 대상으로 합니다. 다른 칩의 실제 음악 데이터, 임의의 악기 구조까지 지원하는 범용 muPb 플레이어는 아닙니다. 디스크 MUB는 MUBPLAY로 여세요. MUCPLAY의 파일명 실행은 MUC를 컴파일하는 동작입니다.

파트와 다중 페이지

파트	MAKOTO의 물리 음원
A B C	FM 1 2 3
D E F	SSG 1 2 3
G	내장 리듬
H I J	FM 4 5 6
K	ADPCM-B

A0, A1부터 K9까지 사용할 수 있습니다. ABC처럼 여러 파트에 공통 악보를 적거나 C0123처럼 페이지를 묶을 수 있습니다. 각 페이지는 진행 위치와 효과 상태를 따로 유지하지만 같은 파트의 물리 레지스터는 공유합니다. 일반 페이지는 음의 소유권이 바뀌는 구조이지 독립된 추가 신시사이저가 아닙니다.

#driver mucomDotNET
A0 o4 l4 cdef
A1 o5 l4 r2 ga
DEF o4 l8 cdefgab>c

위 예는 페이지 문법 조각입니다. FM 음색과 PCM이 필요한 예에는 해당 외부 자원을 별도로 준비하세요. 예제 전체를 연주 검증이 끝난 배포 악곡으로 제공하는 것은 아닙니다.

FM3 독립 슬롯

C 파트에서 EXON으로 효과음 모드를 켜고 EXOF로 끕니다. EX1, EX24, EX1234처럼 사용할 오퍼레이터 번호를 나열합니다. EX0은 그 페이지의 슬롯 할당을 없앱니다. EX 지정만으로 효과음 모드가 켜지지는 않습니다.

#driver mucomDotNET
C0 EXON EX1 o4 l4 cdef
C1 EX2 o3 l4 cgrg
C2 EX3 o5 l8 cdefgab>c
C3 EX4 o2 l2 cg

네 페이지를 네 슬롯에 나누면 FM3 한 채널의 오퍼레이터마다 다른 악보를 진행할 수 있습니다. 네 개의 완전한 4오퍼레이터 FM 채널이 생기는 것은 아닙니다. ALG·FB, 팬과 하드웨어 LFO 관련 설정은 물리 채널에서 공유됩니다. 페이지별 음색은 같은 ALG·FB로 맞추는 것을 권합니다. 같은 슬롯에 복수 페이지를 겹치거나 공유 설정을 계속 바꾸면 서로 영향을 줍니다.

슬롯 디튠 S는 확장 모드에서 네 개의 부호 있는 16비트 값(-32768–32767)을 사용합니다. 순서는 오퍼레이터 4, 3, 1, 2입니다. 이 순서는 vm3나 KD와 다르므로 그대로 복사하지 마세요. 소프트웨어 LFO·포르타멘토·음색 전환도 검증에 포함되어 있지만, 공유 하드웨어 설정까지 페이지별로 독립한다는 보장은 아닙니다.

반복 음정과 직접 길이

x는 앞 음의 음정 종류를 현재 옥타브에서 다시 사용합니다. 음길이, 타이, 매크로와 조옮김 처리를 함께 사용할 수 있습니다. 파트의 첫 x는 c를 기준으로 처리하므로 의도한 첫 음은 명시하는 편이 좋습니다.

l%n은 분모가 아닌 tick 수로 기본 음길이를 지정합니다. 기존 % 명령과 같은 계열입니다.

A o4 l%12 c x x g x

매크로 번호와 시프트

매크로 식별자는 0–99,999까지 지원합니다. **n은 이후 매크로 호출 번호에 더할 오프셋이며 음정 시프트가 아닙니다. 음수 오프셋도 가능하지만 최종 번호는 지원 범위 안이어야 합니다. 파트·페이지가 바뀌면 시프트 상태를 초기화합니다.

A **100 *1 **0 *1

먼저 정의해 둔 *101을 호출하고, 다음에는 *1을 호출하는 예입니다. 큰 번호를 쓴다고 매크로 본문 길이나 호출 중첩 한도가 늘어나지는 않습니다. 범위를 넘는 번호는 감아서 다른 매크로로 실행하지 않고 오류로 처리합니다.

파트별 분기

[| ... | ... |]는 같은 행에 지정한 파트·페이지의 순서에 따라 다른 구간을 선택합니다. 세로줄은 전각 문자가 아니라 ASCII |입니다.

ABC o4 l4 [|cdef|efga|gabc|]

A는 cdef, B는 efga, C는 gabc를 사용합니다. 매크로 안의 분기와 분기 안의 일반 반복도 지원합니다. 분기 자체를 중첩하는 것은 지원하지 않습니다. 일반 반복과 이 문법을 혼동하지 마세요.

FM 음량과 오퍼레이터 제어

문법	동작
vm0	기존 음량 방식
vm1 뒤에 20개 TL 값	v15부터 v0 및 그 아래 4단계까지의 음량표 재정의. 각 TL 0–127
vm2 vN	직접 음량 0–127. 0이 가장 작고 127이 가장 큼
vm3 vN	단일 음량 지정 경로를 유지
vm3 vN4,N3,N2,N1	캐리어 오퍼레이터별 음량. 순서 4, 3, 2, 1. 각 0–127
KDd1,d2,d3,d4	오퍼레이터 1, 2, 3, 4의 키온 지연을 tick 단위로 지정
MTmask,baseTL	FM LFO를 지정 오퍼레이터의 TL에 적용

vm3의 값은 1개뿐 아니라 2개·3개·4개도 받을 수 있습니다. 2개·3개 형식의 뒤쪽 생략 인자는 참조 구현의 생략 표식으로 기록합니다. 생략 값을 0으로 채우거나 앞 값으로 복제한다는 의미는 아닙니다. 네 오퍼레이터를 확실히 지정하려면 네 값을 모두 쓰세요.

A vm3 v127,120,110,100 c4
A vm3 v120,90 d4
A KD0,2,4,6 e4 KD0,0,0,0

#CarrierCorrection Yes/No는 음색의 원래 캐리어 TL 보정을 다룹니다. 기존 V 음량 밸런스와 상대 음량도 결과에 영향을 줍니다. 큰 상대 음량을 누적해 되돌릴 때 중간 값을 먼저 잘라 버리지 않도록 처리했습니다.

MT의 mask는 0–15이고 bit0부터 오퍼레이터 1–4입니다. MT5,64는 오퍼레이터 1과 3, 기준 TL 64입니다. mask 0은 일반 음정 LFO로 돌아갑니다. 속도·깊이는 기존 M 계열 LFO 설정과 함께 사용합니다. KD는 0부터 C로 정한 tick 범위에서 사용하고 KD0,0,0,0으로 지연을 해제하세요.

FM 음색 모핑

@시작음색,목표음색,속도[,리셋] 형식입니다. 음색 번호는 0–255, 속도는 1–255 tick, 리셋은 0 또는 1이며 생략하면 1입니다.

A @1,2,4,1 o4 l1 c

음색 1에서 음색 2로 파라미터를 단계적으로 바꿉니다. 속도 1이 가장 빠릅니다. 리셋 1은 발음마다 시작 음색부터 다시 진행합니다. 두 음색은 실제로 정의되어 있어야 합니다. ALG·FB까지 바뀌므로 FM3 공유 슬롯에서 특히 주의하세요. 여러 페이지의 빠른 모핑은 CPU 부하를 크게 늘릴 수 있습니다.

SSG 하드웨어와 소프트웨어 엔벌로프

문법	의미
S0–S15	하드웨어 엔벌로프 모양 선택
m0–m65535	하드웨어 엔벌로프 주기. 작은 값이 빠름
vN	일반 음량 모드로 복귀
MT1	소프트웨어 LFO를 음량에 적용
MT0	LFO를 음정에 적용
@n=al,ar,dr,sl,sr,rr	소프트웨어 엔벌로프 프리셋 n을 다시 정의

프리셋 번호 n은 0–15, 여섯 파라미터는 각각 0–255입니다. 이 정의는 E 부분만 바꾸며 P·M 설정까지 덮어쓰지 않습니다. 다음 곡을 시작할 때 초기화됩니다.

D S10 m256 o4 l4 cdef
E @1=255,255,8,128,4,16 @1 o4 l4 cdef

실제 YM2608의 하드웨어 엔벌로프를 빠르게 반복시켜 삼각형·톱니형 진폭 변화를 만드는 방법은 지원합니다. 엔벌로프 발생기는 SSG 채널들이 공유하므로 다른 파트의 S·m 설정과 충돌할 수 있습니다. 이것은 에뮬레이터 전용 @I8, @I9 임의 파형 기능을 지원한다는 뜻이 아닙니다.

팬과 리듬

FM·ADPCM의 p1은 오른쪽, p2는 왼쪽, p3은 양쪽입니다. FM의 p0 무음도 지원합니다. p4[,간격]은 오른쪽→중앙→왼쪽→중앙 순환, p5는 반대 방향, p6은 랜덤 팬입니다. 간격은 0–255 tick이며 생략하면 기본 음길이를 사용합니다.

리듬에서는 @mask로 악기를 고른 뒤 vN(0–31)으로 선택 악기의 음량을 지정할 수 있습니다. vm1은 선택 악기에 대한 상대 음량 )( 동작을 켜고 vm0은 기존 방식으로 돌아갑니다.

pm1은 리듬의 팬을 FM과 같은 p1–p6 표기로 쓰게 합니다. pm0은 기존 packed 리듬 팬 표기입니다. 복수 악기에 자동 팬을 적용할 때는 각 악기마다 팬 명령과 대기값이 함께 기록됩니다.

G @3 vm1 v20 pm1 p4,8 l4 cccc

@3은 비트 마스크 1+2, 즉 Bass Drum과 Snare 선택입니다. mask의 bit0–5는 B, S, C, H, T, R 순서입니다. 곡 전체의 특정 리듬을 끄려면 다음처럼 태그에 악기 문자를 나열합니다.

#OPNA1RhythmMute SB

이 예는 Snare와 Bass Drum을 뮤트합니다. 키온을 제한하되 키오프는 막지 않습니다. 컴파일 세션 유지·MUB 태그 저장·외부 MUB 태그 읽기에도 반영됩니다.

MIDI식 포르타멘토

FM·FM3·SSG·ADPCM K에서 지원합니다. 내장 리듬에는 음정 이동 기능이 없어 지원하지 않습니다.

명령	의미
PO스위치,초기음정차,시간	전체 설정. 스위치 0 또는 1, 초기 차이는 반음 단위 -128–127
POS0 또는 POS1	연속 포르타멘토 끄기 또는 켜기
POR음정차	시작 음정을 현재 음에 대한 상대 간격으로 다시 지정
POL시간	이동 시간만 변경. 단위는 tick이며 ms가 아님
_	다음 음 하나만 현재 on/off와 반대로 처리
__	다음 음 하나만 반전. 꺼진 상태에서 켤 때 초기 음정차 사용

처음 켠 뒤의 첫 음은 현재 음에 초기음정차를 더한 곳에서 출발합니다. 다음 음부터는 앞 음의 도착 음정을 출발점으로 사용합니다. 이동을 끝내면 도착 음정을 유지합니다. 이동 시간은 일반적으로 0부터 C로 정한 한 음표 기준 tick 범위에서 작성하세요. 현재 파서는 16비트 시간값을 보관하며 큰 값이 모든 악보에서 유용하다는 보장은 아닙니다.

A o4 l4 PO1,-7,16 cdef POS0 g _a b
K @1 v160 o4 l4 PO1,-7,16 cdef

두 번째 예는 PCM 은행에 샘플 1이 있어야 합니다. 타이·게이트·옥타브 변화·조옮김 및 페이지별 상태도 처리합니다. CPU 가속 빌드의 R800 곱셈은 이 보간 계산을 빠르게 할 뿐, 악보의 길이나 이동 폭을 바꾸지 않습니다.

ADPCM 효과

K 파트에 MIDI식 포르타멘토 외에도 음정 LFO와 기존 중괄호 포르타멘토를 추가했습니다. 아래 세 행은 각각의 사용 예입니다.

K @1 v160 o4 l4 M1,1,8,8 cdef
K @1 v160 o4 l4 {c4g} {g4c}
K @1 v160 E255,255,8,128,4,16 o4 l4 cdef

M은 지연·카운터·변화량·피크의 기존 LFO 문법입니다. 중괄호는 시작 음과 그 길이, 도착 음을 적습니다. E의 여섯 값은 0–255이며 SSG와 같은 계열의 소프트웨어 엔벌로프입니다. ADPCM 포르타멘토와 LFO는 Delta-N 음정값에 반영합니다. 확장을 쓰지 않은 기존 PCM 음표의 음정표는 유지합니다.

여러 K 페이지는 한 ADPCM 재생기를 공유합니다. 발음 소유권이 없는 페이지가 현재 샘플의 음정을 덮어쓰지 않도록 보호합니다. 이 때문에 특정 참조 테스트에서 MDPlayer의 비소유 페이지 쓰기 16건과 의도적으로 다릅니다. 모든 레지스터 기록이 무조건 참조와 일치한다고 설명하지 않습니다.

직접 레지스터 쓰기

y0,포트,주소,값을 지원합니다. 첫 인자 0은 첫 OPNA, 포트는 0 또는 1, 주소·값은 0–255입니다. 다른 칩 번호는 지원 대상이 아닙니다. 타이머·키온·ADPCM 제어를 직접 덮어쓰면 드라이버의 상태와 달라질 수 있으니 레지스터 의미를 알고 사용할 때만 쓰세요.

MUCEDIT에서 확인하는 순서

1. 같은 빌드 세트의 MUCEDIT와 MUCPLAY를 준비합니다. 새 실행파일로 바꾸기 전에는 기존 실행파일로 세션을 종료·해제하세요.
2. MUC를 열고 필요한 부분을 편집합니다. 편집 한도 60,000바이트와 컴파일 입력 65,536바이트는 다릅니다.
3. 컴파일한 뒤 연주하여 페이지 전환, 반복, SSG 드럼, ADPCM 효과를 확인합니다.
4. EXPMUB로 저장하고 MUBPLAY로 다시 연주합니다. PCM 파일 경고가 있으면 샘플 누락 여부부터 확인합니다.
5. EXPVGM으로 출력하고 독립 플레이어와 비교합니다. 녹음 파형, 레지스터 순서, 실행 속도는 서로 다른 검증 항목입니다.
6. 여러 곡을 이어서 시험할 때 큰 세션을 계속 보유하여 새 문서 로드용 여유 공간이 부족하면 정상 종료 후 다시 실행합니다. 재부팅이 필요한 절차라는 뜻은 아닙니다.

편집기의 컴파일 초안은 LF, 일반 저장은 CRLF일 수 있습니다. 전체 MUB 바이트 비교 시 동일한 입력과 PCM·음색 은행을 사용하세요. 헤더·태그·빈 페이지·무음 꼬리만 다른 경우와 실제 음악 이벤트 차이는 나누어 확인해야 합니다.

아직 지원하지 않는 것

• #PCMInvert: ADPCM의 옥타브 방향 반전 태그.
• #@pcm: WAV를 읽어 ADPCM으로 변환·은행을 생성하는 작업. 사전 제작 PCM 은행 사용은 지원합니다.
• PCn 및 작은따옴표 파트 메모: mucomDotNET IDE 표시용 기능.
• 두 번째 OPNA, OPNB, OPM과 그 전용 파트·태그·@M 음색.
• #SSGExtend On의 에뮬레이터 전용 팬·pe·@I·@W 임의 파형. 실칩의 S·m 하드웨어 엔벌로프는 위 설명대로 지원합니다.
• 모든 외부 muPb 구조와 모든 PC 플레이어의 버그까지 똑같이 재현하는 동작.

오류를 만났을 때

입력 초과, 한 행·매크로 길이 초과, 미정의 음색·매크로, 범위 밖 번호, 지원하지 않는 파트의 명령, 분기 중첩, 페이지 또는 총 DATA 한도, 매퍼 부족을 따로 확인하세요. 총 DATA가 120 KiB 이하라는 것만으로 성공이 보장되지 않습니다.

음이 끊기거나 재생이 느리다면 문법 오류와 CPU 순간 부하도 구별해야 합니다. 자동 가속으로 평균 처리 시간은 줄었지만 모든 순간 부하를 해결한 상태는 아닙니다. 실기·모든 곡·모든 파형의 완전 일치 보증 대신 릴리즈 기록에 검증 범위와 남은 제약을 적었습니다.