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