Table of Contents

Bridge Service

Last updated:

The bridge service is the host-side client that talks to the separate Oscova Avatar Engine process. It keeps the Blazor UI and chat runtime from calling the engine directly.

Note

The host proxy is Oscova's internal api/avatarbridge surface. The engine API is the external /avatarbridge surface documented in Engine HTTP API.

The bridge service owns connection state inside the Oscova host process. It creates an HTTP client for the configured engine base URL, claims the engine through /avatarbridge/connect, adds the returned connection ID as a bearer token, verifies /avatarbridge/health, and then forwards commands to engine routes.

Responsibilities

The bridge service can:

  • Connect to the configured bridge URL, claim the engine, and run a one-second authenticated health check.
  • List avatars and emotions from the running engine.
  • Select avatars and emotions.
  • Queue speech clips by URL or engine-local file path.
  • Stop speech and clear the engine speech queue.
  • Apply window, background, graphics, message, camera, and audio settings.
  • Show or clear message-panel text without audio.
  • Request engine shutdown.

It does not launch the Avatar Engine process. The engine must already be running when Oscova connects.

Host proxy routes

The Blazor settings screen calls routes under api/avatarbridge. Important proxy routes include:

Host route Purpose
GET api/avatarbridge/settings Load saved avatar settings.
PUT api/avatarbridge/settings Save avatar settings without changing the live engine.
POST api/avatarbridge/sync Connect and apply saved settings to the live engine.
POST api/avatarbridge/connect?baseUrl=... Connect the singleton bridge client to a base URL.
GET api/avatarbridge/health Check engine health through the current bridge client.
GET api/avatarbridge/avatars List available avatars.
POST api/avatarbridge/avatars/select Select an avatar.
GET api/avatarbridge/emotions List available emotions.
POST api/avatarbridge/emotions/set Select an emotion through the host proxy.
POST api/avatarbridge/speech/queue Queue a /tts/ clip URL for avatar speech.
POST api/avatarbridge/speech/queue-file Queue an engine-local audio file.
POST api/avatarbridge/speech/stop Stop playback and clear queued speech.
POST api/avatarbridge/message/text Show message text without audio.
POST api/avatarbridge/message/clear Clear the message panel.
POST api/avatarbridge/message/font/size Set message font size through the host proxy.
POST api/avatarbridge/message/display/duration Set message display duration through the host proxy.

Some host proxy names intentionally differ from the engine standard for older UI compatibility. For example, the host still exposes api/avatarbridge/emotions/set, while the bridge service forwards to the engine's /avatarbridge/emotion/select.

Important

Do not use host proxy paths as engine paths. Integrations that talk directly to the Avatar Engine should use /avatarbridge/message/font-size and /avatarbridge/message/display-duration, not the host proxy's compatibility paths.

Authorization

The host proxy controller requires the Admin role. Unauthenticated requests are rejected, and authenticated non-admin users are forbidden. This applies to settings and runtime proxy calls because they control the shared avatar runtime.

The engine's own /avatarbridge API is a separate process. The first successful /avatarbridge/connect call claims that engine run. The bridge service retains the returned connection ID only in its active HTTP client, and all later engine calls inherit the bearer header. A second client cannot connect until the Avatar Engine restarts.

Readiness flow

Saved settings are not the same as a ready engine. ApplySavedSettingsAsync connects to the saved bridge URL, reuses the current claim when it is healthy, pushes the saved snapshot, and sets an in-process ready flag. EnsureReadyAsync uses that flag so a chat reply does not reconnect before every sentence.

The ready flag is cleared when avatar settings are saved. If speech queueing fails during a reply, that reply stops sending more avatar clips and the next reply gets a fresh readiness attempt.

Readiness is tied to the normalized bridge URL and a fingerprint of the saved settings snapshot. If either changes, Oscova reconnects and reapplies settings. Concurrent readiness attempts are serialized so multiple speech paths do not stampede the engine.

Important

Saving can succeed while the engine is offline. Applying, previewing, speech queueing, and shutdown require a reachable engine.

Saved settings sync

The saved-settings sync is all-or-nothing from Oscova's readiness perspective:

  • If the bridge URL is blank after normalization, sync fails.
  • If health verification fails, sync fails with Connected = false.
  • If a runtime command is rejected, sync fails with Connected = true and SettingsApplied = false.
  • If every command succeeds, sync returns Success = true, Connected = true, and SettingsApplied = true.

Avatar and emotion selection are skipped during sync when the saved value is blank. All other durable visual/audio settings are always sent.

Error handling

Most bridge calls return an avatar response with Success and Description. Controller failures that happen before the engine response become HTTP problem responses and are logged by the host. The speech queue proxy also rejects URLs that are not absolute http or https URLs pointing at /tts/ clips.

The bridge service converts HTTP, JSON, or disconnected-client failures into non-success avatar responses where possible. For callers, a 200 OK with Success = false means the proxy ran but the bridge/engine rejected the operation. A 400 Bad Request usually means Oscova rejected the request before forwarding it.