Préparer les données de transcription TikTok pour une analyse de contenu

Ce que le collecteur actuel renvoie

Ces faits publics ont été vérifiés le 2026-10-13. La version actuelle est 0.1.36. Chaque exécution accepte de 1 à 100 cibles publiques connues dans `startUrls`. Une cible peut être une URL de vidéo, un lien court ou un identifiant numérique de vidéo. L'Actor ne cherche pas un profil, un mot-clé ni une page de son. Vous devez déjà connaître les vidéos.

`preferredLanguages` est une liste ordonnée de langues de sous-titres publics. L'Actor choisit la première piste publique qui correspond. Une liste vide utilise la première piste publique. Il ne traduit pas le texte. Il ne crée pas de texte à partir d'un son sans sous-titres. Il ne collecte pas les commentaires. Il n'attribue pas de codes de contenu.

L'entrée de la Task enregistrée est :

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

Remplacez cet exemple par vos propres vidéos publiques connues. Pour un essai sur une seule vidéo, placez une URL dans `startUrls`. Si l'anglais est la langue de votre étude, réglez `preferredLanguages` sur `["en"]`. Si votre étude utilise une autre langue, écrivez cette règle de langue et utilisez son code. Ne copiez pas `["en"]` dans une étude d'une autre langue. Une liste vide peut renvoyer une autre piste publique.

Une ligne du jeu de données représente chaque entrée soumise. Une entrée en échec reçoit quand même une ligne. Conservez cette ligne. Elle est la preuve de la tentative. Ces champs sont exacts : `inputIndex`, `inputUrl`, `videoId`, `videoUrl`, `authorHandle`, `durationSeconds`, `languageCode`, `text`, `segments`, `status`, `statusReason`, `isBillable` et `scrapedAt`. Chaque segment a `startSeconds`, `endSeconds` et `text`. Les temps TikTok utilisent ces deux clés. Utilisez `startSeconds` et `endSeconds` tels qu'ils sont renvoyés. Conservez chaque `videoId` comme texte, et non comme nombre. Un identifiant long peut changer si un programme le stocke comme un nombre.

`status` peut être `succeeded`, `no_public_captions`, `language_unavailable`, `duplicate_input`, `not_tiktok`, `invalid_input`, `unsupported_url`, `video_unavailable`, `not_public` ou `blocked_or_challenged`. Des échecs d'extraction et des échecs de sous-titres peuvent aussi se produire. Le succès exige un texte qui n'est pas vide. Une transcription nulle ou vide avec un statut d'échec ne prouve pas que la vidéo ne contient aucune parole. La vidéo peut encore contenir de la parole. Vous savez seulement qu'aucun sous-titre utilisable n'est revenu.

`isBillable` vaut true seulement pour un résultat de transcription native réussi. Le nom du champ utilise un b minuscule. Les autres lignes restent dans les données comme preuve. `isBillable` ne décrit pas toute l'exécution. Une exécution peut mêler des lignes true et des lignes false. Ne dites pas que toute l'exécution est gratuite.

Le décompte de l'exécution utilise ces noms exacts : `inputsReceived`, `resultRows`, `billableTranscriptRows`, `nonBillableResultRows`, `duplicateVideosSkipped` et `statusCounts`. Ce décompte contrôle l'exécution. Il ne montre pas que vos vidéos représentent tous les créateurs.

Un contrôle sur une vidéo, le 2026-10-13, a utilisé l'exemple enregistré. La ligne a réussi. L'identifiant de la vidéo était l'identifiant demandé, `7047596209028074758`. Le code de langue était `eng-US`. Un code tel que `eng-US` est une étiquette régionale de sous-titres. Il signifie l'anglais avec une étiquette de région des États-Unis. Ce n'est pas une traduction. Le texte n'était pas vide. La ligne avait 12 segments. Le minutage des segments avait la forme `startSeconds` et `endSeconds`. Aucun mot de sous-titres de cette vidéo n'est répété ici. Ce contrôle a montré que les sous-titres publics de cette seule source pouvaient être récupérés. Il ne prouve pas que la transcription est parfaitement exacte. Il ne prouve pas que chaque vidéo réussit. Il ne prouve pas que votre code de contenu est valide. Votre propre essai reste nécessaire.

Huit actions

1. Définir la question, le code et l'échantillon

Écrivez une question de recherche. Écrivez un code de contenu que vous pouvez compter. Un code de contenu est la caractéristique que vous marquez comme présente ou absente. Choisissez des URL de vidéos connues selon une règle que vous pouvez énoncer. Énoncez la période, la langue et le périmètre des créateurs avant de collecter.

