Find a Phrase in a TikTok Transcript (Python)

Overview

To find a phrase in a TikTok transcript, fetch the segments, join them into one string, search it and map each hit back to its segment.

Searches one joined string, so split phrases match.
Prints the start second of the matching segment.
Exit code 1 when nothing matches.

Searching segment by segment misses a phrase that is split across two lines. The script joins the text, remembers where each segment starts, and reports the segment where each match begins.

Aisha tracks whether creators mention a sponsor. She needs the second a mention starts so she can check the video herself.

The script

find_phrase.py

"""Find a phrase in a TikTok transcript, even when it spans two segments.
Usage: python find_phrase.py TIKTOK_URL "phrase" """
import os, re, sys
import requests

API = os.environ.get("TTA_API_BASE", "https://api.example.com")
url, phrase = sys.argv[1], sys.argv[2].lower()
r = requests.get(f"{API}/api/v1/tiktok/transcript", params={"url": url},
                 headers={"Authorization": f"Bearer {os.environ['TTA_API_KEY']}"}, timeout=60)
d = r.json()
if not d["success"]:
    sys.exit(f"error {d['error']['code']}: {d['error']['message']}")
text, spans = "", []                      # one long string, remembering where each segment starts
for s in d["segments"]:
    spans.append((len(text), s)); text += s["text"].lower() + " "
hits = [m.start() for m in re.finditer(re.escape(phrase), text)]
for pos in hits:
    seg = [s for start, s in spans if start <= pos][-1]
    print(f"{seg['start']:6.1f}s  {seg['text']}")
print(f"{len(hits)} match(es) for {phrase!r} in video {d['video_id']}")
sys.exit(0 if hits else 1)

Captured runs

A phrase inside one segment (mock)

5.4s  Tip two: raised beds drain better.
1 match(es) for 'raised beds' in video 7000000000000000001

A phrase that spans two segments (mock)

2.6s  Tip one: measure the sun before you buy seeds.
1 match(es) for 'buy seeds. tip two' in video 7000000000000000001

No match, exit code 1 (mock)

0 match(es) for 'pineapple' in video 7000000000000000001

What can go wrong

Speech-to-text and automatic captions mishear names. Search for a few spellings.
Case is ignored; punctuation is not. A phrase with a comma must match it.
One request, one credit per video, so searching a list costs a request per video.

Get an API key to run it against the real service. Run against the local mock in tools/mock-api, which follows the assumed contract on these pages. It is not the real API, and the output is captured from that mock.

Frequently asked questions

Does it do fuzzy matching?

No, only exact text, ignoring case. Add fuzzy matching on top if you need it.

Can it search many videos?

Fetch them with the batch workflow, then run the same search on each saved result.