TikTokの字幕テキストと時間付きセグメント：ChronometricaとClockworksの比較

次のプログラムが必要とする出力を選ぶ

まず、結果を読み込むプログラムを確認します。そのプログラムが必要とする入力を基準に選びましょう。

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を、用途に合う公開動画のURLに置き換えてください。`preferredLanguages`リストは、既存字幕の言語を指定します。ここでは、`en`で英語字幕を指定しています。別の言語を英語に翻訳する要求ではありません。Chronometricaの入力スキーマ。

Chronometricaは、翻訳や新たな音声認識によって、欠落した字幕トラックを補いません。英語を指定すれば必ず英語のテキストが得られると考えずに、返された状態を確認してください。Chronometricaの仕様。

タイムスタンプ付きセグメント用の公開Taskもあります。Taskは、保存済みの入力設定です。出発点として内容を確認し、自分の要件に入力が合うか確認できます。この設定が存在するだけでは、選んだ動画で現在字幕を取得できるとは確認できません。タイムスタンプ付き文字起こしセグメントのTask。

少数の入力で確認するときは、具体的な問いに答えるようにします。この比較では、成功した行から、必要なセグメントのフィールドを利用側のプログラムが直接読み取れるか、という問いが役立ちます。結果ページを開くことは、確認の最初の段階にすぎません。自分の読み込み処理でも、そのデータを受け入れられる必要があります。

結果を読み込む際に意味を保つ

行内データを使う場合は、テキストだけのコピーを作る前に、結果行全体を保持してください。次に、`status`を読み取ります。受け入れ条件を満たす結果だけを、次の分析処理に渡してください。

利用側のプログラムが字幕の全文を必要とする場合は、`text`を読み込みます。時間区間に結び付いたテキストが必要な場合は、`segments`を読み込みます。元のセグメントの開始時刻と終了時刻、および返された言語を、その時間区間と一緒に保持してください。これらのフィールドは、Chronometricaの出力仕様に含まれています。Chronometricaの仕様。

各セグメントをデータベースの別々の行に保存する場合は、親となる結果への参照を残してください。そうしないと、セグメントのテキストから、入力の参照情報、言語、取得結果の背景情報が失われる可能性があります。これは後続処理での保存方法の選択です。Actorは、有用な元レコードを提供するために、最終的なデータベース構造で結果を返す必要はありません。

既存字幕のVTTを使う場合は、ファイルをダウンロードし、時刻情報付きのブロックを解析します。テキスト、開始時刻、終了時刻を保持してください。

どちらの読み込み設計でも、長さを計算したり、調査対象の時点が時間区間に含まれるか確認したりする前に、時刻の単位を確認してください。フィールド名、保存された値、利用側のプログラムが想定する単位が一致している必要があります。

単一のテキストフィールドの方が保存しやすいという理由だけで、セグメントを結合しないでください。結合は検索には役立つ場合がありますが、そのコピーからはセグメントの区切りが失われます。後で区切りが必要になる場合は、時刻情報を含む元データも一緒に保持してください。

音声認識で新たに生成したテキストを使う場合は、別のラベルを付けてください。復元した既存字幕とは呼ばないでください。

架空の例で読み込み方法を判断する

これは架空の例です。実際の抽出、ベンチマーク、顧客の結果ではありません。

3本の動画を指定したとします。2本には利用できる既存字幕トラックがあります。1本は公開字幕がないという結果です。行内データを使う処理では、そのまま使えるテキストとセグメントのレコードが2件と、成功しなかったことを明示する行が1件得られます。

ファイルを使う処理では、2つのVTTファイルを読み込み、時刻情報を解析できます。

この例では、字幕を利用できる条件を同じにしています。同じ既存字幕トラックがあると仮定し、それを後続のデータセットに取り込む方法を示しています。どちらかの製品がより多くの字幕を見つけることや、より早く処理を終えることを示すものではありません。

次に、架空のセグメント1件に、次の値が含まれるとします。

{
  "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のフック分類ガイドを参照してください。まず、分析で使う取得元、言語、取得結果、時刻情報を確認します。