old_readme.txt

FamiTone2 audio library v1.15 by Shiru 04'17

(original readme, does not reflect changes)



About

FamiTone2 is an audio library for NES/Famicom. It is designed to provide 
easy way of adding music and sound effects into homebrew games and 
demos. 

Tool set supplied along with the library allows to create both music and 
sound effects using FamiTracker, a popular tracker, and export them into 
the library's internal formats. It supports all standard channels of 
2A03: two pulse, triangle, noise, and DPCM. Expansion sound chips are 
not supported. 

The main concept of the library is to have very minimalistic set of 
features that is sufficient to create music and sound effects with the 
level of quality comparable with that of the most old commercial NES 
games. It is in no way a direct replacement of FamiTracker player, it 
only supports a very limited subset of its features in order to reduce 
CPU load and memory use. That's the whole point of having a separate
library, so if you need more features, you should stick to the native
FamiTracker's driver instead.

The library is open source and released into the Public Domain. You can 
use it for any purpose without restrictions: redistribute, modify, use 
for commercial and non-commercial projects. You may credit the author, 
inform the author about your project, donate, etc, but nothing is 
obligatory, you could do it at free will. Obviously, the library 
provided AS IS without warranties of any kind, the author is not 
responsible for anything. 




How to create music

You can create music in FamiTracker version 0.3.6 or above, or with 
Musetracker. The music should met these requirements: 

- Allowed notes are C-1..D-6, Note Cut (rest note)
- Only Volume, Arpeggio, and Pitch sequences (no Pitch for noise
  channel) supported
- All instruments should have a volume envelope assigned
- Only the loop part of sequence is supported, release part is not supported
- Pitch envelope accumulate the offset at conversion time only, thus
  it can't go further -64..63, and can't accumulate the offset with loop
- Only first step of Duty envelope for pulse and noise channels is used,
  there is no Duty sequence
- 64 instruments max
- No volume column support
- Tempo is set with the global setting, speed can be changed with effect
  Fxx (1..21)
- Bxx effect for looping without an intro, does not support forward
  references
- D00 effect to cut patterns early
- No effects other than listed above are supported
- Up to 17 sub songs in a file, they will share instruments and pattern
  data

You can use DPCM samples, there are limitations too:

- Up to 63 samples with total size of ~16K
- Only samples assigned to the instrument 0 are supported,
- Note range the same as for normal instruments, C-1..D-6, instrument
  number is ignored
- You can add samples that aren't used in the music to use them as sound
  effects


You can create all music for your game in a single FTM file using the 
multi song feature, this will save memory. If allowed number of 
instruments or sub songs is not enough, you can split the music into few 
files. The library allows to change music data sets at runtime. 

After you have made the music, you need to export it in a text format 
supported by the FamiTone2 converter, text2data. 

In FamiTracker 0.4.2 or above you can use built-in text exporter, it is 
located in File\Export text. This export option is also available from 
the command line (FamiTracker music.ftm -export music.txt). This allows 
seamless integration of music conversion into your build process. The 
old text format exported with TextExporter.dll plug-in is also 
supported, but not recommended to use. 

In Musetracker you can just save it in needed format with LCtrl+LShift+S 
(by default). 

Now you can use text2data tool (text2data music.txt) to convert the 
exported text into assembly file with music data. If you don't use DPCM, 
you'll get one *.asm file as the result. If you use DPCM, there will be 
an extra *.dmc file with sample data. 

text2data outputs data in NESASM format by default, you can use -ca65 or 
-asm6 switches to get output for these assemblers. 



How to create sound effects

Sound effects could be created in FamiTracker or Musetracker as well. 
Effects can use all sound channels except DPCM, so the effects are multi 
channel. Put every effect into a separate sub song using the multi song 
feature. Unlike music, you can use most of the FamiTracker features for 
effects, except the sweep. Every effect should be finished with silence, 
and C00 command put to the last row of the effect.

Once all effects done, export them as a NSF file and use the nsf2data
converter (nsf2data sounds.nsf). You'll get *.asm file with the effects
data. 

