ROL Format

Format type	Music
Notation type	Custom
Instruments	OPL
Max channel count	9 or 11
Max track count	45
Max pattern count	1
Max order count	0
Tags?	None
Games	Pee and Gity Hi Octane

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	Platform	Play?	Create new?	Modify?	Convert/export to other?	Import from other?	Access hidden data?	Edit metadata?	Notes
`playrol.exe`	DOS	Yes	No	No	No	No	No	No	Included with AdLib Visual Composer
AdLib `convert.exe`	DOS	No	No	No	Yes; .mus	No	No	No	Part of AdLib Programmer's Guide
AdLib `rol2midi.exe`	DOS	No	No	No	Yes; .mdi	No	No	No	Part of AdLib Programmer's Guide

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!)