Every 🔊 button on a language-learning page is either a real recorded voice or the flat, robotic one built into the browser — and most sites never get past the second one. AI agents can now generate studio-quality narration for hundreds of words and sentences in one sitting, and wire it into your page so it plays back reliably, everywhere. This lesson covers the whole pipeline: generating the clips, keeping them organized, hosting them, and never leaving a button silent.
語言學習頁面上的 🔊 按鈕，不是播放真人錄音，就是播放瀏覽器內建那種呆板的機器聲——大部分網站從來沒有跨過第二種。現在 AI agent 可以一次幫你生成幾百則單字、例句的錄音室等級配音，並把它接進你的頁面、確保任何裝置上都能穩定播放。這堂課涵蓋整條流程：生成音檔、把它們管好、放到哪裡、以及永遠不讓按鈕啞掉。
A browser's built-in speechSynthesis voice is free and instant, but it sounds exactly like what it is — a device reading text out loud. Neural text-to-speech sounds like a real person, and an AI agent can now generate it in bulk, name the files sensibly, and wire it into a page the same way it writes and edits any other code.瀏覽器內建的 speechSynthesis 語音免費又即時，但聽起來就是那個樣子——一台裝置在照著文字唸。神經網路語音聽起來像真人，而現在 AI agent 可以幫你大量生成、把檔案命名得井然有序，再把它接進頁面裡——手法跟它寫、改任何其他程式碼是同一套邏輯。
The free tool that actually turns text into spoken audio. Your agent runs it for you.
真正把文字轉成語音的免費工具，你的 agent 幫你操作它。
A studio-quality AI voice, not the flat, robotic one built into a browser.
錄音室等級的 AI 語音，不是瀏覽器內建那種呆板的機器聲。
A simple text-to-filename lookup table your page checks before it plays anything.
一份「文字對應檔名」的查詢表，網頁播放前會先查這裡。
A short fixed code generated from the text itself — the same sentence always gets the same filename.
從文字內容本身算出的一段固定代碼——同一句話永遠對應同一個檔名。
If a clip is missing, the button quietly falls back to the device's own voice instead of staying silent.
萬一某個音檔漏生成，按鈕會悄悄退回裝置本身的語音，而不是完全沒反應。
Wherever the finished audio files live so your page can fetch them by URL.
完成的音檔實際存放的地方，讓網頁能透過網址抓到它們。
Two things, installed once. After this, you'll never run a voice-generation command yourself — you'll just describe what you want to your agent, and it will run these tools on your behalf.兩個東西，裝一次就好。裝完之後你就不用自己下任何生成語音的指令了——你只要跟 agent 描述你想要什麼，它會替你操作以下工具。
brew install pipx in Terminal (get Homebrew first at brew.sh if you don't have it). On Windows, ask your agent to install it with pip install pipx instead.乾淨安裝 Python 命令列程式的工具。Mac 上在終端機打 brew install pipx（如果還沒裝 Homebrew，先到 brew.sh 複製安裝指令）。Windows 使用者可以請 agent 改用 pip install pipx 安裝。
pipx install edge-tts. This is the single most important install on this page — nothing below works without it.真正的語音引擎。執行 pipx install edge-tts。這是整頁最重要的一步——沒有它，下面所有事情都做不了。
npm install -g @anthropic-ai/claude-code, then run claude inside your project folder. The ChatGPT desktop app's agent mode can also open Terminal and drive edge-tts the same way — the prompts in this lesson work with either.這堂課主要以 Claude Code 為例——執行 npm install -g @anthropic-ai/claude-code 安裝，再到你的專案資料夾裡執行 claude 就能開始。ChatGPT 桌面版的 agent 模式同樣能開終端機、操作 edge-tts，原理相通——這堂課的提示詞兩邊都適用。
Set up the project folder建立專案資料夾
mkdir my-audio-project
cd my-audio-project
mkdir audio manifest
# list every word, sentence or question you want spoken —
# copy it straight out of your existing materials
claudeDon't name files by line number or lesson order — the moment your materials get reordered or revised, the filenames stop matching. Name each file after a short hash of its own text instead: the same sentence always maps to the same file, and the same word repeated across ten lessons only ever gets generated once.不要用行號或課程順序當檔名——教材一旦改版或重新排序，檔名馬上就對不上了。改用文字內容本身算出的一段短雜湊值當檔名：同一句話永遠對應同一個檔案，同一個單字在十課裡重複出現，也只會生成一次。
Ask your agent跟你的 agent 這樣說
"For every phrase in phrases.txt:
1. Generate an mp3 with edge-tts, voice en-US-AvaMultilingualNeural,
rate -8%, saved into audio/.
2. Name each file after a short hash of its own text, and skip it
if that file already exists.
3. Write manifest/lookup.json mapping every phrase to its filename."edge-tts isn't the only option — worth knowing what else is out there, even though this lesson's workflow is built around it:edge-tts 不是唯一選擇——雖然這堂課的流程是圍繞著它設計的，其他選項還是值得認識：
| Tool工具 | Best for適合用在 |
|---|---|
| edge-tts via your agent透過 agent 用 edge-tts | Free, batch-processes hundreds of phrases in one run, feeds directly into the rest of this workflow.免費、一次能批次處理上百則短句，還能直接接上這堂課後面的整套流程。 |
| Browser "Read Aloud"瀏覽器內建「大聲朗讀」 | Instant, zero setup — fine for previewing one sentence, not for a whole course.即時、免安裝——用來試聽一句話還行，不適合整套課程。 |
| Paid Azure / ElevenLabs API付費 Azure / ElevenLabs API | Officially licensed, guaranteed-stable voices when you need production reliability at real scale.正式授權、聲音穩定不會說變就變，適合需要長期大量正式使用的情況。 |
Every clip needs a public URL your page can fetch. Two free options cover almost every classroom situation — which one to pick depends only on how many clips you'll eventually have.每個音檔都需要一個網頁能抓得到的公開網址。兩個免費選項幾乎涵蓋所有教室情境——選哪個只看你最終大概會有多少則音檔。
gh command line uploads a whole folder in minutes. The catch: a hard cap of 1,000 files per release.如果你的網站本來就放在 GitHub 上，完全不用開新帳號——用 gh 指令列幾分鐘就能上傳一整個資料夾。代價是：單一 release 最多 1,000 個檔案的硬上限。
Every button follows the same three-step priority: check the lookup table, play the recording if it's there, and fall back to the device's own voice if it isn't. That way one missing clip never leaves a button silently dead.每顆按鈕都照同一套三步驟優先序：先查查詢表，查得到就播錄音，查不到就退回裝置本身的語音。這樣一來，漏生成一個音檔也不會讓某顆按鈕完全沒反應。
What your agent should build請 agent 幫你寫出這樣的邏輯
function say(text) {
const hash = manifest[text];
if (hash) {
playAudio(AUDIO_BASE + hash + ".mp3"); // found it — play the real recording
} else {
speechSynthesis.speak(text); // not found — fall back to the device voice
}
}Ask your agent跟你的 agent 這樣說
"Every element with a data-say attribute should call say() with its
own text when clicked. Load manifest/lookup.json once when the page
opens, and cache it — don't fetch it again on every click."Here's the order that works best — each step hands the next one exactly what it needs.照這個順序做效果最好——每一步都會準備好下一步需要的東西。
A full prompt you can copy and adapt一份可直接複製套用的完整指令
"I want to add narration audio to [page / lesson].
1. Pull every word, example sentence and quiz question worth
narrating out of the page content.
2. Generate an mp3 for each with edge-tts, voice
en-US-AvaMultilingualNeural, rate -8%. Name each file after a
short hash of its own text, and skip any that already exist.
3. Write a manifest mapping each phrase to its filename.
4. Upload every new clip to [GitHub Release / Cloudflare R2].
5. Wire up every 🔊 button so it checks the manifest, plays the
recording if found, and falls back to speechSynthesis if not.
6. List a few buttons for me to click and confirm before we're done."| Term術語 | Plain English白話說法 |
|---|---|
| TTS | Text-to-speech — any system that turns written text into spoken audio.Text-to-speech，把文字轉成語音的任何系統。 |
| edge-tts | A free command-line tool that generates neural voice mp3s from text.免費的命令列工具，能從文字生成神經網路語音的 mp3 檔。 |
| Neural voice神經網路語音 | An AI-generated voice that sounds like a real person, not a device reading text.AI 生成、聽起來像真人的語音，不是裝置在唸文字。 |
| Manifest | A text-to-filename lookup table the page checks before playing anything.網頁播放前會先查的「文字對應檔名」查詢表。 |
| Content hash內容雜湊 | A fixed code derived from the text itself, used as the filename — dedupes automatically.從文字本身算出的固定代碼，當作檔名使用——自動去重複。 |
| Fallback voice保底語音 | The device's own built-in voice, used only when a real recording is missing.裝置本身內建的語音，只有在真人錄音沒生成時才會用到。 |
| GitHub ReleaseGitHub Release | The fastest free place to host clips — capped at 1,000 files per release.最快上手的免費存放空間——單一 release 上限 1,000 個檔案。 |
| Cloudflare R2 | A hosting option with no file limit and free bandwidth, for larger or growing libraries.沒有檔案數量上限、免流量費的存放空間，適合規模較大或持續成長的教材庫。 |
Answer every question, then check your score. This grades itself right here in your browser — nothing is saved or sent anywhere.每一題都作答完，再檢查你的分數。這個測驗就在你的瀏覽器裡自動算分——什麼都不會被存起來或傳出去。