From 22bff1bf6c91ff8490751775e9732333f4e70478 Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Mon, 19 Oct 2026 01:21:25 +0900
Subject: [PATCH 1/5] feat(sfx): add sound effects timed to the animation via
 ElevenLabs

---
 quality-baseline.json                 |   8 +-
 skills/motion-render/SKILL.md         |  57 ++++++-
 skills/motion-render/scripts/audio.ts | 121 ++++++++++----
 skills/motion-render/scripts/cli.ts   |  41 ++++-
 skills/motion-render/scripts/sfx.ts   | 190 +++++++++++++++++++++
 skills/motion-render/scripts/work.ts  |  68 +++++++-
 tests/audio.test.ts                   |  34 ++++
 tests/sfx.test.ts                     | 229 ++++++++++++++++++++++++++
 tests/work.test.ts                    |  89 +++++++++-
 9 files changed, 782 insertions(+), 55 deletions(-)
 create mode 100644 skills/motion-render/scripts/sfx.ts
 create mode 100644 tests/sfx.test.ts

diff --git a/quality-baseline.json b/quality-baseline.json
index 5c5ddae..87a5cfb 100644
--- a/quality-baseline.json
+++ b/quality-baseline.json
@@ -4,16 +4,16 @@
   "thresholds": {},
   "issues": [
     {
-      "id": "eslint|complexity|skills/motion-render/scripts/cli.ts|210|1",
+      "id": "eslint|complexity|skills/motion-render/scripts/cli.ts|157|1",
       "tool": "eslint",
       "category": "complexity",
       "path": "skills/motion-render/scripts/cli.ts",
-      "line": 210,
+      "line": 157,
       "column": 1,
-      "detail": "Async function 'main' has a complexity of 25. Maximum allowed is 20.",
+      "detail": "Async function 'main' has a complexity of 22. Maximum allowed is 20.",
       "metric": {
         "name": "complexity",
-        "value": 25,
+        "value": 22,
         "limit": 20,
         "direction": "lowerIsBetter"
       },
diff --git a/skills/motion-render/SKILL.md b/skills/motion-render/SKILL.md
index b07e366..16bcd2f 100644
--- a/skills/motion-render/SKILL.md
+++ b/skills/motion-render/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: motion-render
-description: テーマを渡されたら、それを説明するアニメーション動画を Claude Motion で作り、ナレーション（Gemini TTS）とテーマに合う BGM（Lyria）を付けて MP4 にする。「〇〇を説明する動画を作って」「〇〇の紹介動画」「/motion-render 〇〇」、既存の Motion の動画を MP4 にしたいときに使う。
+description: テーマを渡されたら、それを説明するアニメーション動画を Claude Motion で作り、ナレーション（Gemini TTS）とテーマに合う BGM（Lyria）、アニメーションに合わせた効果音（ElevenLabs）を付けて MP4 にする。「〇〇を説明する動画を作って」「〇〇の紹介動画」「/motion-render 〇〇」、既存の Motion の動画を MP4 にしたいときに使う。
 argument-hint: "<動画のテーマ。長さ・出力先などの指定があれば一緒に>"
 ---
 
@@ -9,7 +9,7 @@ argument-hint: "<動画のテーマ。長さ・出力先などの指定があれ
 `/motion-render <テーマ>` の一言で、テーマを説明するアニメーション動画を作り、ナレーションと BGM を付けて MP4 にする。
 
 **ナレーションと BGM は必ず付ける。** 音のない動画は作らない。既存の Motion の動画を MP4 にするときも、
-場面に合わせてナレーションを書き、BGM を作る。
+場面に合わせてナレーションを書き、BGM を作る。効果音は `ELEVENLABS_API_KEY` があるときだけ付ける（下の「効果音」）。
 
 ## 決め方: 聞かずに決める
 
@@ -37,7 +37,8 @@ Motion の Artifact 型は作成時に Style・Colors・Length を質問する
    Claude Code のプラグインとして入れ直すよう案内する（README の「インストール」。それで追加の作業は要らなくなる）。
    `Unknown file extension ".ts"` で止まるのは Node が 22.18 より古いため。Node の更新を案内する
 3. `GEMINI_API_KEY` が無いと `narrate`・`bgm` が止まる。止まったら、キーを Google AI Studio で発行して
-   シェルの設定に `export GEMINI_API_KEY=...` を足し、Claude Code を起動し直すよう案内する
+   シェルの設定に `export GEMINI_API_KEY=...` を足し、Claude Code を起動し直すよう案内する。
+   `test -n "$ELEVENLABS_API_KEY" && echo set` で効果音のキーの有無も見ておく（無ければ効果音を付けずに進める）
 4. `motion-render stills` などで Chromium が `bootstrap_check_in ... Permission denied` で起動しないのは、
    Claude Code の sandbox の中で動いているため。利用者に `~/.claude/settings.json` へ次を足すよう案内する
    （Claude は自分の権限設定を変えない）:
@@ -57,7 +58,7 @@ Motion の Artifact 型は作成時に Style・Colors・Length を質問する
 <work>/
   script.json   # 原稿（Claude が書く）
   timing.json   # 場面の秒数（narrate が書く）
-  audio/        # <場面id>.wav、bgm.mp3、mix.m4a
+  audio/        # <場面id>.wav、bgm.mp3、mix.m4a、sfx/（効果音と試聴用の preview.m4a）
   film/         # Motion から取得した映像データ（prepare が展開する）
 ```
 
@@ -69,7 +70,12 @@ Motion の Artifact 型は作成時に Style・Colors・Length を質問する
   "bgm": "Calm, focused electronic music for a cloud security explainer: soft pulsing synth, light percussion, 100 BPM",
   "scenes": [
     { "id": "title", "name": "タイトル", "narration": "ワークロードアイデンティティフェデレーションで、…" },
-    { "id": "token", "name": "トークン発行", "narration": "…" }
+    {
+      "id": "token",
+      "name": "トークン発行",
+      "narration": "…",
+      "sfx": [{ "at": 1.2, "prompt": "soft UI pop", "duration": 0.6 }]
+    }
   ]
 }
 ```
@@ -77,7 +83,8 @@ Motion の Artifact 型は作成時に Style・Colors・Length を質問する
 - `id` は英小文字・数字・`-`。Motion の場面の id と同じにする
 - `narration` は TTS に読ませる文。英語の固有名詞・略語はカタカナで書く（`GitHub Actions` → `ギットハブアクションズ`）。
   画面の文字は元の表記のまま
-- 任意: `voice`・`speed`・`bgmVolume`（既定 0.15）・`lead`・`tail`・`endHold`
+- 任意: `voice`・`speed`・`bgmVolume`（既定 0.15）・`sfxVolume`（既定 0.5）・`lead`・`tail`・`endHold`
+- 任意: 場面ごとの `sfx`。`at` は場面の頭からの秒、`duration` は 0.5〜10 秒（既定 1.5）、`volume` は 0〜1（既定 `sfxVolume`）
 
 ## 手順
 
@@ -107,7 +114,10 @@ motion-render narrate <work>
    - 質問はしない（上の「決め方」）
    - `scenes.json` の場面の `id`・`dur` は `timing.json` と同じにする
    - Motion 内蔵の BGM（`score.js`）は作らない。音はこのスキルが付ける
+   - 効果音を付けるときは、タイトルの場面に `🎧:11.ai` を小さく入れる（下の「効果音」）
 3. 並行して BGM を作ってよい: `motion-render bgm <work>`
+4. 効果音を付けるときは、場面ごとに「何秒目に何が出るか」を決めた値で `script.json` の `sfx` を書き、
+   `motion-render sfx <work>` で作る（下の「効果音」）
 
 ### 4. 映像データを取得して確認する
 
@@ -116,6 +126,8 @@ motion-render narrate <work>
 3. `motion-render prepare <work>/store <work>/film`
 4. `motion-render stills <work>/film <work>/stills <各場面の中ほどの秒をカンマ区切り>` で全場面を見る。
    見出しの不自然な改行、はみ出し、重なりがあれば Motion 側を直し、手順 4 をやり直す
+5. 効果音があれば、各効果音の秒（場面の開始 + `at`）の静止画も書き出し、鳴らす対象がその時点で画面に出ているかを見る。
+   ずれていれば `at` を直して `motion-render sfx` をやり直す（作り直されるのは変えたものだけ）
 
 ### 5. MP4 にする
 
@@ -123,12 +135,15 @@ motion-render narrate <work>
 motion-render build <work> [<出力.mp4>]
 ```
 
-ナレーションを各場面の頭に置き、BGM を一定の音量で重ねて MP4 にする。ナレーションか BGM が無いと止まる。
+ナレーションを各場面の頭に置き、BGM を一定の音量で重ね、効果音をそれぞれの秒に置いて MP4 にする。
+ナレーションか BGM、または `script.json` にある効果音が無いと止まる。
 
 ### 6. 確認して報告する
 
 - `ffprobe` で、長さと映像・音声の両トラックがあることを見る
 - 報告: 出力のパス、長さ、場面の流れ、BGM の雰囲気、Motion の URL。耳で聞いていないことは聞いていないと書く
+- 効果音を付けたときは、試聴用の `audio/sfx/preview.m4a` のパスと、その中の順番（`motion-render sfx` の出力）も報告し、
+  合わない音があれば教えてほしいと頼む。Claude には音の良し悪しが判定できないため、ここは人が聞いて決める
 
 ## BGM
 
@@ -144,6 +159,33 @@ motion-render build <work> [<出力.mp4>]
 利用者が BGM を「ださい」などと言ったら、`bgm` を書き直して `motion-render bgm` → `motion-render build` をやり直す。
 映像の描き直しは要らない（`build` は毎回描画するが、Motion 側の変更は不要）。
 
+## 効果音
+
+`ELEVENLABS_API_KEY` があるときだけ付ける。無ければ付けずに進め、報告で「効果音はキーが無いので付けていない」と書く。
+
+置き方:
+
+- 画面で目に見える出来事にだけ置く: カードが現れる、チップが着く、流れ図の段が光る、場面が切り替わる。
+  `at` は Motion の場面で、その動きが始まる秒にする（自分で書いたアニメーションの秒をそのまま使う）
+- 少なく: 1 場面 0〜2 個。毎回鳴る音は耳障りになる。同じ種類の出来事には同じ `prompt` と `duration` を使う
+  （音がそろい、同じものは 1 回しか作られない）
+- 短く: 0.5〜1.5 秒。長い上昇音・環境音・音楽・声は頼まない
+- `prompt` は英語で、柔らかさを指定する（`soft`・`subtle`・`gentle`）。ナレーションより前に出ないこと
+
+| 出来事             | `prompt` の例                    | `duration` |
+| ------------------ | -------------------------------- | ---------- |
+| カード・部品が出る | soft UI pop                      | 0.6        |
+| チップが移動する   | quick airy whoosh                | 0.8        |
+| 段が光る・強調     | gentle glassy chime              | 1.0        |
+| 完了・成功         | soft positive notification chime | 1.2        |
+
+`build` は、効果音ごとに音量を一定の水準にそろえ（生成される音は 30 dB 以上ばらつく）、`duration` で切り、
+両端をフェードしてからナレーションの下に混ぜる。無音で返ってきた効果音は `sfx` が作り直し、3 回とも無音なら止まる。
+
+**表記**: 月額プランなしで作った効果音は、商用に使えず、公開するときは題名に `elevenlabs.io` か `11.ai` を入れる
+（ElevenLabs のヘルプ「Can I publish the content I generate on the platform?」）。効果音を付けた動画では、
+タイトルの場面に `🎧:11.ai` を小さく入れる。利用者が月額プランに入っていると言った場合は省いてよい。
+
 ## 既存の Motion の動画を MP4 にするとき
 
 URL を渡された場合も音を付ける。映像データを取得し（手順 4）、`scenes.json` の場面ごとに、その秒数に収まる
@@ -155,6 +197,7 @@ URL を渡された場合も音を付ける。映像データを取得し（手
 
 - `scripts/cli.ts`: `motion-render` コマンド（TypeScript。Node 22.18 以上がそのまま実行する）
 - `scripts/audio.ts`: Gemini TTS・Lyria の呼び出し（90 秒の上限と再試行付き）と音声の合成
+- `scripts/sfx.ts`: ElevenLabs による効果音の生成（`sfx`）、音量の測定とそろえ方、試聴用ファイル
 - `scripts/work.ts`: `script.json` の検証、`timing.json` の計算、ナレーションを動画の場面の開始時刻に置く処理
 - `scripts/render.ts`: プレーヤーを開いてコマを返す。描画中は外部への通信を遮断し、Chromium の sandbox を有効にする
 - `scripts/json.ts`: ファイル・API・プレーヤーから来る JSON を、形を確かめながら読む
diff --git a/skills/motion-render/scripts/audio.ts b/skills/motion-render/scripts/audio.ts
index 200488e..22198f8 100644
--- a/skills/motion-render/scripts/audio.ts
+++ b/skills/motion-render/scripts/audio.ts
@@ -7,7 +7,7 @@ import { errorMessage, field, readJson } from "./json.ts";
 import type { Script } from "./work.ts";
 
 const API = "https://generativelanguage.googleapis.com/v1beta/models";
-const TIMEOUT_MS = 90_000; // a TTS request once hung for 15 minutes without this
+export const TIMEOUT_MS = 90_000; // a TTS request once hung for 15 minutes without this
 const RETRIES = 3;
 
 interface Audio {
@@ -15,10 +15,19 @@ interface Audio {
   data: Buffer;
 }
 
-// Where each scene's narration goes on the film timeline.
+// One sound effect on the film timeline. `gain` multiplies its volume (it already holds the leveling).
+export interface SfxTrack {
+  file: string;
+  start: number;
+  duration: number;
+  gain: number;
+}
+
+// Where each scene's narration and each sound effect go on the film timeline.
 export interface MixTiming {
   scenes: { id: string; start: number }[];
   total: number;
+  sfx?: SfxTrack[];
 }
 
 // ffmpeg-static downloads its binary in a postinstall script, which Claude Code's plugin dependency
@@ -51,7 +60,7 @@ export function findFfmpeg(): string {
   throw new Error("ffmpeg not found: install ffmpeg or set FFMPEG_PATH");
 }
 
-function runFfmpeg(args: string[]): Promise<void> {
+export function runFfmpeg(args: string[]): Promise<void> {
   return new Promise((ok, fail) => {
     const ff = spawn(findFfmpeg(), ["-y", "-loglevel", "error", ...args], {
       stdio: ["ignore", "inherit", "inherit"],
@@ -63,6 +72,44 @@ function runFfmpeg(args: string[]): Promise<void> {
   });
 }
 
+// Average and peak level of an audio file in dBFS (ffmpeg's volumedetect). Silence reads as -91 dB or lower.
+export function volumeStats(file: string): Promise<{ mean: number; max: number }> {
+  return new Promise((ok, fail) => {
+    const args = ["-hide_banner", "-nostats", "-i", file, "-af", "volumedetect", "-f", "null", "-"];
+    const ff = spawn(findFfmpeg(), args, { stdio: ["ignore", "ignore", "pipe"] });
+    let log = "";
+    ff.stderr?.on("data", (d: Buffer) => (log += d.toString()));
+    ff.on("error", fail);
+    ff.on("close", (code) => {
+      const level = (name: string): number => {
+        const v = new RegExp(`${name}: (-?[\\d.]+|-inf) dB`).exec(log)?.[1];
+        return v === "-inf" ? -120 : Number(v ?? NaN);
+      };
+      const mean = level("mean_volume"),
+        max = level("max_volume");
+      if (code !== 0 || !Number.isFinite(mean) || !Number.isFinite(max))
+        return fail(
+          new Error(`could not measure the level of ${file} (ffmpeg exited with ${code})`)
+        );
+      ok({ mean, max });
+    });
+  });
+}
+
+// Runs `attempt` up to RETRIES times, logging each failure under `label`, and rethrows the last error.
+export async function withRetries<T>(label: string, attempt: () => Promise<T>): Promise<T> {
+  let last: unknown;
+  for (let i = 1; i <= RETRIES; i++) {
+    try {
+      return await attempt();
+    } catch (e) {
+      last = e;
+      console.error(`motion-render: ${label} attempt ${i}/${RETRIES} failed: ${errorMessage(e)}`);
+    }
+  }
+  throw last;
+}
+
 // Picks the first inline audio part out of a generateContent response.
 function audioPart(json: unknown): { mimeType: string; data: string } | null {
   const candidates = field(json, "candidates");
@@ -82,33 +129,24 @@ function audioPart(json: unknown): { mimeType: string; data: string } | null {
 async function generateAudio(model: string, body: object): Promise<Audio> {
   const key = process.env.GEMINI_API_KEY;
   if (!key) throw new Error("GEMINI_API_KEY is not set (needed for narration and BGM)");
-  let last: unknown;
-  for (let attempt = 1; attempt <= RETRIES; attempt++) {
-    try {
-      const res = await fetch(`${API}/${model}:generateContent`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "x-goog-api-key": key },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(TIMEOUT_MS),
-      });
-      const json: unknown = await res.json();
-      if (!res.ok) {
-        const detail = field(field(json, "error"), "message");
-        throw new Error(
-          `${model}: HTTP ${res.status} ${typeof detail === "string" ? detail : ""}`.trim()
-        );
-      }
-      const part = audioPart(json);
-      if (!part) throw new Error(`${model}: no audio in the response`);
-      return { mimeType: part.mimeType, data: Buffer.from(part.data, "base64") };
-    } catch (e) {
-      last = e;
-      console.error(
-        `motion-render: ${model} attempt ${attempt}/${RETRIES} failed: ${errorMessage(e)}`
+  return withRetries(model, async () => {
+    const res = await fetch(`${API}/${model}:generateContent`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-goog-api-key": key },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    const json: unknown = await res.json();
+    if (!res.ok) {
+      const detail = field(field(json, "error"), "message");
+      throw new Error(
+        `${model}: HTTP ${res.status} ${typeof detail === "string" ? detail : ""}`.trim()
       );
     }
-  }
-  throw last;
+    const part = audioPart(json);
+    if (!part) throw new Error(`${model}: no audio in the response`);
+    return { mimeType: part.mimeType, data: Buffer.from(part.data, "base64") };
+  });
 }
 
 // Gemini TTS returns WAV, or raw 16-bit PCM ("audio/L16;rate=24000") on some models: always store WAV.
@@ -198,7 +236,24 @@ export function bgmFile(work: string): string {
   return join(work, "audio", file);
 }
 
-// Narration at each scene's start + lead, BGM at a constant level underneath (ducking made it pump).
+const round = (n: number): number => Math.round(n * 1000) / 1000;
+
+// One sound effect as a filter chain from input `input` to [label]: cut to its length (generated audio can
+// run long), leveled by `gain`, faded at both ends so it cannot click, and delayed to its start.
+export function sfxChain(input: number, t: SfxTrack, label: string): string {
+  const fade = Math.min(0.25, t.duration / 3);
+  return [
+    `[${input}:a]atrim=0:${t.duration},asetpts=PTS-STARTPTS,aresample=44100`,
+    "aformat=channel_layouts=stereo",
+    `volume=${t.gain.toFixed(4)}`,
+    "afade=t=in:d=0.01",
+    `afade=t=out:st=${round(t.duration - fade)}:d=${round(fade)}`,
+    `adelay=${Math.round(t.start * 1000)}:all=1[${label}]`,
+  ].join(",");
+}
+
+// Narration at each scene's start + lead, BGM at a constant level underneath (ducking made it pump),
+// and the sound effects at their times.
 export async function mix(
   work: string,
   script: Script,
@@ -217,11 +272,17 @@ export async function mix(
   const b = timing.scenes.length,
     total = timing.total;
   inputs.push("-stream_loop", "-1", "-i", bgmFile(work));
+  const sfx = timing.sfx ?? [];
+  const fx = sfx.map((t, i) => {
+    inputs.push("-i", t.file);
+    return { chain: sfxChain(b + 1 + i, t, `s${i}`), label: `[s${i}]` };
+  });
   const graph = [
     ...chains,
     `${labels.join("")}amix=inputs=${labels.length}:normalize=0,aresample=44100,pan=stereo|c0=c0|c1=c0,apad=whole_dur=${total}[nar]`, // full level on both sides (an automatic upmix drops mono speech by 3 dB)
     `[${b}:a]atrim=0:${total},asetpts=PTS-STARTPTS,aresample=44100,aformat=channel_layouts=stereo,volume=${script.bgmVolume},afade=t=in:d=0.8,afade=t=out:st=${Math.max(0, total - 3)}:d=3[bgm]`,
-    "[nar][bgm]amix=inputs=2:normalize=0,alimiter=limit=0.95[out]",
+    ...fx.map((f) => f.chain),
+    `[nar][bgm]${fx.map((f) => f.label).join("")}amix=inputs=${2 + fx.length}:normalize=0,alimiter=limit=0.95[out]`,
   ].join(";");
   await runFfmpeg([
     ...inputs,
diff --git a/skills/motion-render/scripts/cli.ts b/skills/motion-render/scripts/cli.ts
index 16b4312..3b2607d 100755
--- a/skills/motion-render/scripts/cli.ts
+++ b/skills/motion-render/scripts/cli.ts
@@ -8,7 +8,8 @@ import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { openFilm, checkFilmDir, type Film } from "./render.ts";
 import { narrate, bgm, bgmFile, mix, findFfmpeg, encodeArgs } from "./audio.ts";
-import { loadScript, writeTiming, loadTiming, placeOnFilm } from "./work.ts";
+import { loadScript, writeTiming, loadTiming, placeOnFilm, placeSfx } from "./work.ts";
+import { checkSfx, makeSfx, previewSfx, sfxTrack } from "./sfx.ts";
 import { prepare } from "./store.ts";
 import { errorMessage, field, readJson } from "./json.ts";
 
@@ -16,15 +17,18 @@ const USAGE = `usage (one work dir per video; see SKILL.md for its layout):
   motion-render narrate <work>            Narrate every scene of <work>/script.json (Gemini TTS)
                                           and write the scene lengths to <work>/timing.json.
   motion-render bgm <work>                Make the BGM from script.json's "bgm" prompt (Lyria).
+  motion-render sfx <work>                Make the scenes' sound effects (ElevenLabs) and write
+                                          <work>/audio/sfx/preview.m4a to listen to them all in order.
   motion-render prepare <storeDir> <work>/film
                                           Expand a Motion film's store (ArtifactData out_dir) into a film dir.
   motion-render stills <filmDir> <outDir> <t1,t2,...>
                                           Write PNG stills at the given seconds.
-  motion-render build <work> [out.mp4]    Mix narration + BGM and render <work>/film to MP4.
+  motion-render build <work> [out.mp4]    Mix narration + BGM + sound effects and render <work>/film to MP4.
                                           Without out.mp4: $MOTION_RENDER_OUT_DIR or the current dir, <work name>.mp4.
 
 env:
   GEMINI_API_KEY         required by narrate and bgm
+  ELEVENLABS_API_KEY     required by sfx
   MOTION_RENDER_OUT_DIR  default output directory for build
   CHROMIUM_PATH          use this Chrome/Chromium instead of the bundled one
   FFMPEG_PATH            use this ffmpeg instead of the bundled one`;
@@ -71,6 +75,18 @@ async function runBgm(work: string): Promise<void> {
   console.log(`bgm: ${file}`);
 }
 
+async function runSfx(work: string): Promise<void> {
+  const script = loadScript(work);
+  const made = await makeSfx(work, script);
+  const preview = await previewSfx(work, script);
+  if (!preview) {
+    console.log("no sound effects in script.json");
+    return;
+  }
+  for (const e of preview.list) console.log(`${e.offset}s\t${e.scene} +${e.at}s\t${e.prompt}`);
+  console.log(`made ${made} new, listen to all of them: ${preview.file}`);
+}
+
 // Pipes rendered frames straight into ffmpeg (no temp files) and muxes the mixed audio.
 async function encode(film: Film, fps: number, audio: string, out: string): Promise<number> {
   const count = Math.round(film.meta.duration * fps);
@@ -105,23 +121,34 @@ async function build(work: string, out: string, fps: number): Promise<void> {
   if (missing.length)
     die(`narration missing for: ${missing.join(", ")} (run "motion-render narrate ${work}")`);
   bgmFile(work);
+  checkSfx(work, script);
   const filmDir = join(work, "film");
   checkFilmDir(filmDir);
 
   const film = await openFilm(filmDir);
   try {
-    const scenes = placeOnFilm(timing, film.meta, script, (w) => console.error(`warning: ${w}`));
+    const warn = (w: string) => console.error(`warning: ${w}`);
+    const scenes = placeOnFilm(timing, film.meta, script, warn);
+    const sfx = placeSfx(script, film.meta.parts, warn).map((c) => sfxTrack(work, c));
     const audio = join(work, "audio", "mix.m4a");
-    await mix(work, script, { scenes, total: film.meta.duration }, audio);
+    await mix(work, script, { scenes, total: film.meta.duration, sfx }, audio);
     mkdirSync(dirname(out), { recursive: true });
     const count = await encode(film, fps, audio, out);
     for (const w of await film.warnings()) console.error("runner", w);
-    console.log(`done: ${out} (${film.meta.duration}s, ${count} frames, narration + BGM)`);
+    const extra = sfx.length ? ` + ${sfx.length} sound effects` : "";
+    console.log(`done: ${out} (${film.meta.duration}s, ${count} frames, narration + BGM${extra})`);
   } finally {
     await film.close();
   }
 }
 
+// Commands that take just the work dir.
+const WORK_COMMANDS = new Map<string, (work: string) => Promise<void>>([
+  ["narrate", runNarrate],
+  ["bgm", runBgm],
+  ["sfx", runSfx],
+]);
+
 function version(): string {
   const v = field(readJson(fileURLToPath(new URL("../package.json", import.meta.url))), "version");
   return typeof v === "string" ? v : "unknown";
@@ -146,8 +173,8 @@ async function main(): Promise<void> {
     return;
   }
   const [a, b, c] = rest;
-  if (cmd === "narrate" && a && rest.length === 1) return runNarrate(resolve(a));
-  if (cmd === "bgm" && a && rest.length === 1) return runBgm(resolve(a));
+  const onWork = WORK_COMMANDS.get(cmd);
+  if (onWork && a && rest.length === 1) return onWork(resolve(a));
   if (cmd === "prepare" && a && b && rest.length === 2) return runPrepare(a, b);
   if (cmd === "stills" && a && b && c && rest.length === 3) return stills(a, b, c);
   if (cmd === "build" && a && (rest.length === 1 || rest.length === 2)) {
diff --git a/skills/motion-render/scripts/sfx.ts b/skills/motion-render/scripts/sfx.ts
new file mode 100644
index 0000000..ea5674d
--- /dev/null
+++ b/skills/motion-render/scripts/sfx.ts
@@ -0,0 +1,190 @@
+// 効果音（ElevenLabs Sound Effects）を作って保存し、合成のときの音量をそろえる。
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { errorMessage, field, readJson } from "./json.ts";
+import {
+  runFfmpeg,
+  sfxChain,
+  TIMEOUT_MS,
+  volumeStats,
+  withRetries,
+  type SfxTrack,
+} from "./audio.ts";
+import type { Script, SfxCue } from "./work.ts";
+
+const API = "https://api.elevenlabs.io/v1/sound-generation?output_format=mp3_44100_128"; // the best format pay-as-you-go allows
+const MODEL = "eleven_text_to_sound_v2";
+const SILENT_DB = -60; // a peak below this means the effect came back silent
+// Generated effects differ in level by 30 dB or more: each is brought to TARGET_MEAN_DB on average,
+// unless that would push its peak past TARGET_PEAK_DB.
+const TARGET_MEAN_DB = -20;
+const TARGET_PEAK_DB = -1;
+const PREVIEW_GAP = 0.6;
+
+interface Level {
+  mean: number;
+  max: number;
+}
+
+// Effects are stored by what was asked for, so an unchanged effect is never paid for twice.
+export const sfxKey = (prompt: string, duration: number): string =>
+  createHash("sha256")
+    .update(JSON.stringify([MODEL, prompt, duration]))
+    .digest("hex")
+    .slice(0, 16);
+
+const sfxFile = (work: string, prompt: string, duration: number, ext: "mp3" | "json"): string =>
+  join(work, "audio", "sfx", `${sfxKey(prompt, duration)}.${ext}`);
+
+// The reason ElevenLabs gives: a plain string, {message}, or a validation list of {msg}.
+function apiReason(body: unknown): string {
+  const detail = field(body, "detail");
+  if (typeof detail === "string") return detail;
+  const message = field(detail, "message");
+  if (typeof message === "string") return message;
+  const msg = Array.isArray(detail) ? field(detail[0], "msg") : undefined;
+  return typeof msg === "string" ? msg : "";
+}
+
+// The only call to the provider, so it can be swapped (fal.ai serves the same model per second).
+async function soundEffect(key: string, prompt: string, duration: number): Promise<Buffer> {
+  const res = await fetch(API, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "xi-api-key": key },
+    body: JSON.stringify({ text: prompt, duration_seconds: duration, model_id: MODEL }),
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    let body: unknown;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text; // not JSON: the status alone has to do
+    }
+    throw new Error(`HTTP ${res.status} ${apiReason(body)}`.trim());
+  }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+const allSfx = (script: Script) =>
+  script.scenes.flatMap((s) => s.sfx.map((fx) => ({ ...fx, scene: s.id })));
+
+// Writes audio/sfx/<key>.mp3 and its measured level (<key>.json) for each distinct effect in the script.
+// Effects already made are kept; a silent result counts as a failed attempt. Returns how many were made.
+export async function makeSfx(work: string, script: Script): Promise<number> {
+  const todo = new Map<string, { prompt: string; duration: number }>();
+  for (const fx of allSfx(script))
+    if (!existsSync(sfxFile(work, fx.prompt, fx.duration, "json")))
+      todo.set(sfxKey(fx.prompt, fx.duration), fx);
+  if (!todo.size) return 0;
+  const key = process.env.ELEVENLABS_API_KEY;
+  if (!key) throw new Error("ELEVENLABS_API_KEY is not set (needed for sound effects)");
+  mkdirSync(join(work, "audio", "sfx"), { recursive: true });
+  for (const { prompt, duration } of todo.values()) {
+    console.error(`sound effect: ${prompt}`);
+    const mp3 = sfxFile(work, prompt, duration, "mp3");
+    const level = await withRetries(`sound effect "${prompt}"`, async (): Promise<Level> => {
+      try {
+        writeFileSync(mp3, await soundEffect(key, prompt, duration));
+      } catch (e) {
+        throw new Error(`sound effect "${prompt}": ${errorMessage(e)}`);
+      }
+      const l = await volumeStats(mp3);
+      if (l.max < SILENT_DB)
+        throw new Error(`sound effect "${prompt}" came back silent (peak ${l.max} dB)`);
+      return l;
+    });
+    writeFileSync(
+      sfxFile(work, prompt, duration, "json"),
+      JSON.stringify({ prompt, duration, ...level }, null, 2)
+    );
+  }
+  return todo.size;
+}
+
+// Stops build before any rendering when an effect in the script was not made yet.
+export function checkSfx(work: string, script: Script): void {
+  const missing = [
+    ...new Set(
+      allSfx(script)
+        .filter((fx) => !existsSync(sfxFile(work, fx.prompt, fx.duration, "json")))
+        .map((fx) => `"${fx.prompt}"`)
+    ),
+  ];
+  if (missing.length)
+    throw new Error(
+      `sound effects missing for: ${missing.join(", ")} (run "motion-render sfx ${work}")`
+    );
+}
+
+function level(work: string, prompt: string, duration: number): Level {
+  const file = sfxFile(work, prompt, duration, "json");
+  const raw = existsSync(file) ? readJson(file) : undefined;
+  const mean = field(raw, "mean"),
+    max = field(raw, "max");
+  if (typeof mean !== "number" || typeof max !== "number")
+    throw new Error(`no usable sound effect for "${prompt}": run "motion-render sfx" again`);
+  return { mean, max };
+}
+
+// An effect ready for mixing: its file, its time and the gain that levels it, times its own volume.
+export function sfxTrack(work: string, cue: SfxCue): SfxTrack {
+  const { mean, max } = level(work, cue.prompt, cue.duration);
+  const db = Math.min(TARGET_MEAN_DB - mean, TARGET_PEAK_DB - max);
+  return {
+    file: sfxFile(work, cue.prompt, cue.duration, "mp3"),
+    start: cue.start,
+    duration: cue.duration,
+    gain: cue.volume * 10 ** (db / 20),
+  };
+}
+
+interface PreviewEntry {
+  offset: number;
+  scene: string;
+  at: number;
+  prompt: string;
+}
+
+// audio/sfx/preview.m4a: every effect in script order, leveled as in the mix, with a gap after each,
+// so a person can hear them all before the film is built. Null when the script has none.
+export async function previewSfx(
+  work: string,
+  script: Script
+): Promise<{ file: string; list: PreviewEntry[] } | null> {
+  const all = allSfx(script);
+  if (!all.length) return null;
+  let offset = 0;
+  const list: PreviewEntry[] = [],
+    inputs: string[] = [],
+    graph: string[] = [];
+  all.forEach((fx, i) => {
+    const t = sfxTrack(work, { ...fx, start: 0 });
+    inputs.push("-i", t.file);
+    graph.push(sfxChain(i, t, `s${i}`), `[s${i}]apad=pad_dur=${PREVIEW_GAP}[p${i}]`);
+    list.push({
+      offset: Math.round(offset * 100) / 100,
+      scene: fx.scene,
+      at: fx.at,
+      prompt: fx.prompt,
+    });
+    offset += fx.duration + PREVIEW_GAP;
+  });
+  graph.push(`${all.map((_, i) => `[p${i}]`).join("")}concat=n=${all.length}:v=0:a=1[out]`);
+  const file = join(work, "audio", "sfx", "preview.m4a");
+  await runFfmpeg([
+    ...inputs,
+    "-filter_complex",
+    graph.join(";"),
+    "-map",
+    "[out]",
+    "-c:a",
+    "aac",
+    "-b:a",
+    "192k",
+    file,
+  ]);
+  return { file, list };
+}
diff --git a/skills/motion-render/scripts/work.ts b/skills/motion-render/scripts/work.ts
index 75b6d50..ec95248 100644
--- a/skills/motion-render/scripts/work.ts
+++ b/skills/motion-render/scripts/work.ts
@@ -4,10 +4,19 @@ import { join } from "node:path";
 import { wavSeconds } from "./audio.ts";
 import { isRecord, readJson, type Json } from "./json.ts";
 
+// A sound effect, `at` seconds after its scene starts.
+export interface Sfx {
+  at: number;
+  prompt: string;
+  duration: number;
+  volume: number;
+}
+
 interface Scene {
   id: string;
   name?: string;
   narration: string;
+  sfx: Sfx[];
 }
 
 export interface Script {
@@ -18,6 +27,7 @@ export interface Script {
   ttsModel: string;
   bgmModel: string;
   bgmVolume: number;
+  sfxVolume: number;
   lead: number;
   tail: number;
   endHold: number;
@@ -42,11 +52,13 @@ const DEFAULTS = {
   ttsModel: "gemini-3.8-flash-tts",
   bgmModel: "lyria-3.5",
   bgmVolume: 0.15,
+  sfxVolume: 0.5,
   lead: 0.25, // silence before each scene's narration
   tail: 0.35, // silence after it
   endHold: 3, // the last scene holds this long after its narration
 };
 
+const SFX_DURATION = 1.5; // asked for when a sound effect gives no length, so none runs long
 const ID = /^[a-z][a-z0-9-]{0,31}$/;
 const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 
@@ -54,7 +66,25 @@ function fail(msg: string): never {
   throw new Error(`script.json: ${msg}`);
 }
 
-function parseScenes(value: unknown): Scene[] {
+function parseSfx(value: unknown, path: string, volume: number): Sfx[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) fail(`${path} must be an array`);
+  return value.map((fx: unknown, i) => {
+    const at = `${path}[${i}]`;
+    if (!isRecord(fx)) fail(`${at} must be an object`);
+    const { prompt } = fx;
+    if (typeof prompt !== "string" || !prompt.trim()) fail(`${at}.prompt is required`);
+    const s = { duration: SFX_DURATION, volume, ...fx };
+    return {
+      at: num(s, "at", 0, 600, at),
+      prompt,
+      duration: num(s, "duration", 0.5, 10, at),
+      volume: num(s, "volume", 0, 1, at),
+    };
+  });
+}
+
+function parseScenes(value: unknown, sfxVolume: number): Scene[] {
   if (!Array.isArray(value) || !value.length) fail('"scenes" must be a non-empty array');
   const seen = new Set<string>();
   return value.map((sc: unknown, i) => {
@@ -65,15 +95,16 @@ function parseScenes(value: unknown): Scene[] {
     seen.add(id);
     if (typeof narration !== "string" || !narration.trim())
       fail(`scenes[${i}].narration is required (every scene is narrated)`);
-    return typeof name === "string" ? { id, name, narration } : { id, narration };
+    const sfx = parseSfx(sc.sfx, `scenes[${i}].sfx`, sfxVolume);
+    return typeof name === "string" ? { id, name, narration, sfx } : { id, narration, sfx };
   });
 }
 
 // These values are written into ffmpeg filter graphs and API URLs: accept plain numbers and names only.
-function num(s: Json, key: string, min: number, max: number): number {
+function num(s: Json, key: string, min: number, max: number, path?: string): number {
   const v = s[key];
   if (typeof v !== "number" || !Number.isFinite(v) || v < min || v > max)
-    fail(`"${key}" must be a number between ${min} and ${max}`);
+    fail(`${path ? `${path}.${key}` : `"${key}"`} must be a number between ${min} and ${max}`);
   return v;
 }
 
@@ -93,12 +124,14 @@ export function loadScript(work: string): Script {
   const { bgm } = s;
   if (typeof bgm !== "string" || !bgm.trim())
     fail('"bgm" (a prompt describing the music) is required');
-  const scenes = parseScenes(s.scenes);
+  const sfxVolume = num(s, "sfxVolume", 0, 1);
+  const scenes = parseScenes(s.scenes, sfxVolume);
   return {
     bgm,
     scenes,
     speed: num(s, "speed", 0.5, 2),
     bgmVolume: num(s, "bgmVolume", 0, 1),
+    sfxVolume,
     lead: num(s, "lead", 0, 5),
     tail: num(s, "tail", 0, 5),
     endHold: num(s, "endHold", 0, 30),
@@ -184,3 +217,28 @@ export function placeOnFilm(
     return [{ ...s, start: p.a0 }];
   });
 }
+
+// A sound effect placed on the film's timeline.
+export interface SfxCue extends Sfx {
+  start: number;
+}
+
+// Each effect goes `at` seconds after where its scene actually starts in the film, so it stays on its
+// animation even when the narration moves the scenes. An effect that starts after its scene ends is reported.
+export function placeSfx(
+  script: Pick<Script, "scenes">,
+  parts: FilmScene[],
+  warn: (msg: string) => void
+): SfxCue[] {
+  const byKey = new Map(parts.map((p) => [p.key, p]));
+  const cues = script.scenes.flatMap((sc) => {
+    const p = byKey.get(sc.id);
+    if (!p) return [];
+    return sc.sfx.map((fx) => {
+      if (fx.at >= p.dur)
+        warn(`sound effect "${fx.prompt}" at ${fx.at}s is past the end of "${sc.id}" (${p.dur}s)`);
+      return { ...fx, start: Math.round((p.a0 + fx.at) * 1000) / 1000 };
+    });
+  });
+  return cues.sort((a, b) => a.start - b.start);
+}
diff --git a/tests/audio.test.ts b/tests/audio.test.ts
index 4848d09..3f93545 100644
--- a/tests/audio.test.ts
+++ b/tests/audio.test.ts
@@ -198,6 +198,9 @@ describe("mix", () => {
     expect(graph).toContain("[1:a]atempo=1.2,adelay=4750:all=1[n1]");
     expect(graph).toContain("[2:a]atrim=0:10,");
     expect(graph).toContain("volume=0.2,afade=t=in:d=0.8,afade=t=out:st=7:d=3[bgm]");
+    expect(graph.split(";").at(-1)).toBe(
+      "[nar][bgm]amix=inputs=2:normalize=0,alimiter=limit=0.95[out]"
+    );
     expect(args.slice(-9)).toEqual([
       "-map",
       "[out]",
@@ -211,6 +214,37 @@ describe("mix", () => {
     ]);
   });
 
+  it("cuts, levels and fades each sound effect, delays it to its time and mixes it with the rest", async () => {
+    const dir = workDir(SCRIPT);
+    writeFileSync(join(dir, "audio", "bgm.json"), JSON.stringify({ file: "bgm.mp3" }));
+    await mix(
+      dir,
+      loadScript(dir),
+      {
+        scenes: [{ id: "intro", start: 0 }],
+        total: 6,
+        sfx: [
+          { file: "/w/pop.mp3", start: 1.25, duration: 0.6, gain: 2.5 },
+          { file: "/w/whoosh.mp3", start: 3, duration: 1.5, gain: 0.123456 },
+        ],
+      },
+      join(dir, "m.m4a")
+    );
+
+    const { args } = ffmpeg.calls[0]!;
+    expect(args.join(" ")).toContain("-i /w/pop.mp3 -i /w/whoosh.mp3 -filter_complex");
+    const graph = args[args.indexOf("-filter_complex") + 1]!.split(";");
+    expect(graph).toContain(
+      "[2:a]atrim=0:0.6,asetpts=PTS-STARTPTS,aresample=44100,aformat=channel_layouts=stereo,volume=2.5000,afade=t=in:d=0.01,afade=t=out:st=0.4:d=0.2,adelay=1250:all=1[s0]"
+    );
+    expect(graph).toContain(
+      "[3:a]atrim=0:1.5,asetpts=PTS-STARTPTS,aresample=44100,aformat=channel_layouts=stereo,volume=0.1235,afade=t=in:d=0.01,afade=t=out:st=1.25:d=0.25,adelay=3000:all=1[s1]"
+    );
+    expect(graph.at(-1)).toBe(
+      "[nar][bgm][s0][s1]amix=inputs=4:normalize=0,alimiter=limit=0.95[out]"
+    );
+  });
+
   it("reports an ffmpeg failure", async () => {
     const dir = workDir(SCRIPT);
     writeFileSync(join(dir, "audio", "bgm.json"), JSON.stringify({ file: "bgm.mp3" }));
diff --git a/tests/sfx.test.ts b/tests/sfx.test.ts
new file mode 100644
index 0000000..ff13632
--- /dev/null
+++ b/tests/sfx.test.ts
@@ -0,0 +1,229 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { SCRIPT, workDir } from "./helpers.ts";
+
+// ffmpeg is never run: spawn records its arguments, prints `log` on stderr (what volumedetect would
+// report) and exits with `exitCode`.
+const ffmpeg = vi.hoisted(() => ({
+  calls: [] as string[][],
+  exitCode: 0,
+  log: "mean_volume: -50.0 dB\nmax_volume: -32.4 dB\n",
+}));
+vi.mock("node:child_process", async (importOriginal) => {
+  const real = await importOriginal<typeof import("node:child_process")>();
+  return {
+    ...real,
+    spawn: (_cmd: string, args: string[]) => {
+      ffmpeg.calls.push(args);
+      const child = Object.assign(new EventEmitter(), { stderr: new EventEmitter() });
+      setImmediate(() => {
+        child.stderr.emit("data", Buffer.from(ffmpeg.log));
+        child.emit("close", ffmpeg.exitCode);
+      });
+      return child;
+    },
+  };
+});
+
+const { checkSfx, makeSfx, previewSfx, sfxKey, sfxTrack } =
+  await import("../skills/motion-render/scripts/sfx.ts");
+const { volumeStats } = await import("../skills/motion-render/scripts/audio.ts");
+const { loadScript } = await import("../skills/motion-render/scripts/work.ts");
+
+const pop = { at: 1, prompt: "soft UI pop", duration: 0.8 };
+const whoosh = { at: 0.5, prompt: "quick airy whoosh" };
+// intro: pop, whoosh; flow: the same pop again.
+const SFX_SCRIPT = {
+  ...SCRIPT,
+  scenes: [
+    { ...SCRIPT.scenes[0], sfx: [pop, whoosh] },
+    { ...SCRIPT.scenes[1], sfx: [{ ...pop, at: 2 }] },
+  ],
+};
+
+let fetchMock: ReturnType<typeof vi.fn>;
+beforeEach(() => {
+  vi.stubEnv("ELEVENLABS_API_KEY", "el-key");
+  vi.stubEnv("FFMPEG_PATH", "/usr/bin/ffmpeg-test");
+  fetchMock = vi.fn(async () => new Response(Buffer.from("mp3"), { status: 200 }));
+  vi.stubGlobal("fetch", fetchMock);
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  ffmpeg.calls = [];
+  ffmpeg.exitCode = 0;
+  ffmpeg.log = "mean_volume: -50.0 dB\nmax_volume: -32.4 dB\n";
+});
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+const sfxPath = (dir: string, prompt: string, duration: number, ext: string) =>
+  join(dir, "audio", "sfx", `${sfxKey(prompt, duration)}.${ext}`);
+
+describe("makeSfx", () => {
+  it("asks ElevenLabs once per distinct effect and stores the MP3 with its measured level", async () => {
+    const dir = workDir(SFX_SCRIPT);
+    expect(await makeSfx(dir, loadScript(dir))).toBe(2);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://api.elevenlabs.io/v1/sound-generation?output_format=mp3_44100_128");
+    expect(init.headers).toMatchObject({ "xi-api-key": "el-key" });
+    expect(JSON.parse(String(init.body))).toEqual({
+      text: "soft UI pop",
+      duration_seconds: 0.8,
+      model_id: "eleven_text_to_sound_v2",
+    });
+    expect(
+      JSON.parse(String((fetchMock.mock.calls[1] as [string, RequestInit])[1].body))
+    ).toMatchObject({
+      text: "quick airy whoosh",
+      duration_seconds: 1.5,
+    });
+    expect(readFileSync(sfxPath(dir, "soft UI pop", 0.8, "mp3"), "utf8")).toBe("mp3");
+    expect(JSON.parse(readFileSync(sfxPath(dir, "soft UI pop", 0.8, "json"), "utf8"))).toEqual({
+      prompt: "soft UI pop",
+      duration: 0.8,
+      mean: -50,
+      max: -32.4,
+    });
+  });
+
+  it("keeps effects that were already made", async () => {
+    const dir = workDir(SFX_SCRIPT);
+    await makeSfx(dir, loadScript(dir));
+    fetchMock.mockClear();
+    expect(await makeSfx(dir, loadScript(dir))).toBe(0);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("does nothing, and needs no key, when the script has no sound effects", async () => {
+    vi.stubEnv("ELEVENLABS_API_KEY", "");
+    const dir = workDir(SCRIPT);
+    expect(await makeSfx(dir, loadScript(dir))).toBe(0);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("needs ELEVENLABS_API_KEY when there is something to make", async () => {
+    vi.stubEnv("ELEVENLABS_API_KEY", "");
+    const dir = workDir(SFX_SCRIPT);
+    await expect(makeSfx(dir, loadScript(dir))).rejects.toThrow("ELEVENLABS_API_KEY is not set");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("treats a silent result as a failure, retries it and does not keep it", async () => {
+    ffmpeg.log = "mean_volume: -91.0 dB\nmax_volume: -91.0 dB\n";
+    const dir = workDir({ ...SCRIPT, scenes: [{ ...SCRIPT.scenes[0], sfx: [pop] }] });
+    await expect(makeSfx(dir, loadScript(dir))).rejects.toThrow(
+      'sound effect "soft UI pop" came back silent (peak -91 dB)'
+    );
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(existsSync(sfxPath(dir, "soft UI pop", 0.8, "json"))).toBe(false);
+  });
+
+  it.each([
+    [
+      422,
+      { detail: [{ loc: ["body", "text"], msg: "field required" }] },
+      "HTTP 422 field required",
+    ],
+    [
+      401,
+      { detail: { status: "invalid_api_key", message: "Invalid API key" } },
+      "HTTP 401 Invalid API key",
+    ],
+    [500, "oops", "HTTP 500"],
+  ])("reports the API's reason for HTTP %i", async (status, body, message) => {
+    fetchMock.mockImplementation(
+      async () => new Response(typeof body === "string" ? body : JSON.stringify(body), { status })
+    );
+    const dir = workDir({ ...SCRIPT, scenes: [{ ...SCRIPT.scenes[0], sfx: [pop] }] });
+    await expect(makeSfx(dir, loadScript(dir))).rejects.toThrow(
+      `sound effect "soft UI pop": ${message}`
+    );
+  });
+});
+
+describe("sfxTrack", () => {
+  const meta = (dir: string, prompt: string, duration: number, mean: number, max: number) =>
+    writeFileSync(
+      sfxPath(dir, prompt, duration, "json"),
+      JSON.stringify({ prompt, duration, mean, max })
+    );
+
+  it("brings a quiet effect up to the common average level", async () => {
+    const dir = workDir(SFX_SCRIPT);
+    await makeSfx(dir, loadScript(dir));
+    meta(dir, "soft UI pop", 0.8, -50, -32);
+    const t = sfxTrack(dir, { ...pop, volume: 0.5, start: 3 });
+    expect(t).toMatchObject({
+      file: sfxPath(dir, "soft UI pop", 0.8, "mp3"),
+      start: 3,
+      duration: 0.8,
+    });
+    expect(t.gain).toBeCloseTo(0.5 * 10 ** (30 / 20), 6); // +30 dB to reach -20 dB on average
+  });
+
+  it("stops short of clipping a loud effect", async () => {
+    const dir = workDir(SFX_SCRIPT);
+    await makeSfx(dir, loadScript(dir));
+    meta(dir, "quick airy whoosh", 1.5, -21.5, 0);
+    const t = sfxTrack(dir, { ...whoosh, duration: 1.5, volume: 1, start: 0 });
+    expect(t.gain).toBeCloseTo(10 ** (-1 / 20), 6); // peak held at -1 dB
+  });
+});
+
+describe("checkSfx", () => {
+  it("names the effects that were not made yet", async () => {
+    const dir = workDir(SFX_SCRIPT);
+    expect(() => checkSfx(dir, loadScript(dir))).toThrow(
+      `sound effects missing for: "soft UI pop", "quick airy whoosh" (run "motion-render sfx ${dir}")`
+    );
+    await makeSfx(dir, loadScript(dir));
+    expect(() => checkSfx(dir, loadScript(dir))).not.toThrow();
+  });
+});
+
+describe("previewSfx", () => {
+  it("writes every effect in script order at its mixing level, with a gap after each", async () => {
+    const dir = workDir(SFX_SCRIPT);
+    await makeSfx(dir, loadScript(dir));
+    ffmpeg.calls = [];
+    const preview = await previewSfx(dir, loadScript(dir));
+
+    expect(preview?.file).toBe(join(dir, "audio", "sfx", "preview.m4a"));
+    expect(preview?.list).toEqual([
+      { offset: 0, scene: "intro", at: 1, prompt: "soft UI pop" },
+      { offset: 1.4, scene: "intro", at: 0.5, prompt: "quick airy whoosh" },
+      { offset: 3.5, scene: "flow", at: 2, prompt: "soft UI pop" },
+    ]);
+    const args = ffmpeg.calls[0]!;
+    const graph = args[args.indexOf("-filter_complex") + 1]!.split(";");
+    expect(graph[0]).toMatch(/^\[0:a\]atrim=0:0\.8,.*adelay=0:all=1\[s0\]$/);
+    expect(graph).toContain("[s0]apad=pad_dur=0.6[p0]");
+    expect(graph.at(-1)).toBe("[p0][p1][p2]concat=n=3:v=0:a=1[out]");
+    expect(args.at(-1)).toBe(preview?.file);
+  });
+
+  it("returns null when there is nothing to listen to", async () => {
+    const dir = workDir(SCRIPT);
+    expect(await previewSfx(dir, loadScript(dir))).toBeNull();
+    expect(ffmpeg.calls).toEqual([]);
+  });
+});
+
+describe("volumeStats", () => {
+  it("reads -inf as a very low level", async () => {
+    ffmpeg.log = "mean_volume: -inf dB\nmax_volume: -inf dB\n";
+    expect(await volumeStats("/x.mp3")).toEqual({ mean: -120, max: -120 });
+  });
+
+  it("fails when ffmpeg reports no level", async () => {
+    ffmpeg.log = "Invalid data found when processing input\n";
+    ffmpeg.exitCode = 1;
+    await expect(volumeStats("/x.mp3")).rejects.toThrow("could not measure the level of /x.mp3");
+  });
+});
diff --git a/tests/work.test.ts b/tests/work.test.ts
index f08dbc9..5891990 100644
--- a/tests/work.test.ts
+++ b/tests/work.test.ts
@@ -5,12 +5,20 @@ import {
   loadScript,
   loadTiming,
   placeOnFilm,
+  placeSfx,
   writeTiming,
+  type Sfx,
 } from "../skills/motion-render/scripts/work.ts";
 import { SCRIPT, tempDir, workDir } from "./helpers.ts";
 
 const scriptWith = (patch: object) => workDir({ ...SCRIPT, ...patch });
 
+// A script whose first scene carries the given "sfx" value.
+const sfxScript = (sfx: unknown) => ({
+  ...SCRIPT,
+  scenes: [{ ...SCRIPT.scenes[0], sfx }, SCRIPT.scenes[1]],
+});
+
 describe("loadScript", () => {
   it("fills in the defaults", () => {
     const s = loadScript(workDir(SCRIPT));
@@ -20,13 +28,30 @@ describe("loadScript", () => {
       ttsModel: "gemini-3.8-flash-tts",
       bgmModel: "lyria-3.5",
       bgmVolume: 0.15,
+      sfxVolume: 0.5,
       lead: 0.25,
       tail: 0.35,
       endHold: 3,
     });
     expect(s.scenes).toEqual([
-      { id: "intro", name: "Intro", narration: "はじめに" },
-      { id: "flow", narration: "流れ" },
+      { id: "intro", name: "Intro", narration: "はじめに", sfx: [] },
+      { id: "flow", narration: "流れ", sfx: [] },
+    ]);
+  });
+
+  it("reads each scene's sound effects, filling in the length and the script-wide volume", () => {
+    const s = loadScript(
+      workDir({
+        ...sfxScript([
+          { at: 1.2, prompt: "soft UI pop", duration: 0.8 },
+          { at: 3, prompt: "quick airy whoosh", volume: 0.4 },
+        ]),
+        sfxVolume: 0.3,
+      })
+    );
+    expect(s.scenes[0]?.sfx).toEqual([
+      { at: 1.2, prompt: "soft UI pop", duration: 0.8, volume: 0.3 },
+      { at: 3, prompt: "quick airy whoosh", duration: 1.5, volume: 0.4 },
     ]);
   });
 
@@ -70,6 +95,29 @@ describe("loadScript", () => {
     ["speed out of range", { ...SCRIPT, speed: 3 }, /"speed" must be a number between 0.5 and 2/],
     ["volume not a number", { ...SCRIPT, bgmVolume: "loud" }, /"bgmVolume" must be a number/],
     ["model with a path", { ...SCRIPT, bgmModel: "../x" }, /"bgmModel" must match/],
+    ["sfxVolume out of range", { ...SCRIPT, sfxVolume: 2 }, /"sfxVolume" must be a number/],
+    ["sfx not an array", sfxScript("pop"), /scenes\[0\]\.sfx must be an array/],
+    ["sfx not an object", sfxScript(["pop"]), /scenes\[0\]\.sfx\[0\] must be an object/],
+    [
+      "sfx without a prompt",
+      sfxScript([{ at: 1, prompt: " " }]),
+      /scenes\[0\]\.sfx\[0\]\.prompt is required/,
+    ],
+    [
+      "sfx at a negative time",
+      sfxScript([{ at: -1, prompt: "pop" }]),
+      /scenes\[0\]\.sfx\[0\]\.at must be a number between 0 and 600/,
+    ],
+    [
+      "sfx too long",
+      sfxScript([{ at: 0, prompt: "pop", duration: 11 }]),
+      /scenes\[0\]\.sfx\[0\]\.duration must be a number between 0.5 and 10/,
+    ],
+    [
+      "sfx volume as text",
+      sfxScript([{ at: 0, prompt: "pop", volume: "1;x" }]),
+      /scenes\[0\]\.sfx\[0\]\.volume must be a number between 0 and 1/,
+    ],
   ])("rejects a script with %s", (_name, script, message) => {
     const dir = tempDir();
     writeFileSync(join(dir, "script.json"), JSON.stringify(script));
@@ -173,3 +221,40 @@ describe("placeOnFilm", () => {
     ).toThrow("these script.json scenes are not in the film: flow (scene ids must match)");
   });
 });
+
+describe("placeSfx", () => {
+  const pop = { at: 1, prompt: "pop", duration: 0.5, volume: 0.5 };
+  const parts = [
+    { key: "intro", a0: 0, dur: 4 },
+    { key: "flow", a0: 4.5, dur: 6 },
+  ];
+  const script = (intro: Sfx[], flow: Sfx[]) => ({
+    scenes: [
+      { id: "intro", narration: "a", sfx: intro },
+      { id: "flow", narration: "b", sfx: flow },
+    ],
+  });
+
+  it("times each effect from where its scene starts in the film, in film order", () => {
+    const placed = placeSfx(
+      script([{ ...pop, at: 2 }], [pop, { ...pop, prompt: "whoosh", at: 0 }]),
+      parts,
+      vi.fn()
+    );
+    expect(placed.map((p) => [p.prompt, p.start])).toEqual([
+      ["pop", 2],
+      ["whoosh", 4.5],
+      ["pop", 5.5],
+    ]);
+  });
+
+  it("warns about an effect that starts after its scene ends", () => {
+    const warn = vi.fn();
+    placeSfx(script([{ ...pop, at: 4 }], []), parts, warn);
+    expect(warn).toHaveBeenCalledWith('sound effect "pop" at 4s is past the end of "intro" (4s)');
+  });
+
+  it("skips scenes that the film does not have", () => {
+    expect(placeSfx(script([], [pop]), [parts[0]!], vi.fn())).toEqual([]);
+  });
+});

From 23f51a50c9b8003f1651b73616a17f6f6864f91a Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Mon, 19 Oct 2026 01:21:25 +0900
Subject: [PATCH 2/5] docs: explain sound effects and the ElevenLabs
 pay-as-you-go key

---
 README.ja.md              | 28 +++++++++++++++++-----
 README.md                 | 32 ++++++++++++++++++-------
 docs/elevenlabs-key.ja.md | 50 +++++++++++++++++++++++++++++++++++++++
 docs/elevenlabs-key.md    | 50 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 146 insertions(+), 14 deletions(-)
 create mode 100644 docs/elevenlabs-key.ja.md
 create mode 100644 docs/elevenlabs-key.md

diff --git a/README.ja.md b/README.ja.md
index cd2367f..9763642 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -22,16 +22,18 @@ https://github.com/user-attachments/assets/eb1bf7e6-a880-4bbe-b575-7f4ec5c21672
 ![motion-render の仕組み](docs/how-it-works.svg)
 
 - 見た目・長さ・声・BGM の雰囲気はテーマから自動で決まります（指定すればそれに従います）
+- ElevenLabs の API キーがあれば、カードが現れる・流れ図が光るといった動きに合わせて効果音も付きます
 - 既存の Motion の動画の URL を渡して、ナレーションと BGM 付きの MP4 にすることもできます
 - 描画用のブラウザ（Chromium）と ffmpeg は自動で用意されるので、環境ごとの差が出ません
 
 ## 必要なもの
 
-| もの               | 備考                                                                                                                                                                                                                                               |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Claude Code        | [Claude Motion](https://support.claude.com/ja/articles/17454997-claude-motion%E3%82%92%E5%A7%8B%E3%82%81%E3%82%8B) を使えるアカウント（ベータ版。Team・Enterprise プランのみ）。Claude Code 専用です（Codex・Cursor などには Motion がありません） |
-| Node.js 22.18 以上 | `node -v` で確認。コマンドの TypeScript を Node がそのまま実行します                                                                                                                                                                               |
-| Gemini API キー    | ナレーションと BGM に使います。Google AI Studio で発行します（[発行の手順](docs/api-key.ja.md)）                                                                                                                                                   |
+| もの                | 備考                                                                                                                                                                                                                                               |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code         | [Claude Motion](https://support.claude.com/ja/articles/17454997-claude-motion%E3%82%92%E5%A7%8B%E3%82%81%E3%82%8B) を使えるアカウント（ベータ版。Team・Enterprise プランのみ）。Claude Code 専用です（Codex・Cursor などには Motion がありません） |
+| Node.js 22.18 以上  | `node -v` で確認。コマンドの TypeScript を Node がそのまま実行します                                                                                                                                                                               |
+| Gemini API キー     | ナレーションと BGM に使います。Google AI Studio で発行します（[発行の手順](docs/api-key.ja.md)）                                                                                                                                                   |
+| ElevenLabs API キー | 任意。効果音に使います。月額プランなしの従量課金で作れます（[作成の手順](docs/elevenlabs-key.ja.md)）                                                                                                                                              |
 
 macOS・Linux・Windows で動きます。
 
@@ -72,6 +74,14 @@ Google AI Studio で Gemini API キーを発行します（[発行の手順](doc
 export GEMINI_API_KEY="発行したキー"
 ```
 
+効果音も付けたい場合は、ElevenLabs のキーも足します（[作成の手順](docs/elevenlabs-key.ja.md)）。無ければ効果音なしで作ります。
+
+```sh
+export ELEVENLABS_API_KEY="作成したキー"
+```
+
+月額プランなしで作った効果音は商用に使えず、公開するときは題名に `11.ai` などの表記が要ります。motion-render は効果音を付けた動画のタイトルに `🎧:11.ai` を入れます。
+
 ### 3. Claude Code の sandbox を使っている場合だけ: 設定を足す
 
 sandbox の中では描画用のブラウザが起動できません。`~/.claude/settings.json` に次の 2 つを足し、`motion-render` だけを sandbox の外で動かします。
@@ -118,14 +128,16 @@ auto mode を使っていて、それでも実行が拒否される場合は、`
 | ------------------------------------------------ | -------------------------------------------------------------------------------- |
 | `motion-render narrate <work>`                   | `script.json` の原稿からナレーションを作り、場面の秒数を `timing.json` に書く    |
 | `motion-render bgm <work>`                       | `script.json` の `bgm` の指示から BGM を作る                                     |
+| `motion-render sfx <work>`                       | `script.json` の `sfx` から効果音を作り、全部を順に聞ける `preview.m4a` を書く   |
 | `motion-render prepare <storeDir> <work>/film`   | Motion から取得した映像データを、描画できる形に展開する                          |
 | `motion-render stills <filmDir> <outDir> 0,5,12` | 確認用の静止画を書き出す                                                         |
-| `motion-render build <work> [out.mp4]`           | ナレーションと BGM を合成し、映像と合わせて MP4 にする（どちらかが無いと止まる） |
+| `motion-render build <work> [out.mp4]`           | ナレーション・BGM・効果音を合成し、映像と合わせて MP4 にする（足りないと止まる） |
 | `motion-render --version`                        | 版を表示する                                                                     |
 
 | 環境変数                | 効果                                                         |
 | ----------------------- | ------------------------------------------------------------ |
 | `GEMINI_API_KEY`        | ナレーションと BGM の生成に必要                              |
+| `ELEVENLABS_API_KEY`    | 効果音の生成に必要（無ければ効果音を付けない）               |
 | `MOTION_RENDER_OUT_DIR` | `build` の出力先を省略したときの保存先                       |
 | `CHROMIUM_PATH`         | 同梱の Chromium の代わりに、手元の Chrome や Chromium を使う |
 | `FFMPEG_PATH`           | 同梱の ffmpeg の代わりに、手元の ffmpeg を使う               |
@@ -136,6 +148,9 @@ auto mode を使っていて、それでも実行が拒否される場合は、`
 | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `bootstrap_check_in ... Permission denied` でブラウザが起動しない | Claude Code の sandbox の中で動いています。インストールの手順 3 を確認してください。`motion-render` は単体で実行する必要があります（`\| grep` や `&&` でつなぐと sandbox の外に出ません）                     |
 | `GEMINI_API_KEY is not set`                                       | インストールの手順 2 を確認し、Claude Code を起動し直してください                                                                                                                                             |
+| `ELEVENLABS_API_KEY is not set`                                   | 効果音のキーがありません。[作成の手順](docs/elevenlabs-key.ja.md)で作るか、効果音なしで作るよう Claude に伝えてください                                                                                       |
+| 効果音の生成が `HTTP 401` などで失敗する                          | キーで Sound Effects が許可されていないか、残高が足りません。エラーに続く理由を見て、ElevenLabs の Developers で確認してください                                                                              |
+| `came back silent` で効果音の生成が止まる                         | 3 回とも無音が返りました。`prompt` を具体的な音の説明に書き換えてやり直してください                                                                                                                           |
 | ナレーションや BGM の生成が何度も失敗する                         | 1 回 90 秒で打ち切り、3 回まで再試行します。それでも失敗するなら、API キーの権限と利用上限を確認してください                                                                                                  |
 | `motion-render` のインストールで ffmpeg のダウンロードが失敗する  | 社内プロキシなどで GitHub からの取得が止められています。`npm install -g --ignore-scripts <スキルのフォルダ>` で入れ、手元の ffmpeg を `FFMPEG_PATH` で指定してください（PATH 上の `ffmpeg` も自動で使います） |
 | 初回の Chromium のダウンロードが失敗する                          | `CHROMIUM_PATH` に手元の Chrome か Chromium を指定してください                                                                                                                                                |
@@ -201,6 +216,7 @@ skills/motion-render/     # スキル本体（skills CLI とプラグインの
   package.json            # motion-render コマンドと、依存の版（playwright-core, ffmpeg-static）
   scripts/cli.ts          # motion-render コマンド
   scripts/audio.ts        # ナレーションと BGM の生成、音声の合成
+  scripts/sfx.ts          # 効果音の生成（ElevenLabs）、音量のそろえ方、試聴用ファイル
   scripts/work.ts         # script.json の検証と場面の秒数の計算
   scripts/render.ts       # ブラウザで描画する部分
   scripts/json.ts         # ファイル・API・プレーヤーから来る JSON を、形を確かめながら読む
diff --git a/README.md b/README.md
index 7765859..a1a3aa6 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ https://github.com/user-attachments/assets/b62fe703-223d-478e-9e9b-3239a48ba1ea
 ![How motion-render works](docs/how-it-works.en.svg)
 
 - Look, length, voice and the mood of the music are chosen from the theme (anything you specify wins)
+- With an ElevenLabs API key, sound effects follow the animation too: a card appearing, a step of a flow lighting up
 - You can also pass the URL of an existing Motion film to get an MP4 with narration and BGM
 - The rendering browser (Chromium) and ffmpeg are set up automatically, so results don't depend on what is installed on your machine
 
@@ -32,6 +33,7 @@ https://github.com/user-attachments/assets/b62fe703-223d-478e-9e9b-3239a48ba1ea
 | Claude Code            | An account that can use [Claude Motion](https://support.claude.com/en/articles/17454997-get-started-with-claude-motion) (beta, Team and Enterprise plans only). Claude Code only: other agents such as Codex or Cursor have no Motion |
 | Node.js 22.18 or later | Check with `node -v`. Node runs the command's TypeScript directly                                                                                                                                                                     |
 | Gemini API key         | Used for narration and BGM. Create one in Google AI Studio ([step by step](docs/api-key.md))                                                                                                                                          |
+| ElevenLabs API key     | Optional, for sound effects. Pay-as-you-go works without a subscription ([step by step](docs/elevenlabs-key.md))                                                                                                                      |
 
 Works on macOS, Linux and Windows.
 
@@ -72,6 +74,14 @@ Create a Gemini API key in Google AI Studio ([step by step](docs/api-key.md)). T
 export GEMINI_API_KEY="your key"
 ```
 
+For sound effects, add an ElevenLabs key as well ([step by step](docs/elevenlabs-key.md)). Without it, videos are made without sound effects.
+
+```sh
+export ELEVENLABS_API_KEY="your key"
+```
+
+Sound effects made without a subscription are for non-commercial use only and must be credited in the title (for example with `11.ai`) when published. motion-render puts `🎧:11.ai` on the title of a video with sound effects.
+
 ### 3. Only if you use the Claude Code sandbox: add settings
 
 Chromium cannot start inside the sandbox. Add these two entries to `~/.claude/settings.json` so that only `motion-render` runs outside it.
@@ -114,18 +124,20 @@ On the first run, Chromium (about 210 MB) and ffmpeg are downloaded automaticall
 
 Each video uses one work directory (`<work>`). Its layout and the `script.json` format are in [SKILL.md](skills/motion-render/SKILL.md).
 
-| Command                                          | What it does                                                                     |
-| ------------------------------------------------ | -------------------------------------------------------------------------------- |
-| `motion-render narrate <work>`                   | Generates narration from `script.json` and writes scene lengths to `timing.json` |
-| `motion-render bgm <work>`                       | Generates the BGM from the `bgm` prompt in `script.json`                         |
-| `motion-render prepare <storeDir> <work>/film`   | Expands a Motion film's data into a directory it can render                      |
-| `motion-render stills <filmDir> <outDir> 0,5,12` | Writes still frames for checking                                                 |
-| `motion-render build <work> [out.mp4]`           | Mixes narration and BGM and renders the MP4 (stops if either is missing)         |
-| `motion-render --version`                        | Prints the version                                                               |
+| Command                                          | What it does                                                                         |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `motion-render narrate <work>`                   | Generates narration from `script.json` and writes scene lengths to `timing.json`     |
+| `motion-render bgm <work>`                       | Generates the BGM from the `bgm` prompt in `script.json`                             |
+| `motion-render sfx <work>`                       | Generates the sound effects in `script.json` and a `preview.m4a` of them in order    |
+| `motion-render prepare <storeDir> <work>/film`   | Expands a Motion film's data into a directory it can render                          |
+| `motion-render stills <filmDir> <outDir> 0,5,12` | Writes still frames for checking                                                     |
+| `motion-render build <work> [out.mp4]`           | Mixes narration, BGM and sound effects and renders the MP4 (stops if any is missing) |
+| `motion-render --version`                        | Prints the version                                                                   |
 
 | Environment variable    | Effect                                                     |
 | ----------------------- | ---------------------------------------------------------- |
 | `GEMINI_API_KEY`        | Required for narration and BGM                             |
+| `ELEVENLABS_API_KEY`    | Required for sound effects (none are added without it)     |
 | `MOTION_RENDER_OUT_DIR` | Default output directory when `build` gets no output path  |
 | `CHROMIUM_PATH`         | Use your own Chrome or Chromium instead of the bundled one |
 | `FFMPEG_PATH`           | Use your own ffmpeg instead of the bundled one             |
@@ -136,6 +148,9 @@ Each video uses one work directory (`<work>`). Its layout and the `script.json`
 | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | The browser fails with `bootstrap_check_in ... Permission denied`   | It is running inside the Claude Code sandbox. Check step 3 of the install. `motion-render` must run on its own (chaining it with `\| grep` or `&&` keeps it in the sandbox) |
 | `GEMINI_API_KEY is not set`                                         | Check step 2 of the install and restart Claude Code                                                                                                                         |
+| `ELEVENLABS_API_KEY is not set`                                     | There is no key for sound effects. Create one ([step by step](docs/elevenlabs-key.md)) or ask Claude to make the video without sound effects                                |
+| Sound effect generation fails with `HTTP 401` or similar            | The key does not allow Sound Effects, or the balance has run out. Read the reason after the status and check Developers in ElevenLabs                                       |
+| Sound effect generation stops with `came back silent`               | Silence came back three times. Rewrite the `prompt` as a more concrete sound and try again                                                                                  |
 | Narration or BGM generation keeps failing                           | Each request times out after 90 seconds and is retried up to 3 times. If it still fails, check your API key's permissions and quota                                         |
 | ffmpeg fails to download                                            | A proxy is blocking downloads from GitHub. Install ffmpeg yourself (it is used from `PATH`) or point `FFMPEG_PATH` at it                                                    |
 | Chromium fails to download on first run                             | Point `CHROMIUM_PATH` at your own Chrome or Chromium                                                                                                                        |
@@ -201,6 +216,7 @@ skills/motion-render/     # The skill (read by both the skills CLI and the plugi
   package.json            # The motion-render command and pinned dependencies (playwright-core, ffmpeg-static)
   scripts/cli.ts          # The motion-render command
   scripts/audio.ts        # Narration and BGM generation, audio mixing
+  scripts/sfx.ts          # Sound effect generation (ElevenLabs), leveling and the listening file
   scripts/work.ts         # script.json validation and scene timing
   scripts/render.ts       # Rendering in the browser
   scripts/json.ts         # Reading JSON from files, APIs and the player without trusting its shape
diff --git a/docs/elevenlabs-key.ja.md b/docs/elevenlabs-key.ja.md
new file mode 100644
index 0000000..0e7a119
--- /dev/null
+++ b/docs/elevenlabs-key.ja.md
@@ -0,0 +1,50 @@
+# ElevenLabs で効果音用の API キーを作る
+
+[English](elevenlabs-key.md)
+
+motion-render は、アニメーションに合わせた効果音を ElevenLabs の Sound Effects API で作る。効果音は任意で、`ELEVENLABS_API_KEY` が無ければ付かない（ナレーションと BGM だけの動画になる）。このページでは、月額プランに入らずに従量課金（Pay As You Go）でキーを作り、motion-render に渡すまでを説明する。
+
+## 1. 残高を入れる
+
+Sound Effects API は無料プランでは使えない。従量課金の残高を入れると使えるようになる。月額プランへの加入は要らない。
+
+1. [elevenlabs.io](https://elevenlabs.io) でアカウントを作り、ログインする。
+2. [Developers](https://elevenlabs.io/app/developers) を開く。
+3. **Usage**（使用状況）の **Add credits**（クレジットを追加）を押す。隣の月額プランへの加入ボタンとは別物なので注意する。
+4. 金額を入れる。最低 $5。月額プランをすすめる確認が出たら、そのまま進める（日本語の画面では「チャージ」）。
+5. 支払い方法を選んで払う。カードを登録していなくても、Stripe の画面で払える。
+6. 自動チャージ（Auto Top Up）は使わなくてよい。
+
+画面に「Pay As You Go」（従量課金プラン）と出れば完了。残高が 0 になると API はその場で止まり、後から請求されることはない。入れた残高は払い戻されず、購入から 12 か月で失効する。
+
+## 2. キーを作る
+
+1. Developers の **API Keys** タブで、新しいキーを作る。名前は `motion-render` など。
+2. **Restrict key**（キーを制限）をオンのままにし、**Sound Effects**（サウンドエフェクト）だけを **Access** にする。ほかはすべて **No Access** のままにする。漏れたときの被害を効果音の生成に限るため。
+3. 使用制限（クレジット）は空欄でよい。残高を超えて使われることはない。
+4. 作成すると、キーが 1 回だけ表示される。後からは末尾 4 文字しか見られないので、すぐにコピーする。
+
+## 3. キーを設定する
+
+motion-render は環境変数 `ELEVENLABS_API_KEY` からキーを読む。キーをリポジトリや dotfiles にコミットしないこと。
+
+```sh
+# ~/.zshrc など
+export ELEVENLABS_API_KEY="..."
+```
+
+macOS のキーチェーンに入れる方法は、[Gemini のキーの手順](api-key.ja.md#2-キーを設定する)と同じ（サービス名を変える）。設定したら Claude Code を起動し直す。
+
+## 料金
+
+出力の秒数に比例する。2026 年 10 月に確かめた値で、1 秒あたり約 5 クレジット、約 $0.002。1 秒の効果音を 10 個付けた動画で約 $0.02。同じ `prompt` と `duration` の効果音は 1 回しか作らないので、作り直しても変えた分しか課金されない。
+
+## 公開と商用利用
+
+ElevenLabs のヘルプ（[Can I publish the content I generate on the platform?](https://elevenlabs.io/docs/help-center/legal/can-i-publish-the-content-i-generate-on-the-platform)）では、商用ライセンスが付くのは有料の月額プランで作ったものだけで、それ以外は非商用に限られ、公開するときは題名に `elevenlabs.io` か `11.ai` を入れる。従量課金についての記述は無い。
+
+motion-render は、効果音を付けた動画のタイトルの場面に `🎧:11.ai` を入れる。商用に使う動画には、月額プランに入ってから効果音を作ること（プラン外で作った音は、後から加入しても商用に使えない）。
+
+## キーが漏れたとき
+
+API Keys タブでそのキーを削除し、新しいキーを作る。
diff --git a/docs/elevenlabs-key.md b/docs/elevenlabs-key.md
new file mode 100644
index 0000000..ed42575
--- /dev/null
+++ b/docs/elevenlabs-key.md
@@ -0,0 +1,50 @@
+# Creating an ElevenLabs API key for sound effects
+
+[日本語](elevenlabs-key.ja.md)
+
+motion-render makes sound effects that follow the animation with the ElevenLabs Sound Effects API. Sound effects are optional: without `ELEVENLABS_API_KEY`, the video gets narration and BGM only. This page shows how to create a key on pay-as-you-go, without a subscription, and hand it to motion-render.
+
+## 1. Add credits
+
+The Sound Effects API is not available on the free plan. A pay-as-you-go balance unlocks it; no subscription is needed.
+
+1. Sign up at [elevenlabs.io](https://elevenlabs.io) and log in.
+2. Open [Developers](https://elevenlabs.io/app/developers).
+3. Under **Usage**, choose **Add credits**. It is not the subscription button next to it.
+4. Enter an amount (at least $5). If you are offered a subscription first, continue with the top-up.
+5. Pay. A saved card is not required: the Stripe checkout takes the payment.
+6. Auto Top Up can stay off.
+
+The account now shows "Pay As You Go". When the balance reaches zero, the API stops at once; you are never billed afterwards. Top-ups are not refundable and expire 12 months after purchase.
+
+## 2. Create the key
+
+1. In the **API Keys** tab of Developers, create a key, for example `motion-render`.
+2. Keep **Restrict key** on and set only **Sound Effects** to **Access**; leave everything else at **No Access**. A leaked key can then only make sound effects.
+3. Leave the credit limit empty: usage can never exceed the balance.
+4. The key is shown once. Copy it now: afterwards only its last four characters are visible.
+
+## 3. Set the key
+
+motion-render reads the key from `ELEVENLABS_API_KEY`. Do not commit the key to a repository or dotfiles.
+
+```sh
+# ~/.zshrc etc.
+export ELEVENLABS_API_KEY="..."
+```
+
+To keep it in the macOS keychain instead, follow the [Gemini key steps](api-key.md#2-set-the-key) with a different service name. Restart Claude Code after setting it.
+
+## Cost
+
+Billed by the second of output. Measured in October 2026: about 5 credits, roughly $0.002, per second. Ten one-second effects cost about $0.02. An effect with the same `prompt` and `duration` is made only once, so a rebuild only pays for what changed.
+
+## Publishing and commercial use
+
+According to the ElevenLabs help center ([Can I publish the content I generate on the platform?](https://elevenlabs.io/docs/help-center/legal/can-i-publish-the-content-i-generate-on-the-platform)), only content made on a paid subscription carries a commercial license. Anything else is for non-commercial use only and must be credited with `elevenlabs.io` or `11.ai` in its title when published. The page does not mention pay-as-you-go.
+
+motion-render puts `🎧:11.ai` on the title scene of a video with sound effects. For a commercial video, subscribe before making its effects: audio made outside a subscription does not become licensed when you subscribe later.
+
+## If the key leaks
+
+Delete the key in the API Keys tab and create a new one.

From 9f0b6b22fe469f18755a37b4062ae39617d88f46 Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Mon, 19 Oct 2026 01:37:54 +0900
Subject: [PATCH 3/5] fix(sfx): level effects against the narration so they are
 audible

---
 skills/motion-render/SKILL.md        |  7 +++--
 skills/motion-render/scripts/cli.ts  |  5 ++--
 skills/motion-render/scripts/sfx.ts  | 36 +++++++++++++++++------
 skills/motion-render/scripts/work.ts |  2 +-
 tests/sfx.test.ts                    | 44 +++++++++++++++++++++++-----
 tests/work.test.ts                   |  2 +-
 6 files changed, 73 insertions(+), 23 deletions(-)

diff --git a/skills/motion-render/SKILL.md b/skills/motion-render/SKILL.md
index 16bcd2f..920e844 100644
--- a/skills/motion-render/SKILL.md
+++ b/skills/motion-render/SKILL.md
@@ -83,7 +83,7 @@ Motion の Artifact 型は作成時に Style・Colors・Length を質問する
 - `id` は英小文字・数字・`-`。Motion の場面の id と同じにする
 - `narration` は TTS に読ませる文。英語の固有名詞・略語はカタカナで書く（`GitHub Actions` → `ギットハブアクションズ`）。
   画面の文字は元の表記のまま
-- 任意: `voice`・`speed`・`bgmVolume`（既定 0.15）・`sfxVolume`（既定 0.5）・`lead`・`tail`・`endHold`
+- 任意: `voice`・`speed`・`bgmVolume`（既定 0.15）・`sfxVolume`（既定 1）・`lead`・`tail`・`endHold`
 - 任意: 場面ごとの `sfx`。`at` は場面の頭からの秒、`duration` は 0.5〜10 秒（既定 1.5）、`volume` は 0〜1（既定 `sfxVolume`）
 
 ## 手順
@@ -179,8 +179,9 @@ motion-render build <work> [<出力.mp4>]
 | 段が光る・強調     | gentle glassy chime              | 1.0        |
 | 完了・成功         | soft positive notification chime | 1.2        |
 
-`build` は、効果音ごとに音量を一定の水準にそろえ（生成される音は 30 dB 以上ばらつく）、`duration` で切り、
-両端をフェードしてからナレーションの下に混ぜる。無音で返ってきた効果音は `sfx` が作り直し、3 回とも無音なら止まる。
+`build` は、効果音ごとに音量をナレーションの平均より 4 dB 下にそろえ（生成される音は 30 dB 以上ばらつく）、
+`volume` を掛け、`duration` で切り、両端をフェードしてから混ぜる。`volume` を下げすぎると話し声に埋もれて聞こえない
+（10 dB 下で聞こえなくなった）。無音で返ってきた効果音は `sfx` が作り直し、3 回とも無音なら止まる。
 
 **表記**: 月額プランなしで作った効果音は、商用に使えず、公開するときは題名に `elevenlabs.io` か `11.ai` を入れる
 （ElevenLabs のヘルプ「Can I publish the content I generate on the platform?」）。効果音を付けた動画では、
diff --git a/skills/motion-render/scripts/cli.ts b/skills/motion-render/scripts/cli.ts
index 3b2607d..c737699 100755
--- a/skills/motion-render/scripts/cli.ts
+++ b/skills/motion-render/scripts/cli.ts
@@ -9,7 +9,7 @@ import { fileURLToPath } from "node:url";
 import { openFilm, checkFilmDir, type Film } from "./render.ts";
 import { narrate, bgm, bgmFile, mix, findFfmpeg, encodeArgs } from "./audio.ts";
 import { loadScript, writeTiming, loadTiming, placeOnFilm, placeSfx } from "./work.ts";
-import { checkSfx, makeSfx, previewSfx, sfxTrack } from "./sfx.ts";
+import { checkSfx, makeSfx, narrationLevel, previewSfx, sfxTrack } from "./sfx.ts";
 import { prepare } from "./store.ts";
 import { errorMessage, field, readJson } from "./json.ts";
 
@@ -129,7 +129,8 @@ async function build(work: string, out: string, fps: number): Promise<void> {
   try {
     const warn = (w: string) => console.error(`warning: ${w}`);
     const scenes = placeOnFilm(timing, film.meta, script, warn);
-    const sfx = placeSfx(script, film.meta.parts, warn).map((c) => sfxTrack(work, c));
+    const narration = await narrationLevel(work, script);
+    const sfx = placeSfx(script, film.meta.parts, warn).map((c) => sfxTrack(work, c, narration));
     const audio = join(work, "audio", "mix.m4a");
     await mix(work, script, { scenes, total: film.meta.duration, sfx }, audio);
     mkdirSync(dirname(out), { recursive: true });
diff --git a/skills/motion-render/scripts/sfx.ts b/skills/motion-render/scripts/sfx.ts
index ea5674d..f595a53 100644
--- a/skills/motion-render/scripts/sfx.ts
+++ b/skills/motion-render/scripts/sfx.ts
@@ -16,10 +16,12 @@ import type { Script, SfxCue } from "./work.ts";
 const API = "https://api.elevenlabs.io/v1/sound-generation?output_format=mp3_44100_128"; // the best format pay-as-you-go allows
 const MODEL = "eleven_text_to_sound_v2";
 const SILENT_DB = -60; // a peak below this means the effect came back silent
-// Generated effects differ in level by 30 dB or more: each is brought to TARGET_MEAN_DB on average,
-// unless that would push its peak past TARGET_PEAK_DB.
-const TARGET_MEAN_DB = -20;
-const TARGET_PEAK_DB = -1;
+// Generated effects differ in level by 30 dB or more, so each is leveled against the narration: on
+// average UNDER_NARRATION_DB below it (chosen by ear; 10 dB under was masked by the speech), times its
+// volume, without letting its peak pass PEAK_DB.
+const UNDER_NARRATION_DB = 4;
+const PEAK_DB = -1;
+const NARRATION_DB = -16; // Gemini TTS's usual average level, for when there is no narration yet
 const PREVIEW_GAP = 0.6;
 
 interface Level {
@@ -129,15 +131,30 @@ function level(work: string, prompt: string, duration: number): Level {
   return { mean, max };
 }
 
-// An effect ready for mixing: its file, its time and the gain that levels it, times its own volume.
-export function sfxTrack(work: string, cue: SfxCue): SfxTrack {
+// The narration's average level in dBFS over the scenes narrated so far: what the effects are leveled against.
+export async function narrationLevel(work: string, script: Script): Promise<number> {
+  const files = script.scenes
+    .map((s) => join(work, "audio", `${s.id}.wav`))
+    .filter((f) => existsSync(f));
+  if (!files.length) return NARRATION_DB;
+  let sum = 0;
+  for (const f of files) sum += (await volumeStats(f)).mean;
+  return sum / files.length;
+}
+
+// An effect ready for mixing: its file, its time and the gain that puts it UNDER_NARRATION_DB below
+// `narration` (dBFS), lowered by its own volume, with the peak capped.
+export function sfxTrack(work: string, cue: SfxCue, narration: number): SfxTrack {
   const { mean, max } = level(work, cue.prompt, cue.duration);
-  const db = Math.min(TARGET_MEAN_DB - mean, TARGET_PEAK_DB - max);
+  const db = Math.min(
+    narration - UNDER_NARRATION_DB - mean + 20 * Math.log10(cue.volume),
+    PEAK_DB - max
+  );
   return {
     file: sfxFile(work, cue.prompt, cue.duration, "mp3"),
     start: cue.start,
     duration: cue.duration,
-    gain: cue.volume * 10 ** (db / 20),
+    gain: 10 ** (db / 20),
   };
 }
 
@@ -156,12 +173,13 @@ export async function previewSfx(
 ): Promise<{ file: string; list: PreviewEntry[] } | null> {
   const all = allSfx(script);
   if (!all.length) return null;
+  const narration = await narrationLevel(work, script);
   let offset = 0;
   const list: PreviewEntry[] = [],
     inputs: string[] = [],
     graph: string[] = [];
   all.forEach((fx, i) => {
-    const t = sfxTrack(work, { ...fx, start: 0 });
+    const t = sfxTrack(work, { ...fx, start: 0 }, narration);
     inputs.push("-i", t.file);
     graph.push(sfxChain(i, t, `s${i}`), `[s${i}]apad=pad_dur=${PREVIEW_GAP}[p${i}]`);
     list.push({
diff --git a/skills/motion-render/scripts/work.ts b/skills/motion-render/scripts/work.ts
index ec95248..9225258 100644
--- a/skills/motion-render/scripts/work.ts
+++ b/skills/motion-render/scripts/work.ts
@@ -52,7 +52,7 @@ const DEFAULTS = {
   ttsModel: "gemini-3.8-flash-tts",
   bgmModel: "lyria-3.5",
   bgmVolume: 0.15,
-  sfxVolume: 0.5,
+  sfxVolume: 1, // 1 = leveled 4 dB under the narration (sfx.ts)
   lead: 0.25, // silence before each scene's narration
   tail: 0.35, // silence after it
   endHold: 3, // the last scene holds this long after its narration
diff --git a/tests/sfx.test.ts b/tests/sfx.test.ts
index ff13632..81be7e9 100644
--- a/tests/sfx.test.ts
+++ b/tests/sfx.test.ts
@@ -27,7 +27,7 @@ vi.mock("node:child_process", async (importOriginal) => {
   };
 });
 
-const { checkSfx, makeSfx, previewSfx, sfxKey, sfxTrack } =
+const { checkSfx, makeSfx, narrationLevel, previewSfx, sfxKey, sfxTrack } =
   await import("../skills/motion-render/scripts/sfx.ts");
 const { volumeStats } = await import("../skills/motion-render/scripts/audio.ts");
 const { loadScript } = await import("../skills/motion-render/scripts/work.ts");
@@ -154,25 +154,55 @@ describe("sfxTrack", () => {
       JSON.stringify({ prompt, duration, mean, max })
     );
 
-  it("brings a quiet effect up to the common average level", async () => {
+  it("brings a quiet effect to 4 dB under the narration's average level", async () => {
     const dir = workDir(SFX_SCRIPT);
     await makeSfx(dir, loadScript(dir));
     meta(dir, "soft UI pop", 0.8, -50, -32);
-    const t = sfxTrack(dir, { ...pop, volume: 0.5, start: 3 });
+    const t = sfxTrack(dir, { ...pop, volume: 1, start: 3 }, -16);
     expect(t).toMatchObject({
       file: sfxPath(dir, "soft UI pop", 0.8, "mp3"),
       start: 3,
       duration: 0.8,
     });
-    expect(t.gain).toBeCloseTo(0.5 * 10 ** (30 / 20), 6); // +30 dB to reach -20 dB on average
+    expect(t.gain).toBeCloseTo(10 ** (30 / 20), 6); // -50 dB -> -20 dB
   });
 
-  it("stops short of clipping a loud effect", async () => {
+  it("lowers an effect by its volume", async () => {
+    const dir = workDir(SFX_SCRIPT);
+    await makeSfx(dir, loadScript(dir));
+    meta(dir, "soft UI pop", 0.8, -50, -32);
+    const t = sfxTrack(dir, { ...pop, volume: 0.5, start: 0 }, -10);
+    expect(t.gain).toBeCloseTo(0.5 * 10 ** (36 / 20), 6); // -50 dB -> -14 dB, then halved
+  });
+
+  it("stops short of clipping a loud effect, and still lowers it by its volume", async () => {
     const dir = workDir(SFX_SCRIPT);
     await makeSfx(dir, loadScript(dir));
     meta(dir, "quick airy whoosh", 1.5, -21.5, 0);
-    const t = sfxTrack(dir, { ...whoosh, duration: 1.5, volume: 1, start: 0 });
-    expect(t.gain).toBeCloseTo(10 ** (-1 / 20), 6); // peak held at -1 dB
+    const loud = { ...whoosh, duration: 1.5, start: 0 };
+    expect(sfxTrack(dir, { ...loud, volume: 1 }, -16).gain).toBeCloseTo(10 ** (-1 / 20), 6); // peak held at -1 dB
+    expect(sfxTrack(dir, { ...loud, volume: 0.1 }, -16).gain).toBeCloseTo(
+      0.1 * 10 ** (1.5 / 20),
+      6
+    );
+  });
+});
+
+describe("narrationLevel", () => {
+  it("averages the narration's level over the scenes", async () => {
+    ffmpeg.log = "mean_volume: -14.0 dB\nmax_volume: -1.0 dB\n";
+    const dir = workDir(SFX_SCRIPT, { intro: 1, flow: 1 });
+    expect(await narrationLevel(dir, loadScript(dir))).toBe(-14);
+    expect(ffmpeg.calls.map((a) => a[a.indexOf("-i") + 1])).toEqual([
+      join(dir, "audio", "intro.wav"),
+      join(dir, "audio", "flow.wav"),
+    ]);
+  });
+
+  it("assumes Gemini TTS's usual level before there is any narration", async () => {
+    const dir = workDir(SFX_SCRIPT);
+    expect(await narrationLevel(dir, loadScript(dir))).toBe(-16);
+    expect(ffmpeg.calls).toEqual([]);
   });
 });
 
diff --git a/tests/work.test.ts b/tests/work.test.ts
index 5891990..8509a38 100644
--- a/tests/work.test.ts
+++ b/tests/work.test.ts
@@ -28,7 +28,7 @@ describe("loadScript", () => {
       ttsModel: "gemini-3.8-flash-tts",
       bgmModel: "lyria-3.5",
       bgmVolume: 0.15,
-      sfxVolume: 0.5,
+      sfxVolume: 1,
       lead: 0.25,
       tail: 0.35,
       endHold: 3,

From d60442aa26d69ff0f72c64e7daca572c0dda03c7 Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Mon, 19 Oct 2026 22:54:53 +0900
Subject: [PATCH 4/5] docs(readme): mention sound effects in the opening
 sentence

---
 README.ja.md | 2 +-
 README.md    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.ja.md b/README.ja.md
index 9763642..6b29f6d 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 日本語
 
-テーマを伝えるだけで、それを説明する**アニメーション動画を作り、ナレーションと BGM を付けて MP4 にする** Agent Skill です。
+テーマを伝えるだけで、それを説明する**アニメーション動画を作り、ナレーション・BGM・効果音を付けて MP4 にする** Agent Skill です。
 
 ```
 /motion-render:motion-render Workload Identity Federation による GitHub Actions から Google Cloud への認証の仕組みを説明する動画つくって
diff --git a/README.md b/README.md
index a1a3aa6..dfd57a4 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 English | [日本語](README.ja.md)
 
-An Agent Skill that turns a theme into an **animated explainer video with narration and background music, rendered to MP4**.
+An Agent Skill that turns a theme into an **animated explainer video with narration, background music and sound effects, rendered to MP4**.
 
 ```
 /motion-render:motion-render Make a video that explains how GitHub Actions authenticates to Google Cloud with Workload Identity Federation

From 2101648dd0925ebb0f8699ae38b8c606be6fc5cf Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Mon, 19 Oct 2026 23:21:34 +0900
Subject: [PATCH 5/5] docs(readme): link the example videos on the wiki

---
 README.ja.md | 2 ++
 README.md    | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/README.ja.md b/README.ja.md
index 6b29f6d..5903661 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -19,6 +19,8 @@ motion-render 自身が作った紹介動画です（59 秒、音声あり）。
 
 https://github.com/user-attachments/assets/eb1bf7e6-a880-4bbe-b575-7f4ec5c21672
 
+効果音付きの動画など、ほかの作例は Wiki の[作例](https://github.com/umiyosh/motion-render/wiki/%E4%BD%9C%E4%BE%8B)にあります。
+
 ![motion-render の仕組み](docs/how-it-works.svg)
 
 - 見た目・長さ・声・BGM の雰囲気はテーマから自動で決まります（指定すればそれに従います）
diff --git a/README.md b/README.md
index dfd57a4..e1fe8e7 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,8 @@ An introduction video made by motion-render itself (57 seconds, with sound).
 
 https://github.com/user-attachments/assets/b62fe703-223d-478e-9e9b-3239a48ba1ea
 
+More videos, including one with sound effects, are in [Examples](https://github.com/umiyosh/motion-render/wiki/Examples) on the wiki.
+
 ![How motion-render works](docs/how-it-works.en.svg)
 
 - Look, length, voice and the mood of the music are chosen from the theme (anything you specify wins)