
                         -------------
                          Musetracker
                         -------------

                              v15

                       by thefox//aspekt
                        thefox@aspekt.fi
                     http://kkfos.aspekt.fi

             Uses Nes_Snd_Emu APU library by blargg.


General
-------

Musetracker is a NES music tracker. Also provided in the package is a
6502 playback library called MUSE, which can be used in games and demos,
and for which Musetracker can export sound data.

NOTE: Version 1.4 brings some changes which change the way note slides,
vibrato and volume slide effects work. Old songs have to be manually
fixed. Here's a breakdown of the changes:

    * All note slides are linear (same speed regardless of note
    frequency). Slide speed of $FF means a semitone (99.6 cents to be
    exact) is added to the note value on each frame/tick.
    * Arpeggio depth doesn't depend on note frequency.
    * Internal maximum channel volume was changed to $3F (63), so
    all volume slides will slide about 4 times slower than they did
    previously when using the same speed values. The actual  difference
    is more like 3 times slower (depending on the speed/tempo setting),
    because in versions prior to 1.4 volume slides were not applied on
    the very first tick of the row.

I have only tested with Finnish keyboard layout. If you make a
configuration file for other keyboard layouts, send it to me and I'll
include it in next release.

Take a look at "musetracker.ini" for configuration settings.


Global keys
-----------

Shift+Esc               Quit program
Esc                     Record mode on/off
Space                   Record mode on/off, stops song if playing
Right Ctrl              Play song
Right Alt/Shift         Play pattern
F1                      Go to pattern editor
F2                      Go to instrument select
F3                      Go to order editor
F4                      Go to instrument editor
Alt+L                   Load song
Alt+S                   Save song
Shift+S                 Export NSF
Shift+Ctrl+S            Export FamiTone text file
Alt+Ctrl+L              Load instrument
Alt+Ctrl+S              Save instrument
Alt+Shift+L             Load raw sample (PCM)
Shift+L                 Load DPCM sample
Numpad / or Alt+F1      Decrease octave
Numpad * or Alt+F2      Increase octave
Numpad , or Alt+F7      Switch NTSC/PAL mode
F5                      Decrease step
F6                      Increase step
F7                      Strip unused samples
F8                      Sample loop on/off
F10                     Remove sample
F11                     Block repeat on/off
F12                     Cursor follow on/off
Numpad - or Alt+F3      Decrease instrument
Numpad + or Alt+F4      Increase instrument
Numpad 0-9              Select instrument
Alt+M                   Switch metronome on/off


Pattern editor keys
-------------------

