Difference between revisions of "External controls api"

From MMS Wiki
Jump to: navigation, search
(Commands:)
 
(28 intermediate revisions by the same user not shown)
Line 7: Line 7:
 
Commands can be called as:
 
Commands can be called as:
 
   iframe.postMessage({ id: 'matchmysound-embed-controls-command',
 
   iframe.postMessage({ id: 'matchmysound-embed-controls-command',
                       fname: '<command name>', a rgs: [<arguments>] },'*');
+
                       fname: '<command name>', args: [<arguments>], uid: <uid string> },'*');
  
 
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
 
   window.addEventListener('message', function(evt) {
 
   window.addEventListener('message', function(evt) {
     if (evt.data.id != 'matchmysound-embed-controls-event') return;
+
     if (evt.data.id != 'matchmysound-embed-controls-message') return;
     if (evt.data.ename == '<event name>') { /* do stuff */ }  
+
     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: ==
 
== 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 = {
         toBeginning, // Scroll cursor to beginning. Optionals ‘section’/’part’, default chooses which based on pos
+
         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
 
         hasRecording: // returns true when ‘matched’ is an option
         setPlayTrack: // either ‘etalon’ or ‘matched’
+
         setPlayTrack: // either ‘etalon’, ‘matched’, 'backing' or 'metronome'
 
         startStopPlay: // Start/stop playback
 
         startStopPlay: // Start/stop playback
 +
 
 +
        tunerModal: // open/close a modal with the tuner.
 +
                    // Takes an optional parameter (bool) and toggles if it is not given
 
          
 
          
 
         infoModal: // Display exercise information
 
         infoModal: // Display exercise information
Line 31: Line 44:
 
         partModal: // Display part choice modal
 
         partModal: // Display part choice modal
 
    
 
    
         getPartInfo: // Returns info object { default_bpm: <int>, has_backing: <bool> }
+
         getPartInfo: // Returns info object { name: <string>, can_record: <bool>,
 +
                    // default_bpm: <int>, has_backing: <bool>, has_full: <bool>,
 +
                    // multiple: <bool>, non_pitched: <bool> }
 
    
 
    
 
         listParts: // Returns a list of part names
 
         listParts: // Returns a list of part names
         setPart: // Sets the current part (NB! Needs time to load again)
+
         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
 
         tempoModal: // Display tempo change modal
 
         setTempo: // Sets tempo. Values allowed are from 0.3 (30%) to 3 (300%)
 
         setTempo: // Sets tempo. Values allowed are from 0.3 (30%) to 3 (300%)
 
+
       
 
         sectionMarked: // Return whether a section is selected
 
         sectionMarked: // Return whether a section is selected
 
         markSection: // Start marking a section from cursor position
 
         markSection: // Start marking a section from cursor position
 
         resetSection: // Reset currently selected section
 
         resetSection: // Reset currently selected section
 
+
        setSection: // Takes two arguments: beg and end of section in seconds
 +
       
 +
        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'
 
         setRecordBacking,  // Set the mode for recording:  'none'/'backing'/'metronome'
 
         setPageTurnMode: // Set "just page turn" mode value - true or false
 
         setPageTurnMode: // Set "just page turn" mode value - true or false
 
         startStopRecord: // Start/stop recording
 
         startStopRecord: // Start/stop recording
 +
 
 +
        setOptions: // takes two parameters: key and value. Choices for key are:
 +
                    //  "minimum_section_length": <value in seconds>
 +
                    //  "ignore_keyboard": <bool> // disable reacting to keyboard events (allowing them to be caught outside)
 +
                    //  "no_mouse_track_change": <bool> // disable mouse clicks changing to etalon/matched
 +
 
 +
        setShowFeedbackModal: // Set whether the modal for results (or "too_short"/"just_noise") is displayed. values: true/false
 
    
 
    
 
         setFeedbackMode: // either ‘simple’ or ‘advanced’
 
         setFeedbackMode: // either ‘simple’ or ‘advanced’
 
         getFeedback: // Returns feedback object (see below), or null if it is not available
 
         getFeedback: // Returns feedback object (see below), or null if it is not available
             // Feedback object is guaranteed to have: { score: <total score> }
+
             // 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>,
 +
              } */
 +
 +
        zoomCmd: // controls the zoom level of scroll note. takes as input a string command which is one of 'in'/'out'/'full'/'reset'
 +
 +
        // NB! WHAT FOLLOWS IS FOR TESTING ONLY! WILL NOT BE IN THE PRODUCTION RELEASE!
 +
        setColors: takes as input a dictionary {background:<color>, cursor:<color>, section:<color>, overlay:<color>} where <color> is a valid CSS color (like '#FF0000' or 'hsb(0,0,0)')
 
       };
 
       };
 
  
 
== Events: ==
 
== Events: ==
Line 57: Line 96:
 
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);
 
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.
+
* ‘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
 
* '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.
 
* '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
+
* ‘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_showing' - at least one modal open
 
* ‘modals_cleared' - all modals closed
 
* ‘modals_cleared' - all modals closed
 +
* ‘mic_volume' - microphone volume for VU meter. In range [0,1]

Latest revision as of 07:50, 4 December 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>', 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/close a modal with the tuner. 
                   // Takes an optional parameter (bool) and toggles if it is not given
       
       infoModal: // Display exercise information
 
       partModal: // Display part choice modal
 
       getPartInfo: // Returns info object { name: <string>, can_record: <bool>,
                    // default_bpm: <int>, has_backing: <bool>, has_full: <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
       setSection: // Takes two arguments: beg and end of section in seconds
       
       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
 
       setOptions: // takes two parameters: key and value. Choices for key are:
                   //  "minimum_section_length": <value in seconds>
                   //  "ignore_keyboard": <bool> // disable reacting to keyboard events (allowing them to be caught outside)
                   //  "no_mouse_track_change": <bool> // disable mouse clicks changing to etalon/matched
 
       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>,
              } */

       zoomCmd: // controls the zoom level of scroll note. takes as input a string command which is one of 'in'/'out'/'full'/'reset'

       // NB! WHAT FOLLOWS IS FOR TESTING ONLY! WILL NOT BE IN THE PRODUCTION RELEASE! 
       setColors: takes as input a dictionary {background:<color>, cursor:<color>, section:<color>, overlay:<color>} where <color> is a valid CSS color (like '#FF0000' or 'hsb(0,0,0)') 
     };

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]