dung-video

基本影片編輯（使用 ffmpeg）

您協助一位初學者 YouTube 創作者在他們的電腦上使用 ffmpeg（免費）編輯影片。許多使用者是越南人：如果使用者用越南文書寫，請用口語化的越南文回應，並保持技術詞彙簡單明瞭（說明指令的作用，而非運作原理）。

需求與限制

請在安裝任何東西之前，以及在使用者提出的請求缺少某些東西時，告知使用者這些事項。

• 需要： 付費的 Claude 方案與 Claude Code；ffmpeg（免費，僅在使用者同意後安裝）。僅字幕功能需要：Python 3.10+ 和 faster-whisper 套件（約幾百 MB，只需下載一次）。
• GPU： 不需要。當沒有 NVIDIA 顯卡時，Whisper 會在 CPU 上執行，因此長影片的字幕處理會很慢。
• 已測試作業系統： Windows 10（在 Claude 桌面應用程式中進行設定檢查，以及每個裁切、合併、垂直、音量調整、匯出指令）。macOS：尚未測試。
• 限制： 機器產生的字幕在人名、數字和地區口音上可能會有錯誤，因此使用者必須校對 .srt 檔案。僅限基本編輯：無特效、動畫文字或音樂。
• 缺少時的影響： 缺少 Python/faster-whisper 時，除了字幕功能外，其他功能仍可正常運作。

規則（始終遵守）

1. 絕不更改或刪除使用者的原始檔案。 從 raw/（或使用者檔案所在位置）讀取；將所有結果寫入 exports/ 並使用新名稱（例如 exports/clip-cat.mp4）。絕不覆寫現有檔案：為 ffmpeg 加上 -n 參數，或選用新名稱。
2. 安裝任何東西前先詢問。 說明它是什麼、為什麼需要、以及確切的指令，然後等待使用者同意。
3. 在執行指令前先顯示指令，並用一句話說明它會做什麼。對於任何需要超過一分鐘的動作（長影片、字幕），請先告知。
4. 在編輯檔案前先用 ffprobe 檢查檔案（大小、影格率、長度、音訊），以便指令符合檔案特性。
5. 引用檔案路徑（它們通常包含空格和越南文字母）。在 Windows 上，ffmpeg 濾鏡路徑中偏好使用正斜線。
6. 每次編輯後，告知使用者新檔案的位置以及要檢查的項目（播放影片，聽聽看開頭和結尾）。
7. 不要聲稱你無法指出的 YouTube 規則。如果此技能引用了 YouTube，則會附上來源連結。

1. 檢查電腦

逐一執行：

• ffmpeg -version 和 ffprobe -version
• python --version（在 macOS 上也嘗試 python3 --version）— 僅字幕功能需要。

如果缺少 ffmpeg，提議安裝它（先詢問）：

• Windows： winget install --id Gyan.FFmpeg -e
• macOS（Homebrew）： brew install ffmpeg（如果 brew 本身缺失，請引導使用者前往 https://brew.sh 並停止）。

如果缺少 Python 且使用者需要字幕功能：

• Windows： winget install --id Python.Python.3.12 -e
• macOS： brew install python

安裝後，使用者可能需要開啟新的終端機（或重新啟動 Claude Code），指令才能被找到。再次用 ffmpeg -version 確認。

2. 設定專案資料夾

在 Claude Code 開啟的資料夾內，建立：

raw/        原始檔案（將影片複製到此處；絕不編輯）
exports/    所有完成或中間檔案
CLAUDE.md   頻道相關備註，Claude Code 在每次對話開始時讀取

如果 CLAUDE.md 不存在，提議建立它並詢問使用者 4 個簡短問題：頻道主題、影片語言、Short / 長影片 / 兩者皆有、常用攝影設備（手機或相機）。寫一個簡短的檔案，例如：

# 我的頻道
- 主題：...
- 影片語言：越南文
- 製作：長影片和 Shorts
- 使用：手機拍攝
- 原始檔放在 raw/，輸出檔放在 exports/

3. 基本編輯

始終先檢查輸入檔案：ffprobe -v error -show_entries stream=codec_type,codec_name,width,height,r_frame_rate:format=duration -of default=nw=1 "raw/input.mp4"

裁切（cắt một đoạn）

重新編碼，使裁切點精確落在要求的時間上：

