MusicNoteLib::Player Class Reference

MIDI Player for Music Strings More...

#include <Player.h>

List of all members.

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

---

Constructor & Destructor Documentation

MusicNoteLib::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

References MusicNoteLib::CParser::AddListener().

---

Member Function Documentation

bool MusicNoteLib::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:

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

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

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

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

bool MusicNoteLib::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:

            MusicNoteLib::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
         

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

Referenced by Play().

bool MusicNoteLib::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 MusicNoteLib::CParser*, MusicNoteLib::CParser::TraceEventHandlerArgs* pEvArgs)
            {
                OutputDebugString(_T("\n"));
                OutputDebugString(pEvArgs->szTraceMsg);
            }

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

           MusicNoteLib::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

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

Referenced by MusicNoteLib::SaveAsMidiFile().

bool MusicNoteLib::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:

            MusicNoteLib::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
        

References MusicNoteLib::MIDIRenderer::SaveToFile().

void MusicNoteLib::Player::StopPlay

(

)

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

References MusicNoteLib::MIDIRenderer::EndPlayAsync().

Referenced by Play().

void MusicNoteLib::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:

            MusicNoteLib::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
         

References MusicNoteLib::MIDIRenderer::WaitTillDone().

---

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

• Player.h
• Player.cpp