pouët.net

nerdtracker ii by Nerds 'R' Us

                        NerdTracker 2 FINAL BETA v2.1
                      official documentation v12.20.2002

                Use MS-DOS edit or a 100% compatible program
               to view this file if you want it to look right

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
                                 
                           Nerdtracker 2 Credits:
     Programming, NES replay code, and .NED file format by Mr. Bananmos
                      ANSI graphic design by Phlum-Dumb

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

                     http://nesdev.parodius.com/nt2/

              NT2 is discontinued.  This is the final version.
                         Better late than never.


Index:
        0.      Introduction
        1.      What's Included
        2.      System Requirements
        3.      Effects
        4.      Keys
          4.a     Pattern Editor
          4.b     Sample Editor
          4.c     Order Editor
        5.      Instrument Settings
        6.      Advice and Suggestions
          6.a     Using the Keyboard for Music
          6.b     Using the DPCM Channel
          6.c     Using the Noise Channel
          6.d     Bugs!
          6.e     Optimizing
          6.f     Tricks
        7.      Replay Program
          7.a     Introduction
          7.b     Usage
        8.      Troubleshooting
        9.      Credits


-==========================================================================-


0.  Introduction:


  Nerdtracker 2 (or NT2 for short) is the brainchild of Michel "Bananmos"
  Iwaniec, designed to create actual Nintendo NES / Famicom music.  NT2 is
  based off a "tracker" layout, where you input your music compositions on
  tracks & patterns -- in the form of hex commands as well as notes.  So if
  you used tracker programs in the past such as Sound/Noise/Protracker,
  Fasttracker, Screamtracker, Impulsetracker, or even MODplug tracker, this
  program's layout will feel quite familiar for you.

  It's technical features are quite vast -- sporting a real-time / decently
  accurate internal playback engine, a healthy tracker command set, low-level
  instrument editing (i.e. duty cycle "timbre" adjustments, volume/pitch
  slides, auto-arpeggios, etc), and even DPCM sampled sound support &
  mapping.  Better yet, with the NT2 sound replay code, you have the ability
  to compile your masterpieces into actual NES 6502 code, expanding cool
  possibilities such as including your music in your own NES game or demo,
  making your own NSF sound file to spread around, of even playing your tune
  in an actual NES system.  =D

  Best of all: it's Giftware!  You're entitled to use NT2 and/or its replay
  code freely for any non-commercial use.  In return, all we ask is to send
  Bananmos something nice to show your appreciation & support.  =)

  Keep in mind, though, that the NT2 program is now DISCONTINUED.  There
  will, unfortunately, be no further official updates to the program.  But
  despite the lack of further official support, NT2 is pretty much already on
  a level where it can stand off on its own, and can prove to be a VERY
  valuable NES music composition tool if you're willing to learn its useful
  features & workaround its beta status.  In little time, you'll be able to
  create your cool little Mario-like jingle to jive with.  And with a little
  patience, you can make some really amazing-sounding NES tunes once its
  power is harnessed.  After all, a few roadblocks didn't stop creative
  musicians from making really nice music off the very first soundtrackers,
  now did it?  =)

  So now it's time for YOU to create a NEW revolution for the NES.

  Happy composing!
        - NT2 support crew, Nov 28, 2002


-==========================================================================-


1.  What's Included in the Archive:


        NT2.EXE         Nerdtracker 2 program.
        NT2.TXT         This document.
        BUBBLE.NED      "Bubble Bobble (In-Game BGM)" example NED, arranged
                        by Memblers.
        BARABANU.NED    "Po-Barabanu (DanceDanceDendy Mix)" example NED,
                        remix by Chibi-Tech.
        DMC-NEW.NED     Example NED for utilizing a full-ranged DPCM melodic
                        instrument, by Memblers.


-==========================================================================-


2.  System Requirements:


        - Soundblaster (or 100% Compatible) Soundcard
        - x86 233 Mhz
        - DOS


-==========================================================================-


3.  Effect:         What it does:

        1xx     Portamento up.  Slides pitch up.
        2xx     Portamento down.  Slides pitch down.
        3xx     Portamento to note.  Slides pitch to note.
        4xy     Vibrato, x = speed, y = depth.  Sine pitch modulation.
        7xy     Tremelo, x = speed, y = depth.  Sine volume modulation.
        8xy     Arpeggio.  Alternates note between specified half-note values.
        Axy     Volume slide, value is the speed.  x = up, y = down
        Cxx     Set volume, maximum is $3F.  (the NES only has 16 volume
                                              levels, though)
        Dxx     Pattern break, value is starting row of next pattern in hex.
        Fxx     Set tempo.  Default is 6.  Lower values are faster.  BPM = 125
        xxx     Theoretically, you could modify the replay program and create
                your own effect, though it would do nothing inside the tracker
                itself.


