MuSICA
This page was last modified 08:30, 19 February 2021 by Mars2000you. Based on work by Gdx and Shram86.
MuSICA 1.0 - SCC intro screen

Contents

Description

MuSICA is a music editor released in 1990 by ASCII. An MSX2 or higher is normally required, but a little trick makes it compatible also with MSX1 computers having 64kB RAM (see Links section).

It supports all 9 FM channels of the OPLL or MSX-MUSIC soundchip (including swapping channels 7-9 for 5-unit rhythm), the 3 PSG channels, and the 5 SCC channels for a total of up to 17 voices.

This editor allows to create MSD files that can be compiled to produce BGM files, what implies they can be used as background for other applications. It includes also three voice editors, one for each supported soundchip.

Versions

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, some MSD files, an (abandoned) Windows-based editing tool, two playback drivers and example of 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.

After launching, version 1.0 will ask you if a SCC or SCC+ is present and in which slot. The SCC/SCC+ is automatically detected in version 2.0.

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 musics. 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.

Screens

Music editor

MuSICA - Music editor

You can create here MSD files (see below for details).

If you press ESC, an extra line gives access to some features:

  • press L then insert a line number to go to this line in the editor
  • press B then define the start and the end of a block in the editor with the cursors and RETURN, this block can then be (C)opied, (M)oved or Cu(T)
  • press V to access the OPLL voice editor
  • press D to access the disk menu
  • press N to clear the editor with exception of the 17 first original lines (FM1 to SCC5) without MML

Voice editors

If you press ESC when you are in one of the three voice editors, an extra line gives access to some features:

  • press C to copy a voice to another voice
  • press S to swap two voices
  • press M to go to another voice editor in the following order: OPLL > PSG > SCC > OPLL ...
  • press Q to go back to the music editor

OPLL voice editor

MuSICA - OPLL voice editor

A maximum of 100 OPLL voices can be created and/or modified here. By default, 63 OPLL voices are available.

Note: it is not possible to modify the 15 hardware MSX-MUSIC instruments (voices 0,2,3,4,5,6,9,10,12,14,16,23,24,33 and 48).

Many parameters can be changed in Modulator and Carrier modes, with exception of the two first parameters that concern only the Modulator.

Technical explanation: the FM soundchip has 9 channels of 2-operator voices, which can be configured as either 9 tone channels or 6 tone channels and 5 'rhythm' sounds. The drum sounds use the same operators as 3 of the tone channels.

There are two possible ways of configuring the operators in each channel, referred to by Yamaha as 'algorithms', and only one of them actually involves phase modulation of one operator (the 'carrier') by the other (the 'modulator'). However the first operator can modulate itself in both algorithms, referred to by Yamaha as 'feedback'.

Parameter Values
Mod.levl Modulation level 0 to 63
Feedback 0 to 7
Percussion Percussion mode 0 or 1
Muliply Frequency multiply 0 to 15
Attc Attack Rate 0 to 15
Decay Decay Rate 0 to 15
Sustn Sustain Level 0 to 15
Rlse Release Rate 0 to 15
Key Mode Envelope scaling per key 0 or 1
Key Level Volume scaling per key 0 to 3
A/FM Tremolo ON/OFF
Vibrato ON/OFF
Sustained ON/OFF

PSG voice editor

MuSICA - PSG voice editor

A maximum of 30 PSG voices can be created and/or modified here. By default, 10 PSG voices are available.

The following parameters can be changed:

Parameter Values
Attc Attack Rate 0 to 32
Decay Decay Rate 0 to 32
Sustn Sustain Level 0 to 15
Rlse Release Rate 0 to 32
Snd Sound Output ON/OFF
Nse Noise Output ON/OFF
N.Freq Noise Frequency 0 to 31

SCC voice editor

MuSICA - SCC voice editor

A maximum of 50 SCC voices can be created and/or modified here. By default, 8 SCC voices are available.

The following parameters can be changed:

Parameter Values
Attc Attack Rate 0 to 32
Decay Decay Rate 0 to 32
Sustn Sustain Level 0 to 15
Rlse Release Rate 0 to 32


You can also modify the data that define the form of the SCC wave and see the result of your changes on the screen.

Disk menu

MuSICA - Disk menu

MuSICA uses the following types of files:

  • MSD - uncompiled music data
  • VCD - voice data
  • BGM - compiled background music

You can here

  • load or save MSD and VCD files
  • save BGM files what implies the conversion of the data in memory

Useful keys

