Crystal LipSync Profile

CrystalLipSyncProfile is a ScriptableObject used to share lip-sync analysis tuning across multiple characters.

It lets you define one reusable profile for:

• Volume gate behavior

• Overall sensitivity

• Smoothing response (attack/release)

• Per-viseme multipliers

This is useful when several characters have similar voice traits and should behave consistently.

---

Create a Profile Asset

In Unity:

1. Open the Project window.

2. Right-click in your desired folder.

3. Select Create → Crystal LipSync → Lip Sync Profile.

Unity creates a LipSyncProfile asset (from CrystalLipSyncProfile).

---

Inspector Fields

Volume

• Volume Threshold (0.0001 to 0.1, default 0.005)

  • Minimum RMS level before visemes begin opening.

  • Lower values react to quieter audio; higher values keep mouth closed longer.

• Sensitivity (0.1 to 30, default 5)

  • Global gain applied to volume-to-viseme mapping.

  • Increase for quiet recordings, reduce for overly strong mouth motion.

Smoothing

• Smoothing Attack (1 to 80, default 30)

  • How quickly visemes rise when speech appears.

  • Higher values feel more responsive.

• Smoothing Release (1 to 40, default 15)

  • How quickly visemes fall back toward rest.

  • Higher values close faster between phonemes.

Per-Viseme Multipliers

• An array of 15 multipliers (one per viseme).

• Default is 1.0 for all entries.

• Values:

  • > 1.0 amplify that viseme

  • < 1.0 suppress that viseme

  • 1.0 leaves it unchanged

Viseme order:

SIL, PP, FF, TH, DD, KK, CH, SS, NN, RR, AA, E, I, O, U

---

How It Is Applied at Runtime

When a profile is assigned to CrystalLipSyncController:

1. Controller reads VolumeThreshold, Sensitivity, SmoothingAttack, and SmoothingRelease from the profile.

2. Analyzer computes viseme weights.

3. Each viseme weight is multiplied by profile.GetVisemeMultiplier(index).

If no profile is assigned, the controller uses its own local inspector settings and no profile multipliers.

---

API Reference

CrystalLipSyncProfile exposes:

• VolumeThreshold (read-only)

• Sensitivity (read-only)

• SmoothingAttack (read-only)

• SmoothingRelease (read-only)

• GetVisemeMultiplier(int visemeIndex)

GetVisemeMultiplier returns:

• The stored multiplier for valid indices

• 1.0 as a safe fallback when index is out of range or array state is invalid

---

Validation Behavior (OnValidate)

The profile automatically enforces the viseme multiplier array size to match VisemeConstants.VisemeCount (15).

• If the array is missing or wrong length, it is rebuilt.

• Existing values are preserved where possible.

• New or missing entries default to 1.0.

This keeps profiles stable if viseme array data is edited manually or serialized data changes.

---

Recommended Workflow

1. Tune one character until lip sync quality looks correct.

2. Save those values in a CrystalLipSyncProfile.

3. Assign the same profile to other similar characters.

4. Adjust only per-viseme multipliers for character-specific mouth shape differences.

---

Troubleshooting

Profile seems ignored

• Ensure CrystalLipSyncController has the profile assigned in Profile (Optional).

• If assigned at runtime, verify SetProfile(...) is called on the active controller instance.

Mouth movement too weak

• Lower Volume Threshold.

• Increase Sensitivity.

• Raise key vowel multipliers (AA, E, I, O, U).

Mouth movement too jittery

• Increase Smoothing Attack and/or Smoothing Release.

• Slightly raise Volume Threshold to reduce low-level noise activation.

One phoneme family looks exaggerated

• Reduce that viseme's multiplier toward 1.0.

• Rebalance neighboring visemes instead of globally lowering sensitivity.