-==========================================================================-


4.  Keys:
  
  (written with american keyboard in mind, may be different on other systems)


  4.a  Pattern Editor:

        Music keys      See section 6a.
        Space           Inserts a note-off at cursor location.
                         (bug: it works in the PCM channel on the NES replay
                          code, but not in NT2's sound emulation)

        Left Ctrl+L     Load .ned (Type in full filename)
        Left Ctrl+S     Save .ned (Don't press backspace while typing the
                                   filename, or it won't be saved!)
        Right Shift     Starts/Stops playing the song.
        ' and \ or      Select current instrument.
        F9 and F10
        
        F1 through F8   Set octave. (use F8 for the lowest, but the pulse &
                                     triangle channels can't go lower than
                                     A-0 !)
        Numeric * or ~  Switch between pattern, instrument, and order editors.
        Left Shift+F3   Go to sample editor.
                        (or Left Shift+* which works in DOS)

        Cursor keys     Moves cursor. (hmm..)
        Insert          Inserts blank line at cursor location.  Moves all
                        notes below cursor down.
        Backspace       Delete note above cursor, moves position and
                        everything below it up.
        Delete          Delete note or effect at cursor position.
        Page Up/Down    Moves cursor up/down by 16 steps.
        Home/End        Moves cursor to the top/bottom of the pattern.
        Enter           Creates DAT and IHD files for use with NES replay code.
        Escape          Escape!  Exits the program.


  4.b  Sample Editor:

        L       load sample (Format is 1bit Delta-PCM.  An 8to1bit converter
                is available at http://nesdev.parodius.com/)
        Numeric *  switch between sample editor, notetable, and instruments.

  
  4.c  Order Editor:

        left/right cursor  Select track.
        up/down cursor  Select order position
        + and -         Set pattern in selected position.
        space           Set current position as loop-back point.
        insert          Insert new pattern in selected position.
        delete          Delete pattern in selected position.
                         (bugs: change track patterns to 0 before deleting,
                          also be sure your last order position doesn't use
                          all pattern 0's, or that entry is removed upon
                          save/load)


-==========================================================================-


5.  Instrument Settings:


        Duty cycle      Shape of squarewave, 4 possible settings
        Hold note       Hold note.  Required, unless Timelength is set
        Envelope fix    Set to ON if you want volume control (you should)
        Inst. Volume    Default volume of instrument
      / Frequency Var.  \
     |  Freq. ChngSpeed  | These settings are no longer supported, so don't
     |  Hi to Lo         | mess with them.
      \ Freq. Range     /  
        Timelength      Use this if 'hold note' is turned off
      / Arpeggio X      \
     |  Arpeggio Y       | Auto-arpeggio settings
      \ Arpeggio Z      /
        Vibrato Speed   Auto-vibrato speed
        Vibrato Depth   Auto-vibrato depth
        Tremelo Speed   Auto-tremelo speed
        Tremelo Depth   Auto-tremelo depth
        Volume fade     Auto-volume fade
        Volume fade=UP  Volume will fade up
        Looped noise    Use to make metallic sounds with noise channel
        Auto portamento Automatically slides frequency down
        Portamento=UP   Auto-portamento will go up
        Unlabeled 1     Reverse arpeggio (lower instead of higher)
        Unlabeled 2     Non-looped auto-arpeggio


-==========================================================================-


6.  Advice and Suggestions:
    
  
  6.a  Using the Keyboard for Music:

        Are you not familiar with other tracking programs?  Then, it really
        helps to know what keys correspond to notes on a musical keyboard.
        "Q" is C, "2" is C#, "W" is D, "3" is D#, "E" is - guess what - E.
        The same pattern repeats until the "P" key, which is high E.
        There's a bottom row too, starting at "Z" (being C) and going until
        "M" (being B).  If you know that that there is no E# or B# (as you
        should anyway), the pattern is really easy to follow.  I highlighted
        the sharp keys with a green magic marker on my keyboard, for visual
        reference.  (Note: If you do this, don't put ink on the top of the
        keys unless you like your fingers changing colors!  Heheh.)

  
  6.b  Using the DPCM Channel:

        NT2 uses instruments, similar to .XI instruments in how several
        samples can be loaded into one instrument.  You'll need to have 5
        samples (with each one 1 half-tone higher than the one before it) 
        of the same sound if you want to have a usable frequency range
        from one sample.

        There is no instrument file saving, so the best way to save your
        instruments is to save them in a blank .NED.

        The NES's frequency control is only *4* bits (yeesh).  If sample #1
        is a C note, then you should set sample #1's frequency value for C-2 
        (or any other octave) to $C in the sample editor.  Now things 
        start to get weird.  Set E-2 to $D, G-2 to $E, and C-3 to $F (all
        of them using sample #1).  This is where the half-tone higher samples
        come in, and if you understood what I was just talking about then
        you can probably see the pattern that you'll need to follow.  This
        technique should work fine, as long as sample #1 plays a C note when
        the frequency value is $C.  It's not known if Nintendo designed
        certain values to be notes, or if it's just blind luck that they are.

        Here are some diagrams to explain NT2's PCM instrument interface.
        

  
  PCM Instrument Editor:
                                  ÚSample Number
                                  ³
                                  ³    ÚSample Filenames 
                                  ³    ³ (this is where you hit 'L' to
                 ÚÄÄÚÄÄÄÄÄÄÄÄÄÄÄijÚÄÄijÄÄÄÄÄÄÄÄÄÄ·     load a sample)
                 ³ßßßßßßßßßßßßßßß³³ßßßß³ßßßßßßßßßß³º
                 ³  ³ Inst Name  ³0³sample1.dmc   ³º
Instrument #ÄÄÄÄÄÄ01³            ³1³sample2.dmc   ³º
(each one can    ³02³            ³2³drum.dmc      ³º
 contain 8       ³03³            ³3³blahblah.dmc  ³º
 samples)        ³04³            ³4³              ³º
                 ³05³            ³5³              ³º
                 ³06³            ³6³              ³º
                 ³07³            ³7³              ³º
                 ³  ³            ³ ³              ³º
                 ³ÜÜÜÜÜÜÜÜÜÜÜÜÜÜܳÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜܳº
                 ÀÄÄÀÄÄÄÄÄÄÄÄÄÄÄÄÀÄÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÀ½

             
  
  PCM Note-table Editor:             

             OctaveÄÄÄÄÄÄÄÄÄÄÄÄ¿
                              00 01 02 03
                             ÚÄÄÂÄÄÂÄÄÂÄÄ¿
             NoteÄÄÄÄÄÄÄÄÄÄC ³00³00³00³00³
                           C#³00³00³00³00³
                           D ³00³00³00³00³
                           D#³00³00³00³00³
                           E ³00³00³00³00³
                           F ³00³00³00³00³
                           F#³00³00³00³00³
                           G ³00³00³00³00³
                           G#³00³00³00³00³
                           A ³00³00³00³00³
                           A#³00³00³00³00³
                           B ³00³00³00³00³
                             À³³ÁÄÄÁÄÄÁÄÄÙ
                              ³³
             Sample NumberÄÄÄÄÙ³
          Sample Playback SpeedÙ



  Sample Playback Speeds:

                0       C-8
                1       D-8
                2       E-8
                3       F-8
                4       G-8
                5       A-8
                6       B-8
                7       C-9
                8       D-9
                9       F-9
                A       G-9
                B       A-9
                C       C-10
                D       E-10
                E       G-10
                F       C-11

        
        Remember that any instrument settings you set for normal instruments
        will have no effect on the PCM channel.  Effects such as volume and
        pitch slides, etc. can't be done with the NES's DMA method of using
        samples.  They are stored in ROM, and are played as-is.  The
        maximum amount of sample data you can use without bankswitching is
        16378 bytes.  It wouldn't be too hard to write the code to do
        bankswitching to get more, but would depend on how the samples were
        arranged.  Contact me if you're wanting to try something like this.

        Also, due to the filtering on the NES's sound the PCM channel is
        significantly quieter and cleaner sounding than most emulators to
        date.  On a real NES, if the pulse channels are too loud, they can
        easily drown out the PCM samples.  Personally, when I use samples I
        keep my pulse channel volumes below 8 because of this.


  6.c  Using the Noise Channel:

        The noise channel has a 4bit frequency range, and that means it can
        produce only 16 unique tones.  The tracker interface doesn't have
        an obvious way of letting you know what notes are what, but if
        you keep the following points in mind, you shouldn't have very much
        trouble using the noise channel.  First, remember that the lowest
        noise frequency is the note C-0, and the highest frequency is D#1.
        Secondly, the tracker will play some noise when you put a note in;
        that sound is not the actual pitch.  This problem is only on the
        noise channel.  Play the song to hear how it actually should sound.

        Noise emulation isn't very accurate in emulation.  Especially the
        'looped' (metallic) noise.  At this time, the emulator that seems
        closest in that aspect is the Festalon plugin for Winamp v2.xx.


  6.d  Bugs!:

        The NES's hardware has a bug, or a design feature, or whatever you
        would call it involving writing the high-byte of the frequency.  What
        happens, is that if a vibrato or a portamento affects the highest 3
        bits of the frequency, the channel's phase counter will reset itself,
        therefore the sound will snap, crackle, and pop.  So basically what
        you do to work around this is not use vibratos on some notes, and
        remember that it will kinda pop if you do portamentos on some notes.
        One game where this is noticeable is Crash 'n the Boys by Technos.
        If you have the cartridge, listen to the .NSF first, then play the
        game on NES and hear the difference.  Also, the title screen music of
        Demon Sword uses this feature to a rather nice effect!

        Damian Yerrick looked into the matter, and sent me this:
        
         A-3 A-2 A-1 F-1 D-1 B-0 <-- Those are approximately the
         notes where the NES switches the high byte.

        Chibi-Tech pointed out the following bugs and SNAFUs:

         Changing the duty cycle of instrument $0E will cause a crash when
         you play the song.  Leave it at $00, or save your song often.     

         Setting the xx value of "Set speed" command (Fxx) to $00 will put
         the NT2 playback in a permanent lock.  It's a legitimate value for
         the NT2 replay code, indeed (as its main use is to set the frame
         countdown to infinity -- in other words, halting further playback),
         and is often used to end a song without looping.  But unfortunately
         in the program, there's no way to set playback to a normal speed
         again after it's set to $00.  If you accidentally set off command
         F00 & halt playback (especially prone to this mistake if you're
         trying to input speed-swings while composing your track), the best
         bet is to just correct/omit the command, save your work, quit &
         restart NT2 (to reset the speed tick counter back to default $06),
         load up the track again, and resume work as usual.

         Inputting ANY command in the DPCM track will do nothing, in both the
         tracker & the replay code.  Sorry, even global variable commands
         such as commands Dxx or Fxx in the DPCM track will be ignored, too.
         (Note: An exception is the note-off command.  It works in the replay
          code but not in the tracker.)

        
  6.e  Optimizing:
               
        NT2's file format works in a very optimization-friendly way.
        Say you want to repeat the same note several times.  E.g.:
        
        E-2 1 A02
              A00       ; volume slide will keep going down at speed 2
        E-2 1 A00
              A00

        You could instead, do this:

        E-2 1 A02
              A00
            1 A00
              A00

        It would sound the same (*), and make the file smaller.  You can
        also change the instrument number to do things like change the
        duty-cycle of a squarewave without affecting the frequency, which
        is great for being able to do duty-cycle or other instrument changes
        during note-slides and such.

        (*): Resetting the instrument in that way will not re-trigger a
             non-looped arpeggio.  It also will not work if you have the
             Hold-Note setting disabled.

        You can also save some space by removing the instrument numbers from
        the pattern in the triangle channel.  Just make sure the first note
        in the pattern has an instrument set.  Since that will not reset the 
        volume, it won't work on the noise or square channels if you are
        using volume effects.


  6.f  Tricks:

        There are lots of different ways people have gone about trying to
        get the most out of chip music, and a good way to learn is to 
        download some NSF and/or SID files, and listen to each channel 
        separately.  For instance, you'll notice in some NES music, the 
        triangle and noise channels work together seamlessly to provide 
        the music with a good drumbeat and bassline.  For example, you could
        make a triangle channel instrument that uses the auto-portamento
        effect at a high-rate, put a note in and give it a space or 2
        depending on the tempo then put a note off or your bassline in the
        triangle channel.
        
        Using the non-looped arpeggio effect, with the first arpeggio value 
        at $C will provide a short percussive sound at the beginning of a
        note.

        Using the noise channel along with drum samples will greatly alter
        the sound of the drum, with a snare sample for example you could
        give it a longer decay and/or a brighter quality.  Try using
        arpeggios (looped and non-looped) on the noise channel.

        Most importantly, try to develop your own style and techniques.
        That is what makes music worth listening to.  But that will happen
        without you really noticing it, anyway.  :)


-==========================================================================-


7.  Replay Program:


  7.a  Introduction:

        This is what makes Nerdtracker 2 really great; it gives one the
        capability to hear your music on a real NES system.  If you want
        to make an NES game or demo, this is a good way to get music in
        your program quickly if you're not planning on writing your own
        music program.  The only downside is the lack of simultaneous
        music and sound effect playback, though that could be possible
        with some kind of code modifications.

        The playback code, like NT2 itself, was designed and written by
        Bananmos.

  7.b  Usage:

        The source code compiles with the x816 assembler by minus.  The
        .NED files are not used directly by the replay program.  Instead,
        NT2 creates these 2 files when you press enter while your song is
        loaded:

        temp.dat        -       pattern, order, and instrument data
        temp.ihd        -       DPCM samples and DPCM note-table

        You'll then run the temp.ihd file through the makedtt.exe program.
        For example:

        makedtt temp.ihd temp.dtt temp.dmc 0

        Would take the temp.ihd file and create temp.dtt (DPCM note-table),
        temp.dmc (DPCM sample data) and set up the sample location to start
        at ROM address $C000. The NES normally can only play samples located
        higher than $C000.  (But it actually wraps-around to $8000.  See
        Brad Taylor's delta moldulation doc for a complete description of
        it's various features and functions.)

        The latest version of the replay code includes a convenient built-in
        NSF header so you can throw it directly into your favorite NES sound
        emulator.

        If you want to play more than one song with the program, you probably
        have the songs.asm file that I created for Solar Wars' soundtrack.
        Simply edit the .incbin commands to include your own .DAT files.  If
        they use samples, they must all have the PCM instruments and note-
        tables set up in the same way in each song, because they will all
        be using the same note-table.

        If you're putting it into a ROM, put it in at the NSF's load address
        if it's without the header, or (load address-$80) if the NSF header
        is present.  Then to initialize a song, load the accumulator with
        the song number to play, and the X register with 0 if you want NTSC
        speed or 1 if you want PAL speed, then do a JSR to the init address
        in the NSF header.  Then you JSR to the play address every frame
        (60hz NTSC or 50hz PAL) to play the music.  If you want to stop the
        music with silence, stop running the play code and clear the sound
        registers (you could probably get away with only clearing $4015).


-==========================================================================-


8.  Troubleshooting:


        Q: I'm getting an error that says "BLASTER environment not found,
           what the?!...".

        A: NT2 requires your soundcard to have DOS drivers.  You can usually
           find out if you have DOS drivers by typing "set" at the command
           prompt.  There should be a line that says "BLASTER=(your config)".
           Your soundcard maker should have DOS drivers on their website.

        A: NT2 might not work on an operating system that doesn't allow a
           program to communicate directly with the hardware.  Full DOS
	   compatibility is required.


        Q: NT2 is running, but I'm not hearing any sound.

        A: Did you give your instrument a volume level, and enable
           'hold note' or 'note length'?

        A: Many DOS programs run into trouble when the soundcard's IRQ is set
           to a high number.  Try the Soundblaster 'default' settings of
           Address=220 IRQ=5 DMA=1, or IRQ=7.  If your soundcard is a
           "Plug-n-Pray", you can change these settings fairly easily in
           windows system properties, but beware of conflicts.


        Q: I still can't get it to work!

        A: Post your problem/question on the NES Music messageboard at
           http://nesdev.parodius.com/



-==========================================================================-


9.  Credits:


      Bananmos        bananmos_uv@nonspam.at.hotmail.dot.com.kthx

        creator of NT2, show your appreciation of his work by sending him
        your NEDs!  But remember that NT2 is discontinued.


      Memblers        memblers@nonspam.at.parodius.dot.com.kthx

        wrote most of this document.  If you want your NES music published
        on the web, send it to me in either NED or NSF format.  Don't forget
        to include the song info! (Title, Author, year/copyright)


      Chibi-Tech      chibitek@nonspam.at.gp.dot.isao.dot.net.kthx

        designed the NT2 website, and helped with this document.


      Damian Yerrick, skankpit, and others (I forget!)

        helped with this document, and misc. stuff.

        

       Nerdtracker 2 is giftware!  If you get good use out of it, please
       send something to Bananmos to show your appreciation.  =)
                  
                

       Visit http://nesdev.parodius.com/ for more NESdev stuff.
       Post your questions and comments on the 'NES Music' messageboard on
       the website above.

       Thanks to everyone who made writing this document worthwhile.
                                       - Memblers

-==========================================================================-
 
                                  -=EOF=-