feat: per-agent voice pilot — VoiceAdapter + OpenClaw demo (3 presets) by lukejmorrison · Pull Request #8 · lukejmorrison/VoiceDNA

lukejmorrison · 2026-04-18T18:53:46Z

Feature: Per-Agent Voice Presets for OpenClaw

Summary

Wire the VoiceDNA VoiceAdapter into the OpenClaw agent voice pipeline, enabling agents to use distinct voice presets (neutral, friendly, flair) based on agent identity. Fully opt-in via env vars — default VoiceDNA behavior is unchanged.

Branch

feature/voicedna-openclaw-per-agent-voices

Changes

New Modules

File	Purpose
`voicedna/openclaw_adapter.py`	`VoiceAdapter` class: per-agent preset selection + synthesis
`voicedna/openclaw_live_voice.py`	`render_agent_voice()` — OpenClaw TTS hook entry point
`examples/openclaw_voicedemo.py`	Demo: 3 agents × 3 presets → WAV output
`tests/test_voice_adapter.py`	Unit/smoke tests for VoiceAdapter
`tests/test_openclaw_live_voice.py`	Integration tests: demo, agent mapping, live bridge

Key Features

Preset Registry — Three pilot presets (neutral, friendly, flair) with voice DNA parameters
Agent Mapping — Environment-driven (JSON) or programmatic agent_id → preset resolution
Fallback Chain — agent_id → agent_name → default_preset
Opt-in Activation — VOICEDNA_OPENCLAW_PRESETS=1 activates the hook; absent = no-op
No Breaking Changes — Existing VoiceDNA CLI/SDK behavior is unchanged

Test Instructions

cd /path/to/VoiceDNA

# Unit + integration tests
python -m pytest tests/test_voice_adapter.py tests/test_openclaw_live_voice.py -q

# Full suite
python -m pytest -q

# Demo smoke test (produces 3 WAV files)
python -m examples.openclaw_voicedemo

Expected Outputs

File	Description
`examples/openclaw/output/namshub_neutral.wav`	Namshub — neutral preset
`examples/openclaw/output/david_friendly.wav`	David Hardman — friendly preset
`examples/openclaw/output/voss_flair.wav`	Dr Voss Thorne — flair preset

All three files should be non-empty RIFF/WAVE format (≥ 100 KB each at 22050 Hz 16-bit mono).

Configuration

# Production opt-in
export VOICEDNA_OPENCLAW_PRESETS=1
export VOICEDNA_OPENCLAW_PRESETS_MAP='{"agent:namshub":"neutral","agent:david-hardman":"friendly","agent:dr-voss-thorne":"flair"}'

Programmatic Usage

from voicedna.openclaw_live_voice import render_agent_voice

wav_bytes = render_agent_voice(
    text=tts_text,
    agent_id=agent.id,
    agent_name=getattr(agent, "name", None),
    output_path=maybe_output_path,
)
# returns None when VOICEDNA_OPENCLAW_PRESETS is not set (no-op)

Or use the adapter directly:

from voicedna.openclaw_adapter import VoiceAdapter

adapter = VoiceAdapter(agent_presets={
    "agent:namshub": "neutral",
    "agent:dr-voss-thorne": "flair",
})
preset = adapter.select_preset("agent:namshub")
wav = adapter.synthesize("Hello.", preset, output_path="output.wav")

Rollback

Unset VOICEDNA_OPENCLAW_PRESETS and VOICEDNA_OPENCLAW_PRESETS_MAP
Remove the render_agent_voice() import from the OpenClaw hook
Return to the previous TTS path

No schema migration or persistent state required.

Validation Results

✅ 52 tests pass (31 unit + 21 integration)
✅ Demo produces 3 valid WAV files (164–212 KB each)
✅ WAVs are valid RIFF PCM 16-bit mono 22050 Hz
✅ VOICEDNA_OPENCLAW_PRESETS guard confirmed: returns None when unset
✅ Linting passes (ruff)
✅ No changes to existing VoiceDNA public API

