# TSE3 library HOWTO

This document provides simple descriptions of how to use the TSE3 API to perform common tasks.

### Including library headers

To use the library you should have you compiler set to point to the appropriate include directory. TSE3 header files should be included with a line like:

        #include "tse3/Midi.h"

Note the `tse3/` section. This will ensure that TSE3 header file names do not clash with other library paths.

Where you do not need to `#include` a header (for example, you do not inherit directly from a TSE3 class, just use pointers to it in your class' interface) you are urged to forward declare TSE3 classes rather than pull in the header file. For example:

        namespace TSE3
        {
            class Song;
            class Track;
        }

### Load a Song

The TSE3 library can save and load standard MIDI files as well as song files in it's own filetype (TSE3MDL). There are benefits and drawbacks of both types. MIDI files are portable - practically any other sequencing/multimedia package will be able to interpret them. However, MIDI files are not expressive enough to describe TSE3's advanced Song structure and so use of the TSE3MDL format is recommended where possible.

- TSE3MDL files
  Use the `TSE3MDL` object (in `TSE3MDL.h`). The KDOC documentation explains how to use it. Do not use the `Serializable` interface of the `Song` class directly, you will not create a complete TSE3MDL file.
- Standard MIDI files
  Use the `MidiFileImport` object (in `MidiFile.h`). The KDOC documentation explains how to use it.
- TSE2MDL files
  These are files as created by the older TSE version 2 library. You use the `TSE2MDL` class (in `TSE2MDL.h`) to import these files.

### Save a Song

To save as TSE3MDL or standard MIDI file is as easy as loading.

- TSE3MDL files
  Use the `TSE3MDL` object.
- Standard MIDI files
  Use the `MidiFileExport` object (in `MidiFile.h`).

### Play a Song

The `Transport` object (in `tse3/Transport.h`) is used to play a `Song` object (or in fact, any kind of object that implements the `Playable` interface). To use it you must also create a `MidiScheduler` object that knows how to play MIDI output on your computer. For example, Linux boxes with the Open Sound System will want to create an `OSSMidiScheduler` object using the `OSSMidiSchedulerFactory` class.

As well as a `MidiScheduler` you must also create a `Metronome` object. If simply playing back a file, you may wish to switch the metronome 'tick' off using the documented API.

Playing a `Song` is simply a matter of calling `play` on the `Transport` object. You can either poll the `Transport` object to find out when the playing has stopped, or implement the `TransportListener` interface to be told directly.

### Any other questions?

If you have any other questions, ask the author!

(The tse3play program is a good example of how to use the library - you might find your answer there).