Chronometrica 與 Clockworks：TikTok 逐字稿文字與時間片段比較

選擇下一個程式需要的輸出

先確認哪個程式會讀取結果。你應依照它的輸入需求來選擇。

Chronometrica 的文件列有資料列內的 `text` 與 `segments` 欄位。每個片段包含 `startSeconds`、`endSeconds` 與 `text`。這適合需要從 JSON 讀取具名值的程式。JSON 是一種包含欄位與清單的結構化資料格式。Chronometrica 規格說明。

Clockworks 的文件說明，原生字幕連結位於 `videoMeta.subtitleLinks`。原生 VTT 檔案保留時間資訊。可選的 `transcriptionLink` 提供語音轉文字產生的內容；產生的 TXT 逐字稿是連續文字，不含時間片段。VTT 是一種字幕檔案格式。Clockworks 規格說明。

收集到的資料進入系統時，這個差異就很重要。結果即使包含有用的資訊，仍可能需要經過載入步驟，程式才能使用。

選擇前，先寫下這個步驟。如果你需要的表格有片段開始時間、片段結束時間及字幕文字欄，請確認這些值如何進入表格。只看產品名稱，無法回答這個問題。

定義什麼文字可以使用

原生字幕是來源影片可提供的字幕軌，也是本文討論的 Chronometrica 規格所採用的來源類型。字幕擷取成功，本身不代表每個說出的字都正確出現在字幕中。請在資料集中清楚標示來源類型。

提交網址前，先定義驗收規則。這些規則會告訴程式哪些結果可以使用。

例如，使用資料的程式可能需要符合以下所有條件：

• 成功取得原生字幕。
• 語言符合研究要求。
• 字幕文字存放在文字欄位中。
• 片段的開始與結束時間以秒表示。
• 可連回提交的輸入與影片。

這些是建議的資料需求，並不是對已完成擷取結果的陳述。請依實際用途調整。

請決定是否只需要完整文字。搜尋索引可能需要整條字幕軌的文字。依時間進行的檢視則需要分開的片段。如果兩者都需要，請保留這兩種形式，不要等到之後才嘗試從合併的文字重建片段的起訖時間。

也請決定如何處理未成功的結果。它可能需要人工檢查，也可能保留在稽核表中。你不應將它當成包含有效字幕軌的結果，送入文字分析。

這項決定有助於保留資料集的正確含義。字幕欄位空白，與字幕本身沒有任何文字，是不同的情況。未檢查結果狀態前，不能將兩者視為相同。

保留每筆已提交輸入的紀錄

Chronometrica 會為每筆已提交的輸入回傳 1 筆結果資料列，也會明確回報未成功的結果。文件列出的欄位包括 `inputIndex`、`inputUrl`、`videoId`、`videoUrl`、`languageCode`、`text`、`segments`、`status`、`statusReason`、`isBillable` 與 `scrapedAt`。Chronometrica 規格說明。

如果系統必須交代整份提交清單的處理結果，這種資料列結構就很有用。即使沒有字幕文字，你仍可保留輸入參照與結果。你不必因為找不到成功紀錄，就自行推斷結果。

公開的結果狀態包括 `succeeded`、`no_public_captions`、`language_unavailable`、`duplicate_input` 與 `invalid_input`。載入文字前，先讀取狀態。如果需要進一步了解回傳結果，請使用 `statusReason`。Chronometrica 規格說明。

請分開保留這些結果。要求的語言無法取得，與輸入沒有公開字幕，是不同的結果。重複輸入，也不同於成功取得新的字幕軌。

不要將所有未成功的結果都轉成空白文字值，並丟棄原因。這會刪除日後說明資料集時需要的資訊。

一種實用的設計，是為同一批收集資料提供 2 個檢視。第 1 個保留所有回傳結果。第 2 個只包含符合文字分析規則的資料列。這是建議的下游設計，不是 Actor 的額外功能。

未知值應維持未知。不要用 0 取代缺少的時間。0 是影片開始時的實際時間值。用它標記缺失值，可能會產生錯誤的片段起訖時間。

先用 1 筆公開輸入檢查

選擇與預定資料集相關的公開影片。要求你需要的原生字幕語言。擴大清單前，先檢查回傳結果。

以下輸入使用已查核的公開結構定義。網址僅用於說明輸入格式，不能證明這部影片目前有可用的字幕軌。

{
  "startUrls": [
    "https://www.tiktok.com/@hankgreen1/video/7047596209028074758"
  ],
  "preferredLanguages": [
    "en"
  ]
}

請將該網址換成與你需求相關的公開來源。`preferredLanguages` 清單用於要求原生字幕語言。在此範例中，`en` 表示要求英文字幕，不是要求將其他語言翻譯成英文。Chronometrica 輸入結構定義。

Chronometrica 不會透過翻譯或新執行的語音辨識來補上缺少的字幕軌。請檢查回傳狀態，不要假設要求英文就一定會產生英文文字。Chronometrica 規格說明。

另有一個公開的時間戳記片段 Task。Task 是已儲存的輸入預設組合。你可以先查看它，再確認其輸入是否符合自己的需求。這個預設組合的存在，不能證明你選擇的影片目前有可用字幕。附時間戳記的逐字稿片段 Task。

小規模檢查應回答一個明確問題。對這項比較而言，一個實用的問題是：使用資料的程式能否直接從成功的資料列讀取所需的片段欄位？開啟結果頁面只是檢查的第一步。你自己的載入程式也必須能接收這些資料。

載入結果時保留資料含義

