External controls api

From MMS Wiki
Revision as of 05:24, 1 November 2017 by Velochy (talk | contribs)
Jump to: navigation, search

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>', 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. Callback argument is evt.data.evalue */ } 
 });

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


Commands:

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’, ‘matched’, 'backing' or 'metronome'
       startStopPlay: // Start/stop playback
 
       tunerModal: // open a modal with the tuner
       
       infoModal: // Display exercise information
 
       partModal: // Display part choice modal
 
       getPartInfo: // Returns info object { default_bpm: <int>, has_backing: <bool>, multiple: <bool>, non_pitched: <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
       
       setLoop: // turn looping on/off. Only applies if a section is marked and shown.
       
       canRecord, // Returns true if record button should be available and false otherwise
       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>,
              } */
 
       setColors: // takes as input a dictionary {background:<color>, cursor:<color>, section:<color>} where <color> is a valid CSS color (like '#FF0000' or 'hsb(0,0,0)')
 
       zoomCmd: // controls the zoom level of scroll note. takes as input a string command which is one of 'in'/'out'/'full'/'reset'
     };

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

  • ‘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
  • 'initial_loading_progress' - callback is passed an integer value in the range [0-100] indicating the progress of loading initial metadata
  • 'loading_progress' - callback is passed an integer value in the range [0-100] indicating the progress of full loading (audio, all systems, recording etalon)
  • ‘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_start' - audio playback started, either by pressing <space> or from ui
  • ‘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
  • ‘mic_volume' - microphone volume for VU meter. In range [0,1]