From 560ca142e2e5a420440e22630170ad43149d6af9 Mon Sep 17 00:00:00 2001 From: Tadas Petra <60107328+tadaspetra@users.noreply.github.com> Date: Sat, 28 Mar 2026 08:59:47 -0500 Subject: [PATCH 01/20] Create example skill --- .../scaffold-elevenlabs-example/SKILL.md | 80 ++ .../scaffold-elevenlabs-example/reference.md | 104 +++ .../scripts/scaffold_example.py | 732 ++++++++++++++++++ 3 files changed, 916 insertions(+) create mode 100644 .cursor/skills/scaffold-elevenlabs-example/SKILL.md create mode 100644 .cursor/skills/scaffold-elevenlabs-example/reference.md create mode 100644 .cursor/skills/scaffold-elevenlabs-example/scripts/scaffold_example.py diff --git a/.cursor/skills/scaffold-elevenlabs-example/SKILL.md b/.cursor/skills/scaffold-elevenlabs-example/SKILL.md new file mode 100644 index 00000000..59c56c97 --- /dev/null +++ b/.cursor/skills/scaffold-elevenlabs-example/SKILL.md @@ -0,0 +1,80 @@ +--- +name: scaffold-elevenlabs-example +description: Scaffold prompt-driven examples in this repository using the existing example patterns and repo skills in `.agents/skills`. Use when adding a new example directory, creating matching `README.md`, `PROMPT.md`, and `setup.sh` files, or preparing a new example for `pnpm run generate`. +--- + +# Scaffold ElevenLabs Example + +Use this skill when a user wants a new example scaffold in this repo. + +## Defaults + +- Ignore the deprecated root `examples/` folder. +- Put new examples under `//`. +- The parent example directory owns authoring files; generated code lives in `example/`. + +## Inputs to confirm + +- destination path +- product and runtime +- title and one-sentence summary +- whether the example needs bundled `assets/` +- whether the user wants scaffold only or scaffold plus a generated `example/` + +Ask concise follow-ups only when these are missing. + +## Workflow + +1. Read [reference.md](reference.md). +2. Inspect available repo skills in `.agents/skills/` and choose the best fit for the requested example. +3. Prefer the helper scaffold: + +```bash +python3 .cursor/skills/scaffold-elevenlabs-example/scripts/scaffold_example.py \ + --path speech-to-text/python/my-example \ + --title "Example Title" \ + --summary "One-sentence summary." +``` + +Add `--with-assets` when the example should ship sample files. + +4. Edit the scaffolded `README.md`, `PROMPT.md`, and `setup.sh` until they match the requested example and the closest current reference. +5. Treat the helper output as a generic starting point. If the requested example needs specialized behavior, add that only after the baseline scaffold exists. +6. Keep `PROMPT.md` terse: +- first line invokes the most relevant repo skill found in `.agents/skills/`; for current examples this is often `/text-to-speech`, `/speech-to-text`, or `/agents`, but do not assume that list is exhaustive +- sections are file-by-file using `## \`path/to/file\`` +- bullets call out concrete SDKs, env handling, models, voice IDs, UI states, and error handling +- do not restate repo preamble like `example/`-only rules or `DESIGN.md`; the generator adds that +7. Keep `setup.sh` aligned with current patterns: +- use `set -euo pipefail` +- derive `DIR` and `REPO_ROOT` +- clean `example/` but preserve cache dirs (`node_modules`, `.venv`, `.next`) when relevant +- seed from `templates//` +- copy `README.md` into `example/README.md` +- copy `assets/` and local `.env` only when present +- install dependencies at the end +- for `nextjs`, fetch latest ElevenLabs package versions at setup time and patch `package.json` +8. Keep `README.md` aligned with the closest current reference: +- always include a heading, one-sentence summary, `## Setup`, and `## Run` +- add `## Usage` for interactive examples such as Next.js and agents demos +- commands should work from inside `example/` +9. Recommended when shipping the example: add it to the root `README.md`. +10. Verify: +- `bash /setup.sh` +- inspect the generated `example/` +- run `pnpm run generate ` only when the user wants full prompt validation or generated output + +## Constraints + +- Stay inside the current template matrix unless the user explicitly asks for a new base template. +- Reuse the closest existing example instead of inventing a new file format. +- Do not add application code directly under the parent example directory. +- Do not use the deprecated root `examples/` folder for new work. + +## Output checklist + +- [ ] new example directory exists at the requested path +- [ ] `README.md`, `PROMPT.md`, and `setup.sh` exist +- [ ] `setup.sh` uses the correct shared template +- [ ] `PROMPT.md` matches the terse style of the current examples +- [ ] the scaffold is ready for `pnpm run generate ` diff --git a/.cursor/skills/scaffold-elevenlabs-example/reference.md b/.cursor/skills/scaffold-elevenlabs-example/reference.md new file mode 100644 index 00000000..78cc4fe1 --- /dev/null +++ b/.cursor/skills/scaffold-elevenlabs-example/reference.md @@ -0,0 +1,104 @@ +# Example Generator Reference + +## Generator behavior + +- `pnpm run generate` runs `scripts/generate-examples.sh`. +- The script finds every `PROMPT.md` outside ignored folders. +- If a target folder has `setup.sh` and no `example/`, it runs `setup.sh` first. +- The generator prepends repo context before sending the prompt: + - check existing `example/` first + - `setup.sh` already ran + - implement in `example/` only + - read root `DESIGN.md` for UI work +- The generator auto-loads repo SDK skills from `.agents/skills` when the prompt contains backticked skill names such as ``/text-to-speech``. Keep the backticks and leading slash. + +## Available repo skills + +Inspect `.agents/skills/*/SKILL.md` before finalizing the first line of `PROMPT.md`. + +Current repo skills: + +- `/agents` +- `/music` +- `/setup-api-key` +- `/sound-effects` +- `/speech-to-text` +- `/text-to-speech` + +## Directory shape + +```text +/// +|-- README.md +|-- PROMPT.md +|-- setup.sh +|-- assets/ # optional +|-- .env # optional, local only +`-- example/ # generated output +``` + +Ignore the deprecated root `examples/` folder for new work. + +## Current example matrix + +| Path | Shared template | Prompt sections | Setup extras | +| --- | --- | --- | --- | +| `text-to-speech/typescript/quickstart` | `templates/typescript` | `index.ts` | Copies `.env`, preserves `node_modules`, installs with `pnpm` | +| `text-to-speech/python/quickstart` | `templates/python` | `main.py` | Copies `.env`, preserves `.venv`, installs with `pip` | +| `speech-to-text/typescript/quickstart` | `templates/typescript` | `index.ts` | Optional `assets/`, copies `.env`, preserves `node_modules` | +| `speech-to-text/python/quickstart` | `templates/python` | `main.py` | Optional `assets/`, copies `.env`, preserves `.venv` | +| `speech-to-text/nextjs/realtime` | `templates/nextjs` | `app/api/scribe-token/route.ts`, `app/page.tsx` | Adds `@elevenlabs/react` and `@elevenlabs/elevenlabs-js`, copies `.env.local`, preserves `node_modules` and `.next` | +| `agents/nextjs/quickstart` | `templates/nextjs` | `app/api/agent/route.ts`, `app/api/conversation-token/route.ts`, `app/page.tsx` | Same Next.js setup pattern, removes `@elevenlabs/client` if present | +| `agents/nextjs/guardrails` | `templates/nextjs` | `app/api/agent/route.ts`, `app/api/conversation-token/route.ts`, `app/page.tsx` | Same as quickstart, but prompt targets guardrails and `onGuardrailTriggered` | + +## Runtime setup rules + +| Runtime | Seed template | Preserve on clean | Env copied into `example/` | Install step | +| --- | --- | --- | --- | --- | +| `typescript` | `templates/typescript/` | `node_modules` | `.env` | `pnpm install --config.confirmModulesPurge=false` | +| `python` | `templates/python/` | `.venv` | `.env` | create `.venv`, upgrade `pip`, `pip install -r requirements.txt` | +| `nextjs` | `templates/nextjs/` | `node_modules`, `.next` | `.env.local` | patch `package.json`, then `pnpm install --config.confirmModulesPurge=false` | + +## Prompt rules + +- Start with `Before writing any code, invoke the \`/skill-name\` skill...`. +- Choose that skill by checking `.agents/skills/` first; do not assume only `/text-to-speech`, `/speech-to-text`, and `/agents` exist. +- Use `## \`path/to/file\`` headings only for files inside `example/`. +- Keep prompts short and implementation-focused. Current prompts are direct checklists, not essays. +- Mention the concrete SDK client, env loading, output format, model ids, voice ids, API route security, and UI behavior when those details are known. +- Do not repeat repo-wide context that the generator already injects. + +## README rules + +- Always include a title, one-sentence summary, `## Setup`, and `## Run`. +- Add `## Usage` for interactive or multi-step examples such as Next.js and agents demos. +- Keep commands valid from inside `example/`. +- Use the closest current example as the formatting reference. + +## Best reference by request + +- Simple CLI text-to-speech script: start from `text-to-speech/typescript/quickstart` or `text-to-speech/python/quickstart`. +- CLI transcription or file-based Scribe example: start from the speech-to-text quickstarts. +- Realtime microphone UI: start from `speech-to-text/nextjs/realtime`. +- Voice agent creation and conversation UI: start from `agents/nextjs/quickstart`. +- For specialized agent behavior, start from `agents/nextjs/quickstart` and consult `agents/nextjs/guardrails` only as an existing reference, not as a scaffold mode. + +## Scaffold helper + +The helper script supports the current template matrix and seeds `README.md`, `PROMPT.md`, and `setup.sh` from the closest current pattern. + +```bash +python3 .cursor/skills/scaffold-elevenlabs-example/scripts/scaffold_example.py \ + --path agents/nextjs/my-agent-demo \ + --title "My Agent Demo (Next.js)" \ + --summary "One-sentence summary." +``` + +Useful flags: + +- `--with-assets` to add the asset copy step and create `assets/` +- `--force` to overwrite scaffold files in an existing directory + +The helper intentionally emits a generic baseline scaffold. If the requested example needs specialized behavior, hand-edit the scaffold after creation instead of expecting a dedicated helper mode. + +If the user asks for a product or runtime outside the current matrix, use the closest supported example as the reference and hand-edit the files instead of relying entirely on the helper. diff --git a/.cursor/skills/scaffold-elevenlabs-example/scripts/scaffold_example.py b/.cursor/skills/scaffold-elevenlabs-example/scripts/scaffold_example.py new file mode 100644 index 00000000..4a98e381 --- /dev/null +++ b/.cursor/skills/scaffold-elevenlabs-example/scripts/scaffold_example.py @@ -0,0 +1,732 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import argparse +import re +from pathlib import Path +from textwrap import dedent + +REPO_ROOT = Path(__file__).resolve().parents[4] +SUPPORTED_COMBOS = { + ("text-to-speech", "typescript"), + ("text-to-speech", "python"), + ("speech-to-text", "typescript"), + ("speech-to-text", "python"), + ("speech-to-text", "nextjs"), + ("agents", "nextjs"), +} + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="Scaffold a new prompt-driven ElevenLabs example." + ) + parser.add_argument( + "--path", + required=True, + help="Relative path like speech-to-text/python/my-example", + ) + parser.add_argument("--title", required=True, help="README title") + parser.add_argument("--summary", required=True, help="One-sentence README summary") + parser.add_argument( + "--with-assets", + action="store_true", + help="Create assets/ and include the asset copy step in setup.sh", + ) + parser.add_argument( + "--force", + action="store_true", + help="Overwrite scaffold files in an existing directory.", + ) + return parser.parse_args() + + +def parse_example_path(path_text: str) -> tuple[str, str, str]: + clean_path = path_text.strip().strip("/") + parts = [part for part in clean_path.split("/") if part] + if len(parts) != 3: + raise SystemExit( + "Example paths must look like //, for example " + "speech-to-text/python/my-example." + ) + + product, runtime, slug = parts + if any(part in {".", ".."} for part in parts): + raise SystemExit("Path segments cannot contain '.' or '..'.") + + if not re.fullmatch(r"[a-z0-9][a-z0-9-]*", slug): + raise SystemExit("Slug must use lowercase letters, numbers, and hyphens only.") + + if (product, runtime) not in SUPPORTED_COMBOS: + combos = ", ".join( + f"{product_name}/{runtime_name}" + for product_name, runtime_name in sorted(SUPPORTED_COMBOS) + ) + raise SystemExit( + f"Unsupported product/runtime '{product}/{runtime}'. " + f"Supported combinations: {combos}." + ) + + return product, runtime, slug + + +def closest_reference(product: str, runtime: str) -> str: + if product == "agents" and runtime == "nextjs": + return "agents/nextjs/quickstart" + if product == "speech-to-text" and runtime == "nextjs": + return "speech-to-text/nextjs/realtime" + return f"{product}/{runtime}/quickstart" + + +def build_prompt(product: str, runtime: str) -> str: + if product == "text-to-speech" and runtime == "typescript": + return dedent( + """\ + Before writing any code, invoke the `/text-to-speech` skill to learn the correct ElevenLabs SDK patterns. + + ## `index.ts` + + Create a minimal script that generates an MP3 from text using ElevenLabs Text-to-Speech. + + - Load env vars from `.env`. + - Read text from CLI args; fall back to a short default sentence. + - Generate speech with `voiceId: "JBFqnCBsd6RMkjVDRZzb"` and `modelId: "eleven_multilingual_v2"`. + - Write output audio to `output.mp3`. + - Print success message with the output path. + - Handle errors with a readable message. + """ + ) + + if product == "text-to-speech" and runtime == "python": + return dedent( + """\ + Before writing any code, invoke the `/text-to-speech` skill to learn the correct ElevenLabs SDK patterns. + + ## `main.py` + + Create a minimal script that generates an MP3 from text using ElevenLabs Text-to-Speech. + + - Import everything at the top. Call `load_dotenv()` after imports, then pass `api_key=os.environ["ELEVENLABS_API_KEY"]` explicitly to the `ElevenLabs` client. + - Read text from CLI args; fall back to a short default sentence. + - Generate speech with `voice_id="JBFqnCBsd6RMkjVDRZzb"` and `model_id="eleven_multilingual_v2"`. + - Write output audio to `output.mp3`. + - Print success message with the output path. + - Handle errors with a readable message. + """ + ) + + if product == "speech-to-text" and runtime == "typescript": + return dedent( + """\ + Before writing any code, invoke the `/speech-to-text` skill to learn the correct ElevenLabs SDK patterns. + + ## `index.ts` + + Create a minimal script that transcribes audio with ElevenLabs Scribe v2. + + - Load env vars from `.env`. + - Read first CLI arg as optional audio file path; default to `./audio.mp3`. + - Use `ElevenLabsClient` and call Speech-to-Text with `modelId: "scribe_v2"`. + - Print transcript text to stdout. + - Handle errors with a readable message. + """ + ) + + if product == "speech-to-text" and runtime == "python": + return dedent( + """\ + Before writing any code, invoke the `/speech-to-text` skill to learn the correct ElevenLabs SDK patterns. + + ## `main.py` + + Create a minimal script that transcribes audio with ElevenLabs Scribe v2. + + - Import everything at the top. Call `load_dotenv()` after imports, then pass `api_key=os.environ["ELEVENLABS_API_KEY"]` explicitly to the `ElevenLabs` client. + - Read first CLI arg as optional audio file path; default to `./audio.mp3`. + - Use `ElevenLabs` client and call Speech-to-Text with `model_id="scribe_v2"`. + - Print transcript text to stdout. + - Handle errors with a readable message. + """ + ) + + if product == "speech-to-text" and runtime == "nextjs": + return dedent( + """\ + Before writing any code, invoke the `/speech-to-text` skill to learn the correct ElevenLabs SDK patterns. + + ## 1. `app/api/scribe-token/route.ts` + + Secure GET endpoint that returns a single-use realtime Scribe token. + Never expose `ELEVENLABS_API_KEY` to the client. + + ## 2. `app/page.tsx` + + Realtime microphone transcription page. + + - Use the ElevenLabs React SDK's realtime scribe hook with VAD commit strategy. + - Fetch a fresh token from the API route on each start (tokens are single-use). + - Show a Start/Stop toggle, connection status, live waveform (use `LiveWaveform` from `components/ui`), partial transcript, and committed transcript history (newest first). + - Keep committed history across stop/start; clear transient state on disconnect. + - Handle connection errors gracefully and allow reconnect. + """ + ) + + if product == "agents" and runtime == "nextjs": + return dedent( + """\ + Before writing any code, invoke the `/agents` skill to learn the correct ElevenLabs SDK patterns. + + ## 1. `package.json` + + - Add `@elevenlabs/react` and `elevenlabs` SDK dependencies. + + ## 2. `app/api/agent/route.ts` + + Secure route that creates or loads a voice agent. Never expose `ELEVENLABS_API_KEY` to the client. + + - `POST` creates a new voice agent with sensible defaults (name, system prompt, first message, TTS voice). Use the CLI `voice-only` template as reference for the agent shape. + - `GET` loads an existing agent by `agentId`. + - Configure as voice-first: real TTS voice and model, text-only disabled, widget text input disabled. + - For English agents (`language: "en"`), use `tts.modelId: "eleven_flash_v2"`. Do not use `eleven_flash_v2_5` for English-only agents, or agent creation may fail validation. + - Enable client events needed for transcript rendering and audio. + - Return `{ agentId, agentName }`. + + ## 3. `app/api/conversation-token/route.ts` + + Secure GET endpoint that returns a fresh conversation token for a given `agentId`. + Never expose `ELEVENLABS_API_KEY` to the client. + + ## 4. `app/page.tsx` + + Minimal Next.js voice agent page. + + - Use `@elevenlabs/react` and the `useConversation` hook. + - Show a `Create Agent` button and an editable agent-id input. Auto-populate on create; allow pasting a different id to load it instead. + - Start WebRTC sessions with a fresh token from `/api/conversation-token`. Request mic access before starting. + - Show a Start/Stop toggle, connection status, and running conversation transcript (append messages, don't replace). + - Handle errors gracefully and allow reconnect. Keep the UI simple and voice-first. + """ + ) + + raise SystemExit(f"Unsupported prompt scaffold for {product}/{runtime}.") + + +def join_blocks(*blocks: str) -> str: + cleaned_blocks = [block.strip("\n") for block in blocks if block.strip("\n")] + return "\n\n".join(cleaned_blocks) + "\n" + + +def build_readme( + product: str, + runtime: str, + title: str, + summary: str, + with_assets: bool, +) -> str: + title_block = f"# {title}\n\n{summary}" + + if product == "text-to-speech" and runtime == "typescript": + return join_blocks( + title_block, + dedent( + """\ + ## Setup + + 1. Copy the environment file and add your API key: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and paste your [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys). + + 2. Install dependencies: + + ```bash + pnpm install + ``` + """ + ), + dedent( + """\ + ## Run + + ```bash + pnpm run start "Hello from ElevenLabs" + ``` + + The generated audio is saved to `output.mp3`. + """ + ), + ) + + if product == "text-to-speech" and runtime == "python": + return join_blocks( + title_block, + dedent( + """\ + ## Setup + + 1. Copy the environment file and add your API key: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and paste your [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys). + + 2. Create a virtual environment and install dependencies: + + ```bash + python3 -m venv .venv + .venv/bin/pip install -r requirements.txt + ``` + """ + ), + dedent( + """\ + ## Run + + ```bash + .venv/bin/python main.py "Hello from ElevenLabs" + ``` + + The generated audio is saved to `output.mp3`. + """ + ), + ) + + if product == "speech-to-text" and runtime == "typescript": + run_section = dedent( + """\ + Transcribe a local file: + + ```bash + pnpm run start ./audio.mp3 + ``` + """ + ) + if with_assets: + run_section = dedent( + """\ + Transcribe the bundled sample: + + ```bash + pnpm run start + ``` + + Transcribe a local file: + + ```bash + pnpm run start ./audio.mp3 + ``` + """ + ) + + return join_blocks( + title_block, + dedent( + """\ + ## Setup + + 1. Copy the example env file and add your API key: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and add your [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys). + + 2. Install dependencies: + + ```bash + pnpm install + ``` + """ + ), + "## Run\n\n" + run_section.strip(), + ) + + if product == "speech-to-text" and runtime == "python": + run_section = dedent( + """\ + Transcribe a local file: + + ```bash + .venv/bin/python main.py ./audio.mp3 + ``` + """ + ) + if with_assets: + run_section = dedent( + """\ + Transcribe the bundled sample: + + ```bash + .venv/bin/python main.py + ``` + + Transcribe a local file: + + ```bash + .venv/bin/python main.py ./audio.mp3 + ``` + """ + ) + + return join_blocks( + title_block, + dedent( + """\ + ## Setup + + 1. Copy the example env file and add your API key: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and add your [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys). + + 2. Create a virtual environment and install dependencies: + + ```bash + python3 -m venv .venv + .venv/bin/pip install -r requirements.txt + ``` + """ + ), + "## Run\n\n" + run_section.strip(), + ) + + if product == "speech-to-text" and runtime == "nextjs": + return join_blocks( + title_block, + dedent( + """\ + ## Setup + + 1. Copy the environment file and add your API key: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and paste your [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys). + + 2. Install dependencies: + + ```bash + pnpm install + ``` + """ + ), + dedent( + """\ + ## Run + + ```bash + pnpm run dev + ``` + + Open [http://localhost:3000](http://localhost:3000) in your browser. + """ + ), + dedent( + """\ + ## Usage + + - Click **Start** and allow microphone access when prompted. + - Speak naturally. Partial text should appear while you talk and committed segments should remain in history. + - Click **Stop** to end the session. + """ + ), + ) + + if product == "agents" and runtime == "nextjs": + return join_blocks( + title_block, + dedent( + """\ + ## Setup + + 1. Copy the environment file and add your credentials: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and set: + - `ELEVENLABS_API_KEY` + + 2. Install dependencies: + + ```bash + pnpm install + ``` + """ + ), + dedent( + """\ + ## Run + + ```bash + pnpm run dev + ``` + + Open [http://localhost:3000](http://localhost:3000) in your browser. + """ + ), + dedent( + """\ + ## Usage + + - Click **Create Agent** to create a voice-first agent and populate the agent id field. + - Paste a different agent id when you want to load an existing agent instead. + - Click **Start** and allow microphone access when prompted. + - Speak naturally and watch the running conversation transcript update. + - Click **Stop** to end the session. + """ + ), + ) + + raise SystemExit(f"Unsupported README scaffold for {product}/{runtime}.") + + +def asset_block_lines() -> list[str]: + return [ + "# Copy sample assets into example/", + 'if [ -d "$DIR/assets" ]; then', + ' cp -a "$DIR/assets/." example/', + "fi", + ] + + +def lines_to_text(lines: list[str]) -> str: + return "\n".join(lines) + "\n" + + +def build_setup( + product: str, + runtime: str, + slug: str, + with_assets: bool, +) -> str: + if runtime == "typescript": + lines = [ + "#!/usr/bin/env bash", + "set -euo pipefail", + "", + 'DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"', + 'REPO_ROOT="$(cd "$DIR/../../.." && pwd)"', + 'cd "$DIR"', + "", + "# Clean example/ but preserve node_modules for speed", + "if [ -d example ]; then", + " find example -mindepth 1 -maxdepth 1 ! -name node_modules -exec rm -rf {} +", + "fi", + "mkdir -p example", + "", + "# Copy shared template into example/", + "rsync -a \\", + " --exclude node_modules \\", + " --exclude pnpm-lock.yaml --exclude package-lock.json \\", + " --exclude example \\", + ' "$REPO_ROOT/templates/typescript/" example/', + "", + "# Copy project-specific README", + "cp README.md example/README.md", + ] + if with_assets: + lines.extend(["", *asset_block_lines()]) + lines.extend( + [ + "", + "# Setup env", + 'if [ -f "$DIR/.env" ]; then', + ' cp "$DIR/.env" example/.env', + "fi", + "", + "# Install dependencies", + "cd example", + "pnpm install --config.confirmModulesPurge=false", + ] + ) + return lines_to_text(lines) + + if runtime == "python": + lines = [ + "#!/usr/bin/env bash", + "set -euo pipefail", + "", + 'DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"', + 'REPO_ROOT="$(cd "$DIR/../../.." && pwd)"', + 'cd "$DIR"', + "", + "# Clean example/ but preserve .venv for speed", + "if [ -d example ]; then", + " find example -mindepth 1 -maxdepth 1 ! -name .venv -exec rm -rf {} +", + "fi", + "mkdir -p example", + "", + "# Copy shared template into example/", + "rsync -a \\", + " --exclude .venv \\", + " --exclude example \\", + ' "$REPO_ROOT/templates/python/" example/', + "", + "# Copy project-specific README", + "cp README.md example/README.md", + ] + if with_assets: + lines.extend(["", *asset_block_lines()]) + lines.extend( + [ + "", + "# Setup env", + 'if [ -f "$DIR/.env" ]; then', + ' cp "$DIR/.env" example/.env', + "fi", + "", + "# Install dependencies", + "cd example", + "python3 -m venv .venv", + ".venv/bin/pip install --upgrade pip", + ".venv/bin/pip install -r requirements.txt", + ] + ) + return lines_to_text(lines) + + if runtime == "nextjs": + package_name = f"{product}-{slug}" + node_lines = [ + " const pkg = JSON.parse(require('fs').readFileSync('package.json', 'utf8'));", + f" pkg.name = '{package_name}';", + " pkg.dependencies['@elevenlabs/react'] = '^' + process.env.REACT_VER;", + " pkg.dependencies['@elevenlabs/elevenlabs-js'] = '^' + process.env.ELEVENLABS_VER;", + ] + if product == "agents": + node_lines.append(" delete pkg.dependencies['@elevenlabs/client'];") + node_lines.append( + " require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\\n');" + ) + lines = [ + "#!/usr/bin/env bash", + "set -euo pipefail", + "", + 'DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"', + 'REPO_ROOT="$(cd "$DIR/../../.." && pwd)"', + 'cd "$DIR"', + "", + "# Clean example/ but preserve node_modules for speed", + "if [ -d example ]; then", + " find example -mindepth 1 -maxdepth 1 ! -name node_modules ! -name .next -exec rm -rf {} +", + "fi", + "mkdir -p example", + "", + "# Copy shared template structure", + "rsync -a \\", + " --exclude node_modules --exclude .next \\", + " --exclude pnpm-lock.yaml --exclude package-lock.json \\", + " --exclude example \\", + ' "$REPO_ROOT/templates/nextjs/" example/', + "", + "# Copy project-specific README", + "cp README.md example/README.md", + ] + if with_assets: + lines.extend(["", *asset_block_lines()]) + lines.extend( + [ + "", + "# Add ElevenLabs dependencies", + "cd example", + "export REACT_VER=$(npm view @elevenlabs/react version)", + "export ELEVENLABS_VER=$(npm view @elevenlabs/elevenlabs-js version)", + 'node -e "', + *node_lines, + '"', + ] + ) + if product == "speech-to-text": + lines.extend( + [ + "", + "# Create API route directory", + "mkdir -p app/api/scribe-token", + ] + ) + if product == "agents": + lines.extend( + [ + "", + "# Create API route directories", + "mkdir -p app/api/agent", + "mkdir -p app/api/conversation-token", + ] + ) + lines.extend( + [ + "", + "# Setup env", + 'if [ -f "$DIR/.env" ]; then', + ' cp "$DIR/.env" .env.local', + "fi", + "", + "# Install dependencies", + "pnpm install --config.confirmModulesPurge=false", + ] + ) + return lines_to_text(lines) + + raise SystemExit(f"Unsupported setup scaffold for runtime '{runtime}'.") + + +def write_file(path: Path, content: str) -> None: + path.write_text(content.rstrip() + "\n", encoding="utf-8") + + +def main() -> None: + args = parse_args() + product, runtime, slug = parse_example_path(args.path) + + target_dir = (REPO_ROOT / args.path.strip().strip("/")).resolve() + if REPO_ROOT not in target_dir.parents: + raise SystemExit("Target path must stay inside the repository root.") + + if target_dir.exists() and any(target_dir.iterdir()) and not args.force: + raise SystemExit( + f"Target directory '{args.path}' already exists and is not empty. " + "Use --force to overwrite scaffold files." + ) + + target_dir.mkdir(parents=True, exist_ok=True) + if args.with_assets: + (target_dir / "assets").mkdir(exist_ok=True) + + prompt_path = target_dir / "PROMPT.md" + readme_path = target_dir / "README.md" + setup_path = target_dir / "setup.sh" + + write_file(prompt_path, build_prompt(product, runtime)) + write_file( + readme_path, + build_readme( + product, + runtime, + args.title.strip(), + args.summary.strip(), + args.with_assets, + ), + ) + write_file(setup_path, build_setup(product, runtime, slug, args.with_assets)) + setup_path.chmod(0o755) + + reference = closest_reference(product, runtime) + print(f"Scaffolded {args.path.strip().strip('/')}") + print(f"Closest current reference: {reference}") + print("Next: customize PROMPT.md and README.md for the requested example, then run the local setup script.") + + +if __name__ == "__main__": + main() From 9313ff08dd159e8ae14a3e103cc1c53713b04ded Mon Sep 17 00:00:00 2001 From: Tadas Petra <60107328+tadaspetra@users.noreply.github.com> Date: Sat, 28 Mar 2026 10:02:50 -0500 Subject: [PATCH 02/20] music example --- .../scaffold-elevenlabs-example/reference.md | 34 +++++------ .../scripts/scaffold_example.py | 56 +++++++++++++++++++ README.md | 5 +- music/typescript/quickstart/PROMPT.md | 12 ++++ music/typescript/quickstart/README.md | 29 ++++++++++ .../quickstart/example/.env.example | 1 + music/typescript/quickstart/example/README.md | 29 ++++++++++ music/typescript/quickstart/example/index.ts | 35 ++++++++++++ .../quickstart/example/package.json | 15 +++++ .../quickstart/example/tsconfig.json | 10 ++++ music/typescript/quickstart/setup.sh | 31 ++++++++++ templates/typescript/package.json | 1 + templates/typescript/tsconfig.json | 10 ++++ 13 files changed, 251 insertions(+), 17 deletions(-) create mode 100644 music/typescript/quickstart/PROMPT.md create mode 100644 music/typescript/quickstart/README.md create mode 100644 music/typescript/quickstart/example/.env.example create mode 100644 music/typescript/quickstart/example/README.md create mode 100644 music/typescript/quickstart/example/index.ts create mode 100644 music/typescript/quickstart/example/package.json create mode 100644 music/typescript/quickstart/example/tsconfig.json create mode 100755 music/typescript/quickstart/setup.sh create mode 100644 templates/typescript/tsconfig.json diff --git a/.cursor/skills/scaffold-elevenlabs-example/reference.md b/.cursor/skills/scaffold-elevenlabs-example/reference.md index 78cc4fe1..c1dbe5f5 100644 --- a/.cursor/skills/scaffold-elevenlabs-example/reference.md +++ b/.cursor/skills/scaffold-elevenlabs-example/reference.md @@ -10,7 +10,7 @@ - `setup.sh` already ran - implement in `example/` only - read root `DESIGN.md` for UI work -- The generator auto-loads repo SDK skills from `.agents/skills` when the prompt contains backticked skill names such as ``/text-to-speech``. Keep the backticks and leading slash. +- The generator auto-loads repo SDK skills from `.agents/skills` when the prompt contains backticked skill names such as `/text-to-speech`. Keep the backticks and leading slash. ## Available repo skills @@ -41,29 +41,30 @@ Ignore the deprecated root `examples/` folder for new work. ## Current example matrix -| Path | Shared template | Prompt sections | Setup extras | -| --- | --- | --- | --- | -| `text-to-speech/typescript/quickstart` | `templates/typescript` | `index.ts` | Copies `.env`, preserves `node_modules`, installs with `pnpm` | -| `text-to-speech/python/quickstart` | `templates/python` | `main.py` | Copies `.env`, preserves `.venv`, installs with `pip` | -| `speech-to-text/typescript/quickstart` | `templates/typescript` | `index.ts` | Optional `assets/`, copies `.env`, preserves `node_modules` | -| `speech-to-text/python/quickstart` | `templates/python` | `main.py` | Optional `assets/`, copies `.env`, preserves `.venv` | -| `speech-to-text/nextjs/realtime` | `templates/nextjs` | `app/api/scribe-token/route.ts`, `app/page.tsx` | Adds `@elevenlabs/react` and `@elevenlabs/elevenlabs-js`, copies `.env.local`, preserves `node_modules` and `.next` | -| `agents/nextjs/quickstart` | `templates/nextjs` | `app/api/agent/route.ts`, `app/api/conversation-token/route.ts`, `app/page.tsx` | Same Next.js setup pattern, removes `@elevenlabs/client` if present | -| `agents/nextjs/guardrails` | `templates/nextjs` | `app/api/agent/route.ts`, `app/api/conversation-token/route.ts`, `app/page.tsx` | Same as quickstart, but prompt targets guardrails and `onGuardrailTriggered` | +| Path | Shared template | Prompt sections | Setup extras | +| -------------------------------------- | ---------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| `text-to-speech/typescript/quickstart` | `templates/typescript` | `index.ts` | Copies `.env`, preserves `node_modules`, installs with `pnpm` | +| `text-to-speech/python/quickstart` | `templates/python` | `main.py` | Copies `.env`, preserves `.venv`, installs with `pip` | +| `speech-to-text/typescript/quickstart` | `templates/typescript` | `index.ts` | Optional `assets/`, copies `.env`, preserves `node_modules` | +| `speech-to-text/python/quickstart` | `templates/python` | `main.py` | Optional `assets/`, copies `.env`, preserves `.venv` | +| `music/typescript/quickstart` | `templates/typescript` | `index.ts` | Copies `.env`, preserves `node_modules`, installs with `pnpm` | +| `speech-to-text/nextjs/realtime` | `templates/nextjs` | `app/api/scribe-token/route.ts`, `app/page.tsx` | Adds `@elevenlabs/react` and `@elevenlabs/elevenlabs-js`, copies `.env.local`, preserves `node_modules` and `.next` | +| `agents/nextjs/quickstart` | `templates/nextjs` | `app/api/agent/route.ts`, `app/api/conversation-token/route.ts`, `app/page.tsx` | Same Next.js setup pattern, removes `@elevenlabs/client` if present | +| `agents/nextjs/guardrails` | `templates/nextjs` | `app/api/agent/route.ts`, `app/api/conversation-token/route.ts`, `app/page.tsx` | Same as quickstart, but prompt targets guardrails and `onGuardrailTriggered` | ## Runtime setup rules -| Runtime | Seed template | Preserve on clean | Env copied into `example/` | Install step | -| --- | --- | --- | --- | --- | -| `typescript` | `templates/typescript/` | `node_modules` | `.env` | `pnpm install --config.confirmModulesPurge=false` | -| `python` | `templates/python/` | `.venv` | `.env` | create `.venv`, upgrade `pip`, `pip install -r requirements.txt` | -| `nextjs` | `templates/nextjs/` | `node_modules`, `.next` | `.env.local` | patch `package.json`, then `pnpm install --config.confirmModulesPurge=false` | +| Runtime | Seed template | Preserve on clean | Env copied into `example/` | Install step | +| ------------ | ----------------------- | ----------------------- | -------------------------- | ---------------------------------------------------------------------------- | +| `typescript` | `templates/typescript/` | `node_modules` | `.env` | `pnpm install --config.confirmModulesPurge=false` | +| `python` | `templates/python/` | `.venv` | `.env` | create `.venv`, upgrade `pip`, `pip install -r requirements.txt` | +| `nextjs` | `templates/nextjs/` | `node_modules`, `.next` | `.env.local` | patch `package.json`, then `pnpm install --config.confirmModulesPurge=false` | ## Prompt rules - Start with `Before writing any code, invoke the \`/skill-name\` skill...`. - Choose that skill by checking `.agents/skills/` first; do not assume only `/text-to-speech`, `/speech-to-text`, and `/agents` exist. -- Use `## \`path/to/file\`` headings only for files inside `example/`. +- Use `## \`path/to/file\``headings only for files inside`example/`. - Keep prompts short and implementation-focused. Current prompts are direct checklists, not essays. - Mention the concrete SDK client, env loading, output format, model ids, voice ids, API route security, and UI behavior when those details are known. - Do not repeat repo-wide context that the generator already injects. @@ -78,6 +79,7 @@ Ignore the deprecated root `examples/` folder for new work. ## Best reference by request - Simple CLI text-to-speech script: start from `text-to-speech/typescript/quickstart` or `text-to-speech/python/quickstart`. +- Simple CLI music script: start from `music/typescript/quickstart`. - CLI transcription or file-based Scribe example: start from the speech-to-text quickstarts. - Realtime microphone UI: start from `speech-to-text/nextjs/realtime`. - Voice agent creation and conversation UI: start from `agents/nextjs/quickstart`. diff --git a/.cursor/skills/scaffold-elevenlabs-example/scripts/scaffold_example.py b/.cursor/skills/scaffold-elevenlabs-example/scripts/scaffold_example.py index 4a98e381..5db6679f 100644 --- a/.cursor/skills/scaffold-elevenlabs-example/scripts/scaffold_example.py +++ b/.cursor/skills/scaffold-elevenlabs-example/scripts/scaffold_example.py @@ -13,6 +13,7 @@ ("speech-to-text", "typescript"), ("speech-to-text", "python"), ("speech-to-text", "nextjs"), + ("music", "typescript"), ("agents", "nextjs"), } @@ -171,6 +172,24 @@ def build_prompt(product: str, runtime: str) -> str: """ ) + if product == "music" and runtime == "typescript": + return dedent( + """\ + Before writing any code, invoke the `/music` skill to learn the correct ElevenLabs SDK patterns. + + ## `index.ts` + + Create a minimal script that generates music from a text prompt using the ElevenLabs JS SDK. + + - Load env vars from `.env`. + - Read the music prompt from CLI args; fall back to `A chill lo-fi beat with jazzy piano chords`. + - Use `ElevenLabsClient` and call `client.music.compose` with `musicLengthMs: 10000`. + - Save the returned audio to `output.mp3` with `Readable.from(track)` and `pipeline`. + - Print a success message with the output path. + - Handle errors with a readable message. + """ + ) + if product == "agents" and runtime == "nextjs": return dedent( """\ @@ -443,6 +462,43 @@ def build_readme( ), ) + if product == "music" and runtime == "typescript": + return join_blocks( + title_block, + dedent( + """\ + ## Setup + + 1. Copy the environment file and add your API key: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and paste your [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys). + + 2. Install dependencies: + + ```bash + pnpm install + ``` + + The Music API is currently available to paid ElevenLabs users. + """ + ), + dedent( + """\ + ## Run + + ```bash + pnpm run start "A chill lo-fi beat with jazzy piano chords" + ``` + + The generated track is saved to `output.mp3`. + """ + ), + ) + if product == "agents" and runtime == "nextjs": return join_blocks( title_block, diff --git a/README.md b/README.md index 25ffdedd..85a1f12c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ![ElevenLabs Examples Header](./examples-header.png) -Prompt-driven ElevenLabs examples for text-to-speech and speech-to-text. Each project includes: +Prompt-driven ElevenLabs examples for text-to-speech, speech-to-text, music, and agents. Each project includes: - `PROMPT.md` — instructions for agent-driven generation - `setup.sh` — scaffolds the `example/` directory from a shared template @@ -16,7 +16,10 @@ Shared base templates live in `templates/` (Next.js, Python, TypeScript). UI sty - [Text-to-Speech Quickstart (Python)](text-to-speech/python/quickstart/example/README.md) — Generate an MP3 from text with the ElevenLabs Python SDK. - [Speech-to-Text Quickstart (TypeScript)](speech-to-text/typescript/quickstart/example/README.md) — Transcribe local audio files with Scribe v2. - [Speech-to-Text Quickstart (Python)](speech-to-text/python/quickstart/example/README.md) — Transcribe local audio files with Scribe v2. +- [Music Quickstart (TypeScript)](music/typescript/quickstart/example/README.md) — Generate an MP3 track from a text prompt with the ElevenLabs JS SDK. - [Real-Time Speech-to-Text (Next.js)](speech-to-text/nextjs/realtime/example/README.md) — Live microphone transcription with VAD in a Next.js app. +- [Real-Time Voice Agent (Next.js)](agents/nextjs/quickstart/example/README.md) — Live voice conversations with the ElevenLabs Agents Platform using the React Agents SDK. +- [Voice Agent Guardrails Demo (Next.js)](agents/nextjs/guardrails/example/README.md) — Demonstrate custom guardrails and the `guardrail_triggered` client event in a live voice agent. ## Generate examples from prompts diff --git a/music/typescript/quickstart/PROMPT.md b/music/typescript/quickstart/PROMPT.md new file mode 100644 index 00000000..67a2ee71 --- /dev/null +++ b/music/typescript/quickstart/PROMPT.md @@ -0,0 +1,12 @@ +Before writing any code, invoke the `/music` skill to learn the correct ElevenLabs SDK patterns. + +## `index.ts` + +Create a minimal script that generates music from a text prompt using the ElevenLabs JS SDK. + +- Load env vars from `.env`. +- Read the music prompt from CLI args; fall back to `A chill lo-fi beat with jazzy piano chords`. +- Use `ElevenLabsClient` and call `client.music.compose` with `musicLengthMs: 10000`. +- Save the returned audio to `output.mp3` with `Readable.from(track)` and `pipeline`. +- Print a success message with the output path. +- Handle errors with a readable message. diff --git a/music/typescript/quickstart/README.md b/music/typescript/quickstart/README.md new file mode 100644 index 00000000..9d29460b --- /dev/null +++ b/music/typescript/quickstart/README.md @@ -0,0 +1,29 @@ +# ElevenLabs Music — Quickstart Example + +Generate an MP3 track from a text prompt using the ElevenLabs JS SDK. + +## Setup + +1. Copy the environment file and add your API key: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and paste your [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys). + +2. Install dependencies: + + ```bash + pnpm install + ``` + +The Music API is currently available to paid ElevenLabs users. + +## Run + +```bash +pnpm run start "A chill lo-fi beat with jazzy piano chords" +``` + +The generated track is saved to `output.mp3`. diff --git a/music/typescript/quickstart/example/.env.example b/music/typescript/quickstart/example/.env.example new file mode 100644 index 00000000..4c49a949 --- /dev/null +++ b/music/typescript/quickstart/example/.env.example @@ -0,0 +1 @@ +ELEVENLABS_API_KEY= diff --git a/music/typescript/quickstart/example/README.md b/music/typescript/quickstart/example/README.md new file mode 100644 index 00000000..9d29460b --- /dev/null +++ b/music/typescript/quickstart/example/README.md @@ -0,0 +1,29 @@ +# ElevenLabs Music — Quickstart Example + +Generate an MP3 track from a text prompt using the ElevenLabs JS SDK. + +## Setup + +1. Copy the environment file and add your API key: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and paste your [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys). + +2. Install dependencies: + + ```bash + pnpm install + ``` + +The Music API is currently available to paid ElevenLabs users. + +## Run + +```bash +pnpm run start "A chill lo-fi beat with jazzy piano chords" +``` + +The generated track is saved to `output.mp3`. diff --git a/music/typescript/quickstart/example/index.ts b/music/typescript/quickstart/example/index.ts new file mode 100644 index 00000000..8290eabe --- /dev/null +++ b/music/typescript/quickstart/example/index.ts @@ -0,0 +1,35 @@ +import "dotenv/config"; +import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; +import { createWriteStream } from "node:fs"; +import path from "node:path"; +import { Readable } from "node:stream"; +import { pipeline } from "node:stream/promises"; + +const DEFAULT_PROMPT = "A chill lo-fi beat with jazzy piano chords"; +const OUTPUT_FILE = "output.mp3"; + +async function main() { + const prompt = process.argv.slice(2).join(" ").trim() || DEFAULT_PROMPT; + const client = new ElevenLabsClient(); + + try { + const track = await client.music.compose({ + prompt, + musicLengthMs: 10_000, + }); + + const outputPath = path.resolve(process.cwd(), OUTPUT_FILE); + await pipeline( + Readable.from(track), + createWriteStream(outputPath), + ); + + console.log(`Wrote generated music to ${outputPath}`); + } catch (err) { + const message = err instanceof Error ? err.message : String(err); + console.error(`Music generation failed: ${message}`); + process.exitCode = 1; + } +} + +void main(); diff --git a/music/typescript/quickstart/example/package.json b/music/typescript/quickstart/example/package.json new file mode 100644 index 00000000..fc73e608 --- /dev/null +++ b/music/typescript/quickstart/example/package.json @@ -0,0 +1,15 @@ +{ + "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0", + "type": "module", + "scripts": { + "start": "tsx index.ts" + }, + "dependencies": { + "@elevenlabs/elevenlabs-js": "latest", + "dotenv": "latest" + }, + "devDependencies": { + "@types/node": "latest", + "tsx": "latest" + } +} diff --git a/music/typescript/quickstart/example/tsconfig.json b/music/typescript/quickstart/example/tsconfig.json new file mode 100644 index 00000000..3055bffc --- /dev/null +++ b/music/typescript/quickstart/example/tsconfig.json @@ -0,0 +1,10 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "types": ["node"], + "strict": true, + "skipLibCheck": true + } +} diff --git a/music/typescript/quickstart/setup.sh b/music/typescript/quickstart/setup.sh new file mode 100755 index 00000000..43b7e490 --- /dev/null +++ b/music/typescript/quickstart/setup.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +set -euo pipefail + +DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$DIR/../../.." && pwd)" +cd "$DIR" + +# Clean example/ but preserve node_modules for speed +if [ -d example ]; then + find example -mindepth 1 -maxdepth 1 ! -name node_modules -exec rm -rf {} + +fi +mkdir -p example + +# Copy shared template into example/ +rsync -a \ + --exclude node_modules \ + --exclude pnpm-lock.yaml --exclude package-lock.json \ + --exclude example \ + "$REPO_ROOT/templates/typescript/" example/ + +# Copy project-specific README +cp README.md example/README.md + +# Setup env +if [ -f "$DIR/.env" ]; then + cp "$DIR/.env" example/.env +fi + +# Install dependencies +cd example +pnpm install --config.confirmModulesPurge=false diff --git a/templates/typescript/package.json b/templates/typescript/package.json index af845469..fc73e608 100644 --- a/templates/typescript/package.json +++ b/templates/typescript/package.json @@ -9,6 +9,7 @@ "dotenv": "latest" }, "devDependencies": { + "@types/node": "latest", "tsx": "latest" } } diff --git a/templates/typescript/tsconfig.json b/templates/typescript/tsconfig.json new file mode 100644 index 00000000..3055bffc --- /dev/null +++ b/templates/typescript/tsconfig.json @@ -0,0 +1,10 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "types": ["node"], + "strict": true, + "skipLibCheck": true + } +} From ee4ea0f953bae546b46243715d994bcf45e7ab62 Mon Sep 17 00:00:00 2001 From: Tadas Petra <60107328+tadaspetra@users.noreply.github.com> Date: Sat, 28 Mar 2026 10:17:51 -0500 Subject: [PATCH 03/20] sound effect examples --- README.md | 4 +- sound-effects/nextjs/quickstart/PROMPT.md | 22 + sound-effects/nextjs/quickstart/README.md | 33 ++ .../nextjs/quickstart/example/.env.example | 1 + .../nextjs/quickstart/example/README.md | 33 ++ .../example/app/api/generate-sound/route.ts | 64 ++ .../nextjs/quickstart/example/app/favicon.ico | Bin 0 -> 25931 bytes .../nextjs/quickstart/example/app/globals.css | 126 ++++ .../nextjs/quickstart/example/app/layout.tsx | 34 ++ .../nextjs/quickstart/example/app/page.tsx | 103 ++++ .../nextjs/quickstart/example/components.json | 23 + .../example/components/ui/live-waveform.tsx | 560 ++++++++++++++++++ .../quickstart/example/eslint.config.mjs | 18 + .../nextjs/quickstart/example/lib/utils.ts | 6 + .../nextjs/quickstart/example/next.config.ts | 13 + .../nextjs/quickstart/example/package.json | 34 ++ .../quickstart/example/postcss.config.mjs | 7 + .../nextjs/quickstart/example/public/file.svg | 1 + .../quickstart/example/public/globe.svg | 1 + .../nextjs/quickstart/example/public/next.svg | 1 + .../quickstart/example/public/vercel.svg | 1 + .../quickstart/example/public/window.svg | 1 + .../nextjs/quickstart/example/tsconfig.json | 34 ++ sound-effects/nextjs/quickstart/setup.sh | 43 ++ sound-effects/typescript/quickstart/PROMPT.md | 12 + sound-effects/typescript/quickstart/README.md | 27 + .../quickstart/example/.env.example | 1 + .../typescript/quickstart/example/README.md | 27 + .../typescript/quickstart/example/index.ts | 38 ++ .../typescript/quickstart/example/output.mp3 | Bin 0 -> 97010 bytes .../quickstart/example/package.json | 15 + .../quickstart/example/tsconfig.json | 10 + sound-effects/typescript/quickstart/setup.sh | 31 + 33 files changed, 1323 insertions(+), 1 deletion(-) create mode 100644 sound-effects/nextjs/quickstart/PROMPT.md create mode 100644 sound-effects/nextjs/quickstart/README.md create mode 100644 sound-effects/nextjs/quickstart/example/.env.example create mode 100644 sound-effects/nextjs/quickstart/example/README.md create mode 100644 sound-effects/nextjs/quickstart/example/app/api/generate-sound/route.ts create mode 100644 sound-effects/nextjs/quickstart/example/app/favicon.ico create mode 100644 sound-effects/nextjs/quickstart/example/app/globals.css create mode 100644 sound-effects/nextjs/quickstart/example/app/layout.tsx create mode 100644 sound-effects/nextjs/quickstart/example/app/page.tsx create mode 100644 sound-effects/nextjs/quickstart/example/components.json create mode 100644 sound-effects/nextjs/quickstart/example/components/ui/live-waveform.tsx create mode 100644 sound-effects/nextjs/quickstart/example/eslint.config.mjs create mode 100644 sound-effects/nextjs/quickstart/example/lib/utils.ts create mode 100644 sound-effects/nextjs/quickstart/example/next.config.ts create mode 100644 sound-effects/nextjs/quickstart/example/package.json create mode 100644 sound-effects/nextjs/quickstart/example/postcss.config.mjs create mode 100644 sound-effects/nextjs/quickstart/example/public/file.svg create mode 100644 sound-effects/nextjs/quickstart/example/public/globe.svg create mode 100644 sound-effects/nextjs/quickstart/example/public/next.svg create mode 100644 sound-effects/nextjs/quickstart/example/public/vercel.svg create mode 100644 sound-effects/nextjs/quickstart/example/public/window.svg create mode 100644 sound-effects/nextjs/quickstart/example/tsconfig.json create mode 100755 sound-effects/nextjs/quickstart/setup.sh create mode 100644 sound-effects/typescript/quickstart/PROMPT.md create mode 100644 sound-effects/typescript/quickstart/README.md create mode 100644 sound-effects/typescript/quickstart/example/.env.example create mode 100644 sound-effects/typescript/quickstart/example/README.md create mode 100644 sound-effects/typescript/quickstart/example/index.ts create mode 100644 sound-effects/typescript/quickstart/example/output.mp3 create mode 100644 sound-effects/typescript/quickstart/example/package.json create mode 100644 sound-effects/typescript/quickstart/example/tsconfig.json create mode 100755 sound-effects/typescript/quickstart/setup.sh diff --git a/README.md b/README.md index 85a1f12c..860c2b8b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ![ElevenLabs Examples Header](./examples-header.png) -Prompt-driven ElevenLabs examples for text-to-speech, speech-to-text, music, and agents. Each project includes: +Prompt-driven ElevenLabs examples for text-to-speech, speech-to-text, music, sound effects, and agents. Each project includes: - `PROMPT.md` — instructions for agent-driven generation - `setup.sh` — scaffolds the `example/` directory from a shared template @@ -17,6 +17,8 @@ Shared base templates live in `templates/` (Next.js, Python, TypeScript). UI sty - [Speech-to-Text Quickstart (TypeScript)](speech-to-text/typescript/quickstart/example/README.md) — Transcribe local audio files with Scribe v2. - [Speech-to-Text Quickstart (Python)](speech-to-text/python/quickstart/example/README.md) — Transcribe local audio files with Scribe v2. - [Music Quickstart (TypeScript)](music/typescript/quickstart/example/README.md) — Generate an MP3 track from a text prompt with the ElevenLabs JS SDK. +- [Sound Effects Quickstart (TypeScript)](sound-effects/typescript/quickstart/example/README.md) — Generate a sound effect MP3 from a text prompt with the ElevenLabs JS SDK. +- [Sound Effects Playground (Next.js)](sound-effects/nextjs/quickstart/example/README.md) — Enter a prompt, generate a sound effect, and play it back in the browser. - [Real-Time Speech-to-Text (Next.js)](speech-to-text/nextjs/realtime/example/README.md) — Live microphone transcription with VAD in a Next.js app. - [Real-Time Voice Agent (Next.js)](agents/nextjs/quickstart/example/README.md) — Live voice conversations with the ElevenLabs Agents Platform using the React Agents SDK. - [Voice Agent Guardrails Demo (Next.js)](agents/nextjs/guardrails/example/README.md) — Demonstrate custom guardrails and the `guardrail_triggered` client event in a live voice agent. diff --git a/sound-effects/nextjs/quickstart/PROMPT.md b/sound-effects/nextjs/quickstart/PROMPT.md new file mode 100644 index 00000000..0cae08dc --- /dev/null +++ b/sound-effects/nextjs/quickstart/PROMPT.md @@ -0,0 +1,22 @@ +Before writing any code, invoke the `/sound-effects` skill to learn the correct ElevenLabs SDK patterns. + +## 1. `app/api/generate-sound/route.ts` + +Secure POST endpoint that generates a sound effect from a text prompt. +Never expose `ELEVENLABS_API_KEY` to the client. + +- Read `{ prompt }` from the request body. +- Validate that the prompt is a non-empty string. +- Use `ElevenLabsClient` and call `client.textToSoundEffects.convert`. +- Return the generated MP3 stream from the server response. +- Return readable JSON errors for validation and API failures. + +## 2. `app/page.tsx` + +Simple sound-effects playground page. + +- Show a textarea for the prompt and a submit button. +- Call the API route from the client and handle loading, success, and error states. +- Convert the returned audio blob into an object URL and render an HTML audio player. +- Auto-clear the previous audio when starting a new request. +- Keep the UI minimal and easy to scan. diff --git a/sound-effects/nextjs/quickstart/README.md b/sound-effects/nextjs/quickstart/README.md new file mode 100644 index 00000000..53611438 --- /dev/null +++ b/sound-effects/nextjs/quickstart/README.md @@ -0,0 +1,33 @@ +# Sound Effects Playground (Next.js) + +Enter a prompt, generate a sound effect with the ElevenLabs Sound Effects API, and play it back in the browser. + +## Setup + +1. Copy the environment file and add your API key: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and paste your [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys). + +2. Install dependencies: + + ```bash + pnpm install + ``` + +## Run + +```bash +pnpm run dev +``` + +Open [http://localhost:3000](http://localhost:3000) in your browser. + +## Usage + +- Enter the sound effect you want to generate. +- Click **Generate sound effect**. +- Wait for the request to finish, then play the generated audio in the built-in player. diff --git a/sound-effects/nextjs/quickstart/example/.env.example b/sound-effects/nextjs/quickstart/example/.env.example new file mode 100644 index 00000000..4c49a949 --- /dev/null +++ b/sound-effects/nextjs/quickstart/example/.env.example @@ -0,0 +1 @@ +ELEVENLABS_API_KEY= diff --git a/sound-effects/nextjs/quickstart/example/README.md b/sound-effects/nextjs/quickstart/example/README.md new file mode 100644 index 00000000..53611438 --- /dev/null +++ b/sound-effects/nextjs/quickstart/example/README.md @@ -0,0 +1,33 @@ +# Sound Effects Playground (Next.js) + +Enter a prompt, generate a sound effect with the ElevenLabs Sound Effects API, and play it back in the browser. + +## Setup + +1. Copy the environment file and add your API key: + + ```bash + cp .env.example .env + ``` + + Then edit `.env` and paste your [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys). + +2. Install dependencies: + + ```bash + pnpm install + ``` + +## Run + +```bash +pnpm run dev +``` + +Open [http://localhost:3000](http://localhost:3000) in your browser. + +## Usage + +- Enter the sound effect you want to generate. +- Click **Generate sound effect**. +- Wait for the request to finish, then play the generated audio in the built-in player. diff --git a/sound-effects/nextjs/quickstart/example/app/api/generate-sound/route.ts b/sound-effects/nextjs/quickstart/example/app/api/generate-sound/route.ts new file mode 100644 index 00000000..884f9b54 --- /dev/null +++ b/sound-effects/nextjs/quickstart/example/app/api/generate-sound/route.ts @@ -0,0 +1,64 @@ +import { ElevenLabsClient, ElevenLabsError } from "@elevenlabs/elevenlabs-js"; +import { NextResponse } from "next/server"; + +export async function POST(request: Request) { + let body: unknown; + try { + body = await request.json(); + } catch { + return NextResponse.json( + { error: "Request body must be valid JSON." }, + { status: 400 }, + ); + } + + const prompt = + body && typeof body === "object" && "prompt" in body + ? (body as { prompt: unknown }).prompt + : undefined; + + if (typeof prompt !== "string" || prompt.trim().length === 0) { + return NextResponse.json( + { error: "prompt must be a non-empty string." }, + { status: 400 }, + ); + } + + const apiKey = process.env.ELEVENLABS_API_KEY; + if (!apiKey) { + return NextResponse.json( + { error: "Server is not configured with ELEVENLABS_API_KEY." }, + { status: 503 }, + ); + } + + const client = new ElevenLabsClient({ apiKey }); + + try { + const stream = await client.textToSoundEffects.convert({ + text: prompt.trim(), + }); + return new Response(stream, { + headers: { + "Content-Type": "audio/mpeg", + "Cache-Control": "no-store", + }, + }); + } catch (err) { + if (err instanceof ElevenLabsError) { + const status = err.statusCode ?? 502; + return NextResponse.json( + { + error: + err.message || + "The ElevenLabs API returned an error for this request.", + details: err.body, + }, + { status: status >= 400 && status < 600 ? status : 502 }, + ); + } + const message = + err instanceof Error ? err.message : "An unexpected error occurred."; + return NextResponse.json({ error: message }, { status: 502 }); + } +} diff --git a/sound-effects/nextjs/quickstart/example/app/favicon.ico b/sound-effects/nextjs/quickstart/example/app/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..718d6fea4835ec2d246af9800eddb7ffb276240c GIT binary patch literal 25931 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 LrJugUA?W`A8`#=m literal 0 HcmV?d00001 diff --git a/sound-effects/nextjs/quickstart/example/app/globals.css b/sound-effects/nextjs/quickstart/example/app/globals.css new file mode 100644 index 00000000..d767ad63 --- /dev/null +++ b/sound-effects/nextjs/quickstart/example/app/globals.css @@ -0,0 +1,126 @@ +@import "tailwindcss"; +@import "tw-animate-css"; +@import "shadcn/tailwind.css"; + +@custom-variant dark (&:is(.dark *)); + +@theme inline { + --color-background: var(--background); + --color-foreground: var(--foreground); + --font-sans: var(--font-geist-sans); + --font-mono: var(--font-geist-mono); + --color-sidebar-ring: var(--sidebar-ring); + --color-sidebar-border: var(--sidebar-border); + --color-sidebar-accent-foreground: var(--sidebar-accent-foreground); + --color-sidebar-accent: var(--sidebar-accent); + --color-sidebar-primary-foreground: var(--sidebar-primary-foreground); + --color-sidebar-primary: var(--sidebar-primary); + --color-sidebar-foreground: var(--sidebar-foreground); + --color-sidebar: var(--sidebar); + --color-chart-5: var(--chart-5); + --color-chart-4: var(--chart-4); + --color-chart-3: var(--chart-3); + --color-chart-2: var(--chart-2); + --color-chart-1: var(--chart-1); + --color-ring: var(--ring); + --color-input: var(--input); + --color-border: var(--border); + --color-destructive: var(--destructive); + --color-accent-foreground: var(--accent-foreground); + --color-accent: var(--accent); + --color-muted-foreground: var(--muted-foreground); + --color-muted: var(--muted); + --color-secondary-foreground: var(--secondary-foreground); + --color-secondary: var(--secondary); + --color-primary-foreground: var(--primary-foreground); + --color-primary: var(--primary); + --color-popover-foreground: var(--popover-foreground); + --color-popover: var(--popover); + --color-card-foreground: var(--card-foreground); + --color-card: var(--card); + --radius-sm: calc(var(--radius) - 4px); + --radius-md: calc(var(--radius) - 2px); + --radius-lg: var(--radius); + --radius-xl: calc(var(--radius) + 4px); + --radius-2xl: calc(var(--radius) + 8px); + --radius-3xl: calc(var(--radius) + 12px); + --radius-4xl: calc(var(--radius) + 16px); +} + +:root { + --radius: 0.625rem; + --background: oklch(1 0 0); + --foreground: oklch(0.145 0 0); + --card: oklch(1 0 0); + --card-foreground: oklch(0.145 0 0); + --popover: oklch(1 0 0); + --popover-foreground: oklch(0.145 0 0); + --primary: oklch(0.205 0 0); + --primary-foreground: oklch(0.985 0 0); + --secondary: oklch(0.97 0 0); + --secondary-foreground: oklch(0.205 0 0); + --muted: oklch(0.97 0 0); + --muted-foreground: oklch(0.556 0 0); + --accent: oklch(0.97 0 0); + --accent-foreground: oklch(0.205 0 0); + --destructive: oklch(0.577 0.245 27.325); + --border: oklch(0.922 0 0); + --input: oklch(0.922 0 0); + --ring: oklch(0.708 0 0); + --chart-1: oklch(0.646 0.222 41.116); + --chart-2: oklch(0.6 0.118 184.704); + --chart-3: oklch(0.398 0.07 227.392); + --chart-4: oklch(0.828 0.189 84.429); + --chart-5: oklch(0.769 0.188 70.08); + --sidebar: oklch(0.985 0 0); + --sidebar-foreground: oklch(0.145 0 0); + --sidebar-primary: oklch(0.205 0 0); + --sidebar-primary-foreground: oklch(0.985 0 0); + --sidebar-accent: oklch(0.97 0 0); + --sidebar-accent-foreground: oklch(0.205 0 0); + --sidebar-border: oklch(0.922 0 0); + --sidebar-ring: oklch(0.708 0 0); +} + +.dark { + --background: oklch(0.145 0 0); + --foreground: oklch(0.985 0 0); + --card: oklch(0.205 0 0); + --card-foreground: oklch(0.985 0 0); + --popover: oklch(0.205 0 0); + --popover-foreground: oklch(0.985 0 0); + --primary: oklch(0.922 0 0); + --primary-foreground: oklch(0.205 0 0); + --secondary: oklch(0.269 0 0); + --secondary-foreground: oklch(0.985 0 0); + --muted: oklch(0.269 0 0); + --muted-foreground: oklch(0.708 0 0); + --accent: oklch(0.269 0 0); + --accent-foreground: oklch(0.985 0 0); + --destructive: oklch(0.704 0.191 22.216); + --border: oklch(1 0 0 / 10%); + --input: oklch(1 0 0 / 15%); + --ring: oklch(0.556 0 0); + --chart-1: oklch(0.488 0.243 264.376); + --chart-2: oklch(0.696 0.17 162.48); + --chart-3: oklch(0.769 0.188 70.08); + --chart-4: oklch(0.627 0.265 303.9); + --chart-5: oklch(0.645 0.246 16.439); + --sidebar: oklch(0.205 0 0); + --sidebar-foreground: oklch(0.985 0 0); + --sidebar-primary: oklch(0.488 0.243 264.376); + --sidebar-primary-foreground: oklch(0.985 0 0); + --sidebar-accent: oklch(0.269 0 0); + --sidebar-accent-foreground: oklch(0.985 0 0); + --sidebar-border: oklch(1 0 0 / 10%); + --sidebar-ring: oklch(0.556 0 0); +} + +@layer base { + * { + @apply border-border outline-ring/50; + } + body { + @apply bg-background text-foreground; + } +} diff --git a/sound-effects/nextjs/quickstart/example/app/layout.tsx b/sound-effects/nextjs/quickstart/example/app/layout.tsx new file mode 100644 index 00000000..f7fa87eb --- /dev/null +++ b/sound-effects/nextjs/quickstart/example/app/layout.tsx @@ -0,0 +1,34 @@ +import type { Metadata } from "next"; +import { Geist, Geist_Mono } from "next/font/google"; +import "./globals.css"; + +const geistSans = Geist({ + variable: "--font-geist-sans", + subsets: ["latin"], +}); + +const geistMono = Geist_Mono({ + variable: "--font-geist-mono", + subsets: ["latin"], +}); + +export const metadata: Metadata = { + title: "Create Next App", + description: "Generated by create next app", +}; + +export default function RootLayout({ + children, +}: Readonly<{ + children: React.ReactNode; +}>) { + return ( + + + {children} + + + ); +} diff --git a/sound-effects/nextjs/quickstart/example/app/page.tsx b/sound-effects/nextjs/quickstart/example/app/page.tsx new file mode 100644 index 00000000..9926ac1d --- /dev/null +++ b/sound-effects/nextjs/quickstart/example/app/page.tsx @@ -0,0 +1,103 @@ +"use client"; + +import { useEffect, useState } from "react"; + +export default function Home() { + const [prompt, setPrompt] = useState(""); + const [audioUrl, setAudioUrl] = useState(null); + const [loading, setLoading] = useState(false); + const [error, setError] = useState(null); + + useEffect(() => { + return () => { + if (audioUrl) URL.revokeObjectURL(audioUrl); + }; + }, [audioUrl]); + + async function handleSubmit(e: React.FormEvent) { + e.preventDefault(); + setError(null); + if (audioUrl) { + URL.revokeObjectURL(audioUrl); + setAudioUrl(null); + } + setLoading(true); + try { + const res = await fetch("/api/generate-sound", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ prompt }), + }); + const contentType = res.headers.get("Content-Type") ?? ""; + if (!res.ok) { + if (contentType.includes("application/json")) { + const data = (await res.json()) as { error?: string }; + throw new Error(data.error ?? `Request failed (${res.status})`); + } + throw new Error(`Request failed (${res.status})`); + } + const blob = await res.blob(); + setAudioUrl(URL.createObjectURL(blob)); + } catch (err) { + setError(err instanceof Error ? err.message : "Something went wrong."); + } finally { + setLoading(false); + } + } + + return ( +
+
+
+

+ Sound effects +

+

+ Describe a sound and generate it with ElevenLabs. +

+
+ +
+
+ +