FamiStudio Documentation

Localization data is stored in a single file per language within the localization folder. The format is an INI file using UTF-8 encoding.

Structure

• Sections: Defined by brackets (e.g., [PianoRoll]), these map directly to C# classes in the source code.
• Keys and Values: Strings are stored as Key=Value.
  • CRITICAL: You are only allowed to change the values. Do not touch, rename, or reorder the keys.
• Comments: Use # or ; to add comments. Anything to the right of these characters is ignored.
• Fallbacks: If a string is missing or commented out in a specific language file, FamiStudio will default to the English version.
• Parameters: Some strings contain placeholders like {0}, {1}, etc., which are inserted at runtime. When translating, ensure these parameters are placed in a position that is grammatically correct for the target language.

[ConfigDialog]

# Title
Title=FamiStudio Configuration
Verb=Apply

# Sections
ConfigSectionNames_0=General
ConfigSectionNames_1=Interface

# Example with parameters
EditEnvelopeTooltip=Edit {0} envelope

The FamiStudio engine includes many features that can be toggled on or off to save CPU and RAM.

Warning: If you disable a feature, you must ensure your songs do not use it. Using a disabled feature may cause crashes (BRK) or undefined behavior.

Always Available (Basic Set)

• Support for the first four 2A03 channels (2 squares, triangle, and noise).
• Full 96 notes (C0 to B7).
• Instruments with duty cycle, volume, pitch, and arpeggio envelopes (including absolute/relative pitch and looping).
• Ability to change speed (FamiTracker tempo mode).
• Song looping.
• Up to 64 instruments per export.

Toggleable Features

You can enable/disable the following to optimize your project:

• Audio Expansions: VRC6/Rainbow Mapper, VRC7, FDS, S5B, MMC5, EPSM, or N163 (Note: at most one can be enabled).
• DPCM: Sample support, bankswitching, and extended range.
• Instruments: Extended range (up to 256 instruments).
• SFX: Sound effect support with configurable stream counts.
• Playback/Effects: PAL/NTSC playback, Blaarg Smooth Vibrato, FamiTracker/FamiStudio tempo mode, Volume tracks/slides, Fine pitch tracks, Slide notes (including noise), Vibrato effect, Arpeggios, Duty cycle effect tracks, Delayed notes/cuts, Delta counter effect tracks, Phase reset support, and FDS auto-modulation.

RAM/Code Considerations

• Zero Page: The engine uses 7 bytes of Zero Page. These are used as temporary variables inside famistudio_xxx subroutines and can be aliased with your own ZP variables.
• Resource Scaling: Enabling more features increases both code size and RAM usage.

FamiStudio handles the conversion between NTSC (60 FPS) and PAL (50 FPS) systems by automatically computing a tempo envelope. This envelope ensures that songs maintain their intended playback speed when played on a non-native platform (e.g., playing an NTSC song on a PAL system).

To maintain speed, FamiStudio uses two primary techniques:

• NTSC to PAL: Runs double frames (2 NTSC frames in a single PAL frame) to keep up with the faster NTSC timing.
• PAL to NTSC: Inserts idle frames to slow down playback to match the slower PAL timing.

The tempo envelope is optimized to distribute these double or idle frames as evenly as possible while following these constraints:

1. Deterministic positions: Frames are placed within notes in a predictable way.
2. Avoid Note Starts: It avoids placing a double/idle frame on the first frame of a note to preserve the attack.
3. Avoid Note Ends: It avoids placing a double/idle frame on the last frame of a note to prevent issues with silent notes.

The FamiStudio text format is a textual representation of the binary .FMS format designed for interoperability with other tools and sound engines.

Key Constraints:

• Compatibility: It is not forward or backward compatible. FamiStudio can only read text files generated with the same major and minor version (e.g., 3.0.x).
• Lossy Elements: While mostly lossless, the following are not preserved:
  • Custom colors assigned to songs, instruments, patterns, arpeggios, and DPCM samples (these will be randomized upon re-import).
  • DPCM sample source data and processing parameters (only the final processed data is exported).
• Availability: Only the desktop version of FamiStudio supports exporting to this format.

Format Structure: The format uses a nested object structure where each line describes an object followed by attributes in double-quotes. Indentation is cosmetic. Double quotes within values are escaped by doubling them (e.g., "").

Project Version="2.0.0" Name="FamiStudio Tutorial"
    Instrument Name="Lead"
        Envelope Type="Volume" Length="1" Values="12"
    Song Name="Tutorial Song"
        Channel Type="Square1"
            Pattern Name="Intro1"
                Note Time="0" Value="G3" Instrument="Lead"