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
MuSICA initially appeared in the first disk of Disk Communication 1990-10 together with its specification document. The latter, which can be accessed by choosing the right menu after choosing MuSICA, instructs to copy MUSICA.BAS (startup file), MUSICED.BIN, BGM.BIN and VOICE.VCD for personal use, though only first two are necessary to run.
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
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
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
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
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.
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 for MSX1 ROM
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 beneath the player and not intervene with music data.
At the moment, there is a MSX-DOS 1.0 compatible version of the MuSICA replay driver WITHOUT SCC support available here in tniasm format or here in z80asm format.
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
Troubleshooting:
- MuSICA requires the stack to be BELOW itself in RAM. To be safe, the routines provided here set the stack pointer below the music song data as well (which defaults to $a5b0) to a usually-valid HIGHMEM address of $a39d.
- Remember the pointer to the song start position expects byte 0 of the song data - you must skip the first seven bytes of the .BGM file to avoid passing the 7-byte file header as a 'song byte' to the player routine.
- The source is not 100% disassembled. Take care when moving things around and un-commenting lines (especially related to SCC playback!).
- Playback address in the BGM file matters! If you export your music file from within MuSICA as meant to be at address 0xa5b7, that is where the music file (immediately after the header) should be in memory. Music files cannot be relocated unless you re-export them with a different target address from the MuSICA program.
Additional playback driver information
(Note that all of these call addresses are based on the default MuSICA load address of 0xCE00. If you choose to load the playback driver into a different location, you must recalculate these offsets.)
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
- Method to run MuSICA on MSX1 by Tiny Yarou (Japanese)
- MSX Magazine 1990-10 manual (Japanese)