(wiki) MuSICA info/macro language reference

By shram86

Expert (88)

shram86's picture

06-07-2019, 21:40

(wiki) MuSICA info/macro language reference

IMO MuSICA is a highly underrated tool that should be used by more developers. It's simple, fast, and easy to learn. To that end I started researching and wanted to compile a page that should go in the Wiki for future reference, given how hard it is lately to find information, tutorials, and downloads. Unfortunately I don't have the ability to create new wiki pages, hence this post.

--------------------------------------------

What is MuSICA?

MuSICA is a music macro language for MSX computers. It supports all 9 FM channels of the OPLL (including swapping channels 7-9 for 5-unit rhythm), the 3 PSG channels, and 5 SCC channels for a total of up to 17 voices.

MuSICA files can be created in any text editor. In fact, any .MSD files created in the MuSICA tool can be opened as-is and edited in any standard PC editor.

The most common distribution of MuSICA is a slightly modified version that is compatible with after-market SCC chips (such as the MFRSCC+). The MuSICA editor for MSX, example .MSD files, an (abandoned) Windows-based editing tool, two playback drivers and example usage can be found within this archive (hosted by woolyss.com) (Mirror)

Making MuSICA MSD files
It is recommended to use the MuSICA editing tool on an actual MSX or emulator configured with an OPLL (FM-PAC) and/or SCC. You don't need both, but you can make use of both if they are present.

A typical MSD file looks like the following (as you would have if you completed the tutorial by Philip Linde in the archive linked above):

; Comments go after semicolons
; Song title, author, copyright, etc.

FM1 =t, s, s1, s2, s3/2
FM2 =t
FM3 =t
FM4 =
FM5 =
FM6 =
FMR =t, r, r1/8
FM7 =
FM8 =
FM9 =
PSG1=
PSG2=
PSG3=
SCC1=
SCC2=
SCC3=
SCC4=
SCC5=

t=t150
s=@10o4l8v15

s1=cde.f16gfedc4r2
s2=cd#ff#ga#>(c16<a>)c4r2<
s3=o3l16@23dd>dd<dd>dd<dd>dd<dd>cd<

r=v15
r1=bh8h8sh8h8

Note:
The names and order of the voice channels ("FM1 " - "SCC5") are specific and cannot be changed or deleted. Additional lines must be placed after these first 17 rows.

MuSICA Macros List
This is a full list of known MuSICA macro commands, their compatible ranges, and what they do.

_Standard macros_
t[n] : Set tempo to [n] (range 32-255)
/[n] : Repeat last sequence [n] times (0-255)
@[n] : Set instrument to [n] (0-99)
o[n] : Set octave to [n] (1-8)
l[n] : Set note length to 1/[n] (1-64)
v[n] : Set volume to [n] (0-15)
abcdef[n][#/+/-] : Play note A-F, optionally for duration 1/[n]. #/+ makes note sharp, - makes note flat.
. : Extend last note by 1/2 a beat (..= 1/4th, ...=1/8th etc.)
r[n] : Rest for 1/[n] beats (1-64)
>/< : Raise or lower octave by one per >/<

_Rhythm-only macros_
b : Bass drum
h : Hi-hat
s : Snare
c : Cymbal
m : To(m)
v[x][n]: Change volume of rhythm-instrument [x] to [n] (0-15)
[n] : Rest period after each rhythm "beat" (1/[n])

_Other macros_
q[n] : Set envelope to 0-8 (see PSG documentation for more info)
w[n] : Set decay 0-255 (Not working?)
p[n] : Portamente 0-255 (values < 64 are most noticable)
i[n] : Vibrato 0-255
m[n] : Period of envelope 0-65000 (untested)
@v[n]: Set master volume 0-15
@w[n]: Wait 0-255 (untested)
@y[n],[m]: Set instrument register [n] to value [m] (untested)
y[n],[m]: Set register [n] to value [m] (untested)
z[n] : Detune 0-255
() : Play all notes within parantheses as legato

How to use MuSICA .BGM files in your own games
From the DISK menu in the MuSICA editor (ESC > D) key), select 5) to compile and export your current song as a .BGM file (remember to name it a full 8 characters including spaces). MuSICA will ask where you want the start address of the song to be - it defaults to A5B7, which is fairly low in memory (about 10kb lower than where the player is loaded, at CE00h). If your song is <2kb, C5B7 is a suitable location. If it is larger, calculate accordingly in respect to your desired memory configuration.