Key
Cursors Move in the voice editors
ESC Access to extra features in the editors
Back to edit mode from extra mode or disk menu
SPACE Increase value of current parameter in voice editors
N Decrease value of current parameter in voice editors
After using of ESC
B Define block in music editor
C Copy voice in voice editors
C (after B) Copy block in music editor
D Go to disk menu
L Go to specified line in music editor
M Browse between the voice editors
M (after B) Move block in music editor
N Clear the music editor
Q Go from a voice editor to music editor
S Swap two voices in voice editors
T (after B) Cut block in music editor
V Go from music editor to OPLL voice editor


Making MSD files

MuSICA uses a Music Macro Language (MML) that you can compare to the one used with the Basic instruction PLAY.

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

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

General layout

A typical MSD file looks like the example below (that you would have if you completed the tutorial by Philip Linde in the archive linked above)

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.

; 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

MuSICA MML instructions

Note: The instructions that are specific to an (abandoned) Windows-based editing tool or MSX expanded tools based on MuSICA are not included.

Instruction Effect Values / Remarks
abcdefg[<halftone>][<period>] Specifies a note from the scale, optionally with a specific increasing / decreasing halftone and/or period * <halftone> = + or # for increasing halftone (sharp), - for decreasing halftone (flat)
* <period>=one or several . (dots), each . lengthens note by 1.5
i<depth> Specifies vibrato depth <depth>=0 to 255 (default value: 0 = OFF)
l<length> Specifies the length of the notes after this instruction * <length>=1 to 64
* 1=full note 2=half note 3=third note 4=quarter note (default value) etc...
* If no length is specifed the length of the last played note is used
m<speed> Specifies vibrato and portamento speed <speed>=1 to 255
o<octave> Specifies the octave of the notes after this instruction <octave>=1 to 8 (default value: 4)
p<width> Specifies portamento width * <width>=0 to 255 (default value: 0 = OFF)
* Values < 64 are most noticeable
r<pause>[<period>] Specifies a pause (or rest) * <pause>=1 to 64
* 1=full pause 2=half pause 3=third pause 4=quarter pause (default value) etc...
* If no pause is specified the length specified by the last l instruction will be applied
* <period>=one or several . (dots), each . lengthens pause by 1.5
s<sustain> Specifies sustain setting <sustain>=0 (OFF - default value) or 1 (ON)
t<tempo> Specifies the tempo of the notes after this instruction * <tempo>=32 to 255 (default value: 120)
* it indicates the number of quarter notes per minute
* If no tempo is set the tempo of the last played note will be used
v<volume> Specifies the volume of the notes after this instruction * <volume>=0 to 15 (default value: 8)
* If no volume is set the volume of the last played note will be used
w<length> Specifies decay length <length>=0 to 8
y<register>,<value> Writes value directly in a register of the sound generator * <value>=0 to 255
* Useful for example to change the pitch of the FM rhythm sound
* See also CALL AUDREG
z<detune> Specifies detune setting <detune>=0 to 255 (default value: 0 = OFF)
< Decreases one octave
> Increases one octave
( Specifies the start of notes played as legato
) Specifies the end of notes played as legato
@<voice> Changes used voice <voice>=0 to 99 for OPLL, 0 to 29 for PSG, 0 to 49 for SCC
/<repetition> Repeats last sequence * <repetition>=0 to 255
* With value 0, the sequence will not be played
Only for PSG
q<shape> Specifies an envelope shape * <shape>=0 to 8 (default value: 8)
* See PSG documentation for more info
Only for rhythm
b[<pause>] Generates bass drum * <pause>=1 to 64 (default value: 4)
* = rest period after each rhythm "beat"
c[<pause>] Generates cymbals * <pause>=1 to 64 (default value: 4)
* = rest period after each rhythm "beat"
h[<pause>] Generates hi-hat * <pause>=1 to 64 (default value: 4)
* = rest period after each rhythm "beat"
m[<pause>] Generates tom-tom * <pause>=1 to 64 (default value: 4)
* = rest period after each rhythm "beat"
s[<pause>] Generates snare drum * <pause>=1 to 64 (default value: 4)
* = rest period after each rhythm "beat"
v<instrument><volume> Change volume of specified rhythm-instrument * <instrument>=b, c, h, m or s
* <volume>=0 to 15

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 music, 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 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).

Creating and using BGM files

Creation

From the DISK menu in the MuSICA editor (ESC > D key), select option 5 to compile and export your current MSD file 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 music 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 music is <2kB, C5B7 is a suitable location. If it is larger, calculate accordingly in respect to your desired memory configuration.

Usage

If you are creating a BASIC game, you can use the BASIC examples provided in the MuSICA archive to load either the REPLAY or GAROU5 driver and play your file. These drivers are compatible with any MSX generation.

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

Note: 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:

  • 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.
  • 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.
  • Set the stack pointer beneath the BGM data.
  • Call InitMus and InitializeIRQ as specified in the asm example above.

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

Links