# Adding Lip-Sync to your Character

## Lip Sync System

Convai sends Visemes or Blend Shape Frame from back-end depending upon the face model the developer chooses to use and when returned Convai SDK out of the box extracts and parses it and provides it to the **`Convai LipSync Component`**, after which the component relies on the **`SkinMeshRenderer`**'s **`Blendshape Effectors`** and **`Bone Effectors`** to give Convai powered NPC's realistic lipsync.

### Components of LipSync System

#### Viseme Effector List

This is where the developer will tell the Convai SDK, which index of Blendshape Array will be effector how much from which value. To better explain its working let's understand it with a diagram.

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2F3Lyr3bIpQix1K9L4bpuQ%2FVisemeSkimEffector.png?alt=media&#x26;token=c1230ba5-d157-4128-b09c-757b2cccf66e" alt=""><figcaption></figcaption></figure>

Here, it is saying that whatever value is coming from the server will affect Blendshape at the 116th index by 0.2 multipliers and Blendshape at the 114th index by 0.5 multipliers. The engine representation of this would look something like this.

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fys7A1dxsVEOrWP2uwcpE%2FScreenshot%202024-08-23%20123918.png?alt=media&#x26;token=0f195ad8-d674-4a53-a689-c01b0d217747" alt=""><figcaption></figcaption></figure>

So, you can make your own Effector list or use one of the many that we ship in the SDK.

**How to Create your own Viseme Effector List**

Right click inside project panel and head over to **`Create > Convai > Expression > Viseme Skin Effector`** which will create a **Viseme Effector List Scriptable Object** and now you can define your own values.

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FTUEtD5IkuEoRPvCKXiPb%2FUntitled.png?alt=media&#x26;token=72feddff-2238-4f28-86ad-d2df79db315b" alt=""><figcaption></figcaption></figure>

#### Viseme Bone Effector List

This is where developer will tell the Convai SDK, how much each value coming from the server will affect the rotation of the bone. To better explain its working let's understand it with a diagram.&#x20;

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FT25yABPucOUQPfChwH9J%2Funtiteld.png?alt=media&#x26;token=035905a1-705f-46bf-b8a0-b6fe7d2cef42" alt=""><figcaption></figcaption></figure>

Here, bone's rotation will be affected by the values coming from the server multiplied by the values in effects. For example, for TH the value will affect the bone's rotation by a 0.2 multiplier and etc. The engine representation of this would look something like this.

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FB0DSJrzWKhWPFk6Fr1Tf%2Fimage.png?alt=media&#x26;token=c2b52e42-83f9-4ea3-a155-d4d3aa943cef" alt=""><figcaption></figcaption></figure>

So, you can make your own Bone Effector list or use one of the many that we ship in the SDK.

We use this formula to calculate the rotation

```csharp
UpdateJawBoneRotation(
new Vector3(
        0.0f, 
        0.0f, 
        -90.0f - CalculateBoneEffect(FacialExpressionData.JawBoneEffector) * 30f
    )
);
UpdateTongueBoneRotation(
new Vector3(
        0.0f,
        0.0f,
        CalculateBoneEffect(FacialExpressionData.TongueBoneEffector) * 80f - 5f
    )
);
```

**How to Create Your Own Viseme Bone Effector List**

Right click inside the project panel and head over to **`Create > Convai > Expression > Viseme Bone Effector`** which will create a **Viseme Bone Effector List Scriptable Object** and now you can define your own values.

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FhRgsFBjfFo1hsOeFty2q%2FScreenshot%202024-08-23%20165836.png?alt=media&#x26;token=5d48bf40-3980-4271-8f92-a1bf859830f4" alt=""><figcaption></figcaption></figure>

#### Convai Lipsync Component

When you attach this component to your Convai Character, you will see something like this. &#x20;

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FcMNnFnkYC7G39jgci8Ba%2FScreenshot%202024-08-23%20170102.png?alt=media&#x26;token=ed8b5c1b-1631-429d-a8a9-2a4baad9a72e" alt=""><figcaption></figcaption></figure>

Let's learn what these learns are

1. Facial Expression Data
   1. Head | Teeth | Tongue
      1. Renderer: Skin Mesh Renderer which corresponds to that specified part of the body
      2. Viseme Effectors List: How the SkinMeshRenderer's Blendshape will be affected by values coming from server.
   2. Jaw | Tongue Bone Effector
      1. How much of Bone's rotation will be affected by values coming from server?
   3. Jaw | Tongue Bone
      1. Reference to the bone which controls jaw and tongue respectively
2. Weight Blending Power
   1. Percentage to interpolate between two frames in late update.
3. Character Emotions
   1. Learn More about Character Emotions here [character-emotion](https://docs.convai.com/api-docs/plugins-and-integrations/unity-plugin/utilities/character-emotion "mention")

### Steps to add Lipsync to your Convai Character

{% tabs %}
{% tab title=" Using Convai Add Component Button" %}

1. Select you Convai Powered Character in the hierarchy.
2. In the inspector panel search for ConvaiNPC component, there you will see Add Component Button.
3. Click on it and select Convai Lipsync Component and click on apply

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FSYAH84aZtqAqyrQ6xxsT%2FScreenshot%202024-08-23%20175552.png?alt=media&#x26;token=88dc97da-4f1c-4495-90be-7485a0abe93c" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Using Unity Add Component Button " %}

1. Select you Convai Powered Character in the hierarchy.
2. Click on Add Component
3. Search for Convai Lipsync
4. Select Convai Lipsync component

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FHiwAjGeWgurbrSDNRov5%2FScreenshot%202024-08-23%20180619.png?alt=media&#x26;token=be1fb34e-9509-450f-ba1c-d7724d74794a" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

Now you can configure the Component according to your custom configuration or use one of the many Presets Convai ships with the SDK

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FWcObDavtAdtbWKQijq9U%2FScreenshot%202024-08-23%20181343.png?alt=media&#x26;token=0a9fefe1-d595-477e-ad28-f4e437a48f10" alt=""><figcaption></figcaption></figure>

Now your lipsync component would be ready to use in your application.
