YouGlish Web APIs and Embeddable Control

https://youglish.com/api/doc/
Admin
This project provides documentation for YouGlish's Web APIs and embeddable controls, including a...
Tokens:11,654
Snippets:122
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Embedding and Controlling YouGlish Widget

Source: https://youglish.com/api/doc/js-api

This example demonstrates how to embed a YouGlish widget, search for a term, and control playback using the Javascript API. It includes setup, event handling for fetch completion, video changes, and caption consumption.

```APIDOC
## Javascript API Reference

The YouGlish Javascript 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 English tracks containing 'courage', and plays each track 3 times before moving to the next one.
```html
<!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: {
            'onFetchDone': onFetchDone,
            'onVideoChange': onVideoChange,
            'onCaptionConsumed': onCaptionConsumed
          }          
        });
        // 4. process the query
        widget.fetch("courage","english");
      }

     
      var views = 0, curTrack = 0, totalTracks = 0;
    
      // 5. The API will call this method when the search is done
      function onFetchDone(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>
```
```

--------------------------------

### Widget Initialization and Usage

Source: https://youglish.com/api/doc/demos/widget-and-api

This section covers how to get an instance of the YouGlish widget and how to use its core functionalities like fetching content and managing the widget's state.

```APIDOC
## Widget API

### Description
Provides methods to interact with the YouGlish widget.

### Methods

#### `YG.getWidget(widgetId)`

- **Description**: Retrieves an instance of the YouGlish widget.
- **Parameters**:
  - `widgetId` (string) - Required - The ID of the widget element.
- **Returns**: A widget instance or null if not found.

#### `widget.fetch(text, language)`

- **Description**: Fetches and displays videos for the given text and language.
- **Parameters**:
  - `text` (string) - Required - The text to search for.
  - `language` (string) - Required - The language to search in (e.g., "english").

#### `widget.pause()`

- **Description**: Pauses the currently playing video in the widget.

#### `widget.close()`

- **Description**: Closes the widget and stops any playback.

#### `widget.addEventListener(eventType, handler)`

- **Description**: Adds an event listener to the widget.
- **Parameters**:
  - `eventType` (string) - Required - The type of event to listen for (e.g., "onError").
  - `handler` (function) - Required - The callback function to execute when the event occurs.

### Error Handling

- **`YG.Error.OUTDATED_BROWSER`**: Indicates that the browser is outdated.
- **`YG.Error.TIMEOUT`**: Indicates that the request to YouGlish timed out.
```

--------------------------------

### widget.fetch

Source: https://youglish.com/api/doc/js-api

Processes a search query and loads the first track. The video starts playing automatically unless autoStart is set to 0.

```APIDOC
## widget.fetch(query: String, lang: String, accent?: String)

### Description
Processes the query and load the first track. The video will start playing automatically unless `autoStart` is set to 0.

### Parameters
#### Path Parameters
- **query** (String) - Required - Query to search for
- **lang** (String) - Required - Audio language. Supported values include: Arabic, Chinese, Dutch, English, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Persian, Polish, Portuguese, Romanian, Russian, Spanish, Swedish, Thai, Turkish, Ukrainian, Vietnamese, Sign Languages.
- **accent** (String) - Optional - Audio accent. Specific values depend on the selected language. See documentation for detailed accent codes per language.

### Request Example
```
widget.fetch("big house", "english")
widget.fetch("big house", "english", "uk")
```
```

--------------------------------

### Example: Embedding and Interacting with a YouGlish Widget

Source: https://youglish.com/api/doc/js-api

This example demonstrates how to embed a YouGlish widget into an HTML page and interact with it using the JavaScript API. It includes waiting for the API to be ready before retrieving the widget object and performing a search.

```html
<html>
  <body>
    <!-- Widget added by copy/paste a widget code (via Widget Builder) -->
    <a id="yg-widget-0" class="youglish-widget" data-components="243" 
    data-bkg-color="FFFFFF" data-link-color="337AB7" data-ttl-color="555555" data-cap-color="6495BF" 
    data-marker-color="FFFF00" data-cap-size="40" data-toggle-ui="0"  
    data-scroll="inner" href="https://youglish.com">Visit YouGlish.com</a>
    <script async src="https://youglish.com/public/emb/widget.js" charset="utf-8"></script>
    
    <!-- Interact with the widget -->
    <script>
      var widget;
      <!-- Wait for YG library to be loaded -->
      function onYouglishAPIReady() {
        <!-- retrieve the widget object-->
        widget = YG.getWidget("yg-widget-0");
        <!-- use the API...-->
        widget.search("welcome");
      }
    </script>
  </body>
</html>
  

```

--------------------------------

### Fetch Video by Query and Language

Source: https://youglish.com/api/doc/js-api

Use this function to search for and load the first video matching your query and specified language. The video will start playing automatically unless autoStart is set to 0.

```javascript
widget.fetch("big house", "english")
```

```javascript
widget.fetch("big house", "english", "uk")
```

--------------------------------

### Embed and Control YouGlish Widget with JavaScript

Source: https://youglish.com/api/doc/js-api

This example demonstrates how to embed a YouGlish widget, configure its components, and handle playback events. Ensure the `onYouglishAPIReady` function is implemented to initialize the widget after the API code has loaded.

```html
<!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: {
            'onFetchDone': onFetchDone,
            'onVideoChange': onVideoChange,
            'onCaptionConsumed': onCaptionConsumed
          }          
        });
        // 4. process the query
        widget.fetch("courage","english");
      }

     
      var views = 0, curTrack = 0, totalTracks = 0;
    
      // 5. The API will call this method when the search is done
      function onFetchDone(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>

```

--------------------------------

### Handle Video Change Event

Source: https://youglish.com/api/doc/js-api

Implement this function to get information about the currently playing track, such as the video ID or its position in the search results. This event fires when a new track is loaded.

```javascript
function onVideoChange(event){
  		var youTubeVideo  = event.video;  
  		var resultNumber = event.trackNumber;
  	}
  	
							

```

--------------------------------

### Get Player Speed Rate

Source: https://youglish.com/api/doc/js-api

Retrieves the current playback speed rate of the player. Speed values can range from 0 to 2. The default speed is 1 (normal speed).

```javascript
widget.getSpeed():Number
```

--------------------------------

### widget.next()

Source: https://youglish.com/api/doc/js-api

Navigates to the next track in the playlist.

```APIDOC
## widget.next()

### Description
Move to the next track.

### Method
Void

### Endpoint
widget.next()
```

--------------------------------

### widget.previous()

Source: https://youglish.com/api/doc/js-api

Navigates to the previous track in the playlist.

```APIDOC
## widget.previous()

### Description
Move to the previous track.

### Method
Void

### Endpoint
widget.previous()
```

--------------------------------

### Configure Ad Locations and Display Ads

Source: https://youglish.com/api/doc/js-api

Use `setAdsLocation` to allow ads on specific locations. Implement `onYouglishDisplayAd` to render different ad types based on the ad location.

```javascript
	function onYouglishAPIReady(){
		...
		//allow ads on the bottom and right locations.
		widget.setAdsLocation(YG.AdLocations.BOTTOM | YG.AdLocations.RIGHT);
		...
	}
	
	
	//display Adsense ad on the bottom and a dummy HTML ad on the right.
	function onYouglishDisplayAd(id, location, parent, sugWidth){
		if (location === YG.AdLocations.BOTTOM){
			//responsive ad require to setup the width of the parent. Lets use the suggested width. 
			parent.style.width =  sugWidth + "px";
			//call adsense
			parent.innerHTML = "<ins class='adsbygoogle' style='display:block' data-ad-client='ca-pub-11111' data-ad-slot='22222' data-ad-format='auto'></ins>";
			(adsbygoogle = window.adsbygoogle || []).push({});
		}	
		else if (location === YG.AdLocations.RIGHT){
			//just a simple div block. Ignore the sugWidth since the div has a 200px width.
			parent.innerHTML = "<div style='color:white;background-color:#6e94ce;display: table;min-height:80px;height:100%;width: 200px;'><div style='display: table-cell;text-align: center;vertical-align: middle;'>Partner Right Ad</div></div>";
		}
	}
```

--------------------------------

### widget.play

Source: https://youglish.com/api/doc/js-api

Plays the currently loaded video.

```APIDOC
## widget.play()

### Description
Play the currently loaded video.

### Method
`widget.play():Void`
```

--------------------------------

### Loading a YouGlish Widget

Source: https://youglish.com/api/doc/js-api

This snippet demonstrates how to initialize a YouGlish widget within your HTML page. The `onYouglishAPIReady` function is called once the API is loaded, allowing you to create a `YG.Widget` instance. The constructor takes an element ID and an options object to configure the widget's appearance and behavior.

```APIDOC
## 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:

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

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+16 = 21
Component | ID  
---|---
Search box | `1`  
Accent panel | `2`  
Title | `4`  
Caption | `8`  
Speed controls | `16`  
Toggle UI (deprecated) | `32`  
Control Buttons | `64`  
Dictionary support | `128`  
Near by panel | `256`  
Phonetic panel | `512`  
Draggable | `1024`  
Minimizable | `2048`  
Closable | `4096`  
All Captions | `8192`  
Toggle light | `16384`  
Toggle tumbnails | `32768`  
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`
* * *
`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`
```

--------------------------------

### onYouglishDisplayAd

Source: https://youglish.com/api/doc/js-api

A callback function that handles the display of different ad types based on the specified location and suggested width.

```APIDOC
## onYouglishDisplayAd

### Description
Callback function to display ads based on location. It handles AdSense ads and custom partner ads.

### Method
`onYouglishDisplayAd(id: string, location: number, parent: HTMLElement, sugWidth: number)`

### Parameters
#### Path Parameters
- **id** (string) - Required - The widget ID.
- **location** (number) - Required - The location of the ad unit, typically a value from `YG.AdLocations`.
- **parent** (HTML Element) - Required - The parent HTML element where the ad will be rendered.
- **sugWidth** (number) - Required - The suggested width for the ad unit, particularly useful for responsive ads.
```

--------------------------------

### onYouglishDisplayAd

Source: https://youglish.com/api/doc/js-api

Implement this callback method to display an ad unit at a specific location. It is called for each location defined via setAdsLocation.

```APIDOC
## onYouglishDisplayAd(id:String, location:Number, parent:HTMLElement, suggestedWidth:Number):Void

### Description
Implement this method to display ad unit at specific location. This callback method will be called for each location defined via setAdsLocation call.
```

--------------------------------

### Set Partner Key

Source: https://youglish.com/api/doc/js-api

Call `setParnterKey` with your unique key provided by YouGlish to authenticate your integration.

```javascript
YG.setParnterKey(key:String)
```

--------------------------------

### Initialize YouGlish Widget

Source: https://youglish.com/api/doc/js-api

This function is called once the YouGlish API's JavaScript code has loaded. It demonstrates how to create a new YG.Widget instance and fetch initial content.

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

```

--------------------------------

### Widget API Functions

Source: https://youglish.com/api/doc/js-api

This section details the available functions for interacting with the YouGlish widget after it has been initialized.

```APIDOC
### Widget API
#### Functions:
  * `widget.fetch(query:String, lang:String, accent:String):Void`
```

--------------------------------

### onPlayerReady

Source: https://youglish.com/api/doc/js-api

This event fires whenever a player has finished loading and is ready to begin receiving API calls. Implement this function if you want to automatically execute certain operations, such as playing the video as soon as the player is ready.

```APIDOC
## onPlayerReady(event)

### Description
This event fires whenever a player has finished loading and is ready to begin receiving API calls. Your application should implement this function if you want to automatically execute certain operations, such as playing the video as soon as the player is ready.
```

--------------------------------

### onVideoChange

Source: https://youglish.com/api/doc/js-api

This event fires whenever a widget loads a new track, typically when you call the widget's `next` or `previous` functions. Your application should implement this function if you need information on the track being played, like the video ID or the track number in the search result.

```APIDOC
## onVideoChange

### Description
This event fires whenever a widget loads a new track, typically when you call the widget's `next` or `previous` functions. Your application should implement this function if you need information on the track being played, like the video ID or the track number in the search result.

### Event Properties

- **video** (String) - Youtube video ID.
- **trackNumber** (Number) - Track position out of total tracks found. Any number between 0 and the total tracks found.

### Example
```javascript
function onVideoChange(event){
  	var youTubeVideo  = event.video; 
  	var resultNumber = event.trackNumber;
}
```
```

--------------------------------

### widget.move(seconds)

Source: https://youglish.com/api/doc/js-api

Moves the video cursor forward or backward by a specified number of seconds.

```APIDOC
## widget.move(seconds)

### Description
Moves the video cursor forward or backward by a specified number of seconds.

### Parameters
#### Path Parameters
- **seconds** (number) - Required - The number of seconds to move the cursor. A negative number will cause the cursor to move backward.

### Example
```javascript
widget.move(-5)
```
```

--------------------------------

### widget.pause

Source: https://youglish.com/api/doc/js-api

Pauses the player.

```APIDOC
## widget.pause()

### Description
Pauses the player.

### Method
`widget.pause():Void`
```

--------------------------------

### widget.replay

Source: https://youglish.com/api/doc/js-api

Replays the search result track.

```APIDOC
## widget.replay()

### Description
Replay the search result track.

### Method
`widget.replay():Void`
```

--------------------------------

### Set Widget Ad Locations

Source: https://youglish.com/api/doc/js-api

Configures the ad locations for the widget. Use bitwise OR to combine multiple locations.

```javascript
//display ads on LEFT and BOTTOM location:
widget.setAdsLocation(YG.AdLocations.LEFT|YG.AdLocations.BOTTOM);
```

--------------------------------

### widget.move

Source: https://youglish.com/api/doc/js-api

Moves the video playback forward or backward by a specified number of seconds.

```APIDOC
## widget.move(seconds:Number)

### Description
Move forward/backward in the video.

### Parameters
#### Path Parameters
- **seconds** (Number) - Required - The number of seconds to move forward (positive value) or backward (negative value).

### Method
`widget.move(seconds:Number):Void`
```

--------------------------------

### widget.setAdsLocation(locations)

Source: https://youglish.com/api/doc/js-api

Sets the ad locations for the Youglish widget.

```APIDOC
## widget.setAdsLocation(locations)

### Description
Set ad locations for this widget.

### Parameters
#### Path Parameters
- **locations** (number) - Required - Specifies the allowed ad locations. Possible values include YG.AdLocations.RIGHT, YG.AdLocations.LEFT, YG.AdLocations.BOTTOM, YG.AdLocations.TOP.

### Example
```javascript
//display ads on LEFT and BOTTOM location:
widget.setAdsLocation(YG.AdLocations.LEFT|YG.AdLocations.BOTTOM);
```
```

--------------------------------

### widget.setSpeed

Source: https://youglish.com/api/doc/js-api

Sets the suggested playback speed rate for the player.

```APIDOC
## widget.setSpeed(suggestedRate:Number)

### Description
This function sets the suggested speed rate of the player. Speed values may include values between 0 and 2, like 0.25, 0.5, 1, etc. A speed rate of 1 indicates that the video is playing at normal speed. Calling this function does not guarantee that the speed value will actually change. However, if the speed value does change, the onSpeedChange event will fire, and your code should respond to the event rather than the fact that it called the setSpeed function.

### Parameters
#### Path Parameters
- **suggestedRate** (Number) - Required - The desired playback speed rate (e.g., 0.25, 0.5, 1, 1.5, 2).

### Method
`widget.setSpeed(suggestedRate:Number):Void`
```

--------------------------------

### Handle Fetch Completion Event

Source: https://youglish.com/api/doc/js-api

Implement this function to receive search result information after a query is processed. It provides details like the total number of results and the query itself.

```javascript
function onFetchDone(event){
  		var query  = event.query; 
  		var lang = event.lang; 
  		var accent = event.accent; 
  		var totalResult = event.totalResult;
  	}
  	
							

```

--------------------------------

### Fetch Video Content

Source: https://youglish.com/api/doc/js-api

Use the fetch function to retrieve video content based on a query and language. This is a core function for populating the widget.

```javascript
widget.fetch(query:String, lang:String, accent:String):Void
```

--------------------------------

### onFetchDone

Source: https://youglish.com/api/doc/js-api

This event fires whenever a widget has finished processing a query. Your application should implement this function if you need search result information like the total number of results found or the actual search query.

```APIDOC
## onFetchDone

### Description
This event fires whenever a widget has finished processing a query. Your application should implement this function if you need search result information like the total number of results found or the actual search query.

### Event Properties

- **query** (String) - The query that was processed.
- **lang** (String) - The language used. See fetch API for all supported languages.
- **accent** (String) - The accent used. See fetch API for all supported accents.
- **totalResult** (number) - Total results found.

### Example
```javascript
function onFetchDone(event){
  	var query  = event.query; 
  	var lang = event.lang;
  	var accent = event.accent;
  	var totalResult = event.totalResult;
}
```
```

--------------------------------

### onCaptionChange

Source: https://youglish.com/api/doc/js-api

This event fires when the caption changes.

```APIDOC
## onCaptionChange

### Description
This event fires when the caption changes.

### Example
```javascript
function onCaptionChange(event) {
  // Handle caption change event
}
```
```

--------------------------------

### onSpeedChange

Source: https://youglish.com/api/doc/js-api

This event fires when the playback speed of the player changes.

```APIDOC
## onSpeedChange(event)

### Description
This event fires when the playback speed of the player changes.
```

--------------------------------

### Play Video Playback

Source: https://youglish.com/api/doc/js-api

Resumes playback of the currently loaded video.

```javascript
widget.play():Void
```

--------------------------------

### YG.setParnterKey

Source: https://youglish.com/api/doc/js-api

Sets the partner key for API authentication. The key is provided by YouGlish to uniquely identify each partner.

```APIDOC
## YG.setParnterKey(key:String)

### Description
Sets the partner key for API authentication.

### Method
JavaScript

### Parameters
#### Path Parameters
- **key** (String) - Required - The key is provided by YouGlish to the Partner in order to uniquely identify each Partner.
```

--------------------------------

### YG.setParnterKey

Source: https://youglish.com/api/doc/js-api

Sets your unique partner key provided by YouGlish. This is essential for API authentication and tracking.

```APIDOC
## YG.setParnterKey

### Description
Set your partner key, provided by YouGlish.

### Method
`YG.setParnterKey(key: String)`

### Parameters
#### Path Parameters
- **key** (String) - Required - Your unique partner key.
```

--------------------------------

### widget.getSpeed

Source: https://youglish.com/api/doc/js-api

Retrieves the current playback speed rate of the player.

```APIDOC
## widget.getSpeed()

### Description
This function retrieves the speed rate of the player. Speed values may include values between 0 and 2, like 0.25, 0.5, 1, etc. The default speed rate is 1, which indicates that the video is playing at normal speed.

### Method
`widget.getSpeed():Number`
```

--------------------------------

### Replay Current Track

Source: https://youglish.com/api/doc/js-api

Restarts playback of the current search result track.

```javascript
widget.replay():Void
```

--------------------------------

### Set Ad Width Ratio with YG.setAdWidthRatio

Source: https://youglish.com/api/doc/js-api

Use YG.setAdWidthRatio to adjust the width of responsive ads relative to the widget's total width. The ratio should be a number between 10 and 50.

```javascript
YG.setAdWidthRatio(ratio:Number)
```

--------------------------------

### Set Player Speed Rate

Source: https://youglish.com/api/doc/js-api

Sets the suggested playback speed rate for the player. While this function attempts to change the speed, the onSpeedChange event should be monitored for confirmation. Speed values range from 0 to 2.

```javascript
widget.setSpeed(suggestedRate:Number):Void
```

--------------------------------

### HTML Structure for YouGlish Widget

Source: https://youglish.com/api/doc/demos/widget-and-api

This HTML code sets up the basic structure for embedding the YouGlish widget, including necessary CSS and JavaScript includes. It also defines clickable elements that trigger widget actions.

```html
<!DOCTYPE html>
<html>
<head>
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
</head>
<body>


<style>
.ygParent{
	position:fixed;
	top: 10%;
	left: 30%;
	width:340px;
	display:none;
}

.playable {
	cursor:pointer;
	font-size:40px;
}

</style>

<script>
var widget;

$('body').on('click', '.playable', function(event){
	if (widget){
		var text = $(this).html();
		widget.fetch(text, "english");
 		$(".ygParent").show();
	}
	else {
		alert("YG is unavailable. Try again later");
	}
	
});

function onYouglishAPIReady(){
	widget = YG.getWidget("yg-widget-0");
	if (widget){
		widget.addEventListener("onError", errorHdler);
	}
}

function errorHdler(event){
	switch(event.code){
		case YG.Error.OUTDATED_BROWSER: 
			alert("YG can't be run. Upgrade your browser and try again!");
			break;
		case YG.Error.TIMEOUT: 
	 		$(".ygParent").hide();
	 		if (widget) widget.close();
			alert("YG is unavailable. Try again later.");
			break;
	}
}
</script>

<ul>
	<li><span class='playable'> take </span>
	<li><span class='playable'> take off </span>
	<li><span class='playable'> take away </span>
	<li><span class='playable'> took away </span>
	<li><span class='playable'> it's time to go </span>
	<li><span class='playable'> Boston Massachusetts </span>
	<li><span class='playable'> take #barackobama </span>
</ul>

<div class='ygParent'>
	<a id="yg-widget-0" class="youglish-widget" data-components="7423" data-delay-load="1" data-toggle-ui="1"  href="https://youglish.com">Visit YouGlish.com</a>
</div>


<script async src="https://youglish.com/public/emb/widget.js" charset="utf-8"></script>

</body>
</html>
```

--------------------------------

### widget.addEventListener(event, listener)

Source: https://youglish.com/api/doc/js-api

Adds a listener function for a specified event. The listener is a string representing the function to execute when the event fires.

```APIDOC
## widget.addEventListener(event, listener)

### Description
Adds a listener function for the specified event. The events section below identifies the different events that the widget might fire. The listener is a string that specifies the function that will execute when the specified event fires.

### Parameters
#### Path Parameters
- **event** (String) - Required - The event to listen for. Possible values: onFetchDone, onVideoChange, onCaptionChange, onCaptionConsumed, onPlayerReady, onPlayerStateChange, onSpeedChange, onError.
- **listener** (String) - Required - The function name.

### Endpoint
widget.addEventListener(event, listener)
```

--------------------------------

### Set Ads Location

Source: https://youglish.com/api/doc/js-api

Allows ads to be displayed in specified locations. Use bitwise OR to combine multiple locations.

```javascript
//Allow ads on LEFT and BOTTOM location:
widget.setAdsLocation(YG.AdLocations.LEFT|YG.AdLocations.BOTTOM);
```

--------------------------------

### onPlayerStateChange

Source: https://youglish.com/api/doc/js-api

This event fires whenever the player's state changes. The state property of the event object passed to your listener function specifies an integer corresponding to the new player state.

```APIDOC
## onPlayerStateChange(event)

### Description
This event fires whenever the player's state changes. The state property of the event object that the API passes to your event listener function will specify an integer that corresponds to the new player state.

### Event Properties

#### state (number)
- **Description**: The new player state.
- **Values**: Possible values are:
    * `YG.PlayerState.UNSTARTED (-1)`
    * `YG.PlayerState.ENDED (0)`
    * `YG.PlayerState.PLAYING (1)`
    * `YG.PlayerState.PAUSED (2)`
    * `YG.PlayerState.BUFFERING (3)`
    * `YG.PlayerState.CUED (5)`
```

--------------------------------

### Event: onPlayerSpeedChange

Source: https://youglish.com/api/doc/js-api

This event fires whenever the player speed rate changes. The application should respond to this event as the speed rate does not automatically change when setSpeed is called.

```APIDOC
## Event: onPlayerSpeedChange

### Description
This event fires whenever the player speed rate changes. For example, if you call the setSpeed(suggestedRate) function, this event will fire if the speed rate actually changes. Your application should respond to the event and should not assume that the speed rate will automatically change when the setSpeed(suggestedRate) function is called.

### Event Properties

#### speed (Number)
- **Meaning**: The new speed rate.
```

--------------------------------

### Move Widget Cursor

Source: https://youglish.com/api/doc/js-api

Moves the widget's cursor forward or backward by a specified number of seconds. Negative values move the cursor backward.

```javascript
widget.move(-5)
```

--------------------------------

### widget.setAdsLocation

Source: https://youglish.com/api/doc/js-api

Sets the allowed ad locations for the Youglish widget. This method takes a bitwise combination of ad location constants.

```APIDOC
## widget.setAdsLocation(locations:Number):Void

### Description
Set ad locations for this widget.

### Parameters

#### locations (number) - Required
- **Meaning**: Ads locations allowed.
- **Values**: `YG.AdLocations.RIGHT | YG.AdLocations.LEFT | YG.AdLocations.BOTTOM | YG.AdLocations.TOP`

### Example
```javascript
//Allow ads on LEFT and BOTTOM location:
widget.setAdsLocation(YG.AdLocations.LEFT | YG.AdLocations.BOTTOM);
```
```

--------------------------------

### widget.setAdsLocation

Source: https://youglish.com/api/doc/js-api

Allows you to specify the locations where ads should be displayed. This method accepts a bitwise OR of `YG.AdLocations` values to enable multiple ad placements.

```APIDOC
## widget.setAdsLocation

### Description
Sets the allowed locations for ad units.

### Method
`widget.setAdsLocation(locations: number)`

### Parameters
#### Path Parameters
- **locations** (number) - Required - A bitwise combination of `YG.AdLocations` values (e.g., `YG.AdLocations.BOTTOM | YG.AdLocations.RIGHT`).

### Example
```javascript
//allow ads on the bottom and right locations.
widget.setAdsLocation(YG.AdLocations.BOTTOM | YG.AdLocations.RIGHT);
```
```

--------------------------------

### YG.setAdWidthRatio

Source: https://youglish.com/api/doc/js-api

Sets the width ratio for ads relative to the widget's width. This is used to calculate the size of responsive ads.

```APIDOC
## YG.setAdWidthRatio(ratio:Number)

### Description
Set width ad ratio relative to the widget width size.

### Parameters
#### Query Parameters
- **ratio** (number) - Required - Width ratio, used to calculate the width of responsive left or right ads. Values between 10 and 50. Default: 35%
```

--------------------------------

### widget.close()

Source: https://youglish.com/api/doc/js-api

Closes the Youglish widget.

```APIDOC
## widget.close()

### Description
Close the widget.

### Method
Void

### Endpoint
widget.close()
```

--------------------------------

### YG.setAdWidthRatio

Source: https://youglish.com/api/doc/js-api

Sets the width ratio for ads relative to the widget's width. This is used for calculating the size of responsive ads.

```APIDOC
## YG.setAdWidthRatio(ratio:Number)

### Description
Set width ad ratio relative to the widget width size.

### Method
JavaScript

### Parameters
#### Path Parameters
- **ratio** (number) - Required - Width ratio, used to calculate the width of responsive left or right ads. Values between 10 and 50. Default: 35%
```

--------------------------------

### Basic YouGlish Widget Embedding

Source: https://youglish.com/api/doc/widget

This code snippet embeds a YouGlish widget into your website. Customize parameters like query, language, components, and background color as needed.

```html
<a id="yg-widget-0" class="youglish-widget" data-query="great%20power" data-lang="english" data-components="8415" data-bkg-color="theme_light"  rel="nofollow" href="https://youglish.com">Visit YouGlish.com</a> <script async src="https://youglish.com/public/emb/widget.js" charset="utf-8"></script>
```

--------------------------------

### onCaptionConsumed

Source: https://youglish.com/api/doc/js-api

This event fires whenever the widget caption has been entirely voiced, typically triggered before the 'onCaptionChange' event. It provides the caption ID.

```APIDOC
## onCaptionConsumed(event)

### Description
This event fires whenever the widget caption has been entirely voiced, typically triggered before the 'onCaptionChange' event.

### Event Properties

#### id (Number)
- **Description**: The caption ID.
```

--------------------------------

### YG.getWidget

Source: https://youglish.com/api/doc/js-api

Retrieves a Widget object by its element ID. This is useful for interacting with widgets created via the Widget Builder.

```APIDOC
## YG.getWidget(id:String):Widget

### Description
Retrieve a Widget object by element id. This is useful when creating widgets using the Widget Builder.

### Method
JavaScript

### Parameters
#### Path Parameters
- **id** (String) - Required - The element ID of the widget.

### Return Value
Widget object.

### Example
```html
<html>
  <body>
    <a id="yg-widget-0" class="youglish-widget" data-components="243" 
    data-bkg-color="FFFFFF" data-link-color="337AB7" data-ttl-color="555555" data-cap-color="6495BF" 
    data-marker-color="FFFF00" data-cap-size="40" data-toggle-ui="0"  
    data-scroll="inner" href="https://youglish.com">Visit YouGlish.com</a>
    <script async src="https://youglish.com/public/emb/widget.js" charset="utf-8"></script>
    
    <script>
      var widget;
      function onYouglishAPIReady() {
        widget = YG.getWidget("yg-widget-0");
        widget.search("welcome");
      }
    </script>
  </body>
</html>
```
```

--------------------------------

### Add Event Listener to Widget

Source: https://youglish.com/api/doc/js-api

Attaches a listener function to a specific widget event. The listener is a string representing the function to be called when the event fires.

```javascript
widget.addEventListener(event, listener)
```

--------------------------------

### onCaptionChange

Source: https://youglish.com/api/doc/js-api

This event fires whenever the widget caption changes. Implement this function if you need information on the current caption. The caption string can highlight search terms between '[[[' and ']]]'. The caption ID typically increments by one after each caption change when playing a video continuously.

```APIDOC
## onCaptionChange(event)

### Description
This event fires whenever the widget caption changes. Your application should implement this function if you need information on the current caption.

### Event Properties

#### caption (String)
- **Description**: The caption string. Search terms in the caption will appear between "[[[" and "]]]". Useful when you need to highlight the query.

#### id (Number)
- **Description**: The caption ID. When playing a video continuously, the id value will typically increment by one after each caption change.
```

--------------------------------

### Pause Video Playback

Source: https://youglish.com/api/doc/js-api

Pauses the currently playing video.

```javascript
widget.pause():Void
```

--------------------------------

### Move Playback Position

Source: https://youglish.com/api/doc/js-api

Advances or rewinds the video playback by a specified number of seconds.

```javascript
widget.move(seconds:Number):Void
```

--------------------------------

### Event: onError

Source: https://youglish.com/api/doc/js-api

This event fires whenever an error occurs. The event object contains a 'code' property specifying the type of error.

```APIDOC
## Event: onError

### Description
This event fires whenever something goes wrong. That object's code property will specify an integer that identifies the type of error that occurred.

### Event Properties

#### code (number)
- **Meaning**: An error code.
- **Values**: Possible values are:
  * `YG.Error.PLAYER (1)`
  * `YG.Error.OUTDATED_BROWSER (2)`
  * `YG.Error.TIMEOUT (3)`
```

--------------------------------

### Retrieve Widget Object with YG.getWidget

Source: https://youglish.com/api/doc/js-api

Retrieve a Widget object using its element ID. This is particularly useful when integrating widgets built with the Widget Builder.

```javascript
YG.getWidget(id:String):Widget
```

--------------------------------

### widget.removeEventListener(event, listener)

Source: https://youglish.com/api/doc/js-api

Removes a listener function for a specified event.

```APIDOC
## widget.removeEventListener(event, listener)

### Description
Removes a listener function for the specified event.

### Method
Void

### Endpoint
widget.removeEventListener(event, listener)
```

--------------------------------

### Remove Event Listener from Widget

Source: https://youglish.com/api/doc/js-api

Detaches a previously added listener function for a specific widget event.

```javascript
widget.removeEventListener(event, listener)
```
Tokens:
Raw