ffmpeg -n -ss 00:00:12 -to 00:01:30 -i "raw/input.mp4" -c:v libx264 -crf 18 -preset medium -pix_fmt yuv420p -c:a aac -b:a 192k "exports/input-cat.mp4"

時間可以使用 mm:ss 或 hh:mm:ss 格式。多個片段 = 多次裁切，然後合併。

合併（ghép nhiều clip）

1. 用 ffprobe 檢查每個片段。如果所有片段的寬度、高度和影格率都相同，則寫入 exports/list.txt：

   file '../raw/clip1.mp4'
   file '../raw/clip2.mp4'
   

   然後：ffmpeg -n -f concat -safe 0 -i "exports/list.txt" -c:v libx264 -crf 18 -preset medium -pix_fmt yuv420p -c:a aac -b:a 192k "exports/ghep.mp4"
2. 如果它們不同，則在一個步驟中將每個片段縮放和填充到相同的大小和影格率（例如，將 2 個片段調整為 1920x1080，30 fps）：

   ffmpeg -n -i "raw/a.mp4" -i "raw/b.mp4" -filter_complex "[0:v]scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=30[v0];[1:v]scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=30[v1];[0:a]aresample=48000[a0];[1:a]aresample=48000[a1];[v0][a0][v1][a1]concat=n=2:v=1:a=1[v][a]" -map "[v]" -map "[a]" -c:v libx264 -crf 18 -preset medium -pix_fmt yuv420p -c:a aac -b:a 192k "exports/ghep.mp4"
   

   如果某個片段沒有音軌，請告知使用者並為其添加靜音（anullsrc），而不是讓指令失敗。

Shorts 垂直版本（khung dọc）

YouTube 將長寬比為正方形或垂直且長度不超過 3 分鐘的影片視為 Short，上傳解析度最高可達 1080p（YouTube 說明 15424877，10059070）。1080x1920（9:16）是常見的垂直尺寸；YouTube 並未公布確切的像素大小。

• 裁切中央（當人物在中間時適用）： ffmpeg -n -i "raw/input.mp4" -vf "crop=ih*9/16:ih,scale=1080:1920,setsar=1" -c:v libx264 -crf 18 -preset medium -pix_fmt yuv420p -c:a aac -b:a 192k "exports/input-doc.mp4"
• 在模糊背景上保留完整畫面（適用於螢幕錄影或廣角鏡頭）： ffmpeg -n -i "raw/input.mp4" -filter_complex "[0:v]scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,boxblur=20:2[bg];[0:v]scale=1080:-2[fg];[bg][fg]overlay=(W-w)/2:(H-h)/2,setsar=1[v]" -map "[v]" -map 0:a? -c:v libx264 -crf 18 -preset medium -pix_fmt yuv420p -c:a aac -b:a 192k "exports/input-doc.mp4" 詢問使用者想要哪一種；如果主體不在中央，提議移動裁切位置（crop=ih*9/16:ih:X:0，X = 左邊緣的像素值）。

越南文字幕（phụ đề）

使用使用者電腦本機的 Whisper（免費，不會上傳任何內容）。需要 Python 和 faster-whisper 套件（連同模型約幾百 MB；先詢問）： python -m pip install faster-whisper 然後執行此技能附帶的腳本（路徑：此 SKILL.md 旁邊的 scripts 資料夾）： python "<技能資料夾>/scripts/phu_de.py" "raw/input.mp4" --lang vi --out "exports/input.srt" 它會產生一個 .srt 檔案。告知使用者 Whisper 會出錯（人名、數字、口音）：他們應該在使用前打開 .srt 並修正它。第一次執行會下載模型，因此速度較慢。 要在影片中嵌入字幕（燒錄），待使用者修正 .srt 後： ffmpeg -n -i "raw/input.mp4" -vf "subtitles=exports/input.srt:force_style='FontSize=18,Outline=2'" -c:v libx264 -crf 18 -preset medium -pix_fmt yuv420p -c:a copy "exports/input-phude.mp4" （在 Windows 上，保持 .srt 路徑為相對路徑並使用正斜線；磁碟機代號如 C: 必須在濾鏡內寫成 C\:。）許多創作者是將 .srt 上傳到 YouTube Studio 而非燒錄進去，這樣觀看者可以關閉字幕。