If you are creating a BASIC game, you can use the .BAS examples provided in the MuSICA archive to load either the REPLAY or GAROU5 driver and play your file.

If you are creating an assembly program launched from BASIC, examine the REPLAY.BIN disassembly and this example to see how to use them accordingly.
REPLAY.BIN MuSICA replay driver disassembly
Example ASM playback routine

Some additional playback driver information:

BGMINI: CE00H
Initializes the music driver. Uses all registers.

BGMON: CE03H
Starts playback. Uses all registers.
Input: HL - address of pointer to music data location
A - number of times to repeat (0 = loop)

BGMOFF: CE06H
Stops playback. Uses all registers.

BGMDRV: CE09H
Jumped to from interrupt address.

BGMTST: CE0CH
Checks if currently playing. Uses A/F registers.
Output: Z is cleared if currently playing.

BGMVOL: CE0FH
Changes master volume. Uses all registers.
Input: A (0-15): Master volume level
A (16): Get master volume
A (17): Pause playback
A (18): Restart playback
Output: A contains 0-15 if input was A=16.

BGMSW: CE12H
Allow/block writing of music data to the PSG. Uses all registers.
Input: A = 00000xxx
bit 0 = channel A, bit 1 = channel B, bit 2 = channel C
If set, writing off, if cleared, writing on.

WORK AREA:
FMSLOT: [CE15H,1]CE97
MSX-MUSIC slot number

SCSLOT: [CE16H,1]CE98
SCC slot number

P1SLOT: [CE17H,1]CE99
Page 1 RAM slot number

MSTVOL: [CE18H,1]CE9A
Master volume level

DRV.ON: [CE19H,1]CE9B
0: not playing, 1: playing

DATADD: [CE1AH,2]CE9C
Points to location of currently playing music data

RPTFLG: [CE1CH,1]CE9E
Remaining times to repeat playback

(Instructions for MSX-DOS will be forthcoming as the driver is adapted)

Additional resources
MSD examples (included in the archive):
https://www.msx.org/downloads/music/musica/musica-mml-examples
MuSICA driver info (translated above):
http://www.big.or.jp/~saibara/msx/data/musica.html
MGSDRV, contains a BGM>MGS compiler and playback tool (Japanese-only):
https://www.gigamix.jp/mgsdrv/index.php

Login or register to post comments

By Grauw

Ascended (8309)

Grauw's picture

06-07-2019, 22:23

You should be able to create new wiki pages, there’s no special privileges needed afaik. What is the problem? You can’t be logged in on the wiki section? If so, clear your cookies, and re-login on the home page.

Then go here and press the Create button at the top:

https://www.msx.org/wiki/MuSICA

By shram86

Expert (88)

shram86's picture

06-07-2019, 23:04

Grauw wrote:

You should be able to create new wiki pages, there’s no special privileges needed afaik. What is the problem? You can’t be logged in on the wiki section? If so, clear your cookies, and re-login on the home page.

Then go here and press the Create button at the top:

https://www.msx.org/wiki/MuSICA

Something is wrong with Chrome I guess. Allowing cookies from msx.org just gives me a 403 error. Regardless, you made me try again on Firefox, and that fixes it for now :)

Added to the wiki!

By Grauw

Ascended (8309)

Grauw's picture

07-07-2019, 01:44

Thanks for posting the article Smile.

Also I meant to get rid of the existing cookies which msx.org managed to mess up (it does that sometimes for the wiki login), so you can log in from a clean slate. I don’t know about Chrome but in Firefox you can clear a site’s cookies from the Security tab in the Page Info window. You can also use a private browsing window in Chrome to check this I guess? (Since it forgets all cookies for that session.)