Text import and export
This feature creates a text equivalent of an FTM file.
It is intended to facilitate the creation of automated tools for
reading or creating Famitracker data.
The syntax consists of a list of commands. One command begins
each line, followed by a series of whitespace-separated tokens
to be consumed by that command. Blank lines are skipped.
The import begins with a new empty document, and each command
makes a change to the document.
The format is not case-sensitive.
Future versions may not be backwards compatible;
save as FTM instead if this is needed.
Commands
- # ...
A line beginning with a # command is ignored by the importer, treated as a comment.
# must be followed by at least one whitespace character before any comments appear.
- TITLE [title]
- title: string - the document's title
- AUTHOR [author]
- title: string - the document's author
- COPYRIGHT [copyright]
- title: string - the document's copyright information
- COMMENT [comment]
This adds a line to the document comment.
Multiple COMMENT commands will each add a new line to the comment.
- comment string - line of text to add
- MACHINE [machine]
- machine: int[0,1] - 0 for NTSC, 1 for PAL
- FRAMERATE [fps]
- fps: int[0,800] - music framerate, 0 for machine default
- EXPANSION [chips]
- chips: int[0,255] - bitfield representing expansion chips used: 1=VRC6, 2=VRC7, 4=FDS, 8=MMC5, 16=N163, 32=S5B
- VIBRATO [mode]
- mode: int[0,1] - 0 for old style vibrato, 1 for new style
- SPLIT [split]
- split: int[0,255] - split point where Fxx effect sets tempo instead of speed
- N163CHANNELS [channels]
- channels: int[1,8] - channels used by N163 expansion
- MACRO [type] [index] [loop] [release] [setting] : [macro]
Defines a macro sequence for a 2A03 instrument.
- type: int[0,4] - 0=volume, 1=arpeggio, 2=pitch, 3=hi-pitch, 4=duty
- index: int[0,127] - index of the macro
- loop: int[-1,253] - loop point, -1 for no loop
- release: int[-1,253] - release point, -1 for no release
- setting: int[0,255] - macro setting (for arpeggio: 0=absolute, 1=fixed, 2=relative)
- macro: int_list[-128,127] - macro sequence
- MACROVRC6 [type] [index] [loop] [release] [setting] : [macro]
Defines a macro sequence for a VRC6 instrument.
- type: int[0,4] - 0=volume, 1=arpeggio, 2=pitch, 3=hi-pitch, 4=pulse-width
- index: int[0,127] - index of the macro
- loop: int[-1,253] - loop point, -1 for no loop
- release: int[-1,253] - release point, -1 for no release
- setting: int[0,255] - macro setting (for arpeggio: 0=absolute, 1=fixed, 2=relative)
- macro: int_list[-128,127] - macro sequence
- MACRON163 [type] [index] [loop] [release] [setting] : [macro]
Defines a macro sequence for a Namco 163 instrument.
- type: int[0,4] - 0=volume, 1=arpeggio, 2=pitch, 3=hi-pitch, 4=wave
- index: int[0,127] - index of the macro
- loop: int[-1,253] - loop point, -1 for no loop
- release: int[-1,253] - release point, -1 for no release
- setting: int[0,255] - macro setting (for arpeggio: 0=absolute, 1=fixed, 2=relative)
- macro: int_list[-128,127] - macro sequence
- MACROS5B [type] [index] [loop] [release] [setting] : [macro]
Defines a macro sequence for a Sunsoft 5B instrument.
- type: int[0,4] - 0=volume, 1=arpeggio, 2=pitch, 3=hi-pitch, 4=tone
- index: int[0,127] - index of the macro
- loop: int[-1,253] - loop point, -1 for no loop
- release: int[-1,253] - release point, -1 for no release
- setting: int[0,255] - macro setting (for arpeggio: 0=absolute, 1=fixed, 2=relative)
- macro: int_list[-128,127] - macro sequence
- DPCMDEF [index] [size] [name]
Creates a DPCM sample of the specified size in bytes.
Use the DPCM command to fill in the sample data.
- index: int[0,63] - index of the sample
- size: int[0,4081] - size in bytes to allocate for the sample
- name: string - original filename of sample
- DPCM : [data]
Fills in sample data for the sample defined by the last DPCMDEF command.
The data list may be of any length as long as it does not exceed the allocated
sample length. Multiple DPCM commands will resume filling the sample
where the previous one left off.
- data: hex_list[00,FF] - contents of the sample
- INST2A03 [index] [seq_vol] [seq_arp] [seq_pit] [seq_hpi] [seq_dut] [name]
Defines a 2A03 instrument. To add DPCM sample key mappings, use the KEYDPCM command.
Use the MACRO command to define sequences for use with 2A03 instruments.
- index: int[0,63] - index of the instrument
- seq_vol: int[-1,127] - volume macro sequence, -1 for none
- seq_arp: int[-1,127] - arpeggio macro sequence, -1 for none
- seq_pit: int[-1,127] - pitch macro sequence, -1 for none
- seq_hpi: int[-1,127] - hi-pitch macro sequence, -1 for none
- seq_dut: int[-1,127] - duty macro sequence, -1 for none
- name: string - name of the instrument
- INSTVRC6 [index] [seq_vol] [seq_arp] [seq_pit] [seq_hpi] [seq_wid] [name]
Defines a VRC6 instrument.
Use the MACROVRC6 command to define sequences for use with VRC6 instruments.
- index: int[0,63] - index of the instrument
- seq_vol: int[-1,127] - volume macro sequence, -1 for none
- seq_arp: int[-1,127] - arpeggio macro sequence, -1 for none
- seq_pit: int[-1,127] - pitch macro sequence, -1 for none
- seq_hpi: int[-1,127] - hi-pitch macro sequence, -1 for none
- seq_wid: int[-1,127] - pulse width macro sequence, -1 for none
- name: string - name of the instrument
- INSTVRC7 [index] [patch] [r0] [r1] [r2] [r3] [r4] [r5] [r6] [r7] [name]
Defines a VRC7 instrument.
- index: int[0,63] - index of the instrument
- patch: int[0,15] - VRC7 patch used by the instrument
- r0-7: hex[00,FF] - custom patch register data
- name: string - name of the instrument
- INSTFDS [index] [mod_enable] [mod_speed] [mod_depth] [mod_delay] [name]
Defines an FDS instrument.
Use the commands FDSWAVE, FDSMOD, and FDSMACRO to fill in the
waveform, modulation table, and macro data for the FDS instrument.
- index: int[0,63] - index of the instrument
- mod_enable: int[0,1] - 0 for modulator disabled, 1 for enabled
- mod_speed: int[0,4905] - modulator speed
- mod_depth: int[0,63] - modulator depth
- mod_delay: int[0,255] - modulator delay
- name: string - name of the instrument
- INSTN163 [index] [seq_vol] [seq_arp] [seq_pit] [seq_hpi] [seq_wav] [w_size] [w_pos] [w_count] [name]
Defines a Namco 163 instrument.
Use the MACRON163 command to define sequences for use with N163 instruments.
- index: int[0,63] - index of the instrument
- seq_vol: int[-1,127] - volume macro sequence, -1 for none
- seq_arp: int[-1,127] - arpeggio macro sequence, -1 for none
- seq_pit: int[-1,127] - pitch macro sequence, -1 for none
- seq_hpi: int[-1,127] - hi-pitch macro sequence, -1 for none
- seq_wav: int[-1,127] - wave macro sequence, -1 for none
- w_size: int[0,32] - wave length
- w_pos: int[0,127] - wave memory position
- w_count: int[0,16] - number of waves
- name: string - name of the instrument
- INSTS5B [index] [seq_vol] [seq_arp] [seq_pit] [seq_hpi] [seq_ton] [name]
Defines a Sunsoft 5B instrument.
Use the MACROS5B command to define sequences for use with S5B instruments.
- index: int[0,63] - index of the instrument
- seq_vol: int[-1,127] - volume macro sequence, -1 for none
- seq_arp: int[-1,127] - arpeggio macro sequence, -1 for none
- seq_pit: int[-1,127] - pitch macro sequence, -1 for none
- seq_hpi: int[-1,127] - hi-pitch macro sequence, -1 for none
- seq_ton: int[-1,127] - tone macro sequence, -1 for none
- name: string - name of the instrument
- KEYDPCM [inst] [octave] [note] [sample] [pitch] [loop] [loop_point] [delta]
Adds a DPCM sample mapping to a key in a 2A03 instrument.
Use the INST2A03 command to define the instrument before attempting to add a key mapping.
- inst: int[0,63] - index of the instrument
- octave: int[0,7] - octave of key
- note: int[0,11] - scale note of key
- sample: int[0,63] - index of the sample to play
- pitch: int[0,15] - pitch of the sample
- loop: int[0,1] - 0 for no loop, 1 for loop
- loop_point: int[0,255] - loop point of the sample (32 byte increments)
- delta: int[-1,127] - delta counter value, -1 for off
- FDSWAVE [inst] : [data]
Defines a waveform for an FDS instrument.
Use the INSTFDS command to define the instrument before attempting to define its waveform.
- inst: int[0,63] - index of the instrument
- data: int_list[0,63] - contents of the waveform, must be 64 elements long
- FDSMOD [inst] : [data]
Defines a modulator table for an FDS instrument.
Use the INSTFDS command to define the instrument before attempting to define its mod table.
- inst: int[0,63] - index of the instrument
- data: int_list[0,7] - contents of the table, must be 32 elements long
- FDSMACRO [inst] [type] [loop] [release] [setting] : [macro]
Defines a macro sequence for an FDS instrument.
Use the INSTFDS command to define the instrument before attempting to define its macros.
- inst: int[0,63] - index of the instrument
- type: int[0,2] - 0=volume, 1=arpeggio, 2=pitch
- loop: int[-1,253] - loop point, -1 for no loop
- release: int[-1,253] - release point, -1 for no release
- setting: int[0,255] - macro setting (for arpeggio: 0=absolute, 1=fixed, 2=relative)
- macro: int_list[-128,127] - macro sequence
- N163WAVE [inst] [wave] : [data]
Defines a waveform for a Namco 163 instrument.
Use the INSTN163 command to define the instrument before attempting to define its waveforms.
- inst: int[0,63] - index of the instrument
- wave: int[0,15] - index of the wave
- data: int_list[0,15] - contents of the waveform, must be the same length as defined by the INSTN163 instrument
- TRACK [pattern] [speed] [tempo] [name]
Begins a new track.
- pattern: int[0,256] - length of patterns
- speed: int[0,255] - track speed
- tempo: int[0,255] - track tempo
- name: string - name of the track
- COLUMNS : [columns]
Sets the number of effect columns in each channel. This should be specified after a TRACK command, and
before using ROW commands to fill in pattern data. If not specified, each channel will have the default
number of effect columns (1).
- columns: int_list[1,4] - number of effect columns for each channel,
must be the same length as needed for the expansion chip set specified by EXPANSION
- ORDER [frame] : [list]
Sets the patterns to be played in each frame. Applies to current track.
- frame: hex[00,7F] - index of frame
- list: hex_list[00,7F] - pattern to use for each channel,
must be the same length as needed for the expansion chip set specified by EXPANSION
- PATTERN [pattern]
Sets the current pattern to be filled by subsequent ROW commands.
- pattern: hex[00,7F] - index of pattern
- ROW [row] : [c0] : [c1] : [c2] ...
Writes data to one row of the current pattern in the current track.
After the row is specified, there is a colon character (:) before
the row data for each channel in turn.
Visually this should look similar the pattern editor, as if you
were editing a frame where all pattern indices are the same
(e.g. ORDER 00 : 00 00 00 00 00).
The first field represents the note, the first character a letter (C,D,E,F,G,A,B)
then
- row: hex[00,7F] - index of pattern
- c0...: channel data for each channel.
The channel data looks like: nnn ii v eee
- nnn: note, begins with a letter (C,D,E,F,G,A,B), then
a sharp (#,+) natural (-,.) or flat (b,f) character,
then an octave (0,1,2,3,4,5,6,7); an empty note
is ..., a halt is ---, a release is ===;
the notes for the noise channel c3 are special:
they begin with a hex[0,F] to specify noise pitch,
followed by two characters "-#"
- ii: hex[00,3F] - instrument index, .. for none.
- v: hex[0,F] - volume, .. for none.
- eee: effect, begins with a letter or number specifying the effect type,
then the last two characters are hex[00,FF] specifying the parameter value.
There must be as many eee fields as specified by the COLUMNS command.
Data Types
The following data types are used in the format:
- int - decimal integer
- hex - unsigned hexadecimal number
- string - string of characters, if whitespace is required the string may be enclosed in quotes ("");
if a quote (") is required, use a double quote ("") instead;
a string may not contain a newline
- int_list - list of whitespace-separated integers following a colon character, continues to end of line
- hex_list - list of whitespace-separated hexadecimal numbers following a colon character, continues to end of line