Un registre d'échantillonnage est la liste de chaque vidéo que vous avez sélectionnée. Remplissez ce registre avant de regarder les sous-titres. Ne sélectionnez pas des vidéos seulement parce qu'un sous-titre existe. Si vous ne gardez que les vidéos avec sous-titres, vous avez changé l'échantillon. Les vidéos sans sous-titres disparaîtraient au lieu d'apparaître comme manquantes.

1. Déclarer l'unité de comptage

Choisissez l'unité que vous compterez. L'unité peut être une vidéo, un segment de sous-titres ou un passage que vous définissez. Dans ces étapes, l'unité comptée est la vidéo. Un segment est un morceau minuté du texte des sous-titres. Les segments sont des preuves pour la vidéo. Ce ne sont pas des vidéos supplémentaires.

Trois segments avec le même code comptent encore comme une seule vidéo. Écrivez cette règle avant l'exécution. Conservez l'URL d'entrée, le `videoId` renvoyé et votre propre `selected_video_key`. La clé d'étude est la vôtre. Elle reste la même même si la forme de l'URL change.

1. Tester une vidéo sélectionnée

Lancez le collecteur sur une vidéo sélectionnée avant toute collecte par lot. C'est un essai pilote. Un essai pilote est un petit test de tout le chemin. Inspectez `status`, `videoId`, `languageCode` et `text`. Le texte doit être non vide pour un succès. Si la langue de votre étude est l'anglais, réglez `preferredLanguages` sur `["en"]` pour cet essai.

Puis comparez un court passage avec l'audio. Regardez aussi l'image à l'écran. Notez les mots manqués, les mots en trop et les mots erronés. Une ligne réussie ne prouve pas que les mots sont exacts. Le contrôle à 12 segments ci-dessus montre seulement que le chemin public peut renvoyer des sous-titres. Ce n'est pas votre validation.

1. Exécuter la liste bornée et la rapprocher

Envoyez seulement vos URL connues, jusqu'à 100 dans une exécution. Une liste sélectionnée plus longue exige une autre exécution. Faites correspondre chaque entrée soumise à une ligne de résultat. Utilisez `inputIndex`, `inputUrl` et `videoId`. Faites correspondre ces lignes au décompte de l'exécution.

Contrôlez `inputsReceived`, `resultRows`, `billableTranscriptRows`, `nonBillableResultRows`, `duplicateVideosSkipped` et `statusCounts`. Gardez les doublons dans les notes, et comptez cette vidéo une seule fois. Gardez les sous-titres manquants dans le registre, mais hors de l'ensemble de succès. Faites de même pour les échecs d'accès à la source. Ces statuts comprennent `video_unavailable`, `not_public`, `blocked_or_challenged`, `unsupported_url`, `not_tiktok` et `invalid_input`.

Ne codez jamais un texte vide en échec comme « code absent ». Un texte vide signifie que vous n'avez pas observé le code. Il ne signifie pas que le code est absent.

1. Faire un tableau des vidéos et un tableau des segments

Faites une ligne par vidéo sélectionnée. Utilisez ces colonnes : `selected_video_key`, `videoId`, `videoUrl`, `languageCode`, `caption_status`, `caption_validated`, `study_eligible` et `exclusion_reason`. `study_eligible` enregistre si la vidéo peut entrer dans le dénombrement. Ce n'est pas le code de contenu. `caption_validated` enregistre si vous avez vérifié les sous-titres par rapport à la vidéo.

Utilisez `unknown` quand vous n'avez pas pu vérifier les sous-titres. N'écrivez pas `caption_validated` comme no quand l'état vrai est unknown. Une ligne en échec n'a pas été validée. Une revue inachevée n'a pas été validée non plus.

Conservez les segments dans un second tableau. Utilisez la clé de vidéo, `startSeconds`, `endSeconds`, `text` et une observation de source. Un tableau de segments dans une seule cellule de tableur est un mauvais export. CSV est un tableau de texte plat. Une liste imbriquée ne tient pas dans cette forme plate de façon sûre. Exportez d'abord en JSON. JSON est un format texte qui peut garder une liste à l'intérieur d'un élément. Puis aplatissez volontairement. Aplatir signifie que vous faites une ligne simple par segment. Répétez la clé de vidéo sur chaque ligne de segment. Ne découpez pas le texte sur les virgules. Les phrases contiennent des virgules. Laissez le texte brut des sous-titres inchangé. Placez chaque code dans de nouvelles colonnes.

1. Écrire une petite règle de codage et l'essayer sur de la fiction

Les exemples à partir de cette étape sont de la fiction. Ils ne sont pas une sortie de l'Actor. Ne collez pas ces identifiants dans une entrée réelle. Leurs URL de vidéo sont inconnues.

