Pornotracker
------------
Version 1.1 BETA
by thefox // aspekt :: thefox@aspekt.fi :: http://kkfos.aspekt.fi

Uses Nes_Snd_Emu APU library by blargg.

I have only tested with Finnish keyboard layout, if you have problems
with other layouts let me know.

If you make something cool with it, send your songs to me! ;=)

This is a BETA version! If something doesn't seem to be working right,
please let me know! I still have some optimizations to add to the NSF
code but it seemed stupid to sit on it just for that reason, so here
you go.


Global
------
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
Alt+Shift+S             Export iNES ROM (VRC6)
Alt+Ctrl+L              Load instrument
Alt+Ctrl+S              Save instrument
Alt+Shift+L             Load raw 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
F9                      Split sample (*1)
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
Alt+Numpad - or Alt+F5  Decrease current sample
Alt+Numpad + or Alt+F6  Increase current sample
Numpad 0-9              Select instrument
Alt+M                   Switch metronome on/off

(*1 splits the current raw sample to two equally sized samples)


Pattern editor
--------------
On channels Pulse 1, Pulse 2, Triangle and Noise notes are entered
like in any other tracker. On PCM channel when ANY note key is pressed,
note using the currently selected raw sample is added to the channel.

Enter               Note off (doesn't work on PCM)
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+D         Delete selection


Order editor
------------
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
-----------------
Insert              Add value to current envelope
Return              Switch envelope 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


Instrument select
-----------------
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


Effects
-------
Effects are mostly ProTracker compatible, the differences are noted
below. Also note that the maximum volume is $0F, not $3F.

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

Axy: Volume Slide
     Slide instrument volume up/down.
     x = speed up
     y = speed down

Bxy: Position Jump
     Jump to an 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

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

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

  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

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


NSF export
----------
To be written.


Miscellaneous
-------------
- PCM sampling rate is ~7801 Hz (every two scanlines on PAL NES).
- The exported iNES ROMs use VRC6 mapper only because of its handy
  CPU cycle based IRQ, the extension sound channels are not supported.
- A backup is saved to backup.pom every couple of minutes.
- You can change the tracker background image by placing a file named
  "user-background.bmp" (736x592) in the same directory as the Pornotracker
  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)


Known Issues
------------
- PCM sample rate in exported iNES files isn't exactly the same as in
  the tracker because of IRQ latencies. I'm planning to rewrite the
  playback routine to be completely cycle timed which should fix the
  issue. Also it would allow using mappers other than VRC6. Unfortunately
  it also brings some complications to PAL/NTSC compatibility,
  maintainability and in general is a pain in the ass to do.


Version History
---------------
- 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!
