ROL Format

From ModdingWiki
Jump to: navigation, search
ROL Format
Format typeMusic
Notation typeCustom
InstrumentsOPL
Max channel count9 or 11
Max track count45
Max pattern count1
Max order count0
Tags?None
Games

The ROL Format is created by Ad Lib, Inc. for AdLib Visual Composer program. Some games use it for the background music.

Earlier ROL files goes with instrument files, but later they were superseded by single instrument bank file.

File format

Header

Data type Name Description
UINT16LE majorVersion Major version number (usually 0)
UINT16LE minorVersion Minor version number (usually 4)
char[40] signature Signature, null terminated (usually "\roll\default")
UINT16LE tickBeat Number of ticks per beat
UINT16LE beatMeasure Number of beats per measure
UINT16LE scaleY Editing scale (Y axis)
UINT16LE scaleX Editing scale (X axis)
BYTE reserved Unused, set to zero
UINT8 isMelodic OPL rhythm mode: 0 = percussive, 1 = melodic
UINT16LE[45] counters Counter values for each track (see below)
BYTE[38] filler Padding, set to zero

The most known version of this format is 0.4.

The fields tickBeat and beatMeasure are used to convert ticks into beats and measures for drawing a musical staff in AdLib Visual Composer.

Tracks

Header is followed by 45 tracks of different type. The first is always a tempo track. Then it's followed by Voice, Timbre, Volume, and Pitch tracks, repeated 11 times for each possible AdLib voice.

This resulting in actual track count:

1 + 4 * 11 = 45

ROL files always contain 45 tracks even if 9-voice melodic mode is used.

Tempo track

Data type Name Description
char[15] trackName Track name, null terminated (usually "Tempo")
Single basicTempo Song tempo, in beats-per-minute
UINT16LE nEvents Number of events
E_TEMPO[nEvents] tempoEvents Array of tempo events

E_TEMPO structure:

Data type Name Description
UINT16LE atTick Time of event, in ticks (absolute)
Single multiplier Tempo multiplier (in range 0.01 - 10.0)

The basicTempo field controls the song playback speed and is measured in beats per minute. The playback frequency can be calculated as follows:

frequency = (basicTempo / 60) * tickBeat

For a song that plays at 120BPM and with 10 ticks per beat, this works out as:

 frequency = (120 / 60) * 10
           = 20 Hz

Therefore playback should happen at 20 ticks per second to be at the correct tempo.

Tempo multiplier allows to change song speed during playback, so the actual frequency is calculated like this:

frequency = (basicTempo / 60) * tickBeat * multiplier

Voice track

Data type Name Description
char[15] trackName Track name, null terminated (usually "Voix ##", # - voice number from 0)
UINT16LE nTicks Total ticks for current track
E_NOTE[] noteEvents Array of note events

E_NOTE structure:

Data type Name Description
UINT16LE note Note number (0: note off, 12..107: note on)
UINT16LE duration Note duration, in ticks

This structure is repeated while the sum of duration values is less than nTicks value.

The note value is compatible with MIDI standard (48 is middle-C).

Timbre track

Data type Name Description
char[15] trackName Track name, null terminated (usually "Timbre ##", # - voice number from 0)
UINT16LE nEvents Number of events
E_TIMBRE[nEvents] timbreEvents Array of timbre events

E_TIMBRE structure:

Data type Name Description
UINT16LE atTick Time of event, in ticks (absolute)
char[9] instName Instrument name, null terminated
BYTE filler Padding, set to zero
UINT16LE unknown Unknown value, sometimes equal to instrument index

These events set the instrument to be played on specified channel.

Instrument name is a reference to INSTNAME.INS file, or an instrument name inside STANDARD.BNK file.

Volume track

Data type Name Description
char[15] trackName Track name, null terminated (usually "Volume ##", # - voice number from 0)
UINT16LE nEvents Number of events
E_VOLUME[nEvents] volumeEvents Array of volume events

E_VOLUME structure:

Data type Name Description
UINT16LE atTick Time of event, in ticks (absolute)
Single volume Volume multiplier (in range 0.0 - 1.0)

These events set the volume for specified channel.

Pitch track

Data type Name Description
char[15] trackName Track name, null terminated (usually "Pitch ##", # - voice number from 0)
UINT16LE nEvents Number of events
E_PITCH[nEvents] pitchEvents Array of pitch events

E_PITCH structure:

Data type Name Description
UINT16LE atTick Time of event, in ticks (absolute)
Single pitch Pitch variation (in range 0.0 - 2.0)

These events works the same as Pitch Bend events. Nominal pitch value is 1.0.

Counter values

There are 45 counter values for each track.

Data type Name Description
UINT16LE[11] cTicks Total ticks for each voice track
UINT16LE[11] cTimbreEvents Number of events for each timbre track
UINT16LE[11] cVolumeEvents Number of events for each volume track
UINT16LE[11] cPitchEvents Number of events for each pitch track
UINT16LE cTempoEvents Number of events in the tempo track

Rhythm mode

If isMelodic is 1, then rhythm mode is off. Valid channels are 0 to 8 inclusive.

When isMelodic is 0, then rhythm mode is on. Valid channels are 0 to 10, with 0 to 5 being melodic and 6 to 10 being percussive (see table below).

Both the top cymbal and the snare drum only use the OPL carrier registers, but the values for these registers are actually stored in the file's modulator fields. The carrier fields for these instruments appear to be unused. In other words, percussive instruments always have their settings loaded from the instrument's modulator fields, even when the values are loaded into the OPL chip's carrier registers.

Channel Percussive instrument Operator used in file OPL cell
0-5 Melodic Modulator
Carrier
Modulator
Carrier
6 Bass drum Modulator
Carrier
13 - Channel 7 Modulator
16 - Channel 7 Carrier
7 Snare drum Modulator 17 - Channel 8 Carrier
8 Tom tom Modulator 15 - Channel 9 Modulator
9 Top cymbal Modulator 18 - Channel 9 Carrier
10 Hi-hat Modulator 14 - Channel 8 Modulator

BNK files have an indicator whether a patch is percussive or melodic, however it is not used by official ROL player. It's controlled entirely by which channel it is used on. It is possible to use the same patch for both percussive and melodic channels.

In percussive mode, the pitch of the single-operator percussive instruments is handled specially (that is, the snare drum, tom tom, top cymbal and hi-hat. The bass drum is not considered here.) When a note is played on channel 8 (tom-tom), the pitch on the other instruments is changed also. The changes are:

Channel Percussive instrument Note pitch
7 Snare drum 7 semitones higher than the last tom-tom note on channel 8
8 Tom tom Use pitch as indicated in the note-on event
9 Top cymbal Use pitch from last tom-tom note on channel 8
10 Hi-hat 7 semitones higher than the last tom-tom note on channel 8

The initial frequency for the tom-tom is supposed to be two octaves below middle-C according to comments in the official adlib.c, however ! this doesn't seem to be the case.

Tools

The following tools are able to work with files in this format.

Name PlatformPlay? Create new? Modify? Convert/export to other? Import from other? Access hidden data? Edit metadata? Notes
playrol.exe DOSYesNoNoNoNoNoNo Included with AdLib Visual Composer
AdLib convert.exe DOSNoNoNoYes; .musNoNoNo Part of AdLib Programmer's Guide
AdLib rol2midi.exe DOSNoNoNoYes; .mdiNoNoNo Part of AdLib Programmer's Guide

See also

Credits

This file format was described by Chris Holmes in 1992 and then adapted and supplemented by binarymaster. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)