- voicedna/openclaw_adapter.py: new opt-in per-agent voice routing module - Pilot presets: neutral, friendly, flair - Env-based mapping via VOICEDNA_OPENCLAW_PRESETS_MAP - Falls back to DEFAULT_PRESET for unmapped agents - No changes to existing CLI or public SDK

- examples/openclaw_voicedemo.py: runnable local demo - examples/openclaw/output/: namshub_neutral, david_friendly, voss_flair WAVs - No cloud deps; espeak-ng or synthetic tone fallback

…ATION_NOTE - README: Per-agent voices for OpenClaw pilot — usage, presets table, API example - CHANGELOG: unreleased entry for feature branch - IMPLEMENTATION_NOTE.md: run/test instructions and assumptions

…th (parents[1]); remove unused imports

…apter, conftest)

…kend; fix lint

…vy deps

…s for per-agent voices PR

…4 passed, ruff clean)

… checklist

…ot ship - Re-ran local demo (piper/local TTS backend, no licensed audio) - All 34 pytest tests pass, ruff clean - Added QA_checklist, pr_description_summary, release_notes to pr_prep/

…port.txt - Applied ruff format to 31 files (no logic changes, whitespace/style only) - Regenerated 3 demo WAVs via openclaw_voicedemo.py (all pass) - Updated local_test_report.txt: 34 tests pass, ruff clean, demo clean - Branch ready for merge

…ent-voices' into feature/voicedna-openclaw-per-agent-voices

- New test_openclaw_live_voice.py: 13 integration tests validating demo, agent mapping, preset registry, and e2e synthesis - VERIFICATION_REPORT.md: comprehensive verification showing 31/31 tests pass, linting passes, demo produces valid WAVs - PR_OPENCLAW_VOICES.md: concise PR description for feature review All success criteria met: ✓ 31 tests pass (18 unit + 13 integration) ✓ Demo produces 3 valid RIFF/WAVE files (164-211 KB) ✓ End-to-end synthesis validated ✓ Agent ID format handling works ✓ No breaking changes

Comprehensive handoff showing all success criteria met, test results, artifact validation, and push instructions for review team.

Complete record of: - 31/31 tests passing (18 unit + 13 integration) - Linting passes (ruff all-clear) - 3 valid WAV artifacts with file format validation - Success criteria checklist - Branch ready for push

Final comprehensive summary showing: - All success criteria met - 31/31 tests pass - Demo validates - Branch ready for push - Full audit trail and next steps

… logs

…es pilot

…sh PR_BODY - voicedna/openclaw_live_voice.py: render_agent_voice() opt-in guard + lazy VoiceAdapter cache; reset_adapter() for test isolation - tests/test_openclaw_live_voice.py: +5 TestRenderAgentVoice tests covering opt-in guard (None when env unset), synthesis path, alias resolution, and adapter cache reset - PR_BODY.md: updated with final test counts (52 passed), openclaw_live_voice usage example, and validation results - examples/openclaw/output/: refreshed demo WAVs (164-212 KB each) All 52 tests pass locally.

…eadiness

…search, demo WAVs

…IGN_DOC

Copilot

Pull request overview

Adds an opt-in OpenClaw integration layer to route agent speech through VoiceDNA “pilot” presets (neutral/friendly/flair), including a live hook entrypoint, demo script, and tests; plus repo-wide formatting/cleanup and extensive supporting docs/artifacts.

Changes:

Introduce OpenClaw-facing live hook (render_agent_voice) with env-gated enablement and preset mapping.
Add/expand tests + demo to validate per-agent preset selection and WAV outputs.
Refactor/format multiple modules and adjust package import behavior to keep optional heavy deps from breaking lightweight usage.

Reviewed changes

