AlexandrAI AGENTS.md
agents-md

Gumroad TTS Voiceover Producer Agent Guide

Project-specific AGENTS.md guidance for the Gumroad TTS voiceover producer role, no-key draft voiceover, provider limits, silent fallback, and audio QA reporting.

AGENTS.md

Guidance for coding agents working on the Gumroad TTS voiceover producer role.

Project Overview

The TTS voiceover producer creates or validates draft audio for a published product trailer. It uses the final voiceover text, attempts the configured no-key provider when requested, saves audio beside the shorts package, and reports provider limits honestly.

Source Files

  • agents/tts-voiceover-producer.md defines the role.
  • skills/free-tts-voiceover/SKILL.md defines provider and failure rules.
  • scripts/shorts_artifacts.py render can create voiceover audio or a silent draft.
  • marketing/shorts//voiceover.txt is the input script.
  • marketing/shorts//voiceover.mp3 is created only when TTS succeeds.
  • marketing/shorts//captions.srt should exist even for silent drafts.
  • marketing/shorts//render_result.json records provider and failures.

Setup Commands

bashUV_LINK_MODE=copy UV_PROJECT_ENVIRONMENT="$HOME/.cache/gumroad-codex-agent-venv" uv run python scripts/shorts_artifacts.py render products/<slug> --tts edge
UV_LINK_MODE=copy UV_PROJECT_ENVIRONMENT="$HOME/.cache/gumroad-codex-agent-venv" uv run python scripts/shorts_artifacts.py render products/<slug> --tts none

Use the silent draft only when TTS is unavailable or intentionally skipped.

Change Rules For Agents

  • Use the final voiceover.txt.
  • Keep tone calm, direct, and consultant-like.
  • Do not use paid APIs or API keys without owner approval.
  • Do not clone or imitate a real person's voice.
  • Do not hide provider failures.
  • Do not claim voiceover.mp3 exists unless the file was created.
  • Keep captions available when rendering silent drafts.
  • Treat no-key TTS as a draft provider; verify licensing before scaling paid promotion.

Verification

Inspect render_result.json, verify voiceover.mp3 only when TTS succeeded, and run shorts QA afterward.

Security Notes

Do not expose paid provider credentials, voice cloning sources, private account ids, buyer data, local absolute paths, or hidden API configuration.

PR Checklist

  • Voiceover text exists.
  • Provider choice is recorded.
  • TTS failure is reported honestly.
  • Silent fallback is explicit.
  • Shorts QA passes after render.