API MPTK - Playing MIDI by script

Look here to see the full API documentation.

One of the strengths of MPTK is the ability for playing music with any line of script. But, for more complex needs, you will have to write some Unity scripts.

Above all, don’t be worried, MPTK API is quite simple and well documented. On the other hand, writing script with Unity requires two skills:

Understanding Unity scripting principles
Learn C# language. Basic knowledge may be sufficient at the start.

Don’t Panic!

There are Excellent Guides to this Galaxy!

Unity proposes a lot of well done tutorials, to begin, I encourage you to follow these two tutorials:

Start with Beginner Scripting to learn about programming for game development, from the very beginning with easy to follow video tutorials.
You need also to learn how writing script with the language C#. There is no need to become a master. Thanks to C# which is quite simple. Associated with Unity, a C# beginner can build great thing. Take the time to follow this tuto Coding in C# in Unity for beginners .

On top of that, Maestro MPTK contains an API (a set of class, functions and attributes: follow the C# tuto if you don’t understand this) which facilitate reaching your target.

With Free and Pro versions of MPTK you will be able to:

Playing MIDI Music from MIDI file, see MidiFilePlayer prefab and class
Playing Generated Music from your algorithm, see MidiStreamPlayer prefab and class and MPTKEvent class.
Loading a MIDI file and get access to all the MIDI events, see MidiFileLoader prefab and class.

In addition with the Pro version, you can also:

Playing External MIDI, see MidiExternalPlayer prefab and class.
Writing a MIDI file, see MidiFileWriter class.
Defined play list with overlap and play extract of MIDI, see MidiListPlayer prefab and class.
Reading MIDI events from a MIDI keyboard, see MidiInReader prefab and class.
Spatialize each instruments from a a MIDI file, see MidiSpatializer prefab and class.
Changing on fly the current SoundFont or bank, see API in MidiPlayerGlobal class.
Applying effects as filter, reverb, chorus.
Build Scales and Chords.

First step, create your scene!

Classically, the Unity scene contains all the necessary gameObjects for your project. In addition, don’t forget to save your scene outside MidiPlayer folder in order to easily update MPTK when new versions are available.

Except for MidiPlayerGlobal or MidiFileWriter, you can’t use directly the MPTK classes because these classes need others components to work correctly.

Rather, add MPTK prefab in your scene hierarchy, directly at the top level of your scene hierarchy or attached to another gameObject (2D or 3D Object, Camera, Light … ).

There is surely a prefab for your need! All you have to do is to add this prefab to your scene. Drag and drop from Unity Project Tab:

Choose your MPTK prefab depending of your need:

Prefab available for Free

MidiFilePlayer: play music from a MIDI file.
MidiStreamPlayer: create music from algo.
MidiFileLoader: load a MIDI file for analysis or processing purpose.

Prefab available with Pro version

MidiListPlayer: play music from list of MIDI files, overlap between MIDI, play part of a MIDI, loop …
MidiExternalPlay: playing a MIDI directly from the Web or anywhere on the desktop.
MidiInReader: read MIDI events from a MIDI keyboard, play directly, or do anything that you want with the MIDI events.
MidiSpatializer: play music from a MIDI files with the spatializer ready for a 3D environnement.

Now, create your script!

Add a gameObject (empty or not) in your scene hierarchy and add a script to your gameObject:

Edit your script with your preferred editor:

You’ll need to add the following at the top of any C# script that need to use MPTK API: using MidiPlayerTK

For using the MPTK methods or attributes, your script must retrieve a reference to your prefab added in your scene. So declare a variable in your script depending the type of prefab you are using:

public MidiFilePlayer midiFilePlayer;
public MidiStreamPlayer midiStreamPlayer;
public MidiFileLoader MidiLoader;
public MidiExternalPlayer midiExternalPlayer;
public MidiInReader midiInReader;
public MidiListPlayer midiListPlayer;

Then, associate the prefab to the variable added in your script.

First method, with Unity Editor:

On the inspector of the gameObject which contains your script, drag and drop a prefab to the field “Midi File Player” (your variable midiFilePlayer has been set to uppercase by Unity with space inserted, I known that could be not intuitive!):

Warning: Always associate a prefab from your scene hierarchy, never from the Unity project tab! That will not work!

Second method, associate your MPTK prefab to a variable just by script:

In your script, write something like that, preferably in the Start() method:

using MidiPlayerTK;

public class MySimplePlayer : MonoBehaviour
{
   public MidiFilePlayer midiFilePlayer ;

   // Use this for initialization
   void Start()
   {
      midiFilePlayer = FindObjectOfType<MidiFilePlayer>();
   }
}

Some important tips:
- All methods and properties are prefixed with MPTK_. To clarify, don’t use the others ! They can be modified or removed without any information.
- Also, avoid using methods or attributes not documented, they could change without any notification.
- Some methods are virtual : also it’s better to encapsulate MPTK class with your own class than modifying MPTK source code if you want to keep the benefit of the future releases.

Now you are able to use the MPTK API. Look at scripts from demo, for example : TestMidiFilePlayerScripting.cs

Example of MPTK API with MidiFilePlayer Class

midiFilePlayer.MPTK_MidiName = "Albinoni - Adagio";
midiFilePlayer.MPTK_Play();

// Change speed of playing. Adagio transformed to Allegretto ;-)
midiFilePlayer.MPTK_Speed = 2f; 

// Change instrument because you don't like the strings
midiFilePlayer.MPTK_ChannelForcedPresetSet(0, 10);

// Disable drum. Albinoni Adagio without drum ? strange ...
midiFilePlayer.MPTK_ChannelEnableSet(9, false);

Example of MPTK API with MidiStreamPlayer Class

// Example of MPTK API with MidiStreamPlayer Class
private void PlayOneNote()
{
 // Play a note C5 for 1 second on the channel 0
 NotePlaying = new MPTKEvent()
 {
    Command = MPTKCommand.NoteOn,
    Value = 60,  //C5
    Channel = 0,
    Duration = 1000f,
    Velocity = 100,
    Delay = 0f,
  };
  midiStreamPlayer.MPTK_PlayEvent(NotePlaying);
}

// Play a C5 Maj chord (MPTK Pro)
ChordLibPlaying = new MPTKChordBuilder(true)
{
   // Parameters to build the chord
   Tonic = 60,
   FromLib = 0,
   Channel = 0,
   Arpeggio = 50, // delay in milliseconds between each notes of the chord
   Duration = 1000f,
   Velocity = 100f
   Delay = 0,
}
midiStreamPlayer.MPTK_PlayChordFromLib(ChordLibPlaying);

Look here to see the full API documentation.

Some examples in the package could be useful for you:

CatchMusic – MIDI music with preprocessing before playing. In short, could become a complete game in the future or for you if you have the desire 😉
EuclideanRhythm – how to build a rythmic box! (Pro only)
TestMidiFilePlayerWithScript – play MIDI music with a GUI, change SoundFont (Pro version)
TestMidiStreamSimple – very simple example for generating music. It’s useful for my regression tests but also for you to quickly understand the two methods available to generate music.

Full example code with MidiExternalPlayer prefab (Pro version):

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using System;
using MidiPlayerTK;

public class SimplePlayer : MonoBehaviour
{
    /// <summary>
    /// MPTK component able to play a Midi file from an external source. 
    /// Add a PreFab MidiExternalPlayer your scene.
    /// </summary>
    public MidiExternalPlayer midiExternalPlayer;

    private void Start()
    {
        // Find the Midi external component 
        if (midiExternalPlayer == null)
        {
            // Not found, try to find in the scene.
            Debug.Log("No midiExternalPlayer defined with the editor inspector, try to find one");
            MidiExternalPlayer fp = FindObjectOfType<MidiExternalPlayer>();
            if (fp == null)
                Debug.Log("Can't find a MidiExternalPlayer in the scene. No music will be played");
            else
            {
                midiExternalPlayer = fp;
            }
        }

        if (midiExternalPlayer != null)
        {
            // Event trigger for each group of notes read from midi file
            if (!midiExternalPlayer.OnEventNotesMidi.HasEvent())
            {
                // Set event by script
                Debug.Log("OnEventNotesMidi defined by script");
                midiExternalPlayer.OnEventNotesMidi.AddListener(ReadNotes);
            }
            else
                Debug.Log("OnEventNotesMidi defined by Hierarchy in Unity editor");
        }
    }

    /// <summary>
    /// Event fired by MidiFilePlayer when Midi notes are available
    /// from the MPTK sequencer.
    /// Try this in the inputfield: http://www.midiworld.com/midis/other/c2/bolero.mid   
    /// </summary>
    public void ReadNotes(List<MPTKEvent> notes)
    {
        Debug.Log("Notes count: " + notes.Count);
        foreach (MidiPlayerTK.MPTKEvent midiEvent in notes)
            if (midiEvent.Command == MPTKCommand.NoteOn)
                Debug.Log(" Channel:" + midiEvent.Channel +
                          " Note:" + midiEvent.Value + 
                          " Velocity:" + midiEvent.Velocity + 
                          " Duration:" + midiEvent.Duration + " ms");
    }


    /// <summary>
    /// Other method: play is fired from the a button or an input field
    /// The URL is used to load the midi file from a web site.
    /// </summary>
    /// <param name="uri">uri or path to the midi file</param>
    public void Play(string uri)
    {
        Debug.Log("Play from script:" + uri);
        midiExternalPlayer.MPTK_Stop();
        midiExternalPlayer.MPTK_MidiName = uri;
        midiExternalPlayer.MPTK_Play();
    }
}

Have Fun!

Thierry Bachmann on News!20.3.2024
Hello John Sorry for the delay to answer. I’m not well follow comments on my blog, rather use my discord…
John on News!2.3.2024
Thanks Tierry, to clarify im not trying to get an external device to integrate, I have a piano prefab that…
Thierry Bachmann on News!29.2.2024
Hello John, Thank for your interest with Maestro MPTK! Integration with an external MIDI device is possible with MPTK Pro.…
John on News!29.2.2024
Hello, Firstly thanks for making this. I have a quick question. I have put the player into a project I…