為了記錄你用來擷取影片畫格的操作步驟，請撰寫一份簡短程序，記錄你的來源檔案、你所選取的精確時間（以秒為單位）、產生 PNG 的動作，以及任何可能改變結果的限制條件。一份好的程序必須簡短到能在兩分鐘內讀完、具體到能在第二段影片上重複執行，並誠實說明哪些部分是由瀏覽器所控制。影片畫格擷取工作流程在設計上就很簡短：一個檔案、一個時間值、一個 PNG。大部分的記錄工作在於正確命名各項輸入與限制，而非描述一長串的點擊動作。
搜尋這項任務的讀者通常想要以下三種東西之一：一份可以貼到 wiki 或 runbook 的檢查清單、一份可供個人使用的可重複執行的腳本，或一份能向審查者證明擷取作業正確完成的證據。這三種需求都能由相同的結構來滿足：前置條件清單、編號動作清單、限制表格，以及驗證步驟。Video Frame Extractor 是本文的錨定工具，因為它涵蓋了最常見的文件記錄情境 —— 單張靜態影像、本機檔案、不上傳、PNG 輸出 —— 且整個流程能夠容納在單一頁面中。
「記錄步驟」對畫格擷取而言意味著什麼
記錄畫格擷取程序與記錄冗長的影片剪輯並不相同。在作者的概念中，沒有軌道、沒有圖層，也沒有關鍵影格需要管理。整個程序只有少數幾個會變動的部分，因此記錄上的問題與冗長剪輯正好相反：步驟少到讓人容易跳過撰寫，而這正是未來執行時開始出現偏差的時刻。
一份有記錄的程序應依序回答以下四個問題：
- 使用的是哪個檔案，以及它是否符合共用安全政策。
- 所要求的時間值為何，以及其計量單位為何。
- 哪個動作會將所要求的時間轉換為下載的 PNG。
- 適用的限制為何 —— 容器、編解碼器、尺寸、長度、檔案大小。
如果你的程序在書面中回答了這四個問題，同事就能在不親自盯著你操作的情況下重複執行。如果沒有回答，那麼在不同影片上執行相同的步驟將產生不同的結果，而你將無從得知原因。
決定程序必須記錄哪些內容
在你寫下任何一個編號步驟之前，請先決定程序負責保留哪些事實。最低限度必須包含來源檔名、要求的時間、輸出格式，以及檔案大小與尺寸限制。除此之外的內容都是選擇性的，取決於程序的讀者是誰。
對個人檢查清單而言，檔名與時間可能就已足夠。對團隊 runbook 而言，請再加上容器類型與編解碼器的註記。對審查軌跡而言，請擷取你執行程序的時間戳記，以及所輸出 PNG 的尺寸。程序的輪廓不會改變；改變的只有被記錄的事實。
除非你要記錄的正是工具本身的行為，否則請讓程序保持不含對工具的評論。例如，「瀏覽器解碼器會選擇最近的關鍵影格」這類句子屬於程序的一部分，因為它說明了為何兩次執行可能產生略有不同的 PNG。而「這是個很棒的工具」這類句子則不屬於。
在開啟工具之前先寫下前置條件
每個畫格擷取程序都應以一個前置條件區塊作為開頭。前置條件是你在第一次點擊之前所進行的檢查。若沒有這些檢查，程序稍後的編號步驟將在不符合規則的檔案上靜默失敗或產生錯誤的 PNG。
一個實用的前置條件區塊涵蓋：
- 容器類型為 MP4、WebM、MOV、M4V 或 Ogg 其中之一。
- 檔案大小最多 500 MiB，且長度最多五分鐘。
- 畫格尺寸每邊不超過 4096 像素，且總面積不超過 3840 × 2160 像素。
- 瀏覽器能夠解碼容器內部的編解碼器；副檔名受支援並不保證一定可以。
撰寫這四個項目只需一分鐘，卻能消除最常見的文件記錄缺口：在作者機器上可行、但在其他人的機器上失敗的程序。
逐步擷取影片畫格
擷取本身是一個三步驟的程序。請將每個步驟撰寫為具有單一預期結果的單一動作。請避免要求讀者「開啟檔案並檢查長度」這類複合式步驟 —— 請將其拆開，讓程序保持可測試性。
- 選擇一個受支援的本機影片，並等待其長度與預覽載入完成。在繼續之前，請確認所顯示的長度不為零。
- 輸入介於零與所顯示長度之間的畫格時間，必要時可包含小數。此值為媒體時間軸上的位置，而非畫格編號。
- 選擇「Extract PNG frame」（擷取 PNG 畫格），確認所出現的靜態影像，並下載本機 PNG。下載的檔名會包含所要求的時間，以便結果可供追溯。
每個步驟都有一個可觀察的結果：檔案載入並顯示預覽、時間欄位接受該值、PNG 完成下載。若任何結果未出現，程序應記錄此次失敗，而非靜默重試。Video Frame Extractor 會回報解碼、seek、canvas 與編碼失敗，而非產生空白的下載檔案，因此程序可以將缺少檔案視為一種訊號，而非例外狀況。
程序中值得記錄的限制
共用安全政策是程序可處理與無法處理內容的唯一真相來源。請將其記錄一次，再以名稱加以引用。下表記錄了會改變工具能否完成任務的數值。
| 限制 | 數值 | 其在程序中為何重要 |
|---|---|---|
| 最大檔案大小 | 500 MiB | 較大的檔案會在解碼前被拒絕，程序隨即停止。 |
| 最大長度 | 5 分鐘 | 較長的影片會被拒絕；時間欄位將沒有可輸入的上限值。 |
| 最大邊長 | 4096 像素 | 寬度或高度超過此值的畫格無法繪製到 canvas 上。 |
| 最大面積 | 3840 × 2160 像素 | 面積上限可捕捉通過邊長檢查但非正方形的超大畫格。 |
| 時間欄位範圍 | 0 至所顯示長度，可使用小數秒 | 超出範圍的時間會在嘗試 seek 之前被拒絕。 |
| 輸出格式 | 以解碼尺寸輸出 PNG | PNG 不會被縮放、裁剪、銳化或濾鏡處理。 |
| 透明度 | 僅在解碼後的畫格提供 alpha 通道時保留 | 大多數解碼後的影片畫格為不透明；請記錄此點以免讀者預期會有 alpha。 |
這些數值不容協商，因此程序無須與其進行協商。程序只需提及這些限制的存在及其來源。若未來的讀者需要瀏覽器媒體元素中 seek 一詞的精確定義，MDN HTMLMediaElement currentTime 參考資料 會說明該值在媒體時間軸上如何被解讀。
透過執行兩次來驗證程序
一份有記錄的程序只有在第二次執行時能重現相同結果才具有實用價值。請加入一個驗證步驟，要求第二位人員 —— 或未來的你 —— 在同一個檔案上重複執行程序，並比較所下載的 PNG。
比較項目：
- PNG 檔名應包含相同的所要求時間。
- PNG 尺寸應與來源的解碼後畫格尺寸相符。
若位元組有所不同，程序應記錄瀏覽器解碼器可能因關鍵影格、可變畫格率、edit list、時間戳記捨入或編解碼器行為而落在鄰近的解碼後畫格。所顯示的時間為所要求的位置，而非來源畫格精確度的保證，因此出現小幅視覺差異屬於預期情況，應在文件中註明，而非視為錯誤。對於需要更嚴格檢查的團隊，驗證影片畫格擷取結果的指南 將逐步說明應檢查所儲存 PNG 中的哪些內容。
何時應升級至瀏覽器工具以外的方案
並非所有的擷取作業都適合在瀏覽器中進行。程序的結尾應加入一條明確的升級規則，避免讀者將工具範圍之外所造成的限制誤怪於已記錄的步驟。當下列任一情況為真時，請升級至專用的桌面工具：
- 任務需要精準到畫格編號的擷取，而非媒體時間軸上的位置。
- 輸出必須進行色彩管理、HDR、alpha 工作流程，或以特定的 gamma 與色彩空間交付。
- 工作流程需要在數十個或數百個時間戳記上進行批次擷取。
- 來源影片長度超過五分鐘或大小超過 500 MiB。
- 容器內部的編解碼器不受瀏覽器解碼器支援。
記錄升級規則能讓主要程序保持誠實。若沒有這條規則，遇到上述任一限制的讀者將會認定程序有誤，而非工具選擇不當。有了這條規則，程序便能正確描述其所能完成的工作，並將其餘事項指向下一個合適的工具。
將程序化為書面文字
文件的最終形式應保持簡短：一個前置條件區塊、一份三步驟的動作清單、一張限制表格、一個驗證步驟，以及一條升級規則。總長度通常在 300 字以內。這正是重點所在。畫格擷取是一項小任務，因此其文件記錄也應保持精簡。不同團隊之間改變的是被記錄的事實，而非程序的結構。一旦結構固定下來，同一套範本就能同時適用於個人檢查清單、團隊 runbook，以及面向審查者的稽核軌跡。
如需更深入的瞭解，請參閱 如何於特定時間擷取影片畫格。