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!