SpeakTrue

Generate Speech to Soundboard Workflow Target

Status

Implemented. This document is the acceptance-contract and regression reference for the legacy web generate-to-Soundboard workflow; it is not an open implementation plan.

Reader and post-read action

This brief is for an engineer maintaining the implemented S02 product workflow. After reading it, the engineer should preserve and verify the end-to-end path where generated speech is saved into Soundboard and can be reloaded for reuse without reopening discovery.

Initial surface decision

The implemented R045 and R046 surface is the legacy web main TTS screen plus the legacy web Soundboard. This surface has the text-to-speech API, the save-to-Soundboard API, the browser save modal, Soundboard category loading, pytest coverage, and the storage-provider seam that proves the user-visible workflow.

Native parity, storage-provider migration execution, and additional speech surfaces are downstream work. They should consume the acceptance contract proven here rather than expand this slice into another platform inventory.

Current evidence files

Only these tracked files are needed for S02 implementation targeting:

• web/python-web-app/src/routes/tts.py exposes POST /api/text-to-speech and delegates generation to the service layer.
• web/python-web-app/src/services/tts_service.py allocates a generated speech artifact, persists its immutable generation-settings sidecar, and returns artifact_id, audio_path, download_path, and clip_metadata on successful generation.
• web/python-web-app/src/routes/legacy.py exposes POST /api/soundboard/save-clip; the route delegates through legacy_route_dependencies to soundboard_route_service.save_clip_to_soundboard, which requires text plus an artifact reference, uploads audio/text/metadata assets, persists clip ordering, and invalidates category cache.
• web/python-web-app/static/js/index_speech.js owns the browser generate-and-save modal flow. It retains the canonical generated artifact and submits artifact_id, artifact_path, audio_path, download_path, text, category, format, bitrate, normalization, and bounded metadata to the save endpoint.
• web/python-web-app/static/js/index_soundboard.js owns Soundboard category load, clip render, play, download, and reload/reuse behavior.
• web/python-web-app/tests/api/test_tts_soundboard_workflow_target.py and web/python-web-app/tests/js/tts_soundboard_workflow_runtime_check.mjs prove the API and browser artifact handoff, success path, structured failures, stale-artifact protection, and reload notification contract.

Exact user workflow

1. The user opens the legacy web main TTS surface.
2. The user enters text and generates speech through POST /api/text-to-speech.
3. A successful response returns a playable generated artifact with audio_path and the immutable metadata snapshot captured when that exact audio was generated.
4. The browser stores the latest generated artifact reference for the active TTS result.
5. The user opens the Save to Soundboard modal, chooses a category, and submits POST /api/soundboard/save-clip.
6. The save request includes the category, source text, requested format options, and the generated artifact reference as audio_path or artifact_path.
7. The backend resolves the artifact from the tracked local/static artifact path, uploads audio and text assets to the provider-backed Soundboard path, persists clip-order metadata, and returns success metadata.
8. The Soundboard category can be reloaded and the saved clip can be played, downloaded, reordered where supported, and reused from the Soundboard UI.

Backend and API acceptance criteria

R045 — Generate speech artifact handoff

Success criteria:

• POST /api/text-to-speech returns a structured success payload that includes artifact_id, audio_path, and download_path for the generated audio artifact.
• Every successful artifact has a persisted generation snapshot containing the provider-facing voice, model, and supported voice settings; streamed web artifacts use an adjacent .metadata.json sidecar and Supabase artifacts use generation_artifacts.metadata.
• The returned audio_path or equivalent artifact reference is stable enough for a subsequent POST /api/soundboard/save-clip request in the same browser workflow.
• The save endpoint accepts the generated artifact reference through artifact_path or audio_path and resolves it through the server-side artifact/download path rules.
• Soundboard save prefers the server-persisted artifact snapshot over client-supplied settings, so changing controls after generation cannot rewrite the clip’s generation history.

Failure criteria:

• Missing generated text, overlong text, provider generation failure, missing artifact reference, and missing text must return structured error responses rather than silent UI failure.
• A save request that omits the artifact reference must fail with SPEECH_ARTIFACT_REFERENCE_REQUIRED.
• A save request whose artifact reference cannot be resolved must fail with a structured SPEECH_ARTIFACT_NOT_FOUND response.

R046 — Save generated speech for Soundboard reuse

Success criteria:

• POST /api/soundboard/save-clip uploads the generated audio to the selected Soundboard category using the configured storage provider path.
• The save path writes the text sidecar, updates or seeds clip-order metadata, and invalidates category cache so reload observes the new clip.
• The saved clip appears after Soundboard reload with enough metadata for play, download, and reuse from the existing Soundboard controls.

Failure criteria:

• Unsupported output format, invalid bitrate, missing storage backend, audio upload failure, text upload failure, and clip-order persistence failure must return explicit non-success responses.
• Provider upload and rollback failures must remain diagnosable through server logs and response error messages.
• Cache invalidation failure must be logged but must not make a successfully saved clip look like a failed save.

UI acceptance criteria

Success criteria:

• The browser keeps the latest successful /api/text-to-speech artifact reference separate from the text input value.
• The Save to Soundboard request body includes audio_path or artifact_path from the latest generated response, plus category, text, format, bitrate, and normalize options.
• After a successful save, the UI shows a success toast and notifies the Soundboard category so reload/reuse can surface the new clip.
• Reloading the selected Soundboard category displays the saved clip and preserves existing play, download, and category actions.

Failure criteria:

• If generation has not produced an artifact yet, the Save to Soundboard action must not submit a request that is missing audio_path or artifact_path.
• If the save endpoint returns SPEECH_ARTIFACT_REFERENCE_REQUIRED, SPEECH_ARTIFACT_NOT_FOUND, or another structured error, the UI must show a clear failure toast and reset the Save button state.
• Switching categories or reopening the modal must not reuse a stale artifact from a previous failed generation.

Failure and error acceptance

• Generation validation errors remain visible as structured /api/text-to-speech failures.
• Save validation errors remain visible as structured /api/soundboard/save-clip failures.
• Artifact handoff bugs are treated as product failures: a user who heard the generated audio must be able to save that exact artifact, not a regenerated or implicit global last-output file.
• The implementation must preserve explicit error codes for future tests and diagnostics, including SPEECH_RUNTIME_ERROR, SPEECH_ARTIFACT_REFERENCE_REQUIRED, and SPEECH_ARTIFACT_NOT_FOUND.

Observability and diagnostics

Future agents must be able to inspect the workflow through pytest failures and runtime diagnostics. Preserve these observable fields and signals:

• /api/text-to-speech success payload: artifact_id, audio_path, download_path, and clip_metadata.
• /api/soundboard/save-clip request payload: category, text, and audio_path or artifact_path.
• Save backend diagnostics: operation name save-clip-to-soundboard, structured speech error codes, provider upload path, text sidecar path, clip-order update result, and cache invalidation log.
• Soundboard reload metadata: category identifier, clip filename, clip name, audio URL, text URL where available, duration where available, and reload/reuse state.

Explicit non-goals

• Do not implement native iOS or Android parity in S02.
• Do not execute the storage migration or change the selected storage provider as part of this workflow target.
• Do not remap the whole speech, Soundboard, storage, or native feature inventory.
• Do not replace the legacy web main TTS screen or Soundboard with a new surface before proving this workflow.
• Do not rely on ignored local planning artifacts, generated static artifacts, or real environment secrets for acceptance tests.