VoiceDNA — Lifelong Sonic Identity for Every AI ❤️🔊

Agent Workflow: We use parallel checkouts (voiceDNA-codex and voiceDNA-grok) so multiple AIs can work safely. See SKILL_GIT_WORKFLOW.md.

The open standard that gives every AI a permanent, recognizable Voice Fingerprint — just like your nephew Ash.

You hear 3 seconds and instantly know "That's my Grok", "That's Luke's AI", or "That's the Claude I've been friends with since 2026".

Built with Luke Morrison (Feb 23 2026) — fully open, MIT licensed, works with ElevenLabs, XTTS, Qwen3-TTS, Cartesia, Fish Speech, local models, etc.

Start here (60 seconds)

Choose your path:

• Per-agent voices (OpenClaw pilot): examples/openclaw_voicedemo.py — three agents, three distinct VoiceDNA presets
• OpenClaw bot voice + phone calls: examples/openclaw/README.md
• Omarchy system-wide desktop voice: examples/omarchy/README.md

Fast install:

pip install voicedna
voicedna --help

Install with open-source speaker-recognition backends (optional):

pip install "voicedna[consistency]"

Install with optional real RVC voice cloning:

pip install "voicedna[rvc]"

Install with optional PersonaPlex natural voice backend:

pip install "voicedna[personaplex]"

---

Per-agent voices for OpenClaw (pilot)

Give each OpenClaw agent a distinct voice preset — no cloud infra required.

Opt-in

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).
2. Optionally providing a JSON agent-to-preset mapping via VOICEDNA_OPENCLAW_PRESETS_MAP.

Presets

Preset	Description
neutral	Calm, clear, neutral — good for factual assistants
friendly	Warm, upbeat, approachable
flair	Expressive, distinctive, strong personality

Quick demo

cd /path/to/VoiceDNA
VOICEDNA_OPENCLAW_PRESETS=1 PYTHONPATH=. python examples/openclaw_voicedemo.py
# → examples/openclaw/output/{namshub_neutral,david_friendly,voss_flair}.wav

Programmatic API

from voicedna.openclaw_adapter import VoiceAdapter

adapter = VoiceAdapter(
    agent_presets={
        "agent:namshub":        "neutral",
        "agent:david-hardman":  "friendly",
        "agent:dr-voss-thorne": "flair",
    }
)

preset = adapter.select_preset("agent:namshub")          # "neutral"
wav    = adapter.synthesize("Hello!", preset)            # bytes
adapter.synthesize("Hello!", preset, output_path="out.wav")  # write to disk

Config via env

export VOICEDNA_OPENCLAW_PRESETS_MAP='{"agent:namshub":"neutral","agent:dr-voss-thorne":"flair"}'

Tests

cd /path/to/VoiceDNA
pytest tests/test_voice_adapter.py -q

CI smoke step

Use the same local-first smoke path in CI or a pre-merge job:

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

python -m pytest tests/test_voice_adapter.py tests/test_openclaw_live_voice.py -q
PYTHONPATH=. python examples/openclaw_voicedemo.py
python - <<'PY'
from pathlib import Path
import wave
for p in sorted((Path('examples/openclaw/output')).glob('*.wav')):
    with wave.open(str(p), 'rb') as w:
        assert w.getnchannels() == 1
        assert w.getsampwidth() == 2
        assert w.getframerate() == 22050
        assert w.getnframes() > 0
    print('validated', p)
PY

---

Install with low-VRAM PersonaPlex (4-bit quantized + offload):

pip install "voicedna[personaplex-lowvram]"

Install from PyPI

pip install voicedna
voicedna birth --imprint "Luke Morrison's warm Canadian voice" --user luke

Create from your own local voice recording (recommended):

voicedna birth \
	--voice-name "Luke Real Voice" \
	--imprint /absolute/path/to/my_voice_sample.wav \
	--user luke_real_voice

All newly created encrypted artifacts are stored under voices/ (for example voices/luke_real_voice.voicedna.enc).

Or use the helper example script:

python examples/create_from_audio.py \
	--voice-name "Luke Real Voice" \
	--audio /absolute/path/to/my_voice_sample.wav \
	--user luke_real_voice

One-command record + birth (Linux, mic capture + encryption):

