Skip to content
EZNSF is a tool for transforming NSF music files into NES ROMs
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
brahms.nsf EZNSF version 1.0 Aug 11, 2018
eznsf_header.cfg EZNSF version 1.0 Aug 11, 2018
eznsf_nrom.cfg EZNSF version 1.0 Aug 11, 2018
info.nam EZNSF version 1.0 Aug 11, 2018
play.nam EZNSF version 1.0 Aug 11, 2018
readme.txt EZNSF version 1.0 Aug 11, 2018
title.nam EZNSF version 1.0 Aug 11, 2018


     /   EEEEE   ZZZZZ   N   N    SSSS   FFFFF   /
    /   E          Z    NN  N   S       F       /
   /   EEE       Z     N N N    SSS    FFF     /
  /   E        Z      N  NN       S   F       /
 /   EEEEE   ZZZZZ   N   N   SSSS    F       /

 EZNSF is a tool for transforming NSF music files into NES ROMs
 Version 1.0
 Written by Brad Smith, 2016-12-05


 1. Python 3
      Available here:
 2. CC65 assembler and linker
      Available here:
      A windows version of CC65's assembler and linker are included in the tools folder.
      Users with other platforms can adapt the python script to use another version of CC65.
 3. NES Screen Tool
      Available here:
      The screen tool is helpful if you wish to modify the graphics produced by the ROM,
      but it is not needed for simply building ROMs.


 1. Create a suitable NSF (see below for requirements).
 2. Edit album.txt with track times and names and other info.
 3. Run to build a ROM as "temp/output.nes".
    If there are any errors, look at the output from and try to fix them.
    Make sure to run from a command line or shell where you can read its result.
    (The included "eznsf.bat" will open a command window and pause to show the output.)

NSF Requirements:

 * No expansion sound.
 * Standard engine rate only (60/50 Hz)
 * NSF may not bankswitch F000
 * NSF may not use RAM (or clear it during init) in the range $600-7FF
 * NSF may not use zero page (or clear it) in the range $FC-FF
 * NSF may not depend on WRAM present at $6000-7FFF

 This program was primarily intended for use with Famitracker, which
 should normally obey all of these requirements since at least 0.4.5 if not earlier.
 It can potentially work with many other NSFs.


 The produced ROM will use mapper 31 by default, which is a relatively new creation.
 Many old emulators will not support this. Recent versions of the following will:
   * FCEUX:
   * MESS:
   * BizHawk:
   * Nintendulator:
   * puNES:
   * Everdrive N8:

 If the NSF does not require bankswitching (many NSFs under 32k), it may be possible to
 build as the simple NROM mapper 0, which is supported by all emulators.
 Simply create a line that says "NROM = 1" in your album.txt file.
 The NROM version will require about 3kb of empty space, so the build may fail if not
 enough room can be found. An example is included as "album_nrom.txt".

 This tool also uses the track times and names to produce an NSFe file in the output
 directory. An NSFe is like an NSF but with playlist features like individual track
 names and times. If undesired you can turn this extra step off in by
 setting "output_nsfe = False" near the top of the file.

 NSFs with the "dual region" bit set will attempt to auto-detect the system region on
 startup, and will pass the appropriate value to the NSF INIT function when tracks are played.
 Otherwise, the detection will be omitted and the region speciied in the NSF header will be used.

 This program is open source, and I give permission to modify and reuse it in any way you like.
 I encourage experimentation. This is hopefully intended as a learning example, and not just as
 a tool.

 The script can be run with two command line arguments. The first argument is the name
 of the album.txt file (if omitted it will use "album.txt"). The second argument is the output
 folder (if omitted it will use "temp").

 The sample music is from the Classic Chips album of classical music arranged for NES:

 The graphics in this are configurable with album.txt, and by editing their definitions in that file.
 Take a look at the comments and experiment to see what they do. Use the NES Screen Tool
 to modify the example CHR/NAM/PAL files.

 Contact me if you have questions or comments.

--- end of file ---
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.