Organya FIle Format Specs

Bavi_H Notes URL.txt

Original URL: http://rnhart.net/orgmaker/

Wayback Machine (in case site goes down): https://web.archive.org/web/20161204035709/http://rnhart.net/orgmaker/

Spec - Moose.txt

-=============================================================================-
                     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.




II.Specs

  A.Header
        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,
     however. 

    2.Instruments
            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.

  B.Song
            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.

        a.Note
                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.

        b.Length
                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.

        c.Volume
                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.

        d.Panning
                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.




III.Credits
        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 (http://www.gameflaws.com/cavestory/) - For
         being a damn good fansite.
        -RuneLancer - For encourangement and inspiration to do this.

Spec - Wedge of Cheese.txt

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.