Enter               Note off
Tab                 Move to next channel
Shift+Tab           Move to previous channel
Shift+Up            Transpose selection up
Shift+Down          Transpose selection down
Left Alt+Arrow key  Select block
Left Ctrl+Arrow key Select repeat block
Page Up             Move up 16 rows
Page Down           Move down 16 rows
Home                Move to beginning of pattern
End                 Move to end of pattern
Delete              Delete note
Backspace           Delete preceding note
Insert              Move column down
Left Ctrl+M         Mute channel
Left Ctrl+S         Solo channel
Left Ctrl+X         Cut selection
Left Ctrl+C         Copy selection
Left Ctrl+V         Paste selection
Left Ctrl+Shift+V   Paste selection (don't paste empty rows)
Left Ctrl+Alt+V     Paste selection (effects column only)
Left Ctrl+D         Delete selection


Order editor keys
-----------------

Insert              Add new order
Left                Decrease pattern number
Right               Increase pattern number
Page Up             Move up 4 orders
Page Down           Move down 4 orders
Home                Move to beginning of order list
End                 Move to end of order list
Delete              Delete order
Backspace           Delete preceding order


Instrument editor keys
----------------------

Insert              Add value to current envelope
Return              Note envelope: Switch value between absolute/relative
Up                  Increase envelope value
Down                Decrease envelope value
Right               Move to next envelope value
Left                Move to previous envelope value
Shift+Right         Move loop point right
Shift+Left          Move loop point left
Page Down           Move to next envelope
Page Up             Move to previous envelope
Home                Move to beginning of envelope
End                 Move to end of envelope
Shift+Home          Move loop point to the beginning of the envelope
Shift+End           Move loop point to the end of the envelope
Delete              Delete envelope value
Backspace           Delete preceding envelope value
Left Ctrl+C         Copy instrument envelopes to clipboard
Left Ctrl+V         Paste instrument envelopes from clipboard


Instrument select keys
----------------------

Enter               Edit instrument name
Page Up             Move up 4 instruments
Page Down           Move down 4 instruments
Home                Move to beginning of instrument list
End                 Move to end of instrument list
Left                Previous color
Right               Next color
Left Ctrl+C         Copy instrument envelopes to clipboard
Left Ctrl+V         Paste instrument envelopes from clipboard


Effects
-------

Effects are mostly ProTracker compatible, the differences are noted
below. For version 1.4 the maximum volume was changed to $3F (63) from
the previous maximum $F (15) to make it easier to do slow slides with
e.g. effect "Axy". Note that the effect "Cxy" still uses a parameter
0..15.

0xy: Arpeggio
     Arpeggiate between current note, current note + x and current note
     + y.
     x = first arpeggio note (offset from current note)
     y = second arpeggio note (offset from current note)

1xy: Slide Up
     Slide note frequency up.
     xy = speed

2xy: Slide Down
     Slide note frequency down.
     xy = speed

3xy: Slide to Note
     Slide to the note specified in the current row.
     xy = speed

4xy: Vibrato
     Oscillate note frequency, currently the depth depends on the
     frequency of the note.
     x = speed
     y = depth

5xy: Continue Slide to Note (3xy), but also do Volume Slide.
     See "Axy".
     x = speed up
     y = speed down

6xy: Continue Vibrato (4xy), but also do Volume Slide.
     See "Axy".
     x = speed up
     y = speed down

7xy: Tremolo
     Oscillate instrument volume.
     x = speed
     y = depth

8xy: Enable Auto Delay
     Enables automatic delay effect. Can be used on Pulse 1, Pulse 2,
     Noise and PCM channels (on PCM channel with PCM Pulse/Saw only).
     x = delay
     y = attenuation

Axy: Volume Slide
     Slide instrument volume up/down. Only one of the parameters can be
     specified, "speed up" takes priority.
     x = speed up
     y = speed down

Bxy: Position Jump
     Jump to an order. NOTE: The value is 0 based (xy of 00 jumps to
     the first order).
     xy = order to jump to

Cxy: Set Volume / Duty Cycle
     Instrument's envelope volume is scaled by the volume set here. If
     x is non-zero, instrument's envelope duty cycle is overridden with x.
     x = duty cycle override [1..4]
     y = volume

Dxy: Pattern Break
     Breaks to the next pattern after the current row
     xy = row in the next pattern (as a BCD number)

Exy: Extended MOD Commands

  NOTE: The fine slide commands are only applied on the first tick of
  the row (unlike 1xy/2xy/Axy), allowing for slower slides.

  E1y: Fine Slide Up
       Slide note frequency up.
       y = speed

  E2y: Fine Slide Down
       Slide note frequency down.
       y = speed

  E3y: Glissando on/off
       If y is non-zero, glissando is enabled. When glissando is enabled,
       all note slide commands (1xy, 2xy, 3xy) slide in semitones. When
       disabled, note slides are smooth.
       y = glissando on/off

  EAy: Fine Volume Slide Up
       Slide instrument volume up.
       y = speed

  EBy: Fine Volume Slide Down
       Slide instrument volume down.
       y = speed

  ECy: Note Cut
       Turn the note off after specified number of ticks.
       y = tick number

  EDy: Note Delay
       Delay the note for specified amount of ticks. If the delay is
       bigger than the number of ticks on the current row, the note will
       not be played.
       y = delay

  EEy: Sync Event
       Gives a sync event to MUSE. Can be used to synchronize visuals
       to music. Also used to mark a looping sound effect (in which case
       value of y doesn't matter).
       y = sync id

Fxy: Set Speed/Tempo
     Set the speed or tempo of the song. The default speed is 6 and the
     default tempo is 125 ($7D).
     xy = speed, if xy < $20
        = tempo, if xy >= $20


Software synthesized pulse/saw
------------------------------

Musetracker now makes it possible to use a software synthesized pulse or
sawtooth wave on the PCM channel. It's synthesized in real time at ~7.8kHz
sampling rate. Because the sampling rate is so slow, there's a lot of
aliasing when using high frequencies, but it can still generate some very
nice sounds (and sometimes the aliasing might even work for your favor).

You can enable this feature by changing the instrument type to PCM Pulse
or PCM Saw. Also note that this changes the precision of volume envelope
to 8 bits, and the duty envelope to 8 bits. Duty envelope is not used
for PCM Saw.

PCM Pulse/Saw instruments can be used on normal channels as well and
vice versa. When a normal instrument is used on the PCM channel, it'll
play using PCM Pulse.

One more thing worth noting is that when normal instruments are used
on PCM channel, their volume is scaled down to match the standard
channels. This isn't done for PCM Pulse/Saw, so their maximum volume is
a lot louder than any of the normal instruments.


DPCM
----

You can load DPCM samples with Alt+Shift+L. Currently it's not possible to
build "note maps" out of multiple DPCM samples similar to other trackers,
so it's mostly useful for drum sounds and alike. It can be used for bass
and more as well if you're careful.

DPCM importing from WAV/etc is not supported yet, so if you want that
you'll have to convert the samples using an external conversion tool
or FamiTracker.


MUSE
----

MUSE is a NES sound engine that can be used in games and demos. It
uses music/sound effect data exported from Musetracker and currently
supports 3 assemblers: CA65, ASM6 and NESASM. It should be relatively
straightforward to use it with other assemblers as well (with minor
search & replace changes).

To export data to use with MUSE the following command line switches
are available:

    -s          Followed by one or more songs to be converted
    -e          Followed by one or more sound effects to be converted
    -o          Followed by the name of the output file (assembly source)
    -nesasm     Output in NESASM compatible format

For example, to export data for CA65/ASM6:

    musetracker -s intro.pom level1.pom -e bling.pom kapow.pom -o sounds.s

It is necessary to specify all of the songs at the same time, so that
their instrument data can be globally optimized. Result is a set of
assembly source files that can be included in a project to use together
with the MUSE library.

More information on how to use MUSE can be found in the documentation
in the package muse-vxx.zip (xx = version) that is included with this
release.

To download the latest version of MUSE, visit:

    http://kkfos.aspekt.fi/projects/nes/muse/


FamiTone export
---------------

FamiTone is an open source NES audio library for homebrew games/demos
written by Shiru.

Press Shift+Ctrl+S to export a text file that can consequently be used
with FamiTone. There are quite a lot of restrictions about how the music
must be composed, these are detailed in the FamiTone documentation.

DPCM samples can be also used, they are re-mapped to the 3rd octave in
the order of appearance.

Absolute note envelope values are converted to 0 when exporting, because
FamiTracker/FamiTone doesn't support them.

Note that the default tempo in Musetracker is 125. FamiTone however
assumes a default tempo of 150. You can easily fix this by adding F96
effect at the beginning of your song. It'll be ignored by FamiTone when
converting. It's also a good idea to switch to NTSC mode (with Numpad
",").

I have not tested this feature very thoroughly, so bug reports are
appreciated.

More information about FamiTone can be found at:

   http://nesdev.parodius.com/bbs/viewtopic.php?t=7329


Miscellaneous
-------------

- PCM sampling rate is ~7801 Hz (every two scanlines on PAL
NES). Musetracker converts the sample rate when importing, but does not
apply an anti-aliasing filter, so for optimal sound quality you should
downsample to 7.8kHz with some good audio tool before importing.

- A backup is saved to backup.pom every 5 minutes.

- You can change the tracker background image by placing a file named
"user-background.bmp" (784x592) in the same directory as the Musetracker
executable.

- Sample looping is only processed every tick (50Hz on PAL), that is
every 156 samples. This means sample length needs to be multiple of 156
to loop perfectly.

- Metronome's time signature is not configurable (yet).

- You can change the instrument colors using Left and Right arrow
keys. This also affects the color that the notes that use that instrument
are rendered in. It can be useful for making it easier to visualize drum
beats etc, when you're using several instruments on one channel.

- Note off command doesn't work for PCM/DPCM samples yet, you can work
around this by importing an empty sample and using it as note off...


Known Issues
------------

None at the moment.


Version History
---------------

- v15 (2012-01-11)
  Name changed to Musetracker, version numbering method changed

- Version 1.4.1 (2011-09-19)
  Fixed some bugs in MUSE export

- Version 1.4 (2011-09-14)
  MUSE (6502 playback library for games and demos), linear frequency
  handling (note slide speed and vibrato is not dependent on the note
  frequency anymore), glissando, max. channel volume was changed from
  15 to 63, modifier keys don't hang when using Alt+Tab to switch
  windows (SDL fix), support for display drivers that don't support
  non-power-of-two textures, fix to copy/pasting from the triangle
  channel, fixed (bad!) bugs in autodelay, volume envelope ending in 0
  with loop is now considered a note off, fixed note slides/etc in the
  example songs, various bugfixes...

- Version 1.3 (2011-08-18)
  FamiTone text export, software synthesized pulse/saw on the PCM
  channel, max. number of instruments increased to 255, max. envelope
  length increased to 250, PCM samples are loaded in normal instrument
  slots, DPCM sample support, instrument type switching, iNES export
  option removed, NSF timing is cycle perfect, instrument colors can
  be changed, instrument envelopes can be copied to clipboard, Triangle
  channel octaves match Pulse octaves, + a bunch of other stuff that I
  forgot about

- Version 1.2 (2011-08-06)
  Configuration file, OpenGL rendering, fine tune envelope, note cut
  effect, auto delay effect, new example song (i-like.pom), PCM column
  was expanded for future updates such as DPCM

- Version 1.1 BETA (2011-03-11)
  NSF export, NTSC/PAL mode switch, customizable background, metronome

- Version 1.0 (2010-11-18)
  Initial release


That's all! Have fun!
