Troubleshooting

The things that go wrong most often, and what to do about each. Symptom, cause, fix.

Start With the Console

FaceCue says what happened. Its messages start with [FaceCue] and a short headline, such as Speech Fallback FAILURE for Clip {intro_01} on Character {Akari}., followed by a paragraph that says why and what to change. The values from your project sit in braces, so the clip and the character are easy to find.

Most problems below have a message of their own, and the message is faster than this page. No message at all is informative too: it usually means FaceCue never saw the line.

The Mouth Does Not Move

Nothing in the Console

The character never heard the line. FaceCue follows the Audio Source that plays the character's voice, and a clip played through any other source goes unnoticed. So does a clip played with PlayOneShot, even on the right source: play voice lines with Play().

Fix: on the FaceCue Brain, under Setup ▸ Core References, check that Audio Source is the source your voice lines actually play through. Left empty, it uses an Audio Source on the same object.

For a line played from a Timeline, see A Timeline Line Does Not Drive the Face.

Speech Fallback FAILURE

No mode in the character's Fallback Chain could play the line, so it shows as an error, and the message gives the reason for each. The common ones:

The message says	Fix
This clip has no baked cues	Bake the clip and add it to a registry. See When a Clip Will Not Load
No Viseme Map is assigned	Assign one on the Speech driver, or set the character up with the OneClick Wizard
No Amplitude Rig Map is assigned	Assign one on the Speech driver, so a clip with no bake still moves the mouth
There are no Skinned Mesh Renderers under Character Root	Point Character Root on the Brain at the object that holds the character's meshes
The clip's audio can't be read	Set the clip's Load Type to Decompress On Load, or see Audio Import for the other options
It is turned off in the Fallback Chain	Turn that mode back on in the Fallback Chain, on the Speech driver

Viseme Map Missing or No Skinned Meshes Found

The character has nothing to move the mouth with. These fire once per character, at setup, rather than per line.

Fix: the same as the table above. The quickest route for a new character is to run the OneClick Wizard on it, which assigns every map in one pass.

The Mouth Moves, but Roughly

The character is playing a tier below the one you chose, almost always because the clip's cues were not found, and the Console says so with Speech Fallback Engaged. If it names Live Amplitude, the mouth is following loudness alone.

Fix: find out why the cues were not found. Cue Data Not Found names the clip and the places it looked, the first time it happens on a character, and its explanation says what to change. When a Clip Will Not Load is the checklist, in order.

An Emotion Takes Over the Mouth

The character speaks, but an emotion with a strong mouth, Angry the clearest, crowds the words so they are hard to read. The shipped emotions are authored to sit well on a speaking face, so this is usually one emotion rather than all of them.

Fix, whichever suits the scene:

• Play the emotion at a lower intensity while the character speaks.
• Tone down the mouth pieces evenly in the Face Rig Designer's Emotion channel, when emotions in general crowd the words on this character rather than one in particular.
• Set Lower Scope to Per Region on the FaceCue Resolver, under Composition ▸ Blend Usage. The emotion gives way across the whole mouth while the character speaks and comes back once the line ends. It is the quickest fix, at the cost of the emotion's mouth for the whole line.

For expressions you authored yourself, keep them off the blendshapes speech uses where the rig allows. See When the Character Speaks and Emotion and Speech on the Mouth.

Cue Files Went Missing

The Cue Registry window shows a banner counting missing cue files, and a clip that played yesterday falls back today. This happens when cue files are copied into a project without their .meta files, which gives them new identities the registry does not recognise.

Fix: press Relink Missing Cue Files in the banner. It finds each file again by its exact name. See Missing Cue Files & Relinking.

A Timeline Line Does Not Drive the Face

A voice line on a Timeline audio track needs a Director Watcher beside the Playable Director to reach the face, and the Audio Source the track is bound to has to be the character's own. A track bound to some other source is skipped without a message.

Fix, in order:

1. Is there a Director Watcher, and does its list hold this director? Its Auto-Setup Director(s) buttons fill it in. See The Director Watcher.
2. Is the audio track bound to the character's Audio Source, the same one set on its Brain?
3. Is the director nested inside another Timeline? Raise the watcher's nesting depth if a deeply nested character is not being driven.
4. Does the line have cues? A Phoneme Clip's Validate Cue Source checks its cue file or registry name.

DSP Clock Timeline in a Fixed-Rate Recording means a watched director was on DSP Clock while a recording moved the game on a frame at a time. The Timeline and its own sound come apart in a recording like that. Set the director's Update Method to Game Time and record again. See Recording a Timeline.

The Head Flickers or Fights the Animation

A head that flickers between FaceCue's pose and the animation's is almost always the bone hold switched off. Animations often write a bone only every few frames, and without the hold the pose alternates between the two.

Fix: on the Brain, under Animator Coexistence, turn Assert Bone Ownership back on. A look that ends in a jump wants a longer Handback Time, and a glance you animated that the character keeps overriding wants Step Aside. See What You Can Tune.

The Eyes Look Off-Centre

The eyes sit slightly wrong, or tilt as they turn. The Brain's Setup ▸ Eyes says so with a warning that an eye bone has no measured aim, or that the bones changed since they were measured.

