MuSICA
This page was last modified 04:06, 24 July 2019 by Shram86.


Contents

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 translated into English with a hard-coded fastloader. An older archive that includes 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).

An updated 2.0 archive with the assembly source linked in this article, as well as a fixed program disk for any SCC (including the MFR SCC+), SCC in any expanded slots, and compatibility-fixed for memory mappers is available here.

Note on MuSICA 2.0: The top of the stack has been moved to directly below the playback driver in memory, at CDFFh. This will likely never cause a problem, but keep in mind you have a couple bytes fewer than the program indicates available for your songs. Additionally, MuSICA 2.0 (just like 1.0) will only use the FIRST SCC or SCC+ that it finds. If you have multiple SCCs, only plug in the one you wish to use.

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#16>)c4r2<
s3=o3l16@23dd>dd<dd>dd<dd>dd<dd>cd<

r=v15
r1=bh8h8sh8h8

Important 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

Command Definition Range
t[n] Set tempo to [n] 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
abcdefg[#/+/-][n] Play note A-G, optionally for duration 1/[n]. #/+ makes note sharp, - makes note flat. 1-64 for [n]
. Extend last note by 1/2 a beat (..= 3/4, ...=7/8 etc.)
r[n] Rest for 1/[n] beats 1-64
>/< Raise or lower octave by one per >/<

Rhythm-only macros

Command Definition Range
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]) 1-64


Other macros

Command Definition Range
q[n] Set envelope (see PSG documentation for more info) 0-8
w[n] Set decay (Not working?) 0-255
p[n] Portamente (values < 64 are most noticeable) 0-255
i[n] Vibrato 0-255
m[n] Period of envelope (untested) 0-65535
@v[n] Set master volume 0-15
@w[n] Wait (untested) 0-255
@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


Miscellaneous Tips

  • The scale begins at C and ends at B. To use the lower octave of A, B and upper octave beginning at C, wrap the notes in angle braces e.g.
<ab>cdefgab>c<
  • BGM files are not compressed when exported, so notation and empty spaces matter. When you're done composing a song, delete all unnecessary spaces. If you are using a lot of 16th and 32nd notes, use the "l[n]" macro (or change the tempo of that pattern) instead of repeating the number many times. Try to condense patterns across channels that use different instruments if they use the same arrangement of notes. Remember any macro can go in any pattern!
  • Sometimes low octave PSG sounds make better percussion than the built-in FM drum set. Experiment with the same instruments across chips.
  • Try to get the end point of the BGM song data as close to the beginning of the player as possible. Any space in between is not used, or must be used by the programmer (though keep in mind that in BASIC, the stack pointer is relocated beneath the music data).


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*
REPLAY2.BIN MuSICA 2.0 replay driver disassembly (fixed for SCC in expanded slots and memory mappers)
Example ASM playback routine

  • The replayer disassembly has been completely labeled, and has been tested to work when relocated in RAM as low as location C700h (and will likely work anywhere in page 3). Keep in mind the stack pointer must be relocated to fit around the player and music data.

At the moment, there is a MSX-DOS 1.0 compatible version of the MuSICA replay driver WITHOUT SCC support available here.
How to use:

  1. Load the driver into page 3, at least at C000h, but it will fit up to approx C580h (or C680h without SCC). It can't go beyond this due to the edge of TPA maxing out at D606h and would therefore overwrite MSXDOS.SYS.
  2. Load the music data (omitting the 7 bytes of the binary header) beneath it, in accordance with the address specified when exporting the BGM file from the MuSICA editor.
  3. Set the stack pointer beneath the BGM data.
  4. Call InitMus and InitializeIRQ as specified in the asm example above.
    1. Note: The IRQ hook will default to the beginning of Vblank. Keep in mind when coding your own graphics loop that you must either call it from the IRQLink subroutine or, preferably, chain your own Vblank interrupt.

Example source for MuSICA playback in MSX-DOS 1.0

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

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
Taro-san's MSX-DOS2 player with source (uses KAROU5):
http://sakuramail.net/fswold/music/kr5tsr07.lzh