TSE3 documentation Version 0.3.0 Index API  Version  Structure 

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.

Save a Song

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

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).
 © Pete Goodliffe, 2001-2003 Copyright Psalm 150