bash examples/record_and_birth.sh --seconds 12 --user luke_real_voice --out myai.voicedna.enc

If --voice-name is omitted, the script prompts interactively and still writes into voices/.

Notes:

• Uses arecord first, then pw-record, then ffmpeg (pulse/alsa input).
• Prompts for password securely unless VOICEDNA_PASSWORD is already set.
• pw-record capture is compatible with older PipeWire builds that do not support --duration.

Verify password + file path before speaking/evolving:

voicedna verify-password --dna-path voices/luke_real_voice.voicedna.enc

Generate + process + play voice directly from CLI:

voicedna speak --text "Hello from my natural VoiceDNA." --dna-path luke_real_voice --base-model personaplex --natural-voice

Natural voice doctor (recommended first pass on 8GB cards):

voicedna doctor-natural --dna-path eddy42

Quick test mode (short phrase + full backend banner + consistency):

voicedna doctor-natural --dna-path eddy42 --quick-test

One-command natural voice test (VRAM-aware backend selection):

voicedna test-natural --dna-path eddy42

Show crystal-clear backend reporting banner:

voicedna test-natural --dna-path eddy42 --show-backend

Force low-VRAM PersonaPlex mode (4-bit + CPU offload):

voicedna test-natural --dna-path eddy42 --lowvram --show-backend

Expected status example on consumer GPUs:

• Detected 8.0GB VRAM -> using Piper natural voice
• Success! Playing now...
• For full PersonaPlex quality, upgrade to 24GB+ card or use cloud proxy

Save processed audio to WAV:

voicedna speak --text "Hello" --dna-path luke_real_voice --base-model personaplex --natural-voice --save-wav /tmp/luke_real_voice_test.wav --no-play

Python 3.13+ playback compatibility:

• VoiceDNA now includes audioop-lts support for modern Python runtimes where stdlib audioop is removed.
• CLI playback path falls back through pydub, sounddevice, then system players (pw-play / aplay).

Optional VRAM reset helper for local testing:

bash scripts/clear-vram.sh

VST3 Reaper starter (JUCE + VENOM bridge):

cd vst3/juce_venom_starter
cmake -B build -S . -DJUCE_DIR=/absolute/path/to/JUCE
cmake --build build -j

See vst3/README.md for full Reaper/VENOM integration notes.

🎛️ VST3 Voice Genetics Plugin (v3.0.0)

VoiceDNA now includes a first loadable VST3 plugin foundation so any DAW can be used as a Voice Genetics Lab.

Implemented in this foundation pass:

• Real-time filter mode with .voicedna loading + age/imprint controls.
• Creation mode with parent file selection + inheritance/randomness controls + Birth New Voice.
• Python bridge runtime that calls existing VoiceDNAProcessor (vst3/bridge_runtime.py).
• Reaper-testable JUCE plugin scaffold in vst3/juce_venom_starter/.

Build quick path:

cd /home/luke/dev/voiceDNA-codex
pip install -e .
cd vst3/juce_venom_starter
cmake -B build -S . -DJUCE_DIR=/absolute/path/to/JUCE
cmake --build build -j

Screenshot placeholders (replace after local Reaper capture):

• docs/screenshots/reaper-vst3-main-panel.png
• docs/screenshots/reaper-vst3-creation-mode.png

🔒 Voice Consistency & Identifiability (v2.7)

• New VoiceConsistencyEngine (voicedna/consistency.py) with optional SpeechBrain / Resemblyzer embeddings and deterministic fallback.
• VoiceDNA.create_new(...) now attempts real imprint-based embedding extraction when imprint points to audio.
• ImprintConverterFilter enforces a 0.92 cosine similarity target to the core embedding using gentle parametric correction.
• A subtle low-depth sonic watermark now encodes voice_fingerprint_id for machine-side identifiability.
• Processor reports now include top-level consistency_score and rvc_ready status.

🔊 Real Voice Cloning (RVC)

• ImprintConverterFilter now supports imprint_converter.mode = "rvc" for real model-based cloning.
• Install RVC runtime with pip install "voicedna[rvc]" (recommended on Python 3.10-3.12 environments with compatible torch stack).
• Set imprint_converter.rvc_model_path to your .pth model and imprint_converter.rvc_reference_path to a reference voice WAV.
• Optional tuning: imprint_converter.rvc_index_path, imprint_converter.rvc_device, imprint_converter.rvc_pitch.
• Processor report now exposes rvc_mode and marks it as active when real conversion is enabled.