There is a major limitation: one effect can't be larger than 255 bytes 
after conversion. FamiTracker effects like slides could increase the 
size greatly, so use them carefully. The converter will report size of 
each effect, and warn you if an effect is too large. 

In addition to these sound effects, you can play any sample,meither used 
or not used in the music, from the current DPCM bank. It will have 
priority over samples in the music, overriding them. 




How to use the library

The main version of the FamiTone2 is written in NESASM. There are 
versions for CA65 and ASM6 assemblers included into the package as well, 
they are automatically converted from the main version using a custom 
tool, nesasmc, also included into the archive. 

Include famitone.asm (famitone.s for CA65, famitone_asm6.asm for ASM6) 
into your project. Include *.asm files of your music and sounds. You can 
place music and sound effects data anywhere, including bankswitched 
memory, they only needed to be switched into the CPU address space 
before FamiTone2 calls. DPCM samples (*.bin file) are a special case. 
They should be placed at $c000 or above, with steps of 64 bytes, and 
they always should be in CPU address space to be accessible by the DPCM 
hardware. 

Next step is to setup the FamiTone. Open famitone.asm, there are few 
defines commented out in the beginning of the file. Copy them into your
code and uncomment. Now you use them to set up RAM and zero page 
locations, DPCM location, number of sound effects played at once, 
PAL/NTSC support. The latter has three options: both NTSC and PAL, NTSC 
only, or PAL only. The first case enables automatic pitch and correction 
to make the music and sound effects play the same. This is a little bit 
slower and uses a bit more ROM. Sound effects data is stored in two 
versions, for NTSC and PAL, there is a switch to use only one system to 
reduce ROM usage. 


User calls of the library:

 FamiToneInit
  A is 0 for PAL, not 0 for NTSC. X,Y are pointer to music data. The music
  data includes instruments, envelopes, sample list, and a number of sub
  songs. Call this routine once before all other calls, and every time you
  need to change music data set.

 FamiToneSfxInit
  X,Y are 16-bit address of sound effects data, one that is generated by
  the nsf2data. Call it after FamiToneInit every time you need to change
  sound effects set.

 FamiToneUpdate
  No parameters. Updates everything and writes to APU registers. Call it
  every TV frame. Usually this done in the end of the NMI handler.

 FamiToneMusicPlay
  Play music. A is number of a sub song.

 FamiToneMusicStop
  No parameters, stops any music

 FamiToneMusicPause
  A is 0 or not 0, to play or pause music that is playing currently

 FamiToneSfxPlay
  A is sound effect number 0..63, X is 0,15,30, or 45 (no other
  values are allowed!). The number in X is sound effect stream. It also
  works like priority. If you start a sound effect, it will stop any
  previous effect with the same priority. There is no automatic priority
  system in FamiTone2, as it would be slow.

 FamiToneSamplePlay
  A is sample number 1..12 (i.e. note C..B with assigned sample). Play
  a sample from active DPCM bank, interrupting any other sample.


Warning: don't forget that active DPCM sound conflicts with $2002 and 
controllers polling. You should poll controllers three times in a row, 
then use matching result. 

With music and few sound effects playing at once you can expect CPU load 
about 11%. It could be reduced by disabling some of sound effect 
channels with the FT_SFX_STREAMS define. 

You can exclude sound effects and DPCM support from code through defines 
FT_SFX_ENABLE and FT_DPCM_ENABLE (not define them to disable the 
functionality). Be aware that speed change commands often placed into 
the DPCM channel by the text2data tool, they'll be missed by player if 
you disable DPCM support. To avoid this situation use text2data with 
-ch4 switch. 

If you are going to put sound update into an interrupt (NMI or other) 
and call sound effects from the main code, make sure that FT_THREAD is 
defined. 




Comparisons

The numbers below could give you idea what to expect in terms of 
resources use, and what could suit better for certain application. 

FamiTracker 0.3.7 and 0.4.2 are listed here because these were actual 
versions when the original FamiTone and FamiTone2 has been released. 
FamiTone has all options enabled, including four sound effect channels. 
FamiTracker player compiled without banking and/or sound expansion 
chips, the size is provided by the NSF exporter for tracks. 

