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

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:

  1. 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.
  2. 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

Default: 255


backgroundColor
string
widget background color.
Any CSS supported color formats (red, #ff0000,etc).

Default: white


linkColor
string
widget links color.
Any CSS supported color formats (red, #ff0000,etc).

Default: #337ab7


titleColor
string
widget title color.
Any CSS supported color formats (red, #ff0000,etc).

Default: #555555


captionColor
string
widget caption color.
Any CSS supported color formats (red, #ff0000,etc).

Default: #6495BF


markerColor
string
widget marker color.
Any CSS supported color formats (red, #ff0000,etc).

Default: yellow


queryColor
string
query color.
Any CSS supported color formats (red, #ff0000,etc).

Default: orange


panelsBackgroundColor
string
'Search', 'phonetic', 'near by' background color.
Any CSS supported color formats (red, #ff0000,etc).

Default: #F5F5F5


textColor
string
text color.
Any CSS supported color formats (red, #ff0000,etc).

Default: #7F98AD


keywordColor
string
keywords color.
Any CSS supported color formats (red, #ff0000,etc).

Default: orange


captionSize
number
caption font size in pixel.
Default: 40

restrictionMode
number
Activate 'Restricted Mode' to block any inappropriate content to be displayed (aka Kids Mode).
1 to enable - 0 to disable.

Default: 0


videoQuality
string
Set video quality: the lower the quality - the lower your network bandwidth consumption & the faster the loading time. Select 'default' to allow YouTube to selects the appropriate playback quality (recommended).
  • default
  • small
  • medium
  • highres

Default: default


toggleUI
number
UI (caption + control buttons) initial position. Based on your selection, the buttons and caption will appear below or inside the player.
0, 1, 2, 3, 4, 5

Default: 0


title
string
title format
ex:

How to say %query% in %lang% (%i% out of %total%)

  • %query% will be replace by the query.
  • %lang% will be replace by the accent.
  • %i% will be replace by the current index.
  • %total% will be replace by the total result.

Default: the string above

Widget API

Functions:

Events:

The API fires events to notify your application of changes to the embedded widget. As noted in the previous section, you can subscribe to events by adding an event listener when constructing the YG.Widget object, and you can also use the addEventListener function.

The API will pass an event object as the sole argument to each of those functions. The event object properties are explained for each event below.

For an example of how to work with events, check out demo #1 which features an events viewer as part of the demo.

YG API

Developer Policy

  • If you expect your embedded widget to exceed 1 million daily impressions, you must contact us about your Youglish API access, as you may be subject to additional terms.
  • You must ensure that an end user is provided with clear and comprehensive information about, and consents to, the storing and accessing of cookies or other information on the end user’s device where providing such information and obtaining such consent is required by law.
  • If you operate a service targeted at children under 13, you must activate the Restricted Mode in the customization options.