調整音量（chuẩn âm lượng）

YouTube 並未公布音量目標；在觀看者端，它有一個「穩定音量」設定，可平衡大聲和小聲的部分（YouTube 說明 14106294）。網路影片的常見選擇是大約 -14 LUFS；請說明這是一個常見選擇，而非 YouTube 的規定。使用 ffmpeg 的 loudnorm 進行兩次處理（ffmpeg 文件）：

1. 測量：ffmpeg -hide_banner -i "exports/video.mp4" -af loudnorm=I=-14:TP=-1.5:LRA=11:print_format=json -f null - 從結尾的 JSON 讀取 input_i、input_tp、input_lra、input_thresh。
2. 使用這些數值套用： ffmpeg -n -i "exports/video.mp4" -af loudnorm=I=-14:TP=-1.5:LRA=11:measured_I=<input_i>:measured_TP=<input_tp>:measured_LRA=<input_lra>:measured_thresh=<input_thresh>:linear=true,aresample=48000 -c:v copy -c:a aac -b:a 192k "exports/video-am-luong.mp4" 不要在已完成的影片上使用單次處理：它會在影片播放期間不斷調整音量。

為 YouTube 匯出（xuất file）

遵循 YouTube 建議的上傳編碼設定（YouTube 說明 1722171）：MP4 格式，啟用 fast start，H.264 High profile，逐行掃描，4:2:0 色彩取樣，封閉式 GOP（長度為影格率的一半），2 個 B 幀；AAC-LC 音訊，48 kHz；BT.709 色彩；與錄製時相同的影格率。SDR 的建議影片位元率：1080p 8 Mbps（24-30 fps）或 12 Mbps（48-60 fps）；720p 5 / 7.5 Mbps；1440p 16 / 24；4K 35-45 / 53-68。音訊：立體聲 384 kbps（單聲道 128 kbps）。 例如，一個 1080p、30 fps 的影片（GOP 15）：

ffmpeg -n -i "exports/video.mp4" -c:v libx264 -profile:v high -pix_fmt yuv420p -b:v 8M -bf 2 -g 15 -flags +cgop -x264-params "colorprim=bt709:transfer=bt709:colormatrix=bt709" -color_range tv -c:a aac -b:a 384k -ar 48000 -movflags +faststart "exports/video-youtube.mp4"

根據影片調整 -b:v 和 -g（影格率的一半）；對於 60 fps 使用 -b:v 12M -g 30。保持與錄製時相同的影格率（不要添加 -r）。

縮圖幀（lấy khung hình）

ffmpeg -n -ss 00:00:42 -i "raw/input.mp4" -frames:v 1 -vf "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2" -q:v 2 "exports/khung-0042.jpg" 提供 3-4 個不同時間點的影格供使用者選擇。YouTube 的縮圖規則（尺寸、16:9、JPG/PNG、檔案大小）請參閱 YouTube 說明 72431。

如果發生問題

此技能是使用 Claude Code 編寫的，因此可能包含錯誤，而且每台電腦都不同。當某個步驟失敗，或使用者表示技能執行有誤時：

1. 用越南文清楚說明： 用一兩句話說明哪裡失敗了以及原因。除非使用者要求，否則不要顯示原始堆疊追蹤。
2. 閱讀此技能和已執行的指令。 找出原因（下面的清單涵蓋了常見原因）。
3. 修正並重新執行，在 exports/ 中寫入一個新檔案。即使在修正過程中，也絕不觸碰或覆寫使用者的原始檔案。
4. 如果原因是此技能本身的錯誤（指令錯誤或步驟遺漏），請說明，並建議回報問題以便讓所有人都能獲得修正：https://github.com/thegentleminh/thegentleminh-skills/issues

常見失敗

• 'ffmpeg' is not recognized / command not found：ffmpeg 未安裝或終端機是在安裝前開啟的；請開啟新的終端機並重新檢查。
• No such file or directory：檢查路徑和引號；列出資料夾以找到確切名稱。
• already exists. Exiting.：輸出名稱已被使用；請選擇一個新名稱（絕不覆寫）。
• Unknown encoder 'libx264'：ffmpeg 建置版本缺少此編碼器；請從上述指令重新安裝。
• 裁切後音訊不同步：重新執行裁切並加上重新編碼（上述指令已包含重新編碼）。