CastReader

View saved version →

---
name: build-voice-app
description: Build and verify a working text-to-speech feature using CastReader Voice API. Use for adding speech, narration, audio lessons or generated voice files to an application, with server-side credentials and restartable jobs.
---

# Build a voice feature

Deliver runnable code in the user's chosen stack and verify the actual flow through audio playback. The plugin root is two directories above this file.

## Current contract

Read `https://voice.castreader.com/integration-manifest.json` and the relevant part of `https://voice.castreader.com/openapi.json`; `https://voice.castreader.com/llms-full.txt` provides integration context. Paths in OpenAPI can be disabled: check `x-enabled` and the manifest. Current queued input limit is 500 normalized Unicode code points; short `/audio/speech` is 120. Streaming and realtime are disabled. Select the spoken language explicitly; language selection does not translate text.

Use a server-side `CASTREADER_API_KEY` supplied through the environment. Never request secrets in chat or put them in browser code, logs, URLs or version control. Activation is at `https://voice.castreader.com/request-access`; App Pro does not fund API usage.

## Deliver the application

For a new Node.js project, run:

```sh
node <plugin-root>/scripts/create-app.mjs /absolute/path/to/new-voice-app
```

The starter is a working audio-card app with editable text, language and voice selection, estimates, playback, downloads and persistent batches. Read its `README.md`. Run `npm install`, set the server environment, then `npm start`. Its dependency uses the versioned official SDK download; do not substitute an unpublished npm package name. Node.js 22+ is required.

For an existing application, adapt to its framework. Use the starter's `server.mjs` and `generate.mjs` as examples; preserve the user's project. For single audio jobs, copy or import the dependency-free `scripts/voice.mjs` implementation. Keep credentials and synthesis on the backend. Return controlled audio bytes or a protected application-owned result URL to the player. Add input validation and reuse account authorization before exposing a paid endpoint publicly. The starter binds to loopback and is not a public multiuser deployment template.

Resolve `https://voice.castreader.com/v1/route`, then pin work to the resource region. The accepted service bases are `https://voice.castreader.com/v1` and `https://api.castreader.cn/voice-api/v1`. Use SDK 0.2.3 or newer. Saved jobs on the retired China hostname are migrated by the bundled CLI without changing their job or idempotency identity. Use an authorized, ready `voice_...` ID from the account's regional list; catalog IDs and display names are not voice IDs. Voice listing may initialize builtin workspace references without synthesis.

Estimate actual input, display estimated charge and trial usage, and respect the budget. Save the body and idempotency key before POST, then the returned job ID. Continue that job after timeout. Missing downloads are download retries. Never silently create new paid requests for failed, expired or cancelled jobs. Save results within the current retention window (24 hours).

## Verify and hand over

Run relevant application checks, launch it, and inspect the user-facing flow. When credentials and the user's generation authorization are present, test one short clip and verify a decodable file, charge receipt and same-job recovery. Use the user's budget; otherwise disclose a small estimate before the authorized generation. Never top up or change subscriptions.

Without a key, complete and test the local app and use clearly labeled existing public samples only when useful. State that live synthesis is unverified; never label a saved sample as newly generated. Report the start command, behavior, test evidence, actual charge and remaining configuration.

Referenced files: 1

View saved version →

---
name: generate-audio
description: Generate playable MP3 or WAV files from text with CastReader, report estimated and actual API charges, and resume interrupted audio jobs without duplicate generation. Use when the user wants audio output or recovery of a CastReader job.
---

# Generate and recover audio

Use Node.js 22+ and `<plugin-root>/scripts/voice.mjs`, two directories above this skill. The output folder contains private input and job state; keep it outside source control. `CASTREADER_API_KEY` belongs in the environment, never in chat, URLs or CLI flags.

## Generate

1. Write UTF-8 `input.json` with the user's `text`, explicit spoken `language`, optional `voice_id` and `output_format` (`mp3` default, or `wav`). Default voice selection uses the account's ready narrator. Do not invent voice IDs. Inspect ready voices with `node <plugin-root>/scripts/voice.mjs voices`.
2. Read current capabilities using `node <plugin-root>/scripts/voice.mjs capabilities`. Current per-job limit: 500 normalized Unicode code points. For longer text, create serial chunk plans with stable folders and a total budget; do not silently omit or summarize. Do not offer realtime or streaming when disabled.
3. Use the user's budget. For a short audio request without a budget, disclose the live estimate and use a conservative $0.01 per-clip ceiling; a request to generate already authorizes ordinary generation within that ceiling. Ask only when a stated limit is exceeded or a materially larger task needs a larger budget.

```sh
node <plugin-root>/scripts/voice.mjs plan --input /absolute/input.json --output /absolute/audio-run --max-usd 0.01
node <plugin-root>/scripts/voice.mjs run --output /absolute/audio-run --wait-ms 45000
```

`plan` routes, checks voices and estimates without synthesis. Its maximum is a current price/balance estimate, not a reserved quote. `run` rechecks before submission. Report the estimate before generating. API trial/wallet are separate from App Pro. Never top up, buy or change subscriptions.

4. Verify successful files with an available audio inspector such as `ffprobe`, and render the absolute local path: `![Generated audio](/absolute/audio-run/audio.mp3)`. Include actual `chargedUSD` and trial characters. `receipt.json` records bytes and SHA-256; private `state.json` preserves recovery identity. File validation does not prove pronunciation quality.

## Resume

```sh
node <plugin-root>/scripts/voice.mjs resume --output /absolute/audio-run --wait-ms 45000
```

