Skip to content
This repository has been archived by the owner on Feb 12, 2023. It is now read-only.

User Reference

Jump to bottom
utz82 edited this page Apr 7, 2017 · 14 revisions

This reference is for those interested in using MDAL to compose music for low-level sound routines. If you are a sound routine coder wishing to create MDAL configurations for your tools, be sure to check out the Programmer's Reference.

Table of Contents

Getting Started

Writing MDAL Modules



Getting Started

Basic Concepts

Terminology

MDAL draws a significant portion of it's terminology from tracker music. If you've never used a tracker before, you might want to familiarize yourself with the tracker lingo first.

Any statement in an MDAL file is a command. Commands are grouped into blocks, which in turn form a module:

Only a few fixed commands exist in MDAL. Most of the commands that will be available are specific to the music driver/player you are composing for. These custom commands are defined in a configuration file. To learn about custom commands, refer to the config's documentation (usually found in the /docs folder).

Blocks come in different flavors - headers, sequences, data blocks, and samples. Some of these may be unavailable depending on the configuration you use.

The header block contains one or more global commands, which are used to set various general parameters affecting the entire module, for example the configuration that should be used.

The header block is usually followed by the sequence block, which contains the order of the module. The order is the main script of your song, the master plan, if you will.

The header block is followed by one or more data blocks. These can be pattern blocks containing the actual music data, or table blocks containing instrument-specific aspects such as volume envelopes or effect chains.

Furthermore, sample blocks containing raw sample data or references to external resources may be available.


Setting up the MDAL Compiler

The MDAL compiler does not require any installation. Simply unzip it to a directory of your choice. If you plan on using third-party configurations, copy those to the /config folder.

Building the Compiler from Source

The compiler is written in pure C++ and has no further dependencies. Building the MDAL compiler from source is a matter of simply running make on a Linux/Unix system with GCC installed. On non-Linux/Unix systems, you can build the MDAL compiler using minGW. You'll need to adjust the makefile accordingly.


Compiling MDAL Modules

The MDAL compiler is a command line tool. In order to compile your MDAL module, open a shell (cmd or powershell on Windows), navigate to the MDAL folder, and run

mdalc -i filename.mdal

where filename.mdal is the name of the MDAL module you want to compile. This will output a file named "music.asm" which you can then use as input for your target music driver.

You can specify another name for the output file with

-o outfile

and print some extra information with -v.



Writing MDAL Modules


General Syntax Rules

  1. One command per line, one line per command. Each command must be on a seperate line, and commands may not contain a line break. Exception: Pattern and table rows can contain more than one command on a given line.
  2. Whitespace is ignored. That means that with the above exception, you can format your module as you wish - the compiler does not care about spaces, tabs, and ignores empty lines.
  3. Command keywords are UPPERCASE.
  4. User strings are lowercase. Any string you provide as an argument to a command must be lowercase.
  5. Numbers can be decimal or hexadecimal. Hex numbers are prefixed with $.

Comments

Both C style block comments (a block of text encased in /* ... */) as well as C++ style single line comments (prepended with //...) are supported.


Creating Blocks

MDAL module data is organized in blocks. The start of a block is denoted by the block delimiter :, followed by the block name. Block names can normally be chosen by the user. Names must be unique, must begin with a letter, and may contain only lowercase letters and numbers.

There are two exceptions - the Header block, which does not use a name or a block delimiter, and the Sequence block, which is denoted with :SEQUENCE.


Header Block

The header block is written before the first block delimiter (ie. at the top of the file). It is the only block that does not use a block name. The header block must necessarily set the built-in CONFIG command. In addition, it may contain one or more global commands, depending on the configuration used.

CONFIG

The CONFIG command specifies which configuration the MDAL compiler should use to process your module. Each MDAL module must have exactly one CONFIG command.
Syntax CONFIG=configuration_name
Example CONFIG=BetaPhase

Global Commands

The MDAL configuration you use may provide for additional global parameters (called global commands), for example a global song speed setting. Global commands may only be set once in a given module.

For information on available global commands, refer to the relevant configuration documentation.


Sequence Block

The sequence block is initiated with :SEQUENCE. It contains a list of generic data blocks to be used as patterns, in the order in which they are to be played.

The [LOOP] command

Many configurations offer a possibility to set a loop point in the sequence. The target player will continue playback at this point once it has completed the sequence. Refer to your target configuration's documentation to verify that the loop command is available.

Loop points are denoted by the command [LOOP], which is placed on the line before the point in the sequence you wish to jump to.

Example Sequence Block:

:SEQUENCE
   intro
   [LOOP]
   theme1
   theme1
   interlude
   theme2
   theme2

This will create a sequence with four unique pattern data blocks named "intro", "theme1", "interlude", and "theme2". "theme1" and "theme2" will each be repeated twice. After the player has completed the sequence, it will loop to the first "theme1" pattern.


Data Blocks

Each MDAL configuration specifies one or more data block types. Data blocks of type "pattern" (containing the actual music data such as note triggers, effect commands, etc.) will always be available. Depending on the configuration, additional data block types, for example fx tables, may be available. MDAL can automatically deduce the type of a given block, you do not need to specify it explicitly.

The data in all data blocks is organized into rows, representing a vertical time flow. Each row may contain one or more commands. Commands generally take the form

COMMAND_NAME=value

An exception are commands marked "automatic" in the documentation. Such commands do not require an additional parameter.

There are no pre-defined data block commands in MDAL (with one exception, see below). Instead, data block commands are defined by the configuration. Refer to your target configuration's documentation to see which data block commands are available.

Block rows on which you do not wish to issue any command must still be written. The . (dot) command denotes such "empty" lines.

Example Data Block

:theme1
   A=c2, B=c1, SPD=8
   .
   A=c3
   A=c4, B=rest

In row 2, the . command is used to denote that no change will happen in this row.


Sample Blocks

This feature is not implemented yet.

Clone this wiki locally