{"slug":"jianshuo-wjs-burning-subtitles-353998","title":"\u5b57\u5e55\u70e7\u5f55\u4e0e\u914d\u97f3\u6df7\u97f3\u5408\u6210","description":"\u628aSRT\u5b57\u5e55\u70e7\u8fdb\u753b\u9762\uff08libass\u786c\u5b57\u5e55\uff09\u6216\u8f6f\u5c01\u88c5\u4e3a\u53ef\u5f00\u5173\u5b57\u5e55\u8f68\uff0c\u5e76\u53ef\u5728\u4e00\u6b21ffmpeg\u7f16\u7801\u5185\u5b8c\u6210\u201c\u70e7\u5b57\u5e55+\u6df7\u5165\u914d\u97f3+\u539f\u58f0\u4f4e\u97f3\u91cf\u57ab\u5e95\u201d\u7684\u6700\u7ec8\u5408\u6210\uff1b\u542blibass\u53ef\u7528\u6027\u6821\u9a8c\u3001\u5b57\u53f7\u6821\u51c6\u4e0e\u9884\u89c8\u786e\u8ba4\u68c0\u67e5\u70b9\u3002","category":"\u526a\u8f91\u4e0e\u5305\u88c5","tags":["jianshuo","\u5efa\u7855","\u526a\u8f91\u4e0e\u5305\u88c5"],"author":"\u5efa\u7855 \u00b7 jianshuo","source_url":"https://github.com/jianshuo/claude-skills/blob/d36bc423286a34eb32adc604121e5c7714b08740/wjs-burning-subtitles/SKILL.md","license":"MIT","status":"published","verification":"source_reviewed","verification_notes":"\u5df2\u6838\u5bf9\u539f\u59cb\u4ed3\u5e93\u3001\u56fa\u5b9a\u63d0\u4ea4\u3001\u8bb8\u53ef\u3001\u6280\u80fd\u6b63\u6587\u4e0e\u5305\u7ed3\u6784\uff0c\u5e76\u8865\u5145\u4e2d\u6587\u6267\u884c\u9a8c\u6536\u8bf4\u660e\uff1b\u672a\u8fd0\u884c\u5305\u5185\u811a\u672c\u3002","revision":"35158766635242018817d8a0f09275a4","created_at":"2026-11-02T14:47:08+00:00","updated_at":"2026-11-02T14:47:08+00:00","source_repo":"jianshuo/claude-skills","source_path":"wjs-burning-subtitles/SKILL.md","source_commit":"d36bc423286a34eb32adc604121e5c7714b08740","source_updated_at":"2026-11-02T14:46:04+00:00","stars":0,"proxy_score":null,"score":null,"grade":null,"dimensions":{},"evaluation":{},"installs":0,"platforms":[],"formats":[],"category_slug":"packaging","category_name":"\u526a\u8f91\u4e0e\u5305\u88c5","quality":{"review_type":"text_and_package_review","readiness":"requires_setup","reviewed_at":"2026-11-02T14:46:04+00:00","review_summary":"\u65b9\u6cd5\u5177\u4f53\u3001\u68c0\u67e5\u70b9\u660e\u786e\uff08libass\u6821\u9a8c\u3001\u62bd\u5e27\u786e\u8ba4\u3001\u9017\u53f7\u8f6c\u4e49\uff09\uff0c\u53ef\u76f4\u63a5\u6307\u5bfc\u6210\u7247\u5408\u6210\uff1b\u4f46\u4f9d\u8d56\u672c\u673affmpeg\u6784\u5efa\u4e0e\u4e0a\u6e38\u5b57\u5e55/\u914d\u97f3\u6280\u80fd\uff0c\u9700\u6309requires_setup\u63d0\u793a\u51c6\u5907\u3002","cost_notes":"\u65e0\u5916\u90e8\u4ed8\u8d39\u670d\u52a1\uff1b\u9759\u6001ffmpeg\u6784\u5efa\u4e3a\u514d\u8d39\u4e0b\u8f7d\uff0c\u4f46\u9700\u8054\u7f51\u4e0e\u78c1\u76d8\u7a7a\u95f4\uff0c\u662f\u5426\u4e0b\u8f7d\u7531\u7528\u6237\u786e\u8ba4\u3002","source_sha256":"c6c4bec70dd676c61d040475ab7ddd2700713641dc4bf0d780c674202f9e9e89","prerequisites":["\u672c\u673affmpeg\uff1b\u786c\u70e7\u9700\u542blibass\u4e0elibfreetype\u7684\u6784\u5efa","Python 3\uff08\u8fd0\u884crender.py\uff09","macOS\u7f3alibass\u65f6\u53ef\u4e0b\u8f7devermeet\u9759\u6001\u6784\u5efa\u5230/tmp/ff_bin\uff08\u9700\u8054\u7f51\uff09","\u4e2d\u6587\u5b57\u4f53\uff08\u5982PingFang SC\uff09\u5df2\u5b89\u88c5"],"checks":["\u786c\u70e7\u524d\u5df2\u7528 ffmpeg -filters \u786e\u8ba4 subtitles/ass \u6ee4\u955c\u5b58\u5728\uff0c\u7f3a\u5931\u65f6\u8bf4\u660e\u66ff\u4ee3\u65b9\u6848","force_style \u5185\u6240\u6709\u9017\u53f7\u5747\u8f6c\u4e49\u4e3a \\,\uff0c\u672a\u51fa\u73b0\u88f8\u9017\u53f7\u5bfc\u81f4\u6ee4\u955c\u94fe\u65ad\u88c2","\u5df2\u62bd\u53d6\u6700\u957f\u884c\u5b57\u5e55\u6240\u5728\u65f6\u95f4\u70b9\u7684\u5e27\u5e76\u5c55\u793a\uff0c\u5b57\u53f7/\u8fb9\u8ddd\u7ecf\u7528\u6237\u786e\u8ba4\u540e\u624d\u8dd1\u5168\u7247","\u8f6f\u5c01\u88c5\u8def\u5f84\u4e3a\u6d41\u590d\u5236\uff08-c:v copy\uff09\uff0c\u672a\u53d1\u751f\u91cd\u7f16\u7801","\u6df7\u97f3\u4f7f\u7528 normalize=0\uff0c\u539f\u58f0\u57ab\u5e95\u97f3\u91cf\u57280.15\u20130.25\u533a\u95f4\u4e14\u53ef\u5173\u95ed"],"limitations":["\u5b57\u53f7\u4e3a\u7ecf\u9a8c\u8d77\u70b9\uff0812\uff09\uff0c\u4e0d\u540c\u5206\u8fa8\u7387\u9700\u9010\u7247\u6821\u51c6\uff0c\u5305\u5185\u672a\u63d0\u4f9b\u81ea\u52a8\u9002\u914d","\u8f6f\u5c01\u88c5mov_text\u5728\u90e8\u5206\u5b89\u5353\u64ad\u653e\u5668\u4e0d\u663e\u793a\uff0c\u9762\u5411\u79fb\u52a8\u7aef\u4e2d\u6587\u7528\u6237\u65f6\u4e0d\u53ef\u9760","evermeet\u9759\u6001\u6784\u5efa\u4ec5\u8986\u76d6macOS\uff0c\u5176\u4ed6\u7cfb\u7edf\u7f3alibass\u65f6\u9700\u7528\u6237\u81ea\u884c\u89e3\u51b3","render.py \u4e0e\u793a\u4f8b\u547d\u4ee4\u672a\u5728\u672c\u5ba1\u9605\u4e2d\u6267\u884c\uff0c\u5b9e\u9645\u7f16\u7801\u7ed3\u679c\u5f85\u7528\u6237\u73af\u5883\u9a8c\u8bc1"],"issues":["SKILL.md \u5f15\u7528\u4e0a\u6e38\u6280\u80fd /wjs-transcribing-audio\u3001/wjs-translating-subtitles\u3001/wjs-dubbing-video \u4e0e /wjs-overlaying-video\uff0c\u5747\u672a\u968f\u5305\u63d0\u4f9b\uff0c\u5c5e\u5916\u90e8\u4f9d\u8d56\uff0c\u9700\u7528\u6237\u53e6\u884c\u5177\u5907","\u81ea\u52a8\u4e0b\u8f7d\u7b2c\u4e09\u65b9\u9759\u6001ffmpeg\u6784\u5efa\u5c5e\u5916\u90e8\u6765\u6e90\uff0c\u9700\u7528\u6237\u77e5\u60c5\u540c\u610f\uff0c\u5305\u5185\u672a\u8bf4\u660e\u6821\u9a8c\u65b9\u5f0f"],"missing_files":[]},"quality_url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/files/SHILIU-QUALITY.md","usage_guide":{"task":"\u7ed9\u5b9a\u89c6\u9891\u4e0eSRT\uff08\u53ef\u9009\u914d\u97f3\u8f68\uff09\uff0c\u4ea7\u51fa\u53ef\u76f4\u63a5\u4e0a\u4f20\u793e\u4ea4\u5e73\u53f0\u7684\u6210\u7247\uff1a\u786c\u5b57\u5e55\u7248\u3001\u8f6f\u5b57\u5e55\u7248\uff0c\u6216\u70e7\u5b57\u5e55+\u914d\u97f3+\u539f\u58f0\u57ab\u5e95\u7684\u5b8c\u6574\u672c\u5730\u5316\u7248\u672c\u3002","inputs":"\u6e90\u89c6\u9891\u6587\u4ef6\uff1bSRT\u5b57\u5e55\u6587\u4ef6\uff08\u65f6\u95f4\u7801\u7528\u9017\u53f7\u6beb\u79d2\uff0c\u5355\u884c\u2264\u7ea615\u4e2a\u6c49\u5b57\uff09\uff1b\u53ef\u9009\u914d\u97f3\u97f3\u8f68\u6587\u4ef6\uff1b\u53ef\u9009\u6837\u5f0f\u53c2\u6570\uff08\u5b57\u4f53\u3001\u5b57\u53f7\u3001\u989c\u8272\u3001\u8fb9\u8ddd\u3001\u57ab\u5e95\u97f3\u91cf\uff09\uff1b\u672c\u673affmpeg\uff08\u9700\u542blibass\u624d\u80fd\u786c\u70e7\uff09\u3002","outputs":"\u786c\u70e7\u7248 <source>_burned.mp4\uff1b\u8f6f\u5c01\u88c5\u7248 <source>_softsub.mp4\uff08mov_text\u8f68\uff09\uff1b\u5b8c\u6574\u5408\u6210\u7248 <source>_final.mp4\uff1b\u4ee5\u53ca\u7528\u4e8e\u786e\u8ba4\u7684\u9884\u89c8\u5e27\u56fe\u7247\u3002","example_input":"\u628a input.mp4 \u548c input.zh-CN.srt \u70e7\u6210\u786c\u5b57\u5e55\uff0c\u5b57\u53f7\u5148\u630912\u8bd5\uff0c\u5148\u7ed9\u6211\u770b\u6700\u957f\u90a3\u884c\u5b57\u5e55\u7684\u9884\u89c8\u5e27\uff0c\u786e\u8ba4\u540e\u518d\u8dd1\u5168\u7247\u3002","example_output":"\u793a\u610f\uff08\u975e\u771f\u5b9e\u7ed3\u679c\uff09\uff1a\u5148\u8f93\u51falibass\u68c0\u6d4b\u7ed3\u679c\u4e0e\u6240\u7528ffmpeg\u8def\u5f84\uff1b\u7ed9\u51fa30\u79d2\u9884\u89c8\u7247\u6bb5\u4e0e\u62bd\u5e27\u56fe\u7247\u8def\u5f84\uff1b\u7528\u6237\u786e\u8ba4\u540e\u8f93\u51fa final \u6587\u4ef6\u540d\u3001\u7f16\u7801\u53c2\u6570\uff08libx264/crf18/yuv420p\uff09\u4e0e\u97f3\u9891\u53c2\u6570\uff08aac 192k\uff09\u3002"},"read_url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998","skill_url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/files/SKILL.md","download_url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/download","install_url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/install","files":[{"path":"LICENSE","bytes":1082,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/files/LICENSE"},{"path":"SHILIU-QUALITY.md","bytes":2116,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/files/SHILIU-QUALITY.md"},{"path":"SKILL.md","bytes":12037,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/files/SKILL.md"},{"path":"scripts/render.py","bytes":6433,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/files/scripts/render.py"},{"path":"shiliu-quality.json","bytes":1983,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/files/shiliu-quality.json"},{"path":"shiliu-source.json","bytes":273,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/files/shiliu-source.json"},{"path":"usage.json","bytes":1040,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-burning-subtitles-353998/files/usage.json"}],"content":"---\nname: wjs-burning-subtitles\ndescription: Use when the user has a video + an SRT and wants the subtitles either burned into the pixels (libass, always-visible) or soft-muxed as a togglable track. Also handles the final composite step for the localization pipeline \u2014 burn subs, mix a dub track, and keep the original audio as a low-volume bed, all in ONE ffmpeg encode (no cascade). Verifies libass availability and auto-downloads a static evermeet ffmpeg build when Homebrew's stripped binary lacks it. Triggers \u2014 \"\u70e7\u5b57\u5e55\", \"\u786c\u5b57\u5e55\", \"burn subtitles\", \"burn-in subs\", \"embed subtitle\", \"soft mux SRT\", \"\u628a\u5b57\u5e55\u70e7\u8fdb\u89c6\u9891\", \"\u505a\u6700\u7ec8\u5408\u6210\".\n---\n\n# wjs-burning-subtitles\n\nVideo + SRT \u2192 video with subtitles. Also the final-encode stage for the localization pipeline: takes a video, an optional dub track from `/wjs-dubbing-video`, and an optional SRT to burn, and produces the upload-ready MP4 in **one** ffmpeg pass. No cascade of decodes/re-encodes.\n\n## When to use\n\n- User has an SRT and wants it always-visible on the video (burn-in for \u5fae\u4fe1\u89c6\u9891\u53f7 / \u6296\u97f3 / WeChat \u2014 players that won't honor embedded subtitle tracks).\n- User wants a togglable subtitle track (soft-mux) for QuickTime / VLC / IINA / mobile players that support `mov_text`.\n- Final composite after `/wjs-dubbing-video`: burn target-language subs + mix dub over original-as-bed in one encode.\n\n## When NOT to use\n\n- No SRT yet \u2192 run `/wjs-transcribing-audio` then `/wjs-translating-subtitles` first.\n- HTML/CSS captions (kinetic, per-word highlights, custom fonts) on a clip composed in HyperFrames \u2192 use `/wjs-overlaying-video` instead. Don't mix libass burn-in with HyperFrames captions on the same output.\n- The \"subtitles\" are actually motion graphics (animated callouts, lower-thirds with logos, kinetic typography) \u2192 that's `/wjs-overlaying-video`, not this skill.\n\n## The 3 modes of `render.py`\n\n`scripts/render.py` auto-detects mode from flags:\n\n1. **Subtitles only** \u2014 `--video + --srt` \u2192 re-encodes video with burned subs, original audio passes through.\n2. **Dub only** \u2014 `--video + --dub` \u2192 keeps original video stream; replaces or mixes the audio track.\n3. **Full localized cut** \u2014 `--video + --srt + --dub` \u2192 burns subs AND mixes dub. By default keeps original audio at low volume as a \"bed\" under the dub (set `--bed-volume 0` or `--no-original-audio` to drop it).\n\nBurn-in requires an ffmpeg built with libass. The script auto-downloads a static libass-enabled build from evermeet.cx into `/tmp/ff_bin/` on first use if needed.\n\n## Soft-mux (togglable subtitle track)\n\nPlayer apps can show/hide. Works with any `ffmpeg` build \u2014 does **not** need libass:\n\n```bash\nffmpeg -i input.mp4 -i input.zh-CN.srt \\\n  -map 0:v -map 0:a -map 1:0 \\\n  -c:v copy -c:a copy -c:s mov_text \\\n  -metadata:s:s:0 language=zho -metadata:s:s:0 title=\"\u4e2d\u6587\" \\\n  output.mp4\n```\n\nThis is fast (stream-copy) and reversible. Use it when:\n\n- Target platform supports embedded subs (YouTube auto-detects; VLC/QuickTime honors).\n- User wants viewers to be able to toggle off.\n- You don't want to re-encode the video.\n\n`render.py --video IN.mp4 --srt SUB.srt --soft-mux` runs this path.\n\n## Hardcoded burn-in (always visible, libass)\n\nRequired for WeChat/\u6296\u97f3/\u670b\u53cb\u5708 etc. where the player will not honor embedded subtitle tracks.\n\n### Verify libass is available BEFORE promising burn-in\n\n```bash\nffmpeg -filters 2>&1 | grep -E \"subtitles|^.. ass \"\n```\n\nIf neither `subtitles` nor `ass` shows up, the build lacks libass. Homebrew's default `ffmpeg` formula is often stripped (no `--enable-libass`, no `--enable-libfreetype`, no `drawtext`). Don't waste time fighting the comma-escaping inside `force_style` \u2014 it will fail with `No such filter: 'subtitles'` no matter how the shell quotes it.\n\n### Fastest fix on macOS \u2014 drop in a static build, no system changes\n\n```bash\ncurl -fsSL -o /tmp/ff.zip https://evermeet.cx/ffmpeg/getrelease/zip\nunzip -o /tmp/ff.zip -d /tmp/ff_bin >/dev/null\nFF=/tmp/ff_bin/ffmpeg\n$FF -version | grep -oE -- \"--enable-(libass|libfreetype)\"\n```\n\nThen use `$FF` instead of `ffmpeg` for the render. The brew binary is fine for everything else (probe, audio extraction, soft-mux). `render.py` does this auto-fallback if its default ffmpeg lacks libass.\n\n### Burn-in render with style overrides\n\n\ud83d\uded1 **Checkpoint \u2014 confirm before full-render.** Burn-in re-encodes the entire video (minutes of CPU on a 5-min clip). Before kicking it off:\n\n1. Render only the first 30s with `-t 30` for a fast preview.\n2. Extract a frame from the longest-line cue (see Fontsize calibration below) and Read it.\n3. Show the user the preview frame + the cue text, ask: \"\u5b57\u53f7/\u5b57\u4f53/\u8fb9\u8ddd OK \u5417\uff1fOK \u624d\u8dd1\u5168\u7247\u3002\" Wait for explicit confirmation.\n\nSkip the checkpoint only if the user has already approved a full render of this exact video at this exact font config in the same conversation.\n\n```bash\n$FF -i input.mp4 \\\n  -vf \"subtitles=input.zh-CN.srt:force_style='Fontname=PingFang SC\\,Fontsize=12\\,PrimaryColour=&H00FFFFFF\\,OutlineColour=&H00000000\\,BorderStyle=1\\,Outline=2\\,Shadow=1\\,MarginL=20\\,MarginR=20\\,MarginV=40'\" \\\n  -c:v libx264 -crf 18 -preset medium -pix_fmt yuv420p \\\n  -c:a copy output.mp4\n```\n\nInside `force_style`, escape every comma as `\\,` (the filter graph parser eats the bare comma as a chain separator). All other special chars are fine.\n\n### Fontsize calibration \u2014 critical\n\nlibass scales its internal PlayRes up to the actual video resolution. The number you pass is **not pixels** in the output. As a starting calibration on a 544\u00d7960 vertical phone video, `Fontsize=22` rendered each Chinese character at ~55px wide and overflowed the frame, while `Fontsize=12` rendered at ~30\u201335px wide and fit cleanly with 15-char lines.\n\nRule of thumb: start at `Fontsize=12`, render, then **always** extract a frame and look:\n\n```bash\n$FF -ss 30 -i output.mp4 -frames:v 1 /tmp/frame.png -y\n# then Read /tmp/frame.png to verify the longest-line cue fits\n```\n\nPick a timestamp that lands on the cue with the most characters per line \u2014 short lines won't expose overflow. Add `MarginL=20 MarginR=20` as a safety inset; never trust default left/right margins.\n\n### Style cheatsheet\n\nKeys that matter (libass `force_style`):\n\n- `Fontname=PingFang SC` \u2014 macOS default CJK; alternates: `Songti SC`, `Heiti SC`, `STHeiti`, `Hiragino Sans GB`.\n- `Fontsize=12` \u2014 start small, scale up only after frame check.\n- `PrimaryColour=&H00FFFFFF` \u2014 white text (BBGGRR + alpha).\n- `OutlineColour=&H00000000` \u2014 black outline.\n- `BorderStyle=1` \u2014 outline only (clean over varied backgrounds). Use `BorderStyle=3` for an opaque box behind text when the background is busy.\n- `Outline=2` \u2014 2px outline thickness.\n- `Shadow=1` \u2014 subtle drop shadow.\n- `MarginL=20 MarginR=20` \u2014 keep text inside the frame.\n- `MarginV=40` \u2014 vertical distance from the bottom edge.\n\n### SRT line-length discipline for burn-in\n\nEven with correct `Fontsize`, lines that are too long will wrap or overflow. Keep each on-screen line \u2264 ~15 Chinese characters (~42 Latin chars). Use explicit `\\n` line breaks inside the SRT block \u2014 do not rely on auto-wrapping. Two short lines beat one long one every time. (This is upstream discipline \u2014 `/wjs-translating-subtitles` should already cap cues at these limits.)\n\n## Audio mixing \u2014 keep the original as a low-volume bed\n\nA pure dub-only track sounds dubbed (because it is). Mixing the original audio at low volume under the dub gives the \"professional translation\" feel \u2014 you still hear the speaker's breath, emphasis, and laughter, just under the new voice.\n\n```bash\n$FF -i original.mp4 -i dub.mp4 \\\n  -filter_complex \"[0:a]volume=0.18[orig];\\\n                   [1:a]volume=1.0[dub];\\\n                   [orig][dub]amix=inputs=2:duration=longest:normalize=0[a]\" \\\n  -map 0:v -map \"[a]\" \\\n  -c:v copy -c:a aac -b:a 192k mixed.mp4\n```\n\nReasonable starting volumes:\n\n- Original bed at `0.15`\u2013`0.25` (\u2248 \u221216 to \u221212 dB)\n- Dub at `1.0`\n- Use `normalize=0` so amix doesn't auto-attenuate when both are active.\n\nTo drop the original entirely: `--no-original-audio` (equivalent to `--bed-volume 0`).\n\n## Combining dub + burn-in + bed (the full job)\n\nOne ffmpeg call does all three \u2014 burn the target subtitle onto the video stream and mix the two audio tracks:\n\n```bash\n$FF -i original.mp4 -i dub.mp4 \\\n  -filter_complex \"[0:v]subtitles=input.zh-CN.srt:force_style='Fontname=PingFang SC\\,Fontsize=12\\,PrimaryColour=&H00FFFFFF\\,OutlineColour=&H00000000\\,BorderStyle=1\\,Outline=2\\,Shadow=1\\,MarginL=20\\,MarginR=20\\,MarginV=40'[v];\\\n                   [0:a]volume=0.18[orig];[1:a]volume=1.0[dub];\\\n                   [orig][dub]amix=inputs=2:duration=longest:normalize=0[a]\" \\\n  -map \"[v]\" -map \"[a]\" \\\n  -c:v libx264 -crf 18 -preset medium -pix_fmt yuv420p \\\n  -c:a aac -b:a 192k final.mp4\n```\n\nThis is the \"ship to social media\" final cut. `render.py --video original.mp4 --dub dub.mp4 --srt input.zh-CN.srt` runs this exact pipeline.\n\n## Running `render.py`\n\n```bash\n# Subtitles only (burn):\npython3 ~/.claude/skills/wjs-burning-subtitles/scripts/render.py \\\n    --video IN.mp4 --srt SUB.srt --out OUT.mp4\n\n# Dub only (replace audio, no subs):\npython3 ~/.claude/skills/wjs-burning-subtitles/scripts/render.py \\\n    --video IN.mp4 --dub IN_zh_dub.mp4 --out OUT.mp4\n\n# Full localized cut (burn + dub + original bed):\npython3 ~/.claude/skills/wjs-burning-subtitles/scripts/render.py \\\n    --video IN.mp4 --srt IN.zh-CN.srt --dub IN_zh_dub.mp4 --out OUT.mp4\n\n# Soft-mux (no re-encode):\npython3 ~/.claude/skills/wjs-burning-subtitles/scripts/render.py \\\n    --video IN.mp4 --srt SUB.srt --soft-mux --out OUT.mp4\n```\n\nSee `render.py --help` for the full style/audio flag list (`--font`, `--fontsize`, `--color`, `--outline-color`, `--margin-v`, `--bed-volume`, `--no-original-audio`).\n\n## Output\n\n- Burn mode: `<source>_burned.mp4` (re-encoded, libass-rendered subs)\n- Soft-mux mode: `<source>_softsub.mp4` (stream-copy, `mov_text` track)\n- Full cut: `<source>_final.mp4` (re-encoded video with burned subs + mixed audio)\n\n## Anti-patterns\n\n- \u274c **Promising burn-in without verifying libass.** Check `ffmpeg -filters | grep subtitles` first; auto-fall back to evermeet static build if missing.\n- \u274c **Committing a burn render without a frame check.** Always extract a frame at the longest-line cue and Read it before kicking off the full render.\n- \u274c **Bare commas inside `force_style`.** The filter graph parser eats them. Escape every internal comma as `\\,`.\n- \u274c **Mixing libass burn-in with HyperFrames captions.** Pick ONE caption system per output video. If you're using HTML/CSS captions in `/wjs-overlaying-video`, don't burn here too.\n- \u274c **Using period milliseconds in the SRT.** Whisper local writes `.mmm`; libass tolerates it but other downstream tools choke. Normalize to `,mmm`.\n- \u274c **Defaulting to `BorderStyle=3` (opaque box).** Use `BorderStyle=1` (outline only) unless the background is genuinely busy \u2014 the box looks heavy and dated.\n\n## Upstream\n\n- **`/wjs-transcribing-audio`** + **`/wjs-translating-subtitles`** \u2014 produce the SRT input.\n- **`/wjs-dubbing-video`** \u2014 produces the `*_<lang>_dub.mp4` input for full-localized-cut mode. The dub-only file is technically a finished video; this skill is what mixes the original underneath and burns the subs to make it shippable.\n\n## Common pitfalls\n\n- **Fontsize that worked on one video looks tiny / huge on another.** libass scales by PlayRes ratio, not pixels. Recalibrate per video resolution; don't trust a hardcoded value.\n- **Margin defaults clip text on vertical phone videos.** Always set `MarginL=20 MarginR=20` and `MarginV=40` (or higher) explicitly.\n- **`mov_text` track shows up in QuickTime but not in some Android players.** If the target audience is mobile-Chinese, soft-mux is unreliable; burn instead.\n- **Background-bus busy / contrast issues.** Increase `Outline=2` \u2192 `Outline=3`, or switch to `BorderStyle=3` for a translucent box (`BackColour=&H80000000` for 50% black).\n","usage":"\u8bfb\u53d6 SKILL.md\uff0c\u5e76\u6309\u9700\u8bfb\u53d6\u914d\u5957\u6587\u4ef6\uff1b\u4e0b\u8f7d ZIP \u83b7\u53d6\u5b8c\u6574\u5305\u3002\u6280\u80fd\u662f\u4efb\u52a1\u65b9\u6cd5\uff0c\u4e0d\u6388\u4e88\u65b0\u589e\u8d26\u6237\u3001\u4ed8\u8d39\u6216\u7cfb\u7edf\u6743\u9650\u3002"}