Fix: run the Eyes driver's Auto Setup again, or Detect Which Way The Bones Face from its Steps menu, which measures the bones afresh. See Auto-Setup.

The Head Nods at an Angle

To nod the head on a stressed word, FaceCue has to know which way the head faces. Normally it knows that from the Eyes driver's setup.

When it does not, the Console says Measured Head Frame Missing, and the nod takes whatever pose the head is in at that moment as facing forward. If an animation has the head turned or tilted right then, the nod takes that on, and can dip at an angle rather than straight down.

Fix: run Auto Setup on the Eyes driver, which measures the head along with the eyes. For a character whose eyes are not set up, press Recapture Head Frame on the Prosody driver, under Setup ▸ Head, which measures it for the nod alone.

A Character Stops Moving

The face holds still, usually when the character goes off screen or far from the camera, and picks up again when it comes back. That is Visibility Freeze or Distance Rate Limiting at work. Visibility Freeze is on by default, so a character that stops when it goes off screen is usually it, doing its job. Distance Rate Limiting is off until someone turns it on.

Find out which. With the game running, open Current State at the foot of the Brain's Optimization section. Reason names what stopped the face: the visibility gate and the source it read, or the distance band and what the character was doing.

Fix, if it freezes when it should not: check Source under Optimization, which is how the character decides whether it is seen. A reflection or shadow camera, or a character whose animator is set to always animate, can each call for a different source. A character that has to keep moving while nobody sees it can have Visibility Freeze switched off. With Distance Rate Limiting on, the distance is counted through the camera's lens, so a wide-angle camera counts a character as farther away than it stands, and can reach a frozen band sooner. See Optimization.

A face that is still from the start, and never moves at all, may have been frozen by hand: check the Brain's Facial Timestep for a rate set to Frozen. The State row under Resolved Rate reads Frozen by author when it has.

The Face Moves in Steps

The face moves, but in visible steps rather than smoothly, as if it were running at a low frame rate.

FaceCue writes the face a set number of times a second, and Display Smoothing fills in between. Steps show when nothing is filling them.

Fix: on the Brain, under Smoothing, set Display Smoothing to Auto, since Off holds each write until the next. Under Clock Rate, check that Frame Drops has not been set to Off, which lets the motion step whenever the game falls behind. And if the Output Rate has been set very low, raise it. See Display Smoothing.

Live Viseme Does Not Work on Linux, in a Browser or on Apple Silicon

Live Viseme's recognizer has builds for 64-bit Windows, Intel Macs, Android and iOS only, so on Linux, in WebGL, and on an Apple silicon Mac outside Rosetta a character moves on down its Fallback Chain. In the editor, Live Viseme Unsupported on Build Target warns you once when the platform you are building for is one of them.

Fix: bake that character's lines and use Baked Phoneme, or use Live Amplitude. On an Apple silicon Mac, running Unity under Rosetta should also work. A browser build also has no microphone of its own. See What Runs Where.

Live Viseme Falls Back on Every Line

A character on Live Viseme plays every line in Live Amplitude instead, and Speech Fallback Engaged says Meta's recognizer could not load.

Causes:

• On a Windows build, the Microsoft Visual C++ Redistributable is missing on that PC.
• The OVRLipSync plugin is not enabled for this platform in its import settings.
• On a Mac, Unity is running natively on Apple silicon.

Fix: install or ship the redistributable, enable the plugin for the platform, or see What Runs Where for Apple silicon.

The Editor Slows Down With a Character Selected

A FaceCue driver's inspector is a large surface, and the editor pays to draw it. With a character selected and its sections open, the editor can feel heavy while the game itself runs fine, and it picks up again the moment you select something else.

Two things decide what it costs. What is on screen, since the sections scrolled out of view are skipped and only the ones you can actually see are drawn. And what those sections are showing: the live readouts keep the inspector redrawing as their values move, which is what you want while watching a character and not what you want while judging a frame rate.

Fix: fold what you are not working on. Every FaceCue inspector carries Collapse All and Expand All at its top, beside the tier toggles, and they fold that inspector alone. Collapsing the component itself goes further, since a collapsed component draws nothing and its live rows go quiet.

Also worth trying:

• Drop the tier. Advanced and Expert rows are not drawn at all while their toggles are off, so a Basic inspector is a much shorter one.
• Select something else while you measure. A character that is not selected costs the editor nothing, and a frame rate read with a driver open is not the frame rate your game has.

None of this reaches your game, since a build has no inspectors. What a character costs while it plays is on Performance.

FaceCue Stopped Compiling After Forcing an Integration

Forcing an integration on for a package the project does not have stops FaceCue compiling, and the FaceCue Hub goes with it.

Fix: Tools ▸ FaceCue ▸ Integrations ▸ Reset Defines, then set that integration back to Auto in the Hub. See Integrations.

A Message Carries a Code

A message with a code in brackets, such as [FaceCue] [FCR-0004], is a fault inside FaceCue rather than something in your setup, and nothing on your side fixes it. Please report it with the code and the full message.

Two coded messages are the exception, because they do have a fix: [FCR-0003] Rounding Shape Missing and [FCR-0005] Openness Shape Missing. Run the OneClick Wizard on that character again to add the missing blendshape.

Still Stuck

Write in through Support with the Console message, if there is one, and what you expected to happen.