For `pending`, retain the folder and resume after the suggested delay. Uncertain submissions reuse the original body and idempotency key. Known jobs are only polled. Verified local files are reused without API calls; missing or damaged bytes are redownloaded from the same job. Respect Retry-After. Do not switch regions, keys, voices or input to force a retry.

For `failed`, `cancelled` or `expired`, report status and charge. Deliberate new generation needs a new plan within the user's authorization. For `output_locked`, inspect the PID in `.lock`; remove the lock only after verifying the earlier process is gone. Keep `state.json` intact; never reset it to resolve an error.

English alignment is optional (`return_timestamps: true`) and can be unavailable even when audio succeeds. Keep segment-relative times and processed text; never invent timestamps or claim other-language alignment. Successful audio remains billable without alignment.

Without a configured key, preserve the requested input and link to `https://voice.castreader.com/console` for setup. Never borrow another account's credentials or claim a prerecorded demo was freshly generated.

Referenced files: 1

View saved version →

---
name: read-answer
description: Read a Codex answer aloud with CastReader in the right-side reading page, preserving Markdown formatting and highlighting spoken words. Use for 朗读刚才的回答, read this answer aloud, or synchronized answer reading. Requires CastReader login; uses daily free minutes or existing Pro, not a developer API key.
---

# Read a Codex answer

Use the CastReader membership reading page in Codex's right-side browser. This workflow is separate from the developer Voice API used by build-voice-app and generate-audio. Never ask for CASTREADER_API_KEY, a developer wallet top-up, or a per-character budget for membership answer reading.

## Preserve the answer

1. Resolve the requested text from visible conversation context:
   - If the user asks to write an answer and then read it, first write that answer visibly in the requested language, then use that exact Markdown for reading in the same turn. This works in a new conversation without a previous answer.
   - Otherwise use the answer or text the user selects or supplies; for “read your previous answer,” use the complete most recent substantive assistant answer before the request.
   - If the requested previous answer is absent, explain that this conversation has no available source and offer either supplying the text or generating a short English demo. Do not invent a previous answer, read this clarification instead, or search unrelated conversations. A request to read existing text does not authorize replacing it with a demo.
   Do not read hidden reasoning, system messages, unrelated history or tool logs.
2. Save the **exact original Markdown** in a private local `.md` file outside source control. Preserve headings, paragraphs, numbered and nested lists, emphasis, links, tables, blockquotes and code fences. Do not strip styling, summarize, translate, rewrite tables or remove code blocks. Do not scrape or patch the Codex application renderer.
3. The initial synchronized-reading preview supports English. If the selected answer is another language, explain that reliable alignment is not ready for that language; do not generate unaligned audio or translate without a request. The full source must fit 120 KB; do not silently truncate a longer answer.

## Automatically open and read

The plugin root is two directories above this skill. Run:

```bash
node <plugin-root>/scripts/read-answer.mjs --markdown /absolute/private/answer.md --language en --title "Codex answer"
```

Keep the returned local server process running while opening the short `url` from its JSON output. The handoff is bound to loopback and expires after fifteen minutes; it does not serve the workspace. It redirects to the CastReader reader with the full Markdown in a URL fragment, which is removed immediately and saved only in that tab. Only individual spoken segments are sent to the consumer TTS service.

Use the available Codex `open_in_codex` tool with `placement: "right"`, `target.type: "browser"` and this URL. If an in-app browser tab is already under control, navigate that tab then open its verified provider tab ID on the right. Do not stop at handing the user a link or require them to copy and paste the answer.

The page checks the real CastReader session and membership before speech. An existing login automatically starts reading. If browser autoplay is blocked, use the visible **开始朗读** button through the supported browser tool, since the user's read-aloud request authorizes playback. Never alter account state or fabricate entitlement through page scripts.

If login is required, leave the formatted answer visible and have the user complete CastReader Google login. Credentials and verification remain with the user. The same tab returns to the answer after login and preserves its position. Do not request another account solely for the plugin.

## Quota, subscription and recovery

- Reuse the canonical CastReader consumer account, server-enforced twenty free AI voice minutes per local day, and Pro unlimited ordinary reading. Reading minutes count actual playback time, excluding pause and buffering. Cached replay avoids another synthesis but still counts listening time for Free accounts.
- The free speed ceiling is 1.25×; higher speeds require Pro. Voice cloning has separate rules and is not offered by this reader.
- When the service reports exhausted quota, display the existing CastReader subscription page. The user chooses and completes purchase. A payment success URL is not proof of Pro: resume only after the authenticated membership endpoint verifies entitlement.
- Keep exact source, current segment, playback position and account-bound audio cache across login/checkout return and refresh. Never automatically retry an ambiguous in-flight synthesis; the page preserves its pending marker to prevent duplicate generation.
- Do not use the developer Voice API as a fallback around login or the daily allowance. Do not top up, buy or change subscriptions on the user's behalf merely because they asked for reading.

## Verify before reporting success

Observe the selected answer's formatting, actual audio playback, and a corresponding highlighted word in the **right-side reading page**. Highlighter timing must follow audio.currentTime, including pause, seek and speed changes. No guessed timings, plain audio-only fallback or claims of original-chat DOM highlighting.

If the page reports unavailable timing, mismatched words, failed login or failed synthesis, describe the actual blocker and preserve the answer. A working local fixture is not proof of successful production membership or payment. Public plugin availability and this test build must remain clearly distinguished.

Referenced files: 1