CPU load is measured for peak time. Average time is usually about 2-3 
times less, but the load peaks occurs at various points during play 
rather than on initializing, this could introduce random lag frames in a 
game that tops CPU frame time. Thus peak load considered more important 
than average load. 

The measurements below were done with FamiTone2 v1.0, the numbers may
be slightly different for newer versions.


Music data sizes (not including DPCM), bytes:

                            FT 0.3.7  FT 0.4.6  FamiTone  FamiTone2
							
After The Rain                7847      6059      6315      4676
Danger Streets                4825      4840      5522      4354
Lan Master (4 sub songs)     12373     10062     12072      7753
Lawn Mower (5 sub songs)      9248      6281      8594      4514

Memory usage by player, bytes:

               RAM     ZP     ROM
FT 0.3.7:      241     21    5128
FT 0.4.2:      245     20    5547
FamiTone:      183      7    1493
FamiTone2:     186      3    1636

CPU time peak usage by player, cycles:

                            FT 0.3.7  FT 0.4.2  FamiTone  FamiTone2
							
After The Rain                6946      7439      3673      3103
Danger Streets                5678      6020      3439      2827



Data formats

Music channel streams:

%0nnnnnn0 is a note (0 rest note, 1..60 are C-1..D-6)
%0nnnnnn1 is a note followed by a single empty row
%1iiiiii0 is an instrument number 0..63 (actual number minus one,
          default is 1)
%1rrrrrr1 is a number of empty rows-1 (0..60), or a special tag

%11111011 is speed, next byte is speed
%11111101 is end of the stream, two next bytes are loop pointer
%11111111 is a reference, three next bytes are number of rows (excluding
          empty ones) and pointer

There are no octaves in the Noise channel, notes codes are always in 
1..16 range. There is no instrument numbers in the DPCM channel.



Envelopes:

%00000000 is end of the envelope, next byte is loop offset
%0rrrrrrr is a number of repeats of previous output value
%1nnnnnnn is output value + 192 (it is in -64..63 range)

Envelope data can't be longer than 255 bytes.



Sound effects:

In a sound effect bank first there is two pointers to list of the effect
pointers, one for NTSC and another for PAL. Then there are lists of
pointers to effects itself.

$00      is end of the effect
$01..$7f is a number of frames to skip before reading next block of data
$80..$8a is a remapped register number followed by a byte of data

Sound effect data can't be longer than 255 bytes. Registers are remapped:

$4000 $80
$4002 $81
$4003 $82
$4004 $83
$4006 $84
$4007 $85
$4008 $86
$400a $87
$400b $88
$400c $89
$400e $8a



Thanks to

jsr (FamiTracker)
Gradualore (plug-in system for FamiTracker)
rainwarrior (bug reports, built-in text export in FamiTracker)
Memblers (library's name)
kevtris
Gil
B00daW
ManicGenius
thefox
UncleSporky
kulor
MovieMovies1
Erik Gough
Lauri Kasanen
Denny R. Walter
NesDev community



List of products using FamiTone

Is the library actually any good? You can find out the answer by
hearing it in the action in these homebrew games:

2048 (by tsone)
Alter Ego
BASIC Championship Wrestling
Beerslinger
Blow 'em Out
Chase
Cheril the Goddess
Crypto
Filthy Kitchen
Flappy Bird (by Nioreh)
Flappy Jack (modified FamiTone2)
Function
Germ Squashers
Gorodki
Jet Paco
Karate Kick
Lan Master
Lawn Mower
Melanchony Of Existance: Chapter 0
Milionesy
MineShaft
Mini Brix Battle
MultiDude
Nebs 'n Debs
Perfect Pair
Rock Paper Scissors Lizard Sbock
Russian Roulette
Quest Forge: By Order of Kings
Ralph 4
Sgt. Helmet - Training Day
Sinking Feeling
Sir Ababol
Snakky
Spacey McRacey
SplatooD
Star Versus
Super Painter
Super Uwol!
Tailgate Party
Waddles The Duck
Wǒ Xiang Niào Niào
Yun
Zombiejack
Zooming Secretary




Contacts

mailto:shiru@mail.ru
http://shiru.untergrund.net/
http://justgiving.com/Shiru