Écrivez une règle courte et donnez-lui une version. Pour une règle simple de mot exact, définissez le mot, la casse des lettres et la frontière de mot. Une frontière de mot empêche un mot court de correspondre à l'intérieur d'un mot plus long. Revoyez vous-même les emplois ambigus. Une règle de mot-clé trouve seulement ce motif. Elle ne prouve pas ce que le locuteur voulait dire. Un message transmis uniquement par les images peut contredire les paroles. Le sarcasme peut aussi contredire les mots. Ces cas demandent qu'une personne les code.

Le code fictif ici est une instruction explicite de mesurer l'eau. La version de règle v1 marque le code 1 quand le texte de sous-titres validé donne cette instruction. Le mot entier « measure » compte, quelle que soit la casse. Le mot « measurement » est un mot différent. Revoyez-le. Ne le marquez pas par la seule règle de mot-clé. Le code 0 n'est permis que sur des sous-titres validés qui n'ont pas l'instruction. Sinon, le code reste unknown.

1. Contrôler un ensemble pilote, puis l'importer dans R

Codez un petit ensemble pilote avant une grande étude. Deux personnes peuvent le coder séparément l'une de l'autre. Ou vous pouvez le coder de nouveau plus tard et comparer. Stockez `code`, `code_version`, `coder`, `decision_note` et un horodatage. L'horodatage enregistre le moment de la décision. Gardez le texte brut dans sa propre colonne.

R peut lire un CSV plat. Dites à R que les colonnes d'identifiants sont du texte. Ne laissez pas R deviner un identifiant numérique. L'extrait ci-dessous utilise seulement R de base. Il utilise les lignes fictives. Il n'ajoute pas de paquet. Ce n'est pas une norme de recherche testée. Ici, `denom` est le dénominateur. Le dénominateur est le nombre de vidéos éligibles par lequel vous divisez. `NA` signifie non disponible. Cet exemple utilise `NA` pour un code inconnu.

videos <- data.frame(
  videoId = c("video-v1", "video-v2", "video-v3", "video-v4", "video-v5"),
  study_eligible = c("yes", "yes", "no", "no", "no"),
  code = c(1, 0, NA, NA, NA),
  stringsAsFactors = FALSE
)
stopifnot(is.character(videos[["videoId"]]))
eligible <- videos[["study_eligible"]] == "yes"
stopifnot(!any(is.na(videos[["code"]][eligible])))
code_count <- sum(videos[["code"]][eligible])
denom <- sum(eligible)
share <- code_count / denom

`code_count` vaut 1. `denom` vaut 2. `share` vaut 0.5. Les valeurs `NA` sont des codes inconnus. Ce ne sont pas des zéros. La ligne `stopifnot` arrête le script si une vidéo éligible a un code inconnu.

Quand vous exportez un vrai CSV, gardez le même contrôle de texte :

videos_from_csv <- read.csv(
  "video_table.csv",
  stringsAsFactors = FALSE,
  colClasses = c(videoId = "character")
)
stopifnot(is.character(videos_from_csv[["videoId"]]))

Vous pouvez aussi tester la règle de mot fictive dans R de base :

raw_text <- "I measure the water before I pour it"
hit <- grepl("\\bmeasure\\b", raw_text, ignore.case = TRUE)
ambiguous <- grepl("\\bmeasure\\b", "measurement", ignore.case = TRUE)

`hit` vaut TRUE. `ambiguous` vaut FALSE. Le second résultat explique pourquoi un mot plus long exige une règle de revue humaine, et non une correspondance silencieuse.

1. Rapporter le dénombrement avec le registre complet des issues

Pour calculer la proportion de vidéos éligibles présentant le code, utilisez uniquement les vidéos éligibles au dénominateur. Éligible signifie `succeeded`, un texte non vide et `caption_validated` à yes. Rapportez chaque issue de vidéo sélectionnée à côté de cette proportion. Les lecteurs doivent voir les échecs et les lignes inachevées. Limitez le constat aux vidéos que vous avez sélectionnées et observées. Ne le présentez pas comme un résultat pour tous les créateurs. Ne le présentez pas comme un résultat pour toute parole politique.

Les sous-titres manquants peuvent changer une conclusion. Cet article s'arrête au registre. Il n'enseigne pas jusqu'où ces lignes manquantes peuvent déplacer un résultat.

Dénombrement fictif de cinq vidéos

La même fiction continue ici. V1 à V5 sont des étiquettes d'étude inventées. Les valeurs de `videoId` sont des étiquettes de texte inventées. Ce ne sont pas des identifiants TikTok réels. `videoUrl` est inconnu pour chaque ligne. N'envoyez pas ces étiquettes à l'Actor. Un vrai `languageCode` peut être une valeur régionale telle que `eng-US`. Cette fiction utilise `en` parce que la langue d'étude déclarée est l'anglais. Dans les tableaux, unknown est la valeur d'étude. Dans l'exemple R, `NA` stocke ce même inconnu. Ne stockez pas unknown comme 0.

