Youglish For Developers

Youglish API Reference

The Youglish API lets you embed Youglish functionality in your website and control it using JavaScript.

Using the API's JavaScript functions, you can easily control every aspect of the widget: play, pause, or stop it, move to the previous or next track, adjust speed, and much more.

Samples illustrating the use of the API are available on the demo page.

Requirements

The user's browser must support the HTML5 postMessage feature. Most modern browsers support postMessage, though Internet Explorer 7 does not.
Embedded widgets must have a viewport that is large enough to display the components selected.
Any web page that uses the API must also implement the following JavaScript function:
- onYouglishAPIReady – The API will call this function when the page has finished downloading the JavaScript for the widget API, which enables you to then use the API on your page. Thus, this function might create the widget objects that you want to display when the page loads.

Getting started

The HTML page below creates an embedded widget that searches for 'courage' tracks with 'US' accent, and plays each track 3 times before moving to the next one.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The widget will replace this <div> tag. -->
    <div id="widget-1"></div>


    <script>
      // 2. This code loads the widget API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://youglish.com/public/emb/widget.js";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates a widget after the API code downloads.
      var widget;
      function onYouglishAPIReady(){
        widget = new YG.Widget("widget-1", {
          width: 640,
          components:9, //search box & caption 
          events: {
            'onSearchDone': onSearchDone,
            'onVideoChange': onVideoChange,
            'onCaptionConsumed': onCaptionConsumed
          }          
        });
        // 4. process the query
        widget.search("courage","US");
      }

     
      var views = 0, curTrack = 0, totalTracks = 0;
    
      // 5. The API will call this method when the search is done
      function onSearchDone(event){
        if (event.totalResult === 0)   alert("No result found");
        else totalTracks = event.totalResult; 
      }
         
      // 6. The API will call this method when switching to a new video. 
      function onVideoChange(event){
        curTrack = event.trackNumber;
        views = 0;
      }
         
      // 7. The API will call this method when a caption is consumed. 
      function onCaptionConsumed(event){
        if (++views < 3)
          widget.replay();
        else 
          if (curTrack < totalTracks)  
            widget.next();
      }
    </script>
  </body>
</html>

Loading a Youglish widget

After the API's JavaScript code loads, the API will call the onYouglishAPIReady function, at which point you can construct a YG.Widget object to insert a widget in your page. The HTML excerpt below shows the onYouglishAPIReady function from the example above:

      var widget;
      function onYouglishAPIReady(){
        widget = new YG.Widget("widget-1", {
          width: 640,
          components:9, //search box & caption 
          events: {
            'onSearchDone': onSearchDone,
            'onVideoChange': onVideoChange,
            'onCaptionConsumed': onCaptionConsumed
          }          
        });
        // 4. process the query
        widget.search("courage","US");
      }

The constructor for the widget specifies the following parameters:

The first parameter specifies either the DOM element or the id of the HTML element where the API will insert the tag containing the widget.
The second parameter is an object that specifies widget options. The object contains the following properties:
- width (number) – The width of the video widget.
- components (number) – The components selected (see them all here).
- events (object) - The object's properties identify the events that the API fires and the functions that the API will call when those events occur.

Click here to see all the properties that can be used to customize the widget.

Name

Type

Meaning

Values

width

number

width of the widget in pixels.

Default: expand to all its container width.

height

number

height of the widget in pixels.

Default: expand to its actual content height.

autoStart

number

loaded video will start playing automatically.

1 to enable - 0 to disable.

Default: 1

components

number

sum of all selected components ID.

ex: widget with search, title and speed support will have a components value of 1+4+8 = 13

Check out demo #1 to see all the components in action.

Component	ID
Search box	`1`
Accent panel	`2`
Title	`4`
Caption	`8`
Speed controls	`16`
Toggle UI	`32`
Control Buttons	`64`
Dictionary support	`128`
Near by panel	`256`
Phonetic panel	`512`
Draggable	`1024`
Minimizable	`2048`
Closable	`4096`
All Captions	`8192`

Default: 255

backgroundColor

string

widget background color.