Copilot reviewed 112 out of 121 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`vst3/venom_bridge.py`	Formatting changes; no functional additions apparent in diff.
`vst3/bridge_runtime.py`	Formatting changes; no functional additions apparent in diff.
`voicedna/synthesis.py`	Formatting changes in backend selection / subprocess calls.
`voicedna/providers/piper.py`	Formatting + small refactor of env parsing and command construction.
`voicedna/providers/personaplex.py`	Formatting + minor refactors; error strings adjusted.
`voicedna/plugins/manager.py`	Formatting changes for readability.
`voicedna/openclaw_live_voice.py`	New OpenClaw live bridge entrypoint with env-gated routing + adapter caching.
`voicedna/framework.py`	Formatting changes + clearer error raising.
`voicedna/filters/imprint_converter.py`	Formatting changes + string literal quoting updates.
`voicedna/filters/audio_helpers.py`	Formatting changes.
`voicedna/filters/age_maturation.py`	Formatting changes.
`voicedna/consistency.py`	Remove unused import + formatting changes.
`voicedna/__init__.py`	Make top-level imports optional via `try/except ModuleNotFoundError`.
`voice_dna.py`	Formatting changes + minor readability refactors.
`tests/test_voice_adapter.py`	New unit/smoke tests for `VoiceAdapter` preset routing and synthesis behavior.
`tests/test_openclaw_live_voice.py`	New integration tests for demo artifacts + live hook behavior.
`tests/test_processor_report.py`	Formatting changes.
`tests/test_natural_doctor.py`	Formatting changes.
`tests/test_consistency_engine.py`	Formatting changes.
`tests/test_audio_roundtrip.py`	Formatting changes.
`tests/conftest.py`	Formatting-only impact in shown diff.
`conftest.py`	New root conftest adding repo root to `sys.path` for pytest collection.
`examples/openclaw_voicedemo.py`	New demo producing 3 WAVs for 3 agents/presets.
`examples/voicebox_demo.py`	Formatting changes.
`examples/openclaw_skill.py`	Formatting changes.
`examples/openclaw_hook.py`	Formatting changes.
`examples/openclaw/voipms_phone_skill.py`	Formatting changes + line wrapping.
`examples/openclaw/voicedna_tts_hook.py`	Formatting changes.
`examples/omarchy/voicedna-pipewire-filter.py`	Formatting changes + small readability improvements.
`examples/omarchy/voicedna-os-daemon.py`	Formatting changes + line wrapping.
`examples/encrypted_plugin_demo.py`	Formatting changes.
`examples/elevenlabs_demo.py`	Formatting changes.
`examples/create_from_audio.py`	Formatting changes.
`examples/cartesia_demo.py`	Formatting changes.
`README.md`	Document OpenClaw per-agent pilot usage and presets.
`CHANGELOG.md`	Add unreleased entry describing OpenClaw per-agent pilot changes.
`scripts/review_feedback.py`	Formatting changes.
`test_results.log`	Added test output artifact.
`test_logs.txt`	Added error-log artifact.
`test-output.txt`	Added test output artifact.
`ruff_results.log`	Added lint output artifact.
`LINT_LOG.txt`	Added lint/mypy notes artifact.
`TEST_LOG.txt`	Added test output artifact.
`TEST_LOGS.txt`	Added summarized test output artifact.
`local_test_report.txt`	Added local verification report artifact.
`missing_items.txt`	Added checklist/notes artifact.
`approval_request.txt`	Added approval/push notes artifact.
`PR_BODY.md`	Added PR body content artifact.
`PR_CHECKLIST.md`	Added PR checklist artifact.
`PR_DESCRIPTION.md`	Added PR description artifact.
`PR_DRAFT.md`	Added PR draft artifact.
`PR_OPENCLAW_VOICES.md`	Added PR narrative artifact.
`PR_READY_REPORT.md`	Added PR readiness artifact.
`PR_ready.md`	Added PR prep TODO artifact.
`PR_description.txt`	Added PR text artifact.
`README_DELIVERABLES.md`	Added deliverables index artifact.
`HANDOFF.md`	Added handoff doc artifact.
`IMPLEMENTATION_NOTE.md`	Added implementation notes artifact.
`INTEGRATION_NOTE.md`	Added integration notes artifact.
`DESIGN_DOC.md`	Added/updated design doc artifact.
`research/*`	Added extensive research/verification/design/push documentation artifacts.
`release/*`	Added release/push/verification artifacts and helper scripts.
`release_prep/*`	Added release prep instructions/artifacts.
`push-plan.md` / `push-checklist.md`	Added push planning artifacts.
`pr_prep/*`	Added PR prep artifacts/checklists.
`.task.md`	Added task brief artifact.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-19T14:27:14Z