如果採用資料列內直接提供資料的方式，請先保留完整結果資料列，再製作純文字副本。接著讀取 `status`。只將通過驗收的結果送入下一個分析步驟。

當使用資料的程式需要完整字幕文字時，載入 `text`。當它需要與時間區間對應的文字時，載入 `segments`。請連同這些區間，保留原始片段的起訖時間與回傳的語言。這些欄位都列於 Chronometrica 的輸出文件中。Chronometrica 規格說明。

如果將每個片段存放在獨立的資料庫資料列中，請保留它與所屬結果的連結。否則，片段文字可能失去輸入參照、語言或結果背景。這是下游儲存方式的選擇。Actor 不必直接回傳你最終採用的資料庫結構，也能提供有用的來源紀錄。

如果使用原生 VTT，請下載檔案，並解析其中附有時間資訊的區塊。保留文字及開始與結束時間。

無論採用哪種載入設計，計算時長或比較研究時間點與區間前，都要先檢查時間單位。欄位名稱、儲存值及使用資料的程式所預期的單位必須一致。

不要只因單一文字欄位比較容易儲存，就將片段合併。合併可能有助於搜尋，但會移除該副本中的片段起訖資訊。如果之後會需要這些資訊，請同時保留附有時間資訊的來源。

如果使用語音轉文字產生的內容，請另外標示。不要將它稱為找回的原生字幕。

用虛構範例說明載入方式的選擇

這是虛構範例，不是實際擷取、效能評測或客戶使用結果。

假設你要求處理 3 部影片。其中 2 部有可用的原生字幕軌，1 部回傳沒有公開字幕的結果。採用資料列內直接提供資料的流程時，你會有 2 筆可直接使用的文字與片段紀錄，以及 1 筆明確標示未成功的資料列。

採用檔案流程時，可以載入 2 個 VTT 檔案，並解析其時間資訊。

這個範例將字幕可用性設定為相同。它說明同一組假設存在的原生字幕軌，如何進入下游資料集。它並未顯示哪個產品能找到更多字幕，或更快完成工作。

現在，假設一個虛構片段包含以下數值：

{
  "startSeconds": 2.50,
  "endSeconds": 4.25,
  "text": "An invented caption for this example."
}

其時長為 `4.25 - 2.50 = 1.75` 秒。位於 `3.00` 秒的研究時間點落在這個區間內，位於 `5.00` 秒的研究時間點則不在區間內。

這項計算只能支持有限的結論：研究時間點落在字幕片段的時間區間內。它無法指出每個字的確切時間，也無法解釋觀眾為何觀看、停止觀看，或與影片互動。

請在虛構資料集中保留未成功的資料列。不要為它編造開始時間為 0 的片段，也不要將缺少文字視為影片沒有語音的證據。

如果使用資料的程式需要直接從 JSON 資料列取得區間值，資料列內直接提供的結果就符合這項需求。這個範例能協助你選擇載入方式，而沒有編造效能結果。

擴大清單前，先進行簡短的驗收

將比較轉成小規模驗收。寫下必須通過的條件，再用 1 筆相關的公開輸入檢查實際結果。

1. 定義所需的來源與資料結構。說明使用資料的程式需要原生字幕證據、完整文字、附有時間資訊的資料列，還是檔案。列出必需的欄位名稱。
2. 設定要求的原生字幕語言。使用符合任務需求的語言。不要在這次請求中加入翻譯需求。
3. 讀取回傳結果。保留已提交輸入的參照。分開記錄成功、語言無法取得、沒有公開字幕，以及其他回傳狀態。
4. 載入所需的值。確認使用資料的程式能讀取通過驗收的文字與時間欄位，並保留它們之間的對應關係。
5. 檢查時間的含義。做減法或區間檢查前，先確認單位。保留缺失值與片段起訖資訊。
6. 記錄決定。擴大清單前，說明哪個必需欄位通過檢查、出現什麼結果，以及哪些事項仍未知。

如果需要在資料列內直接提供資料，驗收陳述應明確：「使用資料的程式能從通過驗收的結果中，讀取 `startSeconds`、`endSeconds` 及片段的 `text`。」這比「逐字稿看起來不錯」更有用。

請將語言列為獨立條件檢查。結果即使可以閱讀，仍可能不符合語言要求。同樣地，成功載入完整文字，也不能證明片段載入程式可以正常運作。

檢查載入的副本時，請保留原始結果供查閱。這樣便能將下游缺少的值追溯至來源資料列，也有助於區分問題來自擷取結果，還是你自己的載入程式碼。

如果無法取得所需的原生字幕軌，請記錄這項發現。不要只為了讓小規模檢查通過，就更改驗收規則。請先決定需求本身是否可以調整，再明確記錄這項變更。

這項比較能確立什麼

觀察到的公開提問，是在詢問取得 TikTok 內容的穩定 API。已儲存的歷史摘錄也提到文字與時間戳記需求。它有助於界定讀者的問題，但不能證明任何一個產品的可靠性。觀察到的公開提問。

本文使用的公開規格已於 2026 年 10 月 20 日查核。它們能支持輸出結構的比較，但無法判定哪個產品在執行時間、價格、可用性或可靠性上較好。實作載入程式時，請再次檢查當前規格。

減少載入工作可能很有用，但不代表資料收集更快。請根據使用資料的程式需要什麼，以及少量輸入實際回傳什麼，判斷是否適合。

取得合適且附有時間資訊的字幕資料後，內容分析就是另一項工作。如果需要以影片開場為重點的方法，請參閱 TikTok 開場吸引點編碼指南。請先確認分析將使用的來源、語言、結果狀態與時間資訊。