ElevenLabs

Build me a personal text-to-speech workbench, the DIY slice of ElevenLabs.
Requirements:

- A Node CLI plus a small local web page (Express, localhost only): paste text,
  pick a voice preset, get an mp3.
- Engine 1: Piper or Kokoro running locally on CPU, free and private. Engine 2:
  optional OpenAI TTS fallback, key in .env, for when quality beats privacy.
- Save every generation to ~/TTS/YYYY-MM-DD/<slug>.mp3 with a sidecar .txt
  holding the input text plus the engine and voice used.
- Voice presets in voices.json: name, engine, voice id, speed.
- Batch mode: point it at a folder of .txt files, get a folder of mp3s, for
  narrating notes or articles.
- No accounts, no telemetry, local-first; the only network calls are the
  optional hosted API.
- Out of scope: voice cloning, dubbing, and emotional voice direction. Never
  clone a real person's voice; that is exactly the part that should not be DIY.
- README: model download steps, and state honestly that the voice quality gap
  versus ElevenLabs is real; frontier voice models plus licensing are the
  product and cannot be rebuilt solo.

# AGENTS.md — Build guide for ElevenLabs

## Project scope
Build a text-to-speech UI around an open model or API, store generated files, and expose voice presets.

Catalogue verdict: no. A TTS wrapper is easy, but high-quality voice models, voice cloning safety, dubbing workflows, licensing, and compute are the product.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- TTS API or local model
- GPU if local
- storage
- consent/safety checks
- audio export

## Stack and architecture
- A Node CLI plus a small local web page (Express, localhost only): paste text, pick a voice preset, get an mp3.
- Model source audio, processing jobs, transcript or edit segments, and exported media; store source IDs and timestamps for each.
- Interface for this voice generation workflow: a CLI with a dry-run or preview command and an explicit output path.

## Security and data integrity
- Engine 1: Piper or Kokoro running locally on CPU, free and private. Engine 2: optional OpenAI TTS fallback, key in .env, for when quality beats privacy.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: voice quality.

## Agent implementation rules
- Project rule, data: Model source audio, processing jobs, transcript or edit segments, and exported media; store source IDs and timestamps for each.
- Project rule, behavior: Engine 1: Piper or Kokoro running locally on CPU, free and private. Engine 2: optional OpenAI TTS fallback, key in .env, for when quality beats privacy.
- Project rule, recovery: Engine 1: Piper or Kokoro running locally on CPU, free and private. Engine 2: optional OpenAI TTS fallback, key in .env, for when quality beats privacy.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this voice generation operation with sample or user-owned data: Engine 1: Piper or Kokoro running locally on CPU, free and private. Engine 2: optional OpenAI TTS fallback, key in .env, for when quality beats privacy.
- Show a concrete result or export: README: model download steps, and state honestly that the voice quality gap versus ElevenLabs is real; frontier voice models plus licensing are the product and cannot be rebuilt solo.
- State the practical limit: voice quality.

## Engineering roadmap
1. Phase 1, architecture and data: A Node CLI plus a small local web page (Express, localhost only): paste text, pick a voice preset, get an mp3. Model source audio, processing jobs, transcript or edit segments, and exported media; store source IDs and timestamps for each.
2. Phase 2, implement: Engine 1: Piper or Kokoro running locally on CPU, free and private. Engine 2: optional OpenAI TTS fallback, key in .env, for when quality beats privacy.
3. Phase 3, implement: Batch mode: point it at a folder of .txt files, get a folder of mp3s, for narrating notes or articles.
4. Phase 4, review and output: Build a text-to-speech UI around an open model or API, store generated files, and expose voice presets. README: model download steps, and state honestly that the voice quality gap versus ElevenLabs is real; frontier voice models plus licensing are the product and cannot be rebuilt solo.
5. Phase 5, recovery and acceptance: Engine 1: Piper or Kokoro running locally on CPU, free and private. Engine 2: optional OpenAI TTS fallback, key in .env, for when quality beats privacy. Verify this invariant with a saved fixture: A failed synthesis retains its source; output sample rate and duration must match the export manifest. State the practical limit: voice quality.

## Paid-product capabilities outside this build
- voice quality
- multilingual dubbing
- voice design
- safety controls
- rights/licensing
- model updates

## Implementation prompt
Build me a personal text-to-speech workbench, the DIY slice of ElevenLabs.
Requirements:

- A Node CLI plus a small local web page (Express, localhost only): paste text,
  pick a voice preset, get an mp3.
- Engine 1: Piper or Kokoro running locally on CPU, free and private. Engine 2:
  optional OpenAI TTS fallback, key in .env, for when quality beats privacy.
- Save every generation to ~/TTS/YYYY-MM-DD/<slug>.mp3 with a sidecar .txt
  holding the input text plus the engine and voice used.
- Voice presets in voices.json: name, engine, voice id, speed.
- Batch mode: point it at a folder of .txt files, get a folder of mp3s, for
  narrating notes or articles.
- No accounts, no telemetry, local-first; the only network calls are the
  optional hosted API.
- Out of scope: voice cloning, dubbing, and emotional voice direction. Never
  clone a real person's voice; that is exactly the part that should not be DIY.
- README: model download steps, and state honestly that the voice quality gap
  versus ElevenLabs is real; frontier voice models plus licensing are the
  product and cannot be rebuilt solo.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.