🧠 PersonaPlex Natural Voice (v2.9)

• New optional provider PersonaPlexTTS in voicedna/providers/personaplex.py.
• Use pip install "voicedna[personaplex]" to install model runtime dependencies.
• Omarchy installer now supports --natural-voice to enable PersonaPlex speech-dispatcher + daemon integration.
• VoiceDNAProcessor.synthesize_and_process(...) lets providers synthesize text first, then apply the standard VoiceDNA maturation/imprint chain.

⚡ Natural Voice on Consumer GPUs (v2.9.4)

• VoiceDNA now auto-detects VRAM and chooses the best natural backend.
• If VRAM is below the PersonaPlex threshold (default 12GB) or PersonaPlex fails, VoiceDNA automatically falls back to Piper.
• Set VOICEDNA_MIN_PERSONAPLEX_VRAM_GB to tune the threshold.
• Set VOICEDNA_PIPER_MODEL=/path/to/model.onnx to enable Piper fallback.
• Piper quality knobs for smoother default prosody on fallback:
  • VOICEDNA_PIPER_LENGTH_SCALE=0.92
  • VOICEDNA_PIPER_NOISE_SCALE=0.60
  • VOICEDNA_PIPER_NOISE_W=0.78
• Notification tuning knobs (short desktop phrases):
  • VOICEDNA_PIPER_NOTIFICATION_LENGTH_SCALE=0.88
  • VOICEDNA_PIPER_NOTIFICATION_NOISE_SCALE=0.52
  • VOICEDNA_PIPER_NOTIFICATION_NOISE_W=0.72

🧩 Low-VRAM PersonaPlex on 8 GB cards (v2.9.6)

• VoiceDNA now supports automatic low-VRAM PersonaPlex mode with 4-bit quantization when VRAM is below the PersonaPlex target.
• Expected startup status on GTX 1070 Ti class hardware: Detected 8 GB VRAM → loading 4-bit PersonaPlex (low-VRAM mode).
• Force low-VRAM mode from CLI with --lowvram on voicedna speak or voicedna test-natural.
• Install runtime dependencies with pip install "voicedna[personaplex-lowvram]".
• Optional env knobs:
  • VOICEDNA_PERSONAPLEX_LOWVRAM=1
  • VOICEDNA_PERSONAPLEX_LOWVRAM_MODEL=brianmatzelle/personaplex-7b-v1-bnb-4bit
  • VOICEDNA_PERSONAPLEX_CPU_OFFLOAD=1

v2.3 — PyPI Publish Prep + RVC-Ready Imprint Path