+        dna = _build_dna_for_preset(preset)
+        raw_audio = self._tts.synthesize(text)
+
+        preset_cfg = PRESET_REGISTRY[preset]
+        process_params: Dict[str, Any] = {


VoiceAdapter.synthesize() calls self._tts.synthesize(text) to compute raw_audio, but later calls VoiceDNAProcessor.synthesize_and_process(..., tts_provider=self._tts) which will call tts_provider.synthesize(text) again. This results in synthesizing the same text twice per request (extra latency + nondeterministic output if backend varies). Consider either (a) calling processor.process(raw_audio, dna, process_params) directly, or (b) removing the raw_audio call and relying solely on synthesize_and_process (keeping the AttributeError fallback consistent).

Copilot · 2026-04-19T14:27:14Z

+        try:
+            processed = self._processor.synthesize_and_process(
+                text=text,
+                dna=dna,
+                tts_provider=self._tts,
+                params=process_params,
+            )
+        except AttributeError:
+            # Older VoiceDNAProcessor: use process() directly
+            processed = self._processor.process(raw_audio, dna, process_params)


Even if you keep synthesize_and_process(), the AttributeError fallback path uses the already-generated raw_audio, but the main path ignores it. After removing the double-synthesis, ensure both the primary and fallback paths use the same single synthesized WAV so behavior is consistent across VoiceDNAProcessor versions.

Copilot · 2026-04-19T14:27:15Z

+    try:
+        mapping: Dict[str, str] = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        logger.warning("VOICEDNA_OPENCLAW_PRESETS_MAP is not valid JSON: %s", exc)
+        return AGENT_PRESETS
+
+    for agent_key, preset_name in mapping.items():
+        if preset_name not in PRESET_REGISTRY:


load_presets_from_env() assumes VOICEDNA_OPENCLAW_PRESETS_MAP decodes to a dict[str, str]. If the env var is valid JSON but not an object (e.g., a list/null/number), mapping.items() will raise at runtime. Add a type check after json.loads (and ideally validate keys/values are strings) to avoid crashing the OpenClaw hook on misconfiguration.

Copilot · 2026-04-19T14:27:15Z

+def _get_adapter() -> VoiceAdapter:
+    """Return (and lazily create) the module-level VoiceAdapter instance."""
+    global _adapter  # noqa: PLW0603
+    if _adapter is None:
+        # Populate from env first; fall back to pilot defaults
+        env_map = load_presets_from_env()
+        agent_presets = dict(_DEFAULT_PILOT_MAP)
+        agent_presets.update(env_map)
+        _adapter = VoiceAdapter(agent_presets=agent_presets)
+        logger.debug(


_get_adapter() lazily initializes a module-level singleton without any synchronization. If OpenClaw calls render_agent_voice() concurrently (common in async/web contexts), multiple threads could race to create adapters or observe a partially-initialized global. Consider guarding initialization with a threading.Lock or using functools.lru_cache for _get_adapter() to make this thread-safe.

Copilot · 2026-04-19T14:27:15Z

+    @pytest.mark.skipif(
+        not all([p.read_bytes() for p in [
+            Path(__file__).resolve().parents[1] / "examples" / "openclaw" / "output" / f
+            for f in ["namshub_neutral.wav", "david_friendly.wav", "voss_flair.wav"]
+        ] if p.exists()]),
+        reason="Demo WAV files not all present"
+    )


The @skipif condition reads the full demo WAV contents at collection time (p.read_bytes()), which adds unnecessary I/O to every test run and can be slow/flaky on CI filesystems. Prefer checking only for file existence/size in the marker, and perform any content validation inside the test body (using pytest.skip when prerequisites aren’t met).

Copilot · 2026-04-19T14:27:15Z

+The feature is entirely additive and disabled by default.  Enable it by:
+
+1. Setting `VOICEDNA_OPENCLAW_PRESETS=1` in your environment (signals intent; not strictly required by the code).


README says setting VOICEDNA_OPENCLAW_PRESETS=1 is “not strictly required by the code,” but the OpenClaw hook entrypoint render_agent_voice() explicitly returns None unless this env var is set. Suggest clarifying that the env var is required for the openclaw_live_voice hook path, while it’s optional when using VoiceAdapter directly.

Suggested change

The feature is entirely additive and disabled by default. Enable it by:

1. Setting `VOICEDNA_OPENCLAW_PRESETS=1` in your environment (signals intent; not strictly required by the code).

The feature is entirely additive and disabled by default. Enable it by:

1. Setting `VOICEDNA_OPENCLAW_PRESETS=1` in your environment. This is required when using the OpenClaw hook path (`openclaw_live_voice` / `render_agent_voice()`), and optional only if you are instantiating `VoiceAdapter` directly.

…o WAVs - DESIGN_DOC.md: add David's 5-item edge-case validation checklist - Refresh demo WAVs (namshub_neutral, david_friendly, voss_flair) - Add research prep artifacts: .env.example, openclaw_integration_plan.md, research_summary.md, smoke_test_tts.sh, prep_for_voss/checklist.md - 52 tests pass, ruff clean

…nd merge gate

…WAVs + checklist

Dr Voss Thorne and others added 30 commits April 13, 2026 09:01

feat: add OpenClaw per-agent voice demo (3 agents × 3 presets → WAV)

7c03e95

- examples/openclaw_voicedemo.py: runnable local demo - examples/openclaw/output/: namshub_neutral, david_friendly, voss_flair WAVs - No cloud deps; espeak-ng or synthetic tone fallback

docs: add per-agent voices README section, CHANGELOG entry, IMPLEMENT…

ccc2eef

…ATION_NOTE - README: Per-agent voices for OpenClaw pilot — usage, presets table, API example - CHANGELOG: unreleased entry for feature branch - IMPLEMENTATION_NOTE.md: run/test instructions and assumptions

fix: add root conftest.py for pytest path resolution; fix demo sys.pa…

19d3388

…th (parents[1]); remove unused imports

style: apply ruff format to PR files (openclaw_adapter, test_voice_ad…

14dcb76

…apter, conftest)

docs: add PR_DRAFT.md, TEST_LOG.txt, LINT_LOG.txt for pre-push review

4035524

docs: prepare VoiceDNA PR materials

f82eadf

fix: make voice_dna import optional; skip synthesis tests without bac…

f9700c5

…kend; fix lint

fix: guard voicedna/__init__ imports with try/except for optional hea…

d8651df

…vy deps

docs: add DESIGN_DOC, research notes, release artifacts, and test log…

4e073b0

…s for per-agent voices PR

chore(pr): finalize PR draft for per-agent voices

c977cc3

chore(pr): update PR docs and research notes

249dcee

docs: finalize PR_DESCRIPTION with test evidence and demo validation

878fd45

fix: suppress F401 noqa on intentional re-exports in __init__.py

21067ee

chore: add PR_READY_REPORT.md with test results and squash plan

c715723

chore: update PR prep materials with 2026-04-17 clean test results (3…

5f43042

…4 passed, ruff clean)

docs: add integration summary, implementation checklist, and PR merge…

8a1bc51

… checklist

chore: resolve PR_DRAFT.md stash conflict

3a04652

chore: refresh demo WAVs, test output, and pr_prep docs for final pil…

df547da

…ot ship - Re-ran local demo (piper/local TTS backend, no licensed audio) - All 34 pytest tests pass, ruff clean - Added QA_checklist, pr_description_summary, release_notes to pr_prep/

docs: add INTEGRATION_NOTE.md for OpenClaw adapter wiring

cb46e92

Merge remote-tracking branch 'origin/feature/voicedna-openclaw-per-ag…

05bd391

…ent-voices' into feature/voicedna-openclaw-per-agent-voices

Add final handoff document for VoiceDNA OpenClaw voice adapter

6c8f401

Comprehensive handoff showing all success criteria met, test results, artifact validation, and push instructions for review team.

Add comprehensive test and verification log

67de43e

Complete record of: - 31/31 tests passing (18 unit + 13 integration) - Linting passes (ruff all-clear) - 3 valid WAV artifacts with file format validation - Success criteria checklist - Branch ready for push

Add subagent completion report for main agent

9e479b1

Final comprehensive summary showing: - All success criteria met - 31/31 tests pass - Demo validates - Branch ready for push - Full audit trail and next steps

chore: refresh demo WAVs (regenerated, bit-exact update)

ead0e00

chore: stage task brief, research docs, refreshed WAVs, and test/lint…

dda9e61

… logs

docs: add PR_DRAFT.md and PR_BODY.md for review readiness

4d3d4bd

chore: stage integration prep notes for OpenClaw wiring review

19e0a73

lukejmorrison added 6 commits April 18, 2026 22:50

feat: refresh demo WAVs and stage integration docs for per-agent voic…

ef637f9

…es pilot

docs: refresh integration plan and stage pre-integration research docs

0920b43

chore: refresh demo WAVs and verify implementation checklist for PR r…

9618b82

…eadiness

chore: finalize VoiceDNA OpenClaw integration - update design doc, re…

81c09a4

…search, demo WAVs

feat: wire VoiceAdapter into OpenClaw pipeline; add demo WAVs and DES…

e37d508

…IGN_DOC

lukejmorrison marked this pull request as ready for review April 19, 2026 14:22

Copilot AI review requested due to automatic review settings April 19, 2026 14:22

Copilot started reviewing on behalf of lukejmorrison April 19, 2026 14:23 View session

Copilot AI reviewed Apr 19, 2026

View reviewed changes

lukejmorrison added 5 commits April 19, 2026 11:55

docs: add final PR_OPENCLAW_VOICES.md with full deliverable summary a…

adac281

…nd merge gate

chore: add demo WAVs dir and implementation_note.md for Namshub

ac2dd62

docs: finalize VoiceDNA OpenClaw integration packet + refreshed demo …

be8df6b

…WAVs + checklist

chore: stage final docs and DESIGN_DOC updates pre-release

5587351

lukejmorrison merged commit c1d157f into main Apr 20, 2026

Navigation Menu

feat: per-agent voice pilot — VoiceAdapter + OpenClaw demo (3 presets) - #8

feat: per-agent voice pilot — VoiceAdapter + OpenClaw demo (3 presets)#8
lukejmorrison merged 41 commits into
mainfrom
feature/voicedna-openclaw-per-agent-voices

lukejmorrison commented Apr 18, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		The feature is entirely additive and disabled by default. Enable it by:

		1. Setting `VOICEDNA_OPENCLAW_PRESETS=1` in your environment (signals intent; not strictly required by the code).

Conversation

lukejmorrison commented Apr 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Feature: Per-Agent Voice Presets for OpenClaw

Summary

Branch

Changes

New Modules

Key Features

Test Instructions

Expected Outputs

Configuration

Programmatic Usage

Rollback

Validation Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lukejmorrison commented Apr 18, 2026 •

edited

Loading