Difference between revisions of "External controls api"

From MMS Wiki
Jump to: navigation, search
Line 6: Line 6:
  
 
Commands can be called as:
 
Commands can be called as:
   iframe.postMessage({ fname: '<command name>', args: [<arguments>] },'*');
+
   iframe.postMessage({ id: 'matchmysound-embed-controls-command',
 +
                      fname: '<command name>', a rgs: [<arguments>] },'*');
  
 
with the events being fired directly on the window object so they can be read via
 
with the events being fired directly on the window object so they can be read via

Revision as of 07:51, 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({ id: 'matchmysound-embed-controls-command',
                      fname: '<command name>', a rgs: [<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.ename == '<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