Difference between revisions of "External controls api"

From MMS Wiki
Jump to: navigation, search
(Created page with "== Commands: == NB! All setXXX functions return current setting when called without parameters window.mms_embed_controls = { toBeginning, // Scroll cursor to begin...")
 
Line 1: Line 1:
 +
== Usage: ==
 +
 +
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({ fname: '<command name>', args: [<arguments>] },'*');
 +
 +
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-event') return;
 +
    if (evt.data.name == '<event name>') { /* do stuff */ }
 +
  });
 +
 +
 
== Commands: ==
 
== Commands: ==
  

Revision as of 07:34, 9 February 2017

Usage:

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({ fname: '<command name>', args: [<arguments>] },'*');

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-event') return;
    if (evt.data.name == '<event name>') { /* do stuff */ } 
 });


Commands:

NB! All setXXX functions return current setting when called without parameters

 window.mms_embed_controls = {
       toBeginning, // Scroll cursor to beginning. Optionals ‘section’/’part’, default chooses which based on 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> }
 
       listParts: // Returns a list of part names
       setPart: // Sets the current part (NB! Needs time to load again)
 
       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
 
       setFeedbackMode: // either ‘simple’ or ‘advanced’
       getFeedback: // Returns feedback object (see below), or null if it is not available
           // Feedback object is guaranteed to have: { score: <total score> }
     };


Events:

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);

  • ‘fully_loaded' - all required assets loaded. Fired both initially and whenever part changes.
  • '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