namespace TSE3 The small amount of time which playback starts before the specified time to give the transport object enough time to get some MidiEvents into the scheduler. More... List of all Methods

Annotated List Files Globals Hierarchy Index

Public Types

• class DisplayParams
• class PresetColours
• enum ErrorCode { TrackAlreadyInsertedErr, PartAlreadyInsertedErr, PartOverlapErr, NoPartInsertedErr, PartTimeErr, PhraseUnparentedErr, PhraseNameExistsErr, PhraseAlreadyInsertedErr, InvalidPhraseNameErr, MidiFileImportErr, MidiFileExportErr, CouldntOpenFileErr, InvalidFileTypeErr, FileFormatErr, MidiSchedulerCreateErr, /** }
• class Error
• class MidiFileImportError
• class MidiFileExportError
• class PhraseListError
• class SongError
• class TrackError
• class PartError
• class MidiSchedulerError
• class SerializableError
• class EventTrack
• class FileItemParser
• struct Clock
• class FileBlockParser
• class FileItemParser_OnOff
• class FileItemParser_ReasonOnOff
• class FileItemParser_Number
• class FileItemParser_Clock
• class FileItemParser_String
• struct MidiEvent
• class Filter
• class Flag
• class FlagTrack
• class KeySig
• class KeySigTrack
• class Metronome
• class Event
• enum MidiCommands { MidiCommand_NoteOff = 0x8, MidiCommand_NoteOn = 0x9, MidiCommand_KeyPressure = 0xa, MidiCommand_ControlChange = 0xb, MidiCommand_ProgramChange = 0xc, MidiCommand_ChannelPressure = 0xd, MidiCommand_PitchBend = 0xe, MidiCommand_System = 0xf, MidiCommand_Invalid = 0x0, MidiCommand_TSE_Meta = 0x1, MidiCommand_NoteEdit_Meta = 0x2 }
• enum TSEMetaMidiCommands { MidiCommand_TSE_Meta_Tempo = 0x00, MidiCommand_TSE_Meta_TimeSig = 0x01, MidiCommand_TSE_Meta_KeySig = 0x02, MidiCommand_TSE_Meta_MoveTo = 0x03 }
• enum MidiSystemCommands { MidiSystem_SysExStart = 0x0, MidiSystem_MidiTimeCode = 0x1, MidiSystem_SongPosition = 0x2, MidiSystem_SongSelect = 0x3, MidiSystem_TuneRequest = 0x6, MidiSystem_SysExEnd = 0x7, MidiSystem_TimingClock = 0x8, MidiSystem_Start = 0xa, MidiSystem_Continue = 0xb, MidiSystem_Stop = 0xc, MidiSystem_ActiveSensing = 0xe, MidiSystem_SystemReset = 0xf }
• enum MidiControlChanges { MidiControl_BankSelectMSB = 0x00, MidiControl_ModulationMSB = 0x01, MidiControl_BreathControllerMSB = 0x02, MidiControl_FootController = 0x04, MidiControl_PortamentoTimeMSB = 0x05, MidiControl_DataEntryMSB = 0x06, MidiControl_ChannelVolumeMSB = 0x07, MidiControl_BalanceMSB = 0x08, MidiControl_PanMSB = 0x0a, MidiControl_ExpressionCtrlMSB = 0x0b, MidiControl_EffectCtrl1MSB = 0x0c, MidiControl_EffectCtrl2MSB = 0x0d, MidiControl_GeneralCtrl1MSB = 0x10, MidiControl_GeneralCtrl2MSB = 0x11, MidiControl_GeneralCtrl3MSB = 0x12, MidiControl_GeneralCtrl4MSB = 0x13, MidiControl_BankSelectLSB = 0x20, MidiControl_ModulationLSB = 0x21, MidiControl_BreathControllerLSB = 0x22, MidiControl_FootControlLer = 0x24, MidiControl_PortamentoTimeLSB = 0x25, MidiControl_DataEntryLSB = 0x26, MidiControl_ChannelVolumeLSB = 0x27, MidiControl_BalanceLSB = 0x28, MidiControl_PanLSB = 0x2a, MidiControl_ExpressionCtrlLSB = 0x2b, MidiControl_EffectCtrl1LSB = 0x2c, MidiControl_EffectCtrl2LSB = 0x2d, MidiControl_GeneralCtrl1LSB = 0x30, MidiControl_GeneralCtrl2LSB = 0x31, MidiControl_GeneralCtrl3LSB = 0x32, MidiControl_GeneralCtrl4LSB = 0x33, MidiControl_SustainPedal = 0x40, MidiControl_Portamento = 0x41, MidiControl_Sostenuto = 0x42, MidiControl_SoftPedal = 0x43, MidiControl_Legato = 0x44, MidiControl_Hold2 = 0x45, MidiControl_SoundVariationLSB = 0x46, MidiControl_Timbre = 0x47, MidiControl_ReleaseTime = 0x48, MidiControl_AttackTime = 0x49, MidiControl_Brightness = 0x4a, MidiControl_GeneralCtrl5 = 0x50, MidiControl_GeneralCtrl6 = 0x51, MidiControl_GeneralCtrl7 = 0x52, MidiControl_GeneralCtrl8 = 0x53, MidiControl_PortamentoSource = 0x54, MidiControl_ReverbDepth = 0x5b, MidiControl_TremoloDepth = 0x5c, MidiControl_ChorusDepth = 0x5d, MidiControl_CelesteDepth = 0x5e, MidiControl_PhaserDepth = 0x5f, MidiControl_DataIncrement = 0x60, MidiControl_DataDecrement = 0x61, MidiControl_NRPM_LSB = 0x62, MidiControl_NRPM_MSB = 0x63, MidiControl_RPM_LSB = 0x64, MidiControl_RPM_MSB = 0x65, MidiControl_AllSoundOff = 0x78, MidiControl_ResetAllControllers = 0x79, MidiControl_LocalControl = 0x7a, MidiControl_AllNotesOff = 0x7b, MidiControl_OmniModeOff = 0x7c, MidiControl_OmniModeOn = 0x7d, MidiControl_MonoModeOn = 0x7e, MidiControl_PolyModeOn = 0x7f }
• struct MidiCommand
• class MidiCommandFilter
• class MidiData
• class MidiScheduler
• class MidiEcho
• class Song
• class Track
• class MidiFileImport
• class Progress
• class MidiFileExport
• class MidiFilter
• class MidiMapper
• class MidiParams
• class MidiSchedulerFactory
• class MixerChannel
• class MixerPort
• class Mixer
• namespace Impl
• class Listener
• class Notifier
• class Panic
• class Part
• class PhraseList
• class Phrase
• class PhraseEdit
• class PlayableIterator
• class Playable
• class Repeat
• class RepeatTrack
• struct SerializableLoadInfo
• class Serializable
• class TempoTrack
• class TimeSigTrack
• class TSE2MDL
• class TSE3MDL
• class FileRecogniser
• class Tempo
• class TimeSig
• class Transport
• class DisplayParamsListener
• class PresetColoursListener
• class EventTrackListener
• typedef EventTrackListener FlagTrackListener
• typedef EventTrackListener KeySigTrackListener
• class MetronomeListener
• class MidiCommandFilterListener
• class MidiDataListener
• class MidiEchoListener
• class MidiFileImportListener
• class MidiFilterListener
• class MidiMapperListener
• class MidiParamsListener
• class MidiSchedulerListener
• class MixerChannelListener
• class MixerPortListener
• class MixerListener
• class PanicListener
• class PartListener
• class PhraseListener
• class PhraseEditListener
• class PhraseListListener
• class PlayableListener
• typedef EventTrackListener RepeatTrackListener
• class SongListener
• typedef EventTrackListener TempoTrackListener
• typedef EventTrackListener TimeSigTrackListener
• class TrackListener
• class TransportListener
• class TransportCallback

Public Methods

• const char * errString (ErrorCode reason)
• inline std::ostream & operator<< (std::ostream &s, const Serializable::indent &i)
• const char * TSE3_Version ()
• const char * TSE3_Copyright ()

Public Members

• extern unsigned int MidiCommand_NoDataBytes[]

Detailed Description

The small amount of time which playback starts before the specified time to give the transport object enough time to get some MidiEvents into the scheduler.

The DisplayParams class holds data related to how a TSE3 object should be drawn on the screen by some application that uses the TSE3 library.

This is perhaps unusual for a pure 'sequencer engine' library, however it is a useful piece of application support. It also ensures that different applications based on TSE3 will display Song data in a relatively similar manner (as deemed appropriate).

Obviously, TSE3 does not use these display values itself (since it does no displaying whatsoever). An application is not required to use the information in this class; however for inter-application constency it is encouraged.

The classes that contain a DisplayParams object are:

• Part
• Phrase

The Part's DisplayParams are considered to 'override' that of it's Phrase.

The DisplayParams object allows an object to be displayed in a number of different states (see the DrawingStyle enum type). For some of these states the DisplayParams object holds extra information (for example a specific colour).

Command classes

Use the following command classes to manipute this object in a undo/redo environment.

• TSE3::Cmd::Track_SetInfo
• TSE3::Cmd::Part_SetInfo
• TSE3::Cmd::Phrase_SetInfo

This class holds information about a set of global colours that can be used by a DisplayParams object whose DisplayParams::style() is set to PresetColour.

See also: DisplayParams

This enum type represents each of the different types of error that may be raised by the TSE3 API. They are used by the exception class Error and it's subclasses.

You can use the errString() function to convert the ErrorCode into an English description string.

See also: Error, errString

This is the base class of all TSE3 errors.

The Error class provides a reason code for each type of error that can be raised, although subclasses are also used to distinguish the type of the error. Each subclass may have more than one reason code associated with it. The reason codes are provided by the ErrorCodes enum type.

The rationale for the reason codes, rather than use of pure subclassing to denote error type, is to allow the application to provide internationalised error messages for the user. It is easier to lookup a string via an integer reason code than convert a class type to some error string. (See ErrorCode and errString() for more information on this.)

Returns a string containing an English representation of the specified TSE3 ErrorCode.

See also: ErrorCode, Error

Class of exception thrown by the MidiFileImport class.

See also: Song

Class of exception thrown by the MidiFileExport class.

See also: Song

Exception thrown by PhraseList class.

See also: PhraseList

Class of exception thrown by the Song insert methods.

Class of exception thrown by the Track class when inserting a Part fails.

Class of exception thrown by the Part class.

Exception class thrown by OSS MidiScheduler classes.

Exception class thrown by Serializable classes.

The EventTrack provides a simple track containing a given type of events.

It is used with instantiations of the Event generic class.

The EventTrack is used as a base class for other types of TSE3 track, for example the TimeSigTrack and TempoTrack.

The contained Event objects are held by value.

The EventTrack has two modes of operating, specified as a boolean parameter in the constructor. The normal operation (as used by most subclasses) is to prevent the insertion of two events with the same time. For example, you don't want to have two different time signatures at the same time. The second mode of operation allows this time duplication.

See also: Event, EventTrackListener

A TSE3 utility class.

This class is used by the FileBlockParser class to act on lines of the format "Name:Data". The FileBlockParser will identify the line as beginning with Name and mantains the mapping of Name string to FileItemParser. It then passes on the data portion of the line to the appropriate FileItemParser.

The Clock class describes a time at which an MidiCommand or other Event may be transmitted/recieved. It is used primarily by the MidiEvent class.

The time is a signed integer value of pulses, where a pulse is a division of a quarter note (crotchet) as defined by the Clock::PPQN variable.

This is a value type.

See also: MidiEvent, PPQN

A TSE3 utility class.

This class can be used by Serializable objects to ease writing a block parser. Provides facilities for reading a whole block (enclosed by "{" and "}") in from an input stream, and act on the data contained within it by either loading subblocks or passing on data lines to helper objects of type FileItemParser.

The advantage of using this class is that it saves a lot of tedious stream parsing code, and prevents silly mistakes like not handling blocks that are not recognised (in this verison of the TSE3 library the Metronome does not have any sub-blocks, but who's to say there won't be some in future versions?)

A TSE3 utility class.

A utility class implementing a specific type of FileItemParser. This class will call a member function with signature void setXXX(bool) with the value true if the data string is either "On" or "Yes".

A TSE3 utility class.

A utility class implementing a specific type of FileItemParser. This class will call a member function with signature void setXXX(reason r, bool) with the boolean value of the data string.

A TSE3 utility class.

A utility class implementing a specific type of FileItemParser. This class will call a member function with signature void setXXX(int) with the numeric value of the data string in a similar manner to FileItemParser_OnOff.

A TSE3 utility class.

A utility class implementing a specific type of FileItemParser. This class will call a member function with signature void setXXX(Clock) with the numeric value of the data string in a similar manner to FileItemParser_OnOff.

This FileItemParser looks partically identical to the _Number version.

A TSE3 utility class.

A utility class implementing a specific type of FileItemParser. This class will call a member function with signature void setXXX(const string &) with the string in the data string.

The MidiEvent is a special kind of event, since any MidiCommand_NoteOn that is sent must be ballanced by a matching MidiCommand_NoteOff to prevent 'hanging notes'.

To facilitate this, this class wraps two MidiCommand events together. The second is only used if the first is a MidiCommand_NoteOn and will always be a ballancing MidiCommand_NoteOff.

(The MidiEvent class contents are not Event<MidiCommand>s because the syntax becomes cumbersome.)

When you create a MidiEvent which contains a MidiCommand_NoteOn you will generally always want to fill in the second MidiCommand's details to be the matching MidiCommand_NoteOff. You will only not honour this in the case where there is no relevant matching note off. This is explained in more detail in the documentation for the PhraseEdit class.

See also: MidiCommand

The Filter is an interface that allows the use of MidiEvent 'filters'. These filters accept a single MidiEvent, and return the MidiEvent filtered in some way.

See also: MidiEvent

Flags are simply named time points in the Song, held in the FlagTrack. This class defines the type that is used to create Flag events, which are of type Event<Flag>.

Flag is a value type.

See also: FlagTrack, Event

The FlagTrack provides a simple time ordered list of Flag Events in the Song. These are just marked time positions.

There is one FlagTrack per Song.

Command classes

Use the following command classes to manipute this object in a undo/redo environment.

• TSE3::Cmd::FlagTrack_Add

See also: Event, Flag

KeySig objects are values of key signature change that occur in the Song, held in the KeySigTrack.

This class defines the type that is used to create KeySig events, which are of type Event<KeySig>.

When streamed from a Playable interface (using the KeySigTrackIterator class) KeySig objects are represented by a MidiEvent containing a MidiCommand_TSE_Meta MidiCommand with data 1 byte as MidiCommand_TSE_Meta_KeySig.

KeySig is a value type.

See also: KeySigTrack, Event

The KeySigTrack provides a simple time ordered list of KeySig changes in the Song.

There is one KeySigTrack per Song.

See also: Event, KeySig

This class provides the functionality of a metronome.

The metronome remembers whether it should be produced in playing and recording modes, but it doesn't enforce this itself - it is the responsibility of the Transport playback routines.

There are two different metronome ticks that are produced, for bars and beats. They must have the same MIDI channel, port, and duration, but can have different notes and velocities.

To determine the point at which clocks bar ticks are produced, a bar reference exists.

See also: Playable

The Event class is an internal part of the Notifier/Listener framework, used to multicast a particular event to a set of Listener objects.

It is a class that can 'hold' zero or more parameters. The upper limit is set by the number of template parameters and invokeImpl member functions - more can be added if you really need them.

If a parameter is not needed, the template declaration will provide def_type which counts as 'no parameter'.

This enum type describes the top four bits of a MIDI command status byte as defined by the MIDI standard.

The values should be passed as 'status' to a MidiCommand object.

Values in the range 0x8 - 0xf are defined by the MIDI standard and will be transmitted to MIDI devices. Values in the range 0x0 - 0x7 are internal TSE3 'meta' status bytes which are used to encode extra information within MidiData objects.

The 'channel messages' which are addressed to one of 16 specific MIDI channels are:

• MidiCommand_NoteOff - Switch a note off
• MidiCommand_NoteOn - Switch a note on
• MidiCommand_KeyPressure - Change velocity of a note
• MidiCommand_ControlChange - Send a controller value
• MidiCommand_ProgramChange - Change voice
• MidiCommand_ChannelPressure - Chnage pressure of entire channel
• MidiCommand_PitchBend - Change note pitch of entire channel
• MidiCommand_System - Special system command (see MidiSystemCommands)

Current meta events are:

• MidiCommand_Invalid - A 'nothing' command. These progate around the system quite a lot and so you must be prepared to see (and ignore) these commands.
• MidiCommand_TSE_Meta - A TSE3 library defined meta event. See the TSEMetaMidiCommands. These include tempo and timesig.
• MidiCommand_NoteEdit_Meta - A range of metas reserved for the NoteEdit program.

This enum type defines the data 1 bytes for meta MidiCommands with the status byte MidiCommand_TSE_Meta. The data 2 byte will contain some data related to this command.

The defined bytes are:

• MidiCommand_TSE_Meta_Tempo - Data 2 holds a new tempo value See Tempo.
• MidiCommand_TSE_Meta_TimeSig - Data 2 is 0xAB. 'A' has the time sig top value, 'B' has the time sig bottom value. See TimeSig.
• MidiCommand_TSE_Meta_KeySig - Data 2 is 0xAB. 'A' has the incidentals values, 'B' has the minor/major value. See KeySig.
• MidiCommand_TSE_Meta_MoveTo - Data 2 is ignored, and the second event in the MidiEvent holds the time to move to. This is generated by the SongIterator.

This enum type describes the MidiCommand_System messages as defined by the MIDI standard. If the MidiCommand status byte is MidiCommand_System, then these values will be found in the 'channel' data bits.

This enum type defines data 1 values for the MidiCommand MidiCommand_ControlChange. The data 2 value will be a number related to this control change type.

Some controllers are continuous values in the range 0-127. Some act as on off switches, where a value of 63 or below is 'off' and 64-127 is 'on'.

The MidiCommand describes one complete MIDI message, including status byte and any data associated with it.

This is a value type.

See also: MidiEvent

This class provides a configurable filter for the different kinds of MidiCommand. It tells it's users whether a given MidiCommand is to be used or not.

The MidiCommandFilter considers MidiCommand_NoteOff and MidiCommand_NoteOns to be the same (otherwise you could produce 'hanging notes').

See also: MidiCommand

The MidiData class represents a list of MidiEvents in time order. It is an abstract base class, notably implemented by Phrase and PhraseEdit.

MidiData objects are not designed to be editable. Only the PhraseEdit class defines an editable MidiData object.

MidiData does not implement the Playable interface. This is for a very good reason: more than one Part may be using a given Phrase at the same time. The Playable interface doesn't provide an 'iterator' type so only one client can play a Playable at once. Therefore MidiData doesn't implement Playable. It's a piece of cake to use, anyway.

See also: MidiEvent, Phrase, PhraseEdit, MidiDataListener

The MidiScheduler provides the interface to the MIDI system (be it a software or hardware driver). On top of this it implements a timed stream for reception and transmission of MidiEvents.

This is the TSE3 platform independant interface to the underlying MIDI hardware. (In fact, it might not even be hardware, this could be the interface to a software synth).

To create a MidiScheduler you will need to use an object derived from this class. The MidiSchedulerFactory classes help you to create this.

Ports

The interface provides a number of MIDI "ports" (which may be added to or removed at run time, depending on the type of system TSE3 is running on).

These ports are referenced by a unique number. You read or write data from/to ports via the MidiEvent data type. The MidiEvent has a "port" number field which identifies which port the command is destined for.

As well as having numbers, the API allows you read a port name. You can also set a "preferred" name for each port. This allows the user to give a more useful name to the port (perhaps for use in a GUI).

Port numbers are not necessarily contiguous and can have any value - this will depend on the phyiscal MIDI device in use. In order to find out what port numbers are in use use the following APIs:

• MidiScheduler::numPorts()
• MidiScheduler::portNumbers()

Note that there are two reserved special port numbers:

• MidiCommand::NoPort - Commands addressed here disappear
• MidiCommand::AllPorts - Commands addressed here go to every port in the system.

Time

As well as managing the MIDI ports, the MidiScheduler looks after a clock that it used to schedule delivery of these events. The API allows you to start/stop/move the time line, as well as set the clock's tempo.

The MidiScheduler can notify back to its clients if the timestream has moved, or been started/stopped by a device on the MIDI connection.

If the timestream is 'stopped' the MidiScheduler class will still remember a 'current' clock value, informally known as the 'resting clock'. When you ask for the time (see MidiScheduler::clock) you will be given this 'resting clock'.

Remote control

Additionally, the MidiScheduler provides a MIDI remote control facility, where certain MIDI notes can trigger transport start/stop.

The keys that are set to be "remote controls" will not be passed up through the API in a MidiEvent if remote control is enabled.

If you switch this facility on, you have to bear in mind that the only time the MidiScheduler gets a chance to investigate the input note stream is as you consume events from it. (For simplicity it doesn't have a clever background thread implementation).

Therefore, read events from the MidiScheduler in a timely manner.

That's all folks

The MidiScheduler class does not incorporate a lot of other fancy utilities, like channel/port remapping, for example. Higher level TSE3 components do this, for example the MidiMapper class. The Transport class ties this all together.

Implementing a MidiScheduler

If you are porting TSE3 to another platform, you will need to implement this MidiScheduler interface. It uses the template method pattern (GoF book) - you have to implement a few member functions and the base MidiScheduler class looks after most of the logic.

These template methods are in the protected section near the end and are all pretty easy to understand.

See also: MidiEvent

The MidiEcho class provides a software equivalent to the MIDI Thru port found on some MIDI equipment.

MIDI Thru provides an exact copy of the MIDI data recieved at the MIDI In port allowing a number of MIDI devices to be 'daisy-chained' together.

Many MIDI interfaces, however, do not provide a MIDI Thru capability so the MidiEcho class is used to emulate it in software.

The MidiEcho class contains a MidiFilter to provide some software filtering of the incoming/outgoing data. You can disable the MidiEcho functionality by setting the filter's status to false.

The Transport class creates and maintains an object of this class to do good things.

The Song is the container of an entire piece of music. It contains a number of Track s, which play concurrently - they correspond to the different members in a band playing together.

The Song class also holds a TempoTrack, TimeSigTrack, KeySigTrack, and FlagTrack. It conatins the PhraseList which holds the list of every Phrase in the Song. (The Phrases are used by Part objects held within each Track).

Command classes

Use the following command classes to manipute this object in a undo/redo environment.

• TSE3::Cmd::Song_SetInfo
• TSE3::Cmd::Song_SetTitle
• TSE3::Cmd::Song_SetAuthor
• TSE3::Cmd::Song_SetCopyright
• TSE3::Cmd::Song_SetDate
• TSE3::Cmd::Song_InsertTrack
• TSE3::Cmd::Song_RemoveTrack
• TSE3::Cmd::Song_SoloTrack
• TSE3::Cmd::Track_Sort
• TSE3::Cmd::Phrase_Erase
• TSE3::Cmd::Phrase_Replace

See also: Notifier, Track

A Track is a subunit of a Song. Many Tracks can exist in a Song and are played concurrently. You can imagine them to correspond to the different members of a band or orchestra.

Tracks contain a number of parameters that effect the way the musical data they contain is produced.

Tracks contain Parts. They 'own' them, and so a Part's lifetime is bound to it's parent Track. Parts are created by external agents - the user of the TSE3 library. Each Part has a well defined start and end time, and the Part objects in the Track may not overlap.

Command classes

Use the following command classes to manipute this object in a undo/redo environment.

• TSE3::Cmd::Track_SetInfo
• TSE3::Cmd::Track_Snip
• TSE3::Cmd::Track_Glue
• TSE3::Cmd::Track_RemovePart
• TSE3::Cmd::Track_Sort
• TSE3::Cmd::Song_InsertTrack
• TSE3::Cmd::Song_RemoveTrack
• TSE3::Cmd::Song_SoloTrack
• TSE3::Cmd::Part_Move

See also: Song, Part

Utility to import a MIDI file and convert it into a TSE3 Song.

There are two ways to play a standard MIDI file. One is to create a MidiFileImport object, use it to generate a Song and then play that. You will also be able to edit the Song and save it again.

The second way to play a MIDI file it to use the MidiFileImport class' Playable interface - this will generate a MidiFileImportIterator object. The advantage of this is that you do not have to delay for the import process (which for large MIDI files can be significant). On the other hand, the data will not be editable or modifiable.

If you only need to play the MIDI file, use the second method. If you need to modify the MIDI file data you need to use the load method to generate a Song.

See also: Song, MidiFileExport

Callback interface for TSE3 classes that provide progress information. This is used, for example, by the file import/export mechanisms (see TSE3MDL, MidiFileImport and MidiFileExport) and the Util::Demidify utility.

See also: Demidify

Utility to export MIDI files converted from a TSE3 Song.

See also: Song, MidiFileImport

This the a standard (and comprehensive) Filter object type that is used by the TSE3 library.

There is provision for the following features:

• enable/disable all events
• incomming MIDI channel filter
• forcing to a MIDI channel/port
• time shift
• time scaling
• linear quantise
• transposition
• velocity window clipping
• velocity scaling

Command classes

Use the following command classes to manipute this object in a undo/redo environment.

• TSE3::Cmd::Part_SetInfo
• TSE3::Cmd::Track_SetInfo

See also: Filter

The MidiMapper maintains a table mapping logical port destinations with where MidiEvents should /really/ be sent.

This is used by the Transport class prior to sending an event to a MIDI interface.

This interface allows you to establish arbitrary mappings. For ports that aren't mapped, the mapper will let the event through unchanged.

The MidiParams class holds values for MIDI parameters used by several of the TSE3 classes.

The parameters it defines can generally be assigned values, not assigned values or forced to not allow any changes in these values at all.

For this reason, MidiParams implements both the Playable and Filter interfaces.

Command classes

Use the following command classes to manipute this object in a undo/redo environment.

• TSE3::Cmd::Track_SetInfo
• TSE3::Cmd::Part_SetInfo

This class will generate an appropriate MidiScheduler for the current platform. It provides a measure of platform indepenance in the generation of MidiSchedulers.

To create a portable and maintainable TSE3 application, do not directly instantiate a particular MidiScheduler, use the MidiSchedulerFactory.

The MixerChannel holds all Mixer values for a particular MIDI channel. It holds information on the current state of the following MIDI parameters:

• channel volume
• pan
• chorus
• reverb
• program
• bank select MSB
• bank select LSB

See also: Mixer, MixerChannel

The MixerPort hols all Mixer values for a particular MIDI port. It contains 16 MixerChannel objects which hold the information for each of the port's MIDI channels.

See also: Mixer, MixerChannel

The Mixer class acts in a similar way to a studio mixing desk - it represents the values of all the knobs and sliders you might find (in the MIDI realm). The values it stores include main volume, channel volume, channel pan, channel reverb, etc.

The values can be updated in real time according to MIDI input, MIDI output, or both. Values can be altered and sent back out through MIDI out.

It contains a number of MixerPort objects which hold the state for each MIDI port in the system.

See also: MidiCommand, MixerPort

Internal implementation namespace.

You can ignore the classes in this namespace. They are internal implementation details for the TSE3 library and are not part of the normal public API.

The contents include implementation details for the Notifier class and the Impl::Mutex classes which provide TSE3 thread-safety.

See also: Notifier, Listener

The Listener class receives events sent from a Notifier class.

Listener inherits from the specified interface_type so you don't need to mupltiply inherit from both Listener the interface_type in your derived class.

To instatiate the Listener class inherit from Listener. Following the example in the Notifier documentation, this would be:

     class Voyeur : public Listener
     {
         public:
             virtual void eventOne(Exhibitionist *src)        { ... }
             virtual void eventTwo(Exhibitionist *src, int a) { ... }
             virtual void Notifier_Deleted(Exhibitionist *src)
             {
                 // The 'src' is being deleted - you do not need to
                 // detach from it, the link is automatically broken.

                 // This method is not defined in the
                 // ExhibitionistListener base class, but is defined by
                 // the Listener class. You
                 // don't have to implement it if you don't need it.
             }
     };

Upon deletion, the Listener class ensures that it is detached from every Notifier it has been attached to. This prevents a Notifier later trying to callback to an invalid object.

See also: Notifier

The Notifier template base class is an implementation of the observer design pattern (GoF book).

Objects that need to send out specific callback events derive from this base class. Each Notifier class may have any number of callback events, and each of these events may take any number (and type) of parameters. The callback system is type safe and easy to use.

Events sent from the Notifier class are received by objects of the Listener class.

Usage

A separate interface class detailing each callback event and the type of Notifier source class must be written, for example:

     class Exhibitionist;

     class ExhibitionistListener
     {
         public:
             typedef Exhibitionist notifier_type;

             virtual void eventOne(Exhibitionist *)        = 0;
             virtual void eventTwo(Exhibitionist *, int a) = 0;
     };

The first parameter of callback events must always be a pointer to the source object.

You may choose to provide a default implementation for the callback methods. This will save you having to reimplement every callback, only the ones for the events you are interested in.

You can now declare a Notifier class thus:

     class Exhibitionist : public Notifier
     {
         // Other contents....
     };

and implement your functionality.

The Exhibitionist class can send callbacks to any attached listener by calling the notify member function. For example:

     notify(&ExhibitionistListener::eventTwo, 1);

The source object pointer parameter is automatically provided and does not need to be specified.

To receive events from a Notifier class, you must write a class that derives from Listener. The documentation for Listener describes how to do this.

See also: Listener

The Panic class encapsulates the playable 'panic' information that can reset attached MIDI devices. This MIDI data stream is produced for a single port number, which you can specify.

Several different kinds of reset information can be sent:

• A basic MIDI reset sequence
• A GM format MIDI reset sequence
• A GS format MIDI reset sequence (to particular device IDs)
• An XG format MIDI reset sequence (to particular device IDs)
• Different MIDI protocol reset messages.

See also: MidiData, PhraseList

The Part class represents a placement of a Phrase in a Track. It holds a reference to the Phrase and the realtime parameters that affect how the Phrase sounds as it is played.

A Part can only exist in one Track at once.

Each Part has a start and end time, which it manages. Before you insert a Part in a Track ensure that you have set the appropriate times with setStart() and setEnd() or with the consolidated setStartEnd().

The Part has a DisplayParameters object associated with it which may be used by an application to redraw the Part on screen (this use is optional). If you do use it, the Part DisplayParams should superceed any Phrase DisplayParams.

Command classes

Use the following command classes to manipute this object in a undo/redo environment.

• TSE3::Cmd::Part_SetInfo
• TSE3::Cmd::Part_SetPhrase
• TSE3::Cmd::Part_Move
• TSE3::Cmd::Track_Snip
• TSE3::Cmd::Track_Glue
• TSE3::Cmd::Track_RemovePart

See also: MidiEvent, Phrase, PhraseEdit

A list of Phrases within a certain Song.

Command classes

Use the following command classes to manipute this object in a undo/redo environment.

• TSE3::Cmd::Phrase_Create
• TSE3::Cmd::Phrase_Erase

See also: Phrase, Song

The Phrase class is a MidiData object with a unique reference name.

Phrases are held in a PhraseList. This PhraseList is the context of the unique name - there can be two Song objects which have Phrases with the same name, but you can't have two Phrases with the same name in one PhraseList.

Phrases are only generated by PhraseEdit objects (see PhraseEdit::createPhrase() for details).

Phrases are used in a Part to produce MIDI data in the Song.

The Phrase has a DisplayParameters object associated with it which may be used by an application to redraw the Phrase in any Part on screen (this use is optional). If you use this, a Part DisplayParams should superceed any Phrase DisplayParams.

Command classes

Use the following command classes to manipute this object in a undo/redo environment.

• TSE3::Cmd::Phrase_SetInfo
• TSE3::Cmd::Phrase_Create
• TSE3::Cmd::Phrase_Erase
• TSE3::Cmd::Phrase_Replace
• TSE3::Cmd::Part_SetInfo
• TSE3::Cmd::Part_SetPhrase

See also: MidiData, PhraseList

This class provides an editable MidiData area. It is the mechanism used to generate Phrase objects.

The PhraseEdit object can be used as an area into which MidiEvent data is recorded in real time (it is used by the Transport class), or as the basic data structure for a GUI Phrase editor, for example.

For this latter mode of usage, the PhraseEdit class provides a number of callbacks (see PhraseEditListener) that can be used to keep the display updated.

Tidiness

The state of the PhraseEdit area can be one of:

• Tidy: Sustain pedal usage has been converted into sustained notes and MidiCommand_NoteOffs are coalescened into their appropriate MidiEvent. The data in the PhraseEdit object is suitable for being played through the Playable interface.
• Untidy: MidiCommand_NoteOffs may not be matched into MidiEvents, sustain pedal events may not have been cleaned up, events could be out of chronological order. Basically, the data is likely to me a big mess and all hell could break loose if you try to play this MidiData in it's current state. (All hell breaking loose is likely by be 'hanging notes'.)

It is up to the user to know if a PhraseEdit area may be untidy and to deal with it appropriately (i.e. make sure it is never played). After having tidied the data (by calling tidy()) the only way to make the data untidy is to write a MidiEvent directly using operator[]().

When the PhraseEdit is tidy, the safest way of modifying a MidiEvent is to remove it and the reinsert the modified MidiEvent.

Managing selected MidiEvent contents

The PhraseEdit object can manage the selection status of it's MidiEvent contents. This will be useful for GUI editors that use the PhraseEdit as the underlying data buffer.

Selections are denoted by the selected bit in the MidiCommand data type. You can use select() and deselect() to alter selection states.

For convenience the PhraseEdit class remembers the index of the first and last selected MidiEvent.

Working with selections only really makes sense when the data area is tidy. You can still use the selection facilities with an untidy data area, however.

Modification status

As an extra utility for GUI uses, the PhraseEdit class manages a 'modification' status. It allows the user to find out whether the data has been modified since the last reset(), and also fires an event off the first time it is modified.

Changing the selection does not affect the modified status.

Command classes

Use the following command classes to manipute this object in a undo/redo environment.

• TSE3::Cmd::Phrase_Create

See also: MidiData, Phrase

This is an iterator that moves over every MidiEvent in a Playable object. Each MidiEvent are delivered in time order. This is a use of the 'Iterator' design pattern in the GoF book.

Each kind of Playable object will provide an implementation of the PlayableIterator interface that knows how to iterate over that kind of object.

See also: Playable, MidiEvent

The interface that an object that can produce MidiEvents must implement. Playable objects allow a 'player' to get an iterator that will produce all the MidiEvents in the object. Each implementation of Playable will therefore also supply an implementation of PlayableIterator which is accesed via the iterator() method.

Since all Song components implement the Playable interface, this is an application of the 'Composite' pattern from the GoF book.

See also: PlayableIterator

Repeat objects hold the repeat time.

This class defines the type that is used to create repeat events, which are of type Event.

When streamed from a Playable interface (using the RepaetTrackIterator class) Repeat objects are represented by a MidiEvent containing a MidiCommand_TSE_Meta MidiCommand with data 1 byte as MidiCommand_TSE_Meta_MoveTo.

Repeat is a value type.

See also: RepeatTrack, Event

The RepeatTrack provides a simple time ordered list of repeat points in the Song.

The RepeatTrack is no longer used by the Song class - it has been superceeded by a more simple mechanism. However it remains in the TSE3 library since it may find other uses.

See also: Event, Repeat

Data structure used by the Serializable class during loading. It contains information that has been gained about the file, mostly from the "Header" chunk. Most Serializable classes will not need to write to this struct, but will almost certainly need to read it (at least to convert local file PPQN resolution to TSE3 system PPQN).

Serializable is the base class of objects that can save their state to a file in the block structure of the TSE3MDL specification. Any class that wishes to be able to persist itself needs to implement this interface.

Important note

The entry point to save/load facilities is the TSE3MDL class, you should use that rather than the Song class's Serializable interface directly.

See the TSE3MDL class documentation for more details.

File format

Data is to be saved in the TSE3MDL file format. Each object will save an amount of data in a block, whose format follows the layout below.

   IDENTIFIER
   {
       DATA_TAG1:DATA
       DATA_TAG2:DATA
   }

One data item exists per line. A mechanism exists to determine the number of indentation spaces that precedes each line (it is passed as a parameter to each save() call). There are means to make it easy to produce this indentation (see the indent() method).

When parsing the data unrecognised data items should be ignored, and unrecognised chunks shall be skipped.

The file format is further described in the HTML documentation that comes with the TSE3 library, in the "doc" directory.

See also: TSE3MDL

Used by implementations of Serializable::save.

An implementation can call this to indent the line to the given level.

e.g. o << indent(5) << "DATA_TAG:" << data << "\n";

The TempoTrack provides a simple time ordered list of tempo changes in the Song.

There is one TempoTrack per Song.

See also: Event, Tempo

The TimeSigTrack provides a simple time ordered list of TimeSig changes in the Song.

There is one TimeSigTrack per Song.

See also: Event, TimeSig

This class provides file import for TSE2MDL files.

It uses the TSE2MDL file type, as created by programs based on the earlier TSE2 library. This format differs somewhat from the TSE3MDL format, notably in that it is a binary format. It is not forwards and backwards compatible, and it does not support all of TSE3's Song structure. Since these files are produced by programs based on the older TSE2 library this class is provided merely for compatibility.

When saving/loading TSE3 Song objects, you should prefer the TSE3MDL file format which is accessed via the TSE3MDL class.

You may see TSE2MDL files referred to simply as 'TSEMDL' files.

Returns a string containing the TSE3 version number.

Returns: TSE3 version string

Returns a string containing the TSE3 copyright message.

Returns: TSE3 copyright string

The TSE3MDL object provides file operations for the TSE3 library, being the main entry point for saving/loading in the TSE3MDL file format.

It uses the Serializable interface implemented by the various TSE3 classes.

See also: Serializable

The FileRegoniser class will return information about a given file.

It can recognise three file types - the three types that TSE3 provides support for. These are:

• Native TSE3MDL files
• TSE2MDL (the file format of TSE2)
• Standard MIDI files

Tempo objects are simply integer values of a tempo change that occur in the Song, held in the TempoTrack.

This class defines the type that is used to create tempo events, which are of type Event<Tempo>.

When streamed from a Playable interface (using the TempoTrackIterator class) Tempo objects are represented by a MidiEvent containing a MidiCommand_TSE_Meta MidiCommand with data 1 byte as MidiCommand_TSE_Meta_Tempo.

Tempo is a value type.

See also: TempoTrack, Event

TimeSig objects are representations of a time signature change that occurs in the Song. They are held in the TimeSigTrack.

This class defines the type that is used to create TimeSigEvents, which are of type Event<TimeSig>.

When streamed from a Playable interface (using the TimeSigTrackIterator class) TimeSig objects are represented by a MidiEvent containing a MidiCommand_TSE_Meta MidiCommand with data 1 byte as MidiCommand_TSE_Meta_TimeSig.

TimeSig is a value type.

See also: TimeSigTrack, Event

This object handles the playback/record mechanism. It is the central control for musical input and output.

It usually plays a Song, but isn't restricted to Songs since it uses the abstract Playable interface as the music source.

When using this class it is important to call the poll method as often as possible: it does most of the work. It would be a good idea to do this polling in a background thread (see Impl::Mutex for information on threading issues).

Facilities provided by the Transport class include:

• Play
• Record into PhraseEdit
• Fast forward and rewind
• Ability to attach callbacks which are kept informed of MIDI activity coming into or leaving the Transport object
• Uses Panic objects (for start and stop reset sequences), a MidiEcho object
• Synchro start (playback starts when MIDI input recieved)
• Uses a FlagTrack to move around the Playable easily
• Auto stop at the end of the Playable object
• Lead in values for play and record
• Adaptive look ahead
• Ability to 'inject' a MidiCommand into the Transport stream.

See also: Song, Playable, TransportCallback

DisplayParams listener interface.

See also: Listener

PresetColours listener interface.

See also: Listener

EventTrack listener interface.

See also: Listener

Metronome listener interface.

See also: Listener

MidiCommandFilter listener interface.

See also: Listener

MidiData listener interface.

See also: Listener

MidiEcho listener interface.

See also: Listener

MidiFileImport listener interface.

See also: Listener

MidiFilter listener interface.

See also: Listener

MidiMapper listener interface.

See also: Listener

MidiParams listener interface.

See also: Listener

MidiScheduler listener interface.

See also: Listener

MixerChannel listener interface.

See also: Listener

MixerPort listener interface.

See also: Listener

Mixer listener interface.

See also: Listener

Panic listener interface.

See also: Listener

Part listener interface.

See also: Listener

Phrase listener interface.

See also: Listener

PhraseEdit listener interface.

See also: Listener

PhraseList listener interface.

See also: Listener

Playable listener interface.

See also: Listener

Song listener interface.

See also: Listener

Track listener interface.

See also: Listener

Transport listener interface.

See also: Listener

This class is used as a base for objects that want to be called back from the Transport object to be informed when MIDI activity occurs. Uses of this may be a MIDI activity monitor, for example.

See also: Transport