Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Organya FIle Format Specs
Original URL:
Wayback Machine (in case site goes down):
ORG File Format Description Ver 1.0
by Moose
|Table of Contents |
| I.Foreward |
| |
| II.Specs |
| |--A.Header |
| | |--1.File Properties |
| | |--2.Instruments |
| | |
| |--B.Song |
| |--1.Note Positions |
| |--2.Note Properties |
| |--a.Note |
| |--b.Length |
| |--c.Volume |
| |--d.Panning |
| |
| III.Credits |
I. Foreward
This document is basically a summarized, more organized version of my
posts at the Cave Story Fansite Forums. They were all made in the same day,
while I was working on the specs. It wasn't really too hard to figure out the
format, especially since I was familiar with the different attributes that
OrgMaker gave its notes. Hopefully this document will help those working in
the Cave Story community to create their own ORG-editing programs, or perhaps,
hopefully, an ORG-to-MIDI or MIDI-to-ORG converter. Even if no one reads this,
it was fun for me to make, so I hope you enjoy it.
A few things to note: I will be signifying all offsets using the 0x
precursor, but in cases where I need to define a hex value, I will be ordering
from left to right. Keep in mind that the file itself stores these values
backwards, such that 7D0 would be the two-byte value D0 07 in the file.
In addition, there are no buffers between sections - one goes right
into the next.
The header of an ORG file is 114 bytes long and contains several
different pieces of information about the file itself, as well as the
instruments used within the music. The header begins with the string,
"Org-02," followed by several different file settings. After the settings
are a set of bytes defining the instruments used in the file.
1.File Properties
Below is a list of offsets between 0x06 and 0x11 and what
properties they correspond to, as well as their value ranges:
Offset Length Property Range(Hex)
0x06 2 bytes Tempo 01 to 7D0
0x08 1 byte Steps per Bar Predef*
0x09 1 byte Beats per Step Predef*
0x0A 4 bytes Loop Beginning** 0 to FFFFFFFF
0x0E 4 bytes Loop End** 0 to FFFFFFFF
*Steps and Beats per bar cannot be set by the user - OrgMaker limits the
values to 8 combinations(Steps/Beats): 4/4, 3/4, 4/3, 3/3, 6/4, 6/3, 2/4,
and 8/4. The results of any other cominations is unknown and not
recommended for compatibility.
**OrgMaker restricts the user to only selecting which bar to begin and end
looping - the marker will be placed at the beginning of the bar specified.
this, however, is dependant on the steps and beats per bar settings.
Values that do not begin on the first beat of a bar *will* play correctly,
The instruments settings of the header takes up the remaining 96
bytes of the header. There are 16 instruments in total: 8 sounds and 8
drums can be used. Each instrument is represented by a 6-byte long entry
defining several properties. The offsets in the table below are for the
first instrument - simply repeat these six bytes until all 16 instruments
are accounted for.
Offset Length Property Range(Hex)
0x12 2 bytes Pitch 64 to 76C
0x14 1 byte Instrument 00 to 63 OR 00 to 0B*
0x15 1 byte "Pi"** 00 to 01
0x16 2 bytes Number of Notes*** 00 to 100
*The first range is for sounds, the second range is for drums - drum
offsets begin at 0x42.
**Pi is a true or false value that, if true, disables sustaining notes,
playing them only on the first beat of the note.
***Total number of notes in the entire file for specific instrument.
Sustained notes are counted as one note.
The rest of an ORG file is where the actual notes are stored. Notes
are first seperated by instrument - only instruments that play any notes
are included. Instruments without notes do not have a section in this
block. Each instrument is divided into two sections: Note Positions and
Note Properties.
1.Note Positions
The Note Positions section contains a block of data whose length is
defined by the "Number of Notes" property for the instrument - each note
has a 4-byte value defining the exact beat it begins on. For example, a
note placed on the fourth beat in the first bar of a song has a value of
00000004 in the Note Positions block.
Note Positions are placed in sequential order - a note with a
smaller value is placed before another with a larger value. Thus the note
at 000001CD is placed before the note at 000002FF. The limit for a note
position is FFFFFFFF, although OrgMaker cannot display this far depending
on it's display.
2.Note Properties
The Note Properties section contains four blocks of data whose
length is defined by the "Number of Notes" property for the instrument -
each note has a 1-byte value in each block. Each block is arranged
sequentially in a similar way to the Note Positions section. The first
block defines the note itself, the second block note length, the third
block volume, and the fourth block panning.
NOTE: OrgMaker limits each channel so that only one note can be played on
a single instrument at any time. Note CANNOT overlap if they are on
the same instrument. This affects note length and position.
The first block contains the actual note to be played. Each
byte corresponds to a single note that has already been defined in the
Note Positions section. Each byte can range from between 00 and 5F. 00
corresponds to the C key on a very low octave, and adding 1 moves up a
key on the piano, including black keys.
The second block contains the values corresponding to the
length of each note in steps. A value of 00 will display a note but it
will not be played. The range of safe values is 00 to FF.
The third block defines the volume of each note. The range is
00 to F8, with 00 being barely audible and F8 being decently loud.
Values larger than F8 will play louder once, and then play at the F8.
They will not be displayed in OrgMaker.
The fourth and final block contains the panning value for each
note. Values can be between 00 and 0C, with 00 being full left pan, 06
being centered, and 0C being full right.
A few people who deserve credit for their work:
-Radical R's Translations - For translating OrgMaker
-Pixel Studios - For making Org Maker and Cave Story, duh.
-Aeon Genesis - For translating Cave Story.
-Cave Story, A Tribute Site ( - For
being a damn good fansite.
-RuneLancer - For encourangement and inspiration to do this.
All integer values are unsigned little-endian.
A "click" is the smallest unit of time in an org file.
6 bytes: ascii string "Org-02" (or "Org-03" if the file uses percussion instruments only available in orgmaker 2.05)
2 bytes: "wait" value (the length of a click in milliseconds)
1 byte: beats per measure
1 byte: clicks per beat
4 bytes: position of the loop start, in clicks (the first click being position 0)
4 bytes: position of the loop end, in clicks
for each track:
2 bytes: "freq" value*
1 byte: instrument
1 byte: 1 if "pi" checkbox is checked, 0 otherwise*
2 bytes: number of resources
for each track:
for each resource in the track:
4 bytes: position of the resource, in clicks
for each resource in the track:
1 byte: note (0=lowest note, 45=A440, 95=highest note, 255=no change)
for each resource in the track:
1 byte: duration (in clicks, I believe this is ignored if note value is "no change")
for each resource in the track:
1 byte: volume (0=silent, 200=default, 254=max, 255=no change)
for each resource in the track:
1 byte: pan (0=full left, 6=center, 12=full right, 255=no change)
*Even though orgmaker only allows you to edit these for melody tracks, percussion tracks also have this data,
with the default values of freq=1000, pi=0.
I haven't tested to see if modifying these has any effect on playback.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment