Difference between revisions of "External controls api"

From MMS Wiki
Jump to: navigation, search
Line 27: Line 27:
== Commands: ==
== Commands: ==
NB! All setXXX functions return current setting when called without parameters
NB! All setters also function as getters when called without parameters, i.e. calling setXXX functions return current setting when called with ()
   window.mms_embed_controls = {
   window.mms_embed_controls = {

Revision as of 06:18, 30 March 2017


On iOS and Android webViews, there is direct access to window object. As such, everything works via "window.mms_embed_controls" object as outlined in the next two sections.

For cross-origin uses in HTML5 with iframes, the message passing api (postMessage) needs to be used instead.

Commands can be called as:

 iframe.postMessage({ id: 'matchmysound-embed-controls-command',
                      fname: '<command name>', args: [<arguments>], uid: <uid string> },'*');

with the events being fired directly on the window object so they can be read via

 window.addEventListener('message', function(evt) {
    if (evt.data.id != 'matchmysound-embed-controls-message') return;
    if (evt.data.ename == '<event name>') { /* do stuff */ } 

If command returns a value, it is fired as a message similar to the events with the structure:

   id: 'matchmysound-embed-controls-result',
   fname: <name of function called>,  args: <arguments called with>, uid: <uid echoed back>,
   result: <result that was returned>

If the command does not exist, a message with id: 'matchmysound-embed-controls-result-error' is fired


NB! All setters also function as getters when called without parameters, i.e. calling setXXX functions return current setting when called with ()

 window.mms_embed_controls = {
       toBeginning, // Scroll cursor to beginning. Optionally takes an argument ‘section’/’part’. By default chooses which based on current cursor pos
       hasRecording: // returns true when ‘matched’ is an option
       setPlayTrack: // either ‘etalon’ or ‘matched’
       startStopPlay: // Start/stop playback
       infoModal: // Display exercise information
       partModal: // Display part choice modal
       getPartInfo: // Returns info object { default_bpm: <int>, has_backing: <bool>, multiple: <bool> }
       listParts: // Returns a list of part names
       setPart: // Sets the current part. Takes the name of the part as argument. NB! Needs time to load again
       setViewType: // Choices are 'page'/'scroll'/'wf'
       tempoModal: // Display tempo change modal
       setTempo: // Sets tempo. Values allowed are from 0.3 (30%) to 3 (300%)
       sectionMarked: // Return whether a section is selected
       markSection: // Start marking a section from cursor position
       resetSection: // Reset currently selected section
       setRecordBacking,  // Set the mode for recording:  'none'/'backing'/'metronome'
       setPageTurnMode: // Set "just page turn" mode value - true or false
       startStopRecord: // Start/stop recording
       setShowFeedbackModal: // Set whether the modal for results (or "too_short"/"just_noise") is displayed. values: true/false
       setFeedbackMode: // either ‘simple’ or ‘advanced’
       getFeedback: // Returns feedback object (see below), or null if it is not available
           // NB! null is also returned when a match could not be made ("Heared only noise!")
           /* Feedback object is guaranteed to have: { 
                score: <total score>,
                pitch_score: <pitch score>,
                rhythm_score: <rhythm score>,
                percent_played: <percentage of the piece played>,
                duration: <duration of recording in seconds>,
              } */


You can also register a listener callback to certain events via an "on" function. Currently three events are available: mms_embed_controls.on(‘<evt name>’, callbackFunction);

  • ‘external_controls_ready' - commands are ready to be called and events will fire, although loading is still going on.
  • ‘partially_loaded' - exercise information is loaded up. Waiting only for visuals, audio and etalon. Safe to start calling commands (except play/record)
  • ‘fully_loaded' - all required assets loaded. Fired both initially and whenever part changes
  • ‘view_type_changed' - fired whenever view_type is either first set or changed
  • 'changed_part' - user has chosen a different part in a multi-part exercise
  • 'feedback_available' - feedback is avaliable, i.e. an attempt was just finished. Fired whenever recording stops.
  • ‘play_end’' - audio playback stopped, either automatically or from ui
  • ‘changed_active_track’ - switched between ‘etalon’ and ‘matched’. Query setPlayTrack() to see current
  • ‘modals_showing' - at least one modal open
  • ‘modals_cleared' - all modals closed