Configuration reference

Where settings live#

Each desktop face keeps its files in a folder of its own. The original face (started without --face) uses data\ itself; a face started with --face NAME uses data\faces\NAME\, and one started with --config PATH keeps its other files in data\faces\ under the config file's name. data\ is in the app's folder: %LOCALAPPDATA%\Programs\Wireface\data when installed, or the clone's own data\ folder (the WIREFACE_DATA environment variable moves it).

Shared by every face: data\sandbox (the default working folder), data\cache (the model lists), dataackups (a copy of each of the agents' files as it was before the Tools tab first changed it), and the speech models (deps\models, or MODELS_DIR).

wireface-core keeps nothing on disk: a face's settings are the config you give createFace, or a config file you load.

Face settings#

How the face looks and moves. These settings are the engine's, so they're the same in wireface-core's config, the embed's URL parameters and the desktop app's face.json, apart from the differences listed below. Numbers outside their range are refused: wireface-core throws a ConfigError naming the setting, and the desktop app rejects the change.

Skin and wireframe#

The normal way to choose a look is a skin plus skin_amount: how far the whole face is faded from the glowing wireframe to the skin.

Colours#

Look#

Teeth#

Motion and lip sync#

Colour presets#

The desktop app's face.json#

Wireface Desktop keeps each face's look in face.json, changed from the Face tab. It has the face settings above, with these differences:

• No skin setting. The face always wears a picture: one of the eight portraits or your own photo, chosen on the Face tab or dropped on the face, and kept in the face's face\ folder. A new face wears Mei. photo records which (version, w, h and portrait); Wireface sets it, not you.
• style is always photo. A face.json from an older version that says hologram is read as photo with skin_amount 0 (the wireframe), and sculpt as photo.
• Other defaults: the colours are the claude preset, glow is 1, wire 0.85, fill 0.35 and scanlines 0.3.
• The presets are claude, cyan, green, amber, violet, rose and ice.

And four settings of its own:

When it loads face.json, Wireface drops anything that's no longer valid and uses the default instead.

Config files for wireface-core#

A wireface-core face's settings can live in a small JSON file. Every setting is optional; missing ones take their defaults. $schema points editors such as VS Code at the JSON Schema, for autocomplete and checking:

{
  "$schema": "https://raw.githubusercontent.com/compsmart/wireface-core/main/config/face.schema.json",
  "skin": "dracula",
  "skin_amount": 0.6,
  "teeth_style": "vampire",
  "preset": "rose",
  "motion": 0.7,
  "expressiveness": 1.3
}

import { createFace, validateConfig } from '@wireface/core';

const config = await (await fetch('/faces/dracula.json')).json();
const face = createFace(canvas, { config });   // checked: a ConfigError names the bad setting
validateConfig(config);                        // or check one yourself: returns the full config

The errors say exactly what's wrong: glow: 3 is outside 0..2, colors.primary: expected #rrggbb, unknown setting "glo". The schema is config/face.schema.json in wireface-core (or @wireface/core/face.schema.json), and config/examples/ has a few files to start from. The demo's Config panel shows any face you set up there as a file, with only what differs from the defaults.

In code, DEFAULTS holds every default, RANGES the limits of every number setting, PRESETS the presets, and STYLES and TEETH_STYLES the choices.

The desktop app's profile.json#

Each desktop face's settings, apart from its look. It's created the first time a setting is saved, and it's easiest to change from the panel, which saves as you go. To edit it by hand, quit the face first. The copy button next to Config file on the Agent tab gives you its path. profile.example.json, next to the app, shows the shape.

• A file that isn't valid JSON is reported, and the defaults are used until it's fixed. If the face saves over it meanwhile, the broken file is kept as profile.json.bad.
• A setting that's no longer valid (a working folder that's gone, say) is dropped, with a warning in app.log, and its default used.
• Changes made in the panel are checked the same way, and a refused change names the setting.

The face#

The original face takes its defaults for these from WIREFACE_NAME and WIREFACE_PORT.

The agent: backend#

The voice: voice#

Rooms: room#

The phone line: phone#

An example#

{
  "name": "Claude",
  "port": 0,
  "backend": {
    "type": "claude",
    "cwd": "C:\\Users\\you\\projects\\something",
    "model": null,
    "skip_permissions": false,
    "permission_mode": "default",
    "auto_start": true,
    "options": {}
  },
  "voice": {
    "on": true,
    "listening": false,
    "mode": "realtime",
    "realtime": {
      "provider": "gemini",
      "gemini": { "model": "gemini-3.8-live", "voice": "Puck", "api_key_env": "GEMINI_API_KEY" },
      "openai": { "model": "gpt-realtime-2.1", "voice": "marin", "api_key_env": "OPENAI_API_KEY" },
      "narration": "normal",
      "persona": "self",
      "barge_in": false
    },
    "hearing": { "name_interrupt": true, "denoise": true, "focus": true },
    "engine": "auto"
  },
  "room": { "name": null, "aliases": [], "lead": "first" }
}

Older versions kept a single face's settings in data\settings.json. If the original face has no profile.json yet, its working folder, permission mode, model, voice settings and conversation are carried over from there.

Environment variables#

Each key setting can name another variable to read (api_key_env, auth_token_env). A key pasted into Settings is used before any variable. On Windows, a user or system variable set while Wireface is running is picked up within seconds.

Command line#

Wireface Desktop#

Wireface.exe (installed), Wireface.cmd (a clone) and .venv\Scripts\python -m wireface all take the same options:

From a clone, there are also:

RefreshModels.cmd                                 # download the Model settings' lists again (--face NAME for another face)
.venv\Scripts\python -m wireface.models --check   # which speech models are installed or missing (--load: load them too)
.venv\Scripts\python -m wireface.models --install # download what's missing (--with-kokoro: the Kokoro voice too)
scripts\setup.ps1                                 # install or repair everything (-WithKokoro)

wireface-core#

npm start                     # the examples and demo on http://127.0.0.1:5173/ (PORT=8080 npm start for another port)
npm test                      # node --test: config, schema, assets, loading
python -m tools.voice "Hello there." --voice Kore -o assets/voices/hello     # text to a clip (GEMINI_API_KEY)
python -m tools.lipsync speech.wav --text "Hello there." -o speech.json      # any audio to a clip
python -m tools.lipsync --get-lexicon                                        # once: the pronunciation lexicon

The clip tools are explained in Making clips.