# Chronometrica 與 Topaz Sharingan：如何處理缺漏的 YouTube 逐字稿記錄 如果應用程式需要詳細的失敗記錄，請選擇 Chronometrica；如果逐字稿或 null 的結果已能滿足需求，請選擇 Topaz Sharingan。經查核的 Chronometrica 規格包含輸入識別資訊、按類型區分的失敗詳情，以及 `isRetryable` 旗標。Topaz Sharingan 的文件說明，無法取得逐字稿時會回傳 null。這是回報結果的 2 種不同方式。[Chronometrica 規格](https://apify.com/chronometrica/youtube-transcript-scraper)、[Topaz Sharingan 規格](https://apify.com/topaz_sharingan/youtube-transcript-scraper)。 關鍵問題是：查詢逐字稿失敗後，應用程式必須做什麼？它需要說明失敗原因、保留記錄，並決定是否重試嗎？還是只要顯示未回傳逐字稿即可？ 對於前一種需求，我們推薦 Chronometrica。它另行提供的失敗詳情，可為應用程式的這些決定提供資訊。不過，更完整的失敗記錄無法讓原本無法取得的逐字稿出現。所提供的證據沒有在相同條件下進行的對照測試，因此無法證明兩者在穩定性、封鎖情況、速度、恢復能力或成功率上有差異。 本指南由 Chronometrica 發布。比較依據為 2026 年 10 月 20 日查核的公開規格。本文比較文件記載的行為，並非實際測量的正式環境效能。 ## 依應用程式需要說明的結果來選擇 Actor 是託管執行的資料收集程式。應用程式向它提供輸入、執行它，再讀取結果。結果規格定義了應用程式可以預期收到的內容。 對逐字稿擷取來說，成功結果只是規格的一部分。應用程式也需要規則，處理未產生逐字稿的輸入。這項規則會影響向使用者顯示的訊息，以及應用程式接下來的動作。 一則[開發者的公開提問](https://www.reddit.com/r/sideprojects/comments/1v4zk6t/is_there_a_stable_way_to_pull_youtube_transcripts/)描述了本機執行成功，到了正式環境卻失敗、請求遭到封鎖、結果為空，以及重試行為不明確等問題。該問題涉及另一個 Python 逐字稿函式庫。它說明了為什麼結果必須容易理解，但沒有提供本次比較中任一 Actor 的測試證據。 先從需要向使用者呈現的結果著手： | 應用程式需要…… | 可考慮的規格 | 原因 | | --- | --- | --- | | 說明不同輸入的失敗情況 | Chronometrica | 另行提供的失敗詳情，包含按類型區分的結果欄位。 | | 建立有重試次數上限的佇列 | Chronometrica | 回傳的 `isRetryable` 旗標可作為這項決定的依據。 | | 儲存逐字稿，或表示無法取得的值 | Topaz Sharingan | 其文件記載的逐字稿或 null 結果，可能已足夠。 | 資料來源：[Chronometrica 結果規格](https://apify.com/chronometrica/youtube-transcript-scraper)、[Topaz Sharingan 結果規格](https://apify.com/topaz_sharingan/youtube-transcript-scraper)。 如果較簡單的規格能滿足完整需求，就選擇它。如果應用程式必須區分結果並採取相應動作，就選擇較詳細的規格。這樣能依應用程式的行為來選擇，而不是依據缺乏證據的說法，認定哪個服務較少失敗。 ## 一併讀取 Chronometrica 的成功記錄與失敗詳情 Chronometrica 的預設資料集，每列對應 1 部成功取得逐字稿且不重複的 YouTube 影片。資料集就是這些結果記錄的集合。失敗的輸入不會成為資料集中的成功記錄，也不會成為計費的逐字稿記錄。獨立的 `OUTPUT` 摘要會回報執行資訊，並可能包含 `failedInputDetails`。[Chronometrica 規格](https://apify.com/chronometrica/youtube-transcript-scraper)。 當資料集的記錄數較少時，這種區分很重要。資料集的記錄數少於輸入清單的項目數，不能證明所有輸入都成功。它只表示資料集中有哪些成功的逐字稿記錄。對於未產生記錄的輸入，你也必須檢查它們所回報的結果。 請將 `includeFailedInputDetails` 保持設為 `true`。文件記載的失敗詳情包含可安全使用的輸入識別資訊、`errorCategory`、`errorCode` 和 `isRetryable`。類別用來區分失敗類型。代碼提供更明確、可由程式讀取的值。重試旗標指出回報的失敗是否可以重試。[Chronometrica 輸入結構定義](https://apify.com/chronometrica/youtube-transcript-scraper/input-schema)、[結果規格](https://apify.com/chronometrica/youtube-transcript-scraper)。 應用程式可利用這些詳情，自行整理所有已提交輸入的狀態。請將每筆成功逐字稿或失敗輸入詳情，與對應的輸入識別資訊配對。不要按記錄在清單中的位置來配對。只要缺少 1 筆成功記錄，依位置連結輸入與結果就不再可靠。 請區分來源結果與應用程式顯示的訊息。結果記錄查詢所回報的內容。顯示訊息則向使用者解釋該結果。這樣你就能修改措辭，而不必變更已儲存的觀察記錄。 ## 另行判斷所需語言是否可用 執行任一工作流程之前，先決定應用程式是否要求特定字幕語言。可用的逐字稿除了必須包含文字，也必須符合這項要求。 Chronometrica 的 `preferredLanguages` 設定一旦填入，就會嚴格依照該設定處理。如果無法取得指定語言，Actor 會回傳 `LANGUAGE_UNAVAILABLE`，而不會在未告知的情況下選擇另一種語言。這項設定不會翻譯字幕。Chronometrica 讀取公開的原生字幕，沒有語音轉文字的備援機制。[Chronometrica 規格](https://apify.com/chronometrica/youtube-transcript-scraper)、[輸入結構定義](https://apify.com/chronometrica/youtube-transcript-scraper/input-schema)。 如果應用程式必須向使用者提供指定語言的字幕，這種行為就適合。它也明確指出一項限制：即使影片有其他語言的字幕，仍可能不符合應用程式的要求。 不要只因為存在某種字幕文字，就將該結果標記為成功取得逐字稿。請在輸入記錄中保留指定語言。這樣應用程式就能說明，它未找到符合請求的字幕。 如果使用者可以接受其他語言，請先在應用程式中定義這項選擇，再擴充工作流程。語言要求改變，就代表請求改變。請將它與原始請求的重試區分開來。如需進一步了解字幕可用性，請參閱 [YouTube 字幕擷取指南](/zh-Hant/articles/%E5%8F%96%E5%BE%97-youtube-%E9%80%90%E5%AD%97%E7%A8%BF-%E6%AA%A2%E6%9F%A5%E7%BC%BA%E5%B0%91%E5%AD%97%E5%B9%95/)。 ## 用一組虛構的記錄缺漏情況逐步說明 以下範例為虛構內容。它不是實際執行、效能測試或客戶的結果。 某應用程式提交 8 個不重複的影片 ID，並指定字幕語言。5 部影片有可用字幕。1 部沒有公開字幕。1 部缺少指定語言的字幕。另 1 部發生存取失敗，回傳旗標將其標記為可重試。 對這組虛構輸入而言，可用字幕的比例為： `5 / 8 × 100 = 62.5%` 這項計算只描述這組虛構資料。它不是對任一 Actor 實際成功率的估計。 依 Chronometrica 文件記載的結果結構，應用程式會讀到 5 筆成功逐字稿記錄，以及 3 筆失敗輸入詳情。它不會在成功逐字稿資料集中加入 3 筆虛構的失敗記錄。接著，應用程式可呈現 5 筆逐字稿記錄和 3 個尚未解決的結果。[Chronometrica 結果規格](https://apify.com/chronometrica/youtube-transcript-scraper)。 這些尚未解決的結果需要不同訊息。應用程式可說明，有 1 次查詢未找到公開字幕。也可說明，另 1 次查詢未找到指定語言。對於存取失敗，應用程式可表示將在次數上限內重試，因為回傳旗標允許做出這項決定。 只有旗標標記的案例會進入重試佇列。應用程式不會對每個缺少成功資料集記錄的輸入都重試。可重試旗標提供再次嘗試的依據，但不保證這次嘗試會成功。 如果應用程式稍後重試該輸入，就會記錄新的結果。它會保留首次觀察記錄，讓記錄仍能呈現每次嘗試發生的情況。 這個範例可用來實際檢視選擇規則。如果應用程式需要這些不同訊息和重試佇列，請選擇詳細規格。如果完整需求只是可為 null 的逐字稿值，較簡單的規格可能就能滿足需求。 ## 用少量輸入檢查結果規格 少量檢查可讓你在增加輸入之前，確認應用程式能讀取文件記載的記錄。它不能證明正式環境的可靠性。 以下 JSON 使用文件記載的公開輸入欄位。網址用來說明輸入格式，不保證目前存在字幕內容，也不保證特定結果。請將它換成相關的公開來源。 ```json { "startUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "includeFailedInputDetails": true } ``` 用少量輸入檢查結果規格 這些欄位記載於 [Chronometrica 輸入結構定義](https://apify.com/chronometrica/youtube-transcript-scraper/input-schema)。一個[公開的 Task 範例](https://apify.com/chronometrica/youtube-transcript-scraper/examples/youtube-transcript-api-dataset)也提供了相關的起點。Task 是已儲存的輸入預設組合。結構定義中的範例和 Task 連結，都不是本指南已完成執行的證據。 請用以下簡短步驟檢查工作流程： 1. 定義輸入與驗收規則。建立沒有重複項目的影片清單。記錄所有必要的語言要求。決定什麼樣的字幕文字算是可用，以及未回傳可用逐字稿時，應用程式要顯示什麼。 2. 保持啟用失敗詳情。將 `includeFailedInputDetails` 設為 `true`，並提交少量公開來源的輸入。確認應用程式能讀取成功資料集，以及獨立的 `OUTPUT` 結果。 3. 將結果與輸入配對。使用文件記載的輸入識別資訊，將結果連結至請求。比對成功記錄與失敗輸入詳情。不要將記錄數較少的資料集，視為已提交清單的完整結果。 4. 檢查失敗後的處理決定。讀取回傳的失敗欄位。區分可用性結果與明確標記為可重試的案例。不要只因缺少逐字稿，就推斷可以重試。 5. 採用有次數上限的重試規則。在應用程式中設定嘗試次數上限。只重試符合條件的案例。保留每次嘗試的觀察記錄，並在達到上限時停止。 6. 如實顯示最終狀態。如果重試結束後仍未取得逐字稿，請將輸入保留為未解決狀態。不要將缺漏文字轉成空白的成功記錄，也不要暗示再次嘗試就能取得逐字稿。 如果應用程式已讀取的內容中，某個輸入既沒有配對的成功記錄，也沒有配對的失敗詳情，請保留這項不確定性。檢查執行資訊，以及讀取結果的程式碼。不要為了讓數量一致而捏造結果。 當應用程式能釐清收到的記錄，並依預定規則決定向使用者呈現的結果，這項檢查就算成功。不必為每部提交的影片都產生逐字稿，才能證明讀取結果的方法有效。 ## 增加輸入前，先設定重試上限 重試佇列是應用程式計劃再次提交的輸入清單。這裡的用途很明確：在保留清楚記錄的同時，讓符合條件的失敗輸入獲得有限次數的重試機會。 擴大清單之前，先決定嘗試次數上限。沒有上限時，可重試的失敗可能持續循環，即使後續每次嘗試都不成功。明確的停止規則，也讓應用程式能告知使用者，自動嘗試已經結束。 請在應用程式的記錄中，保留已提交的輸入、語言要求、觀察到的結果，以及嘗試順序。這些是應用程式自行選擇儲存的記錄內容，並非聲稱 Actor 會額外輸出的欄位。這些記錄讓你能區分原始請求、後續嘗試，以及已變更的請求。 保留缺失值。未知值必須維持未知。不要以 0 取代缺失值，也不要用空白逐字稿作為成功的證據。應用程式應能區分已收到的文字、已回報的失敗，以及尚未確認的結果。 請將因字幕無法取得而產生的失敗，視為對當時請求的觀察結果。要保留準確記錄，不一定需要自動重試這些輸入。如果使用者之後變更指定語言，或要求重新檢查，請將它儲存為新的請求或觀察記錄。 這些規則讓應用程式的行為可以被清楚說明。它們不以「重試就能取得字幕」的說法為前提。 ## 依應用程式的需求選擇 Actor 如果缺少逐字稿時必須提供可解釋的結果，Chronometrica 就很適合。其經查核的失敗欄位，可支援輸入配對、不同的使用者訊息，以及有次數上限的重試決定。對於必須交代查詢失敗情況的應用程式，這就是推薦它的具體原因。[Chronometrica 規格](https://apify.com/chronometrica/youtube-transcript-scraper)。 主要限制是字幕是否可用。詳細失敗記錄可解釋查詢為何未提供可用文字，但不會建立字幕、翻譯字幕，也不會提供語音轉文字的備援機制。 如果 Topaz Sharingan 文件記載的逐字稿或 null 結果能滿足應用程式需求，請選擇它。其輸入結構定義包含 `startUrls` 和 `timestamps`。null 結果是其所述規格的一部分，並非缺陷的證據。[Topaz Sharingan 規格](https://apify.com/topaz_sharingan/youtube-transcript-scraper)、[輸入結構定義](https://apify.com/topaz_sharingan/youtube-transcript-scraper/input-schema)。 如果兩者的相對穩定性是決定因素，本次比較無法替你確定選擇。經查核的證據中，沒有在相同條件下進行的效能對照測試。請將這項不確定性納入決策，不要將更詳細的錯誤記錄視為成功率更高的證明。 ## 用 1 部相關的公開影片試用這項規格 開啟 [Chronometrica YouTube Transcript Scraper](https://apify.com/chronometrica/youtube-transcript-scraper)，並使用 1 個相關的公開來源，測試所述的輸入格式。保持啟用 `includeFailedInputDetails`。如果應用程式有語言要求，請先檢查文件記載的語言設定，再提交輸入。 接著，檢查成功資料集、`OUTPUT` 摘要，以及任何 `failedInputDetails`。確認應用程式能將結果與輸入配對，並說明結果。這項小規模檢查成功後，再增加輸入。將回傳的重試旗標與應用程式的嘗試次數上限搭配使用；如果未取得逐字稿，請如實保留未解決狀態。 ## 來源與延伸閱讀 - [Chronometrica YouTube Transcript Scraper 規格](https://apify.com/chronometrica/youtube-transcript-scraper) - [Chronometrica 輸入結構定義](https://apify.com/chronometrica/youtube-transcript-scraper/input-schema) - [Chronometrica 公開 Task 範例](https://apify.com/chronometrica/youtube-transcript-scraper/examples/youtube-transcript-api-dataset) - [Topaz Sharingan YouTube Transcript Scraper 規格](https://apify.com/topaz_sharingan/youtube-transcript-scraper) - [Topaz Sharingan 輸入結構定義](https://apify.com/topaz_sharingan/youtube-transcript-scraper/input-schema) - [關於逐字稿可靠性的開發者公開提問](https://www.reddit.com/r/sideprojects/comments/1v4zk6t/is_there_a_stable_way_to_pull_youtube_transcripts/)