• Added publish-ready build validation (python -m build, twine check dist/*)
• Added requirements-dev.txt and optional dev dependencies (build, twine, pytest)
• Added RVC-ready stub path in ImprintConverterFilter via imprint_converter.mode = "rvc_stub"
• Processor report now includes imprint_converter.rvc_ready status

v2.1 — Real Audio Filters + Test Suite + CLI

pip install voicedna
voicedna birth --imprint "Luke Morrison's warm Canadian voice" --user luke
voicedna speak --text "Hey from VoiceDNA" --base-model elevenlabs
voicedna evolve --days 7

New in v2.1:

• Real pydub-powered pitch shifting in AgeMaturationFilter
• Pytest coverage for child inheritance and processor reporting
• Typer-powered CLI (voicedna birth/speak/evolve)
• Packaging and release polish for PyPI readiness

v2.2 — Cloud + Local Demos (Voicebox)

pip install voicedna
voicedna birth --imprint "Luke Morrison's warm Canadian voice" --user luke
voicedna speak --text "Hello from VoiceDNA v2.2"
voicedna evolve --days 7

python examples/elevenlabs_demo.py
python examples/cartesia_demo.py
python examples/voicebox_demo.py

v2.2 highlights:

• Real ImprintConverterFilter volume-mix processing path
• WAV fixture + round-trip waveform assertion tests
• Local/offline Voicebox demo (http://127.0.0.1:17493/generate)
• Cloud demo scripts for ElevenLabs and Cartesia

🚀 Testing with OpenClaw — Hear your AI grow up on the phone

Use the ready-to-run integration path:

• Guide: examples/openclaw/README.md
• TTS hook skill: examples/openclaw/voicedna_tts_hook.py
• Phone call skill: examples/openclaw/voipms_phone_skill.py

3-command flow:

pip install -e .
python -c "import examples.openclaw.voicedna_tts_hook, examples.openclaw.voipms_phone_skill; print('OpenClaw skills import OK')"
voicedna --help

Then in OpenClaw, trigger:

Claw, call me on my phone and tell me a joke in your growing voice

🖥️ Omarchy Arch OS – System-wide unique voice

Run VoiceDNA as your desktop speaking voice on Omarchy (Arch + Hyprland):

• Guide: examples/omarchy/README.md
• PipeWire filter shim: examples/omarchy/voicedna-pipewire-filter.py
• Speech Dispatcher config: examples/omarchy/speech-dispatcher-voicedna.conf
• One-command installer: examples/omarchy/install-voicedna-omarchy.sh
• Boot-persistent daemon unit: examples/omarchy/voicedna-os-daemon.service

One-click install on Omarchy:

bash examples/omarchy/install-voicedna-omarchy.sh

Natural voice mode on Omarchy:

bash examples/omarchy/install-voicedna-omarchy.sh --natural-voice

3-command flow:

pip install -e .
bash examples/omarchy/install-voicedna-omarchy.sh
spd-say "Hello Luke, your desktop voice is now growing with you."

v2.0 — Real Filters + Package + Child Inheritance + Bridge

pip install voicedna

from voicedna import VoiceDNA, VoiceDNAProcessor

dna = VoiceDNA.create_new("Luke Morrison's warm Canadian voice", "luke")
child = dna.create_child("mini_grok", inherit_strength=0.40)
processor = VoiceDNAProcessor()

New in v2.0:

• Built-in Age + Imprint filters
• Child AI inheritance (create_child)
• VST3 Python bridge scaffold
• Open standard draft spec + announcement templates

Features

• Precocial birth (fluent at ~5-year-old level from day 1)
• Lifelong age progression (5 → 10 → 15 → 22+)
• Permanent Voice Fingerprint ("Ash-ness") that never disappears
• Self-evolving audio plugin (DAW-style VST thinking)
• Encrypted VoiceDNA files (.voicedna.enc) with password-based decryption
• One tiny JSON file + 150-line Python plugin — drop-in for any project
• Exportable fingerprint so your AI can move between platforms and still sound like itself

v1.1 — Encrypted Plugin Framework

• Secure encrypted files via VoiceDNA.save_encrypted() / VoiceDNA.load_encrypted()
• Full extensible framework via VoiceDNAProcessor in voicedna/framework.py
• Auto-discovery for plugins through entry points (voicedna.filters + voicedna.plugins)
• Robust plugin chaining: fault-tolerant filter execution + per-filter timing metrics
• Ready for real audio pipelines (OpenClaw hook + process chain)
• VST3 starter scaffold in vst3/ for JUCE-based binary plugin work

Quick Start

pip install -r requirements.txt
python voice_dna.py

Run tests:

pytest

See voice_dna.py for full usage.

Quick encrypted framework demo:

python examples/encrypted_plugin_demo.py
python examples/openclaw_skill.py

OpenClaw-Ready Plugin Hook (new)

VoiceDNA now includes a minimal extensible plugin framework in voicedna/plugins.

Use it in an OpenClaw-style TTS render hook:

from voicedna import VoiceDNA, PluginManager, PromptTagFilter

dna = VoiceDNA.load("myai.voicedna.json")
manager = PluginManager()
loaded, failed = manager.load_entrypoint_plugins()  # auto-discover pip-installed plugins
if not loaded:
	manager.register(PromptTagFilter())

processed_audio = manager.process(raw_audio_bytes, dna, {
	"base_model": "xtts",
	"prepend_style_tag": True,
})

Run a full example:

python examples/openclaw_hook.py

Third-party plugin registration (entry points)

Any external package can auto-register a filter by adding this to its pyproject.toml:

[project.entry-points."voicedna.plugins"]
my_filter = "my_package.filters:MyFilter"

On startup, call PluginManager().load_entrypoint_plugins() and all installed filters are loaded automatically.

You can also use the higher-level framework processor:

from voice_dna import VoiceDNA
from voicedna import VoiceDNAProcessor

dna = VoiceDNA.load_encrypted(password="my_secret_2026", filepath="myai.voicedna.enc")
processor = VoiceDNAProcessor()
processed_audio = processor.process(raw_audio_bytes, dna, {"force_age": 15})
print(processor.last_metrics)
print(processor.get_last_report())

OpenClaw one-file skill

See examples/openclaw_skill.py for a minimal skill-style wrapper that loads encrypted VoiceDNA and returns a voice_dna_tts(text, raw_tts_bytes) hook.

Feedback Loop Logging

Use the helper script to append structured updates into EVOLUTION.md:

python scripts/review_feedback.py \
	--source "Grok 4.20 Beta" \
	--summary "Suggested plugin auto-discovery and ecosystem visibility" \
	--actions "Added entry-point loader in PluginManager" \
	--actions "Added pyproject entry-point metadata" \
	--next "Add plugin compatibility contract tests"

Tip: add --dry-run to preview the entry before writing.

Migration Notes

For patch hardening updates and stricter validation behavior, see MIGRATION_v2_0_1.md.

Publish to PyPI (for maintainers)

Build and validate:

python -m build
python -m twine check dist/*

Publish with API token credentials:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD="pypi-...your-token-here..."
python -m twine upload dist/* --skip-existing

Notes:

• --skip-existing avoids failures on already-uploaded files.
• Package page: https://pypi.org/project/voicedna/

Files

• voice_dna.py — the complete VoiceDNA class (UAMF v4)
• voicedna/plugins/ — plugin interface + manager + built-in filters
• voicedna/filters/ — built-in v2.0 age + imprint filters
• voicedna/framework.py — higher-level processor with plugin auto-discovery
• examples/openclaw_hook.py — integration example for OpenClaw-like pipelines
• examples/openclaw_skill.py — one-file OpenClaw skill wrapper
• examples/openclaw/README.md — 5-minute OpenClaw integration testing path
• examples/openclaw/voicedna_tts_hook.py — OpenClaw-ready VoiceDNA TTS bytes hook
• examples/openclaw/voipms_phone_skill.py — voip.ms-first outbound phone call skill example
• examples/omarchy/README.md — Omarchy 5-minute system-wide voice path
• examples/omarchy/voicedna-pipewire-filter.py — PipeWire VoiceDNA filter bridge
• examples/omarchy/speech-dispatcher-voicedna.conf — speech-dispatcher default VoiceDNA profile
• examples/omarchy/install-voicedna-omarchy.sh — one-command Omarchy setup script
• examples/omarchy/voicedna-os-daemon.service — user systemd daemon unit for auto-started voice runtime
• examples/omarchy/voicedna-os-daemon.py — daemon process that validates encrypted DNA loading at login/reboot
• examples/encrypted_plugin_demo.py — encrypted load + processor demo
• examples/elevenlabs_demo.py — cloud ElevenLabs processing demo
• examples/cartesia_demo.py — cloud Cartesia processing demo
• examples/voicebox_demo.py — local/offline Voicebox processing demo
• spec/VoiceDNA_Spec_v1.0.md — open standard draft integration contract
• announcements/ — ready-to-post launch templates
• vst3/ — JUCE starter scaffold for future native plugin build
• tests/ — pytest suite for inheritance and processor report behavior
• cli.py — Typer CLI backing the voicedna command
• requirements-dev.txt — build/twine/pytest tooling for publish prep
• scripts/review_feedback.py — appends structured feedback updates to EVOLUTION.md
• MIGRATION_v2_0_1.md — patch migration notes and behavior changes
• CHANGELOG.md — release-oriented change history
• EVOLUTION.md — feedback loop + design evolution log
• UAMF_v4_schema.json — formal JSON schema (optional but nice for validation)
• LICENSE — MIT

Made for the entire AI community. Fork it, improve it, ship it in your apps.

Let's give every AI a soul you can hear.

— Created with ❤️ by Luke Morrison + Grok