README for MilkyTracker SDL Versions
====================================


This file contains information that is specific to the SDL versions of
MilkyTracker.  Please read this file in addition to MilkyTracker.html

It is advisable that you run MilkyTracker from the command line (at least the
first time you run it) as it will output some messages informing you of what
audio driver it is using as well as any errors that occurred.


MIDI (Alsa only)
================

If available, MilkyTracker will detect Alsa and configure itself as a Midi
receiver.  You can then link MilkyTracker up to a Midi sender in the normal
manner.  You can enable midi velocity recording with the following command line
argument:

$ ./milkytracker -recvelocity

Midi velocity recording only works in live record mode (pattern is playing).
Midi support is currently only available on the Linux versions.


Audio Driver
============

SDL *should* detect the best available audio driver on your system, however if
this isn't the case you can set the environment variable 'SDL_AUDIODRIVER' to
configure SDL to use the driver of your choice. Some known values to try are
'alsa', 'dsp', 'arts', 'esd'.  For example:

$ SDL_AUDIODRIVER=alsa ./milkytracker

Note that due to weaknesses in some audio configurations we have had to force
MilkyTracker to use 2^N audio buffer sizes.  This option can be disabled in the
config menu and this is recommended if your audio driver will accept it.

* New for version v0.90.80 *

Two new audio drivers have been added; ALSA and JACK. JACK by default does not
attempt to guess which output device to connect to, the connection should be
made manually.


Video Driver
============

MilkyTracker should auto-detect your screen mode, however if it doesn't there
are the following command line options:

-bpp N        Set N to either 16 or 24
-swap         Swaps the red and blue values in 24 BPP mode
-orientation  Valid arguments are NORMAL|ROTATE90CCW|ROTATE90CW

The screen size can be selected in the Config->Layout menu.  Fullscreen mode can
be toggled using ALT+Return.  Note that these arguments are likely to be removed
in the future - drop us a note if you actually need to use them.

For very minimal platforms, make sure to run milkytracker in non-opengl mode:

$ NO_OPENGL=1 ./milkytracker

This will disable SDL2 from automatically switching to OpenGL.
SDL2 is quite liberal in assuming that opengl is great idea.
This can lead to immediate crashes (for example when only libGL is installed, but not GLX).


Crash Handler
=============

Hopefully you should never need to know this, but just in-case the unthinkable
happens MilkyTracker has a crash handler which should intercept most crashes
(but not freezes!).  If this does happen, a message will be outputted to stderr
and MilkyTracker will attempt to save a backup of the song currently loaded.
This will be named BACKUPxx.XM and saved in your home directory (where xx is a
sequential number in the range 00 to 99).

If MilkyTracker should crash, please attempt to reproduce the crash and then
post details on the bug forum so we can attempt to fix whatever is causing it.

Enjoy!


- Christopher O'Neill (Deltafire) 19/8/2006