Table of Contents

Connect the Engine

Last updated:

Oscova Agents connects to the Avatar Engine through the engine's HTTP bridge. The default address is http://127.0.0.1:11318, which means "this same machine, port 11318."

Note

A bridge URL is the address Oscova uses to reach another running program. Use the default for a local engine, or a LAN address when the engine runs on another computer.

Before you begin

You need:

  • The Avatar Engine binary running on the machine that will render the avatar.
  • An Oscova account with the Admin role.
  • Speech synthesis configured if the avatar will speak.
  • A bridge URL that the Oscova host can reach.
  • For remote engines, network access from the engine machine back to Oscova's /tts/ URLs.
Note

If Oscova and the engine are on the same PC, 127.0.0.1 is correct. If they are on different PCs, 127.0.0.1 points at the wrong machine from at least one side.

Start the engine

  1. Start the Avatar Engine binary.
  2. Leave it running while you configure Oscova.
  3. Open Settings > Avatar in Oscova.
  4. Confirm Bridge URL points at the running engine.
  5. Click Refresh Engine.

If the engine is on another machine, use that machine's reachable HTTP address. The Avatar Engine must be able to fetch /tts/ audio URLs from the Oscova host for speech queue playback.

Important

The first client to connect owns the Avatar Engine API until that engine process stops. Repeated refresh and apply actions from the same running Oscova process reuse the connection. If Oscova exits or loses the connection ID while the engine remains open, restart the Avatar Engine before reconnecting.

Understand the status badge

The Avatar settings screen checks the bridge when it loads and whenever you click Refresh Engine:

  • Not checked means the bridge URL has not been verified yet, or you edited it after the last check.
  • Checking means Oscova is connecting and loading live choices.
  • Connected means the health check passed and live lists were loaded.
  • Offline means Oscova could not reach the bridge URL.
  • Catalog issue means the engine answered, but avatar or emotion lists could not be loaded.

Editing Bridge URL resets the status to not checked and clears live choices until the next refresh.

Save before applying

The Avatar settings screen separates saved configuration from live engine commands:

  • Save Settings persists the form values in Oscova.
  • Apply to Live Avatar connects to the saved bridge URL and pushes the saved visual and audio settings to the running engine.
  • Section-level Apply buttons send only that section's current draft values to the live engine.
Important

Apply to Live Avatar is disabled while there are unsaved changes or while the engine is offline. Save first, then refresh/apply.

Saving can succeed while the Avatar Engine is offline. Applying cannot. This lets you prepare settings before the engine is available, but it also means a successful save is not proof that the engine changed.

Apply live sections

Use the section buttons when you want immediate feedback:

  • Apply Avatar loads the selected avatar.
  • Apply Expression sends the selected emotion and blend speed.
  • Apply Window sends resolution, fullscreen, graphics preset, and background color.
  • Apply Appearance sends message font size, color, and opacity.
  • Apply Message Box sends box position, size, and display duration.
  • Apply Camera sends camera yaw.
  • Apply Audio sends speech volume.

Send Preview shows message text without audio. Clear hides the preview panel. Shutdown Avatar asks for confirmation before requesting engine shutdown.

Section-level apply buttons require a reachable engine. Apply Avatar also requires that the selected avatar is present in the live avatar list. Apply Expression requires that the selected emotion is present in the live emotion list.

Confirm the connection

A successful Apply to Live Avatar call means Oscova connected to the engine and pushed the saved settings. If it fails, check that the engine process is running, the bridge URL is reachable, no firewall blocks the port, and the engine was not claimed by another client.

For speech, also confirm the reverse direction: the Avatar Engine must be able to download the absolute /tts/ URL Oscova sends. A local engine usually can. A remote engine may need Oscova to be served on a LAN-visible host name or IP address.

Remote engine checklist

When the Avatar Engine runs on another computer:

  1. Start the engine on the remote machine.
  2. Find that machine's LAN IP address or DNS name.
  3. Enter a bridge URL such as http://192.168.1.25:11318.
  4. Allow the engine port through the remote machine's firewall.
  5. Make sure the remote engine can reach the Oscova host URL used in queued /tts/ clips.
  6. Avoid Shutdown Avatar unless you intend to shut down that remote engine.