Chronometrica 与 Clockworks 对比：TikTok 字幕文本与带时间信息的分段

选择下游程序需要的输出

先看读取结果的程序。根据它要求的输入来选择。

Chronometrica 文档列出了行内的 `text` 和 `segments` 字段。每个分段包含 `startSeconds`、`endSeconds` 和 `text`。这适合需要读取 JSON 中命名字段值的程序。JSON 是一种包含字段和列表的结构化数据格式。Chronometrica 输出约定。

Clockworks 文档说明，`videoMeta.subtitleLinks` 提供原生字幕链接。原生 VTT 文件保留时间信息。可选的 `transcriptionLink` 提供通过语音转文字生成的内容；生成的 TXT 转写文本是连续文本，不含时间分段。VTT 是一种字幕文件格式。Clockworks 输出约定。

当采集的数据进入你的系统时，这一区别就很重要。结果即使包含有用信息，也可能需要经过加载步骤，程序才能使用。

选择前，先写下这个步骤。如果目标表需要分段开始时间列、分段结束时间列和字幕文本列，就要检查这些值如何进入目标表。仅凭产品名称无法回答这个问题。

定义什么文本可用

原生字幕是指源视频提供的字幕轨。本文讨论的 Chronometrica 输出约定采用的就是这类来源。成功返回字幕，并不能单独证明每个说出的词都已正确呈现。请在数据集中明确标注来源类型。

提交 URL 前，先定义验收规则。这些规则告诉程序哪些结果可以使用。

例如，下游程序可能要求同时满足以下条件：

• 成功获取原生字幕。
• 语言符合研究要求。
• 字幕文本存储在文本字段中。
• 分段边界以秒为单位。
• 能够关联回提交的输入和视频。

这些是建议的数据要求，并非对已完成提取结果的描述。请根据实际用途调整。

确定是否只需完整文本。搜索索引可能需要整条字幕轨。按时间审查则需要独立分段。如果两者都需要，就保留这两种形式，避免日后再从合并文本中重建分段边界。

还要确定如何在下一步处理未成功的结果。它可能需要人工审核，也可能保留在审计表中。但不能把它当作包含有效字幕轨的结果送入文本分析。

这个决定能保留数据集的含义。字幕字段为空，与字幕本身没有任何词，并不是可以直接视为相同的事实。必须先检查返回结果。

保留每项已提交输入的记录

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 项公开输入做小规模检查

选择一个与你计划构建的数据集相关的公开视频。请求所需的原生字幕语言。扩展列表前，先检查返回结果。

以下输入使用已核查的公开输入结构。URL 仅用于展示输入格式，并不能证明该视频目前有可用字幕轨。

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

将该 URL 替换为与你需求相关的公开视频来源。`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 开头吸引点编码指南。分析前，先确认要使用的来源、语言、处理结果和时间信息。