CFugue::Player Class Reference

MIDI Player for Music Strings More...

#include <Player.h>

Public Member Functions
	Player (unsigned int nMIDIOutPortID=MIDI_MAPPER, unsigned int nMIDITimerResMS=20)
MusicStringParser &	Parser ()
	Returns the associated Parser object.
unsigned int	MidiOutPort ()
	Get/Set the Midi Output Port that should be used with this Player.
unsigned int	TimerResolution ()
	Get/Set the Timer Resolution (in MilliSeconds) that should be used with this Player.
bool	Play (const MString &strMusicNotes)
bool	PlayAsync (const MString &strMusicNotes)
void	WaitTillDone ()
void	StopPlay ()
bool	IsPlaying () const
	Returns true if an asynchronous Play is currently in progress
bool	SaveAsMidiFile (const MString &strMusicNotes, const char *szOutputFilePath)
bool	SaveToMidiFile (const char *szOutputFilePath)

Detailed Description

MIDI Player for Music Strings

Definition at line 22 of file Player.h.

Constructor & Destructor Documentation

CFugue::Player::Player	(	unsigned int	nMIDIOutPortID = MIDI_MAPPER,
		unsigned int	nMIDITimerResMS = 20
	)

Construct the Player Object using supplied Midi Output port and Timer Resolution

Parameters

nMIDIOutPortID	the output MIDI port to be used for the play
nMIDITimerResMS	timer resolution in Milliseconds

Definition at line 22 of file Player.cpp.

References CFugue::CParser::AddListener().

Member Function Documentation

bool CFugue::Player::Play

(

const MString &

strMusicNotes

)

Plays a string of music notes. Will not return till the play is complete. To Play the Notes asynchronously, use the PlayAsync() method instead.

Returns false if unable to start the play. Failures can happen if unable to open the MIDI output port or if unable to create a MIDI timer with supplied resolution or if there are any critical parsing errors in the supplied Music String.

Parameters

strMusicNotes

the input Music string to be played on MIDI output port

Returns

True if play was successful, false otherwise

Example Usage:

    CFugue::Player player; // Create the Player Object with the default MIDI output port

    player.Play(_T("ci di f fi")); // Play the Music Notes

Definition at line 28 of file Player.cpp.

References PlayAsync(), StopPlay(), and CFugue::MIDIRenderer::WaitTillDone().

Referenced by CFugue::PlayMusicString(), CFugue::PlayMusicStringCB(), CFugue::PlayMusicStringWithOpts(), and CFugue::PlayMusicStringWithOptsCB().

bool CFugue::Player::PlayAsync

(

const MString &

strMusicNotes

)

Starts playing the notes asynchronously. Returns false if unable to start the Play. Play failures can happen if unable to open the MIDI output port or if unable to create a MIDI timer with supplied resolution or if there any critical errors in the Music String parsing.

After Play starts, use IsPlaying() method to determine if play is still in progress. Use the StopPlay() method to stop the play.

You can also use WaitTillDone() to wait till the play completes. Refer WaitTillDone.

Note that each PlayAsync() should have a matching StopPlay() method call to release MIDI resources.

Parameters

strMusicNotes

the input Music string to be played on MIDI output port

Returns

True if play started successfully, false otherwise

Example Usage:

   CFugue::Player player(nMIDIOutPortID, nMIDITimerResMS); // Create the Player object

   if(player.PlayAsync(strMusicNotes) // Start Playing Asynchronously
       while(player.IsPlaying()) // Wait while the play is still in progress
           Sleep(1000);

   player.StopPlay(); // Stop the Play and release MIDI resources

Definition at line 40 of file Player.cpp.

References CFugue::MIDIRenderer::BeginPlayAsync(), CFugue::MIDIRenderer::Clear(), and CFugue::MusicStringParser::Parse().

Referenced by Play().

bool CFugue::Player::SaveAsMidiFile	(	const MString &	strMusicNotes,
		const char *	szOutputFilePath
	)

Parses the Music String and saves the generated MIDI events to a Midi output file.

Returns true upon success. If there are any parsing errors for the Music string, result is undefined.

To get notified about the parsing events, retrieve the associated parser object using the Player::Parser() method and subscribe to the

evTrace

and

evError

events.

Parameters

strMusicNotes	the input Music string to be converted to MIDI output
szOutputFilePath	the output MIDI file path

Returns

True if content is saved successfully, False otherwise

Example Usage:

    void OnParseTrace(const CFugue::CParser*, CFugue::CParser::TraceEventHandlerArgs* pEvArgs)
    {
        OutputDebugString(_T("\n"));
        OutputDebugString(pEvArgs->szTraceMsg);
    }

    void OnParseError(const CFugue::CParser*, CFugue::CParser::ErrorEventHandlerArgs* pEvArgs)
    {
        OutputDebugString(_T("\nError --> "));
        OutputDebugString(pEvArgs->szErrMsg);
        if(pEvArgs->szToken)
        {
            OutputDebugString(_T("\t Token: "));
            OutputDebugString(pEvArgs->szToken);
        }
    }

    CFugue::Player player; // Create the Player Object

    player.Parser().evTrace.Subscribe(&OnParseTrace); // Subscribe to the Trace Events
    player.Parser().evError.Subscribe(&OnParseError); // Subscribe to the Error Events

    player.SaveAsMidiFile(_T("Cq Dw Ex"), "MidiOutput.midi"); // Save the Music Notes to Midi file directly, without playing

Definition at line 60 of file Player.cpp.

References CFugue::MIDIRenderer::Clear(), CFugue::MusicStringParser::Parse(), and CFugue::MIDIRenderer::SaveToFile().

Referenced by CFugue::SaveAsMidiFile().

bool CFugue::Player::SaveToMidiFile

(

const char *

szOutputFilePath

)

Saves any previously played Music Notes into a Midi output file. If Play() or PlayAsync() is not called on this object previously, the output MIDI file will be empty.

To save the notes directly to MIDI file without playing, use Player::SaveAsMidiFile method instead.

Parameters

szOutputFilePath

the output MIDI file path

Returns

True if content is saved successfully, False otherwise

Example Usage:

    CFugue::Player player; // Create the Player Object

    player.Play(_T("ci di f fi")); // Play the Music Notes on MIDI output port

    player.SaveToMidiFile("Output.mid"); // Save the played content to MIDI Output file

Definition at line 69 of file Player.cpp.

References CFugue::MIDIRenderer::SaveToFile().

void CFugue::Player::StopPlay

(

)

Stops the Play started with PlayAsync(). Each PlayAsync() should have a matching StopPlay() method call.

Definition at line 50 of file Player.cpp.

References CFugue::MIDIRenderer::EndPlayAsync().

Referenced by Play().

void CFugue::Player::WaitTillDone

(

)

After play starts asynchronously with PlayAsync(), use WaitTillDone() to wait till the play completes. Caller gets blocked. Once WaitTillDone() returns call StopPlay() to release MIDI resources.

Example Usage:

   CFugue::Player player(nMIDIOutPortID, nMIDITimerResMS); // Create the Player object

   if(player.PlayAsync(strMusicNotes) // Start Playing Asynchronously
    player.WaitTillDone(); // wait while the play is in progress

   player.StopPlay(); // Stop the Play and release MIDI resources

Definition at line 55 of file Player.cpp.

References CFugue::MIDIRenderer::WaitTillDone().

---

The documentation for this class was generated from the following files:

• Player.h
• Player.cpp