Le code déclaré reste l'instruction explicite de mesurer l'eau.

V1 est en anglais. La collecte a réussi. Les sous-titres ont été validés. Le texte est « I measure the water before I pour it ». Ce texte est une instruction explicite de mesurer l'eau. Le code est 1.

V2 est en anglais. La collecte a réussi. Les sous-titres ont été validés. Le texte est « I pour water into the tray ». Il dit à quelqu'un de verser. Il ne dit pas à quelqu'un de mesurer. Le code est 0.

V3 a le statut `no_public_captions`. Le texte est vide. `languageCode` est unknown. N'en inventez pas un. `caption_validated` est unknown, pas no. Le code est unknown. Un texte vide n'est pas le code 0. Ce n'est pas non plus une preuve de silence.

V4 a le statut `language_unavailable`. Le texte est vide. `languageCode` est unknown. `caption_validated` est unknown. Le code est unknown. Cet échec n'est pas le même échec que V3. Gardez les deux raisons séparées.

V5 est en anglais. La collecte a réussi. Une personne a comparé les sous-titres avec l'audio. Les sous-titres ont omis la phrase prononcée concernant la mesure. La validation n'est pas terminée. `caption_validated` est unknown, pas no. `study_eligible` est no. Le code reste unknown. Le succès n'est pas la même chose qu'un sous-titre de confiance. Ne transformez pas cette ligne en code 0.

Une vidéo entre dans le dénominateur de la proportion de vidéos éligibles présentant le code seulement quand `study_eligible` est yes. Cette décision est séparée de la valeur du code. V1 et V2 sont éligibles parce que les sous-titres ont réussi, le texte est non vide et une personne les a validés. V3 et V4 ne sont pas éligibles parce que la collecte a échoué. V5 n'est pas éligible parce que la validation n'est pas terminée. `isBillable` serait true pour V1, V2 et V5, parce que ces résultats de transcription ont réussi. `isBillable` serait false pour V3 et V4. V5 est facturable et pourtant non éligible. L'indicateur facturable ne décide pas le dénombrement de l'étude.

Tableau des vidéos :

Tableau des codes :

Tableau des segments :

V3 et V4 n'ont pas de lignes de segment. Le texte de leur résultat est vide. N'ajoutez pas un segment à 0 seconde. Zéro ressemblerait à un temps réel. Un temps manquant reste unknown.

Le premier segment de V1 se termine à 2,5 secondes et commence à 0,5 seconde. 2,5 moins 0,5 font 2,0 secondes. Cette durée utilise `endSeconds` et `startSeconds`. Le second segment de V1 appuie aussi le code de mesure. Il ne crée pas une seconde vidéo. V1 reste une seule vidéo codée. L'unité comptée est la vidéo.

Vidéos validées éligibles : 2. Vidéos avec le code 1 : 1. 1 / 2 = 0,5, soit 50 pour cent. Le registre sélectionné a encore 5 vidéos. 1 / 5 = 0,2, soit 20 pour cent. Ne rapportez pas 20 pour cent. V3, V4 et V5 n'ont pas été vérifiées comme code 0. Unknown n'est pas zéro.

Dénombrements des issues pour les cinq vidéos sélectionnées : 2 validées et éligibles, 2 en échec, et 1 validation inachevée. Les deux échecs ont des statuts différents. L'un est `no_public_captions`. L'autre est `language_unavailable`.

Supposez que vous avez soumis ces cinq entrées une fois. Supposez qu'il n'y avait pas de doublons. Le décompte attendu ci-dessous est une arithmétique tirée de cette fiction. Ce n'est pas un reçu réel. `inputsReceived` vaudrait 5. `resultRows` vaudrait 5. `billableTranscriptRows` vaudrait 3. `nonBillableResultRows` vaudrait 2. `duplicateVideosSkipped` vaudrait 0. `statusCounts` montrerait `succeeded` 3, `no_public_captions` 1 et `language_unavailable` 1. Votre exécution réelle doit être contrôlée avec le décompte que vous recevez vraiment.

Cet exemple montre que des segments supplémentaires n'ajoutent pas de vidéos. Il montre aussi le dénominateur éligible. Il ne montre pas un ensemble réel de vidéos. Il ne montre pas un taux d'exactitude des sous-titres. Il ne montre pas un effet au-delà de ces lignes inventées.

Une forme JSON plate pour le segment V1 connu est :

{
  "videoId": "video-v1",
  "segments": [
    {
      "startSeconds": 0.5,
      "endSeconds": 2.5,
      "text": "I measure the water before I pour it"
    }
  ]
}

Cet objet est une fiction pour l'étape d'aplatissement. Après l'aplatissement, le tableau des segments ci-dessus est la copie de codage. Le tableau des vidéos reste la copie de dénombrement.