Table of Contents

Avatar Settings

Last updated:

Avatar settings control how Oscova Agents reaches the separate Avatar Engine and what state it applies to that running engine.

Note

The Avatar Engine is not part of the Blazor web host. Oscova saves settings locally, then sends HTTP commands to the engine when you apply them.

Avatar settings are shared system settings. They are not personal preferences for one user. The screen is available to admins because it controls the singleton avatar runtime and can send commands to a separate process.

Save and apply behavior

The page uses a draft pattern:

  • Editing a field changes only the on-screen draft.
  • Save Settings writes the draft to Oscova's shared avatar settings.
  • Saving marks the live runtime as not ready, so the next speech sequence or Apply to Live Avatar reconnects and reapplies the saved snapshot.
  • Apply to Live Avatar is available only when there are no unsaved changes and the engine is reachable.
  • Reset to defaults replaces the draft with default values but does not save them.

Section-level Apply buttons send current draft values to the live engine immediately. They do not replace Save Settings when you want the values kept for later sessions.

Important

A section-level Apply can change the live engine with unsaved draft values. Save afterward if you want those values to survive a restart or the next runtime sync.

The full saved-settings apply sends values in this order: resolution, graphics preset, background color, message font size, message color/opacity, message box position, message box size, message display duration, camera yaw, speech volume, selected avatar, and selected emotion.

Connection

Bridge URL is the engine address. The default is http://127.0.0.1:11318. A blank saved value falls back to the default.

Use Apply to Live Avatar after starting or restarting the engine. The apply pass connects, applies window, graphics, background, message, camera, audio, avatar, and emotion settings, then reloads the avatar and emotion lists.

The status badge is based on a live refresh:

  • Connected means the bridge health check and catalog load succeeded.
  • Offline means the bridge URL could not be reached.
  • Catalog issue means health succeeded but avatar or emotion choices failed to load.
  • Not checked means the bridge URL has changed or has not been refreshed.

Avatar and expression

Refresh Avatars calls the running engine for available avatar names. Apply Avatar is disabled until a non-empty avatar is selected.

Refresh Emotions calls the running engine for available emotion names. Apply Expression is disabled until a non-empty emotion is selected. Blend Speed ranges from 0 through 5 in the UI and is sent with the selected emotion.

Avatar and emotion names are case-sensitive at the engine boundary.

If a saved avatar or emotion is not present in the running engine's catalog, the dropdown can show it as a saved-but-unavailable value. That protects the saved configuration from being silently erased, but Apply Avatar and Apply Expression stay disabled until a live catalog contains the selected value.

Window and camera

Resolution offers the presets shown in the UI, from 1280x720 through 5120x2160. Graphics Preset maps Low, Medium, High, and Epic to engine levels 0 through 3. Fullscreen and Background Color are applied with the same Apply Window action.

Camera Yaw is shown as -45 to 45 degrees in Oscova. The engine receives the mapped yaw value from -5.0 through 5.0.

Default window settings are 1920x1080, windowed mode, graphics preset Medium, and RGB background 134,134,134.

Message panel

The message panel can show speech text, captions, or a preview without audio.

  • Message Font Size ranges from 8 through 120.
  • Color and Opacity control the text appearance.
  • X, Y, Width, and Height are displayed as percentages.
  • Display Duration is in seconds. 0 means the message can remain until replaced or cleared.
  • Send Preview calls message/text. Clear calls message/clear.

Defaults are font size 32, white text at full opacity, position 25% from the left and 75% from the top, size 50% wide by 20% high, and display duration 5 seconds.

The settings UI displays box values as percentages, but the engine receives fractions. For example, 25% is sent as 0.25.

Audio and shutdown

Avatar Voice chooses the speech synthesis voice used when an agent speaks through avatar_speak. Available choices show the voice name plus gender and language when provided, while saving the provider voice ID. When no voices are available, the default voice ID is shown.

Speech Volume ranges from 0% through 100%. The engine may not drive lip sync when volume is exactly zero, so use a low nonzero value when you want very quiet speech with visible mouth movement.

Shutdown Avatar asks for confirmation, then sends a shutdown request to the engine at the current bridge URL. This can affect an engine running on another machine if the bridge URL points there.

Avatar voice is saved with avatar settings, not with the current user's speech screen. Chat read-aloud uses the user's selected synthesis voice. The avatar_speak agent tool uses the shared Avatar Voice.

Default values

Setting Default
Bridge URL http://127.0.0.1:11318
Emotion blend speed 1.0
Background color RGB 134,134,134
Resolution 1920x1080
Graphics preset Medium (1)
Message font size 32
Message text color RGBA 1.0,1.0,1.0,1.0
Message box X 25%, Y 75%, width 50%, height 20%
Message display duration 5 seconds
Camera yaw centered
Speech volume 0%
Avatar voice speech default voice