A prototype that collects public TikTok videos to study which posts work
Wavelength wanted to learn from more than a few successful posts. This prototype collected public TikTok videos and checked a sample of downloads. The next steps, describing each video and finding which features go with good results, had not run yet.
CreditDesigned and built by our founder, as lead developer for a partner agency.
What was measured
How a search became a checked sample of videos
Follow the recorded collection run. Every request is recorded, and every chosen file has to pass the checks.
across five topics
Keyword and hashtag searches.
Every paid request is recorded and capped.
TikTok videos
- Results returned
- 474
- Search credits
- 20
- Recorded duration
- 133 sec
Every answer is saved with the run,
so the counts can be checked again.
six per search
Files are chosen before downloading,
so download results cannot change the list.
60 files. Checks passed.
This was one sample of 60 files, run on a laptop. It checks this run's downloads, not future reliability or how well posts perform. Testing how long download links stay valid was not finished.
About Wavelength
A few successful posts are too small a sample to show a reliable pattern.
Wavelength knew what had worked on a small number of its own accounts. It wanted evidence from many more posts to guide its content team and, later, the Instagram carousels its content software makes.
- Client
- WavelengthA growth-marketing startup researching creative patterns
- Research source
- Public TikTok postsInstagram was planned, not built.
- Measured scope
- Discovery and a 60-file download sample
- Next phases
- Describing videos, matching them to their results and reportingNo performance findings existed yet.
The problem
Studying only viral posts cannot show what made them different
Too few posts to learn from
A team's own posts show only a small part of its market. A bigger comparison needs a clear set of posts and a repeatable way to collect them.
No ordinary posts to compare with
A feature might appear in viral videos and ordinary videos alike. Looking only at the viral ones cannot show the difference.
Findings need proof
A useful finding needs counts and a moment in the video that a person can check. Saying an opening line makes a video go viral would claim more than the evidence shows.
What was built
Collecting the videos was built and measured; studying them was not
Measured on a sample
The work that ran
Searches with a spending limit
The software searches TikTok by keyword and hashtag, and saves every paid request and its answer. A person sets the spending limit before it starts.
Checks every downloaded video
A fixed list picks six videos per starting search before anything is downloaded. Each file's size and contents are checked, and it is read back to confirm it saved correctly.
Designed, not yet run
The next research steps
Sets out how videos will be described
The planned description has 11 groups of features, from the opening line to the call to action. Each is marked supported, partly supported or unsupported. No video had been described yet.
Plans a fair comparison
The written method compares successful posts with similar ordinary posts. A separate set of posts, kept aside, would test whether the features really add useful information.
A look ahead · Planned output
Every description should point back to the video.
Descriptions were planned to link each observation to its moment in the video. The 11 feature groups had not been applied to any video.
00:02Opening line
The speaker opens with a question.
“Where does your research begin?”
—Call to action
If the video does not clearly show something, that field stays empty. Nothing is guessed to fill the gap.
The video is described first. Final view counts are kept out of this step.
Control and safety
Findings will only claim what the evidence supports
The planned report will say which features appear together with good results in a defined set of posts. It will not claim causes or make promises. Each finding would link to a moment in a video that a person can check.
- Public information only. The project uses only public posts and their public numbers. It does not guess private analytics, audience details or intent.
- Unknown does not mean zero. The design leaves missing numbers empty and records when each number was collected.
- People set the limits. Limits cover search credits, downloads, traffic through the backup download route (proxy), file size, uploads and analysis time. The scripts cannot raise their own budgets.
- Results are kept out of the descriptions. The planned description step leaves out final view counts, late readings and success labels.
For technical readers
How the system works
The search saves every answer and fixes a list of videos to download. The same job downloads and checks each file. Dashed steps show the planned next steps: describing the videos, comparing their results and writing a report.
Dashed lines show supporting connections, or parts that are paused or not yet built.
In more detail
Technology used (7 parts)Each part of the system, and why it was chosen.
| Layer | Technology | Why it was chosen |
|---|---|---|
| Contracts | TypeScript · Node 22 · Zod 4 | Checks data from outside services, and the planned video descriptions, as soon as it arrives. |
| Public data | ScrapeCreators API | Keyword and hashtag searches, public numbers and video links, with the credit cost of each recorded. |
| Downloads | undici 7 · metering dispatcher · Decodo proxy | Measures how much data comes back, and uses a backup route (proxy) only when a direct download fails. |
| Media checks | ffprobe · SHA-256 | Checks each file is a real video of the right length, then confirms it did not change after saving. |
| Video understanding | TwelveLabs · Jockey API · Analyze batch | Connection code written and tested with recorded data; not yet run on real videos. |
| Next phases | Supabase Postgres · Backblaze B2 · DuckDB · ffmpeg | Database chosen, storage planned, analysis proposed and turning carousels into videos planned. None of these connections was finished. |
| Checks | Vitest · strict TypeScript · GitHub Actions | Type checks and tests with recorded data run on every code change. |
5 engineering decisions that matteredThe problem, what was done, and what it changed.
Record every paid request before and after it runs
A request with no saved answer is counted as spent. Its cost is set aside and the run stops for a person to check, instead of retrying a request that may already have been paid for.
Download before the link expires
The first run's video links carried expiry timestamps of six or 24 hours. Downloads now happen in the same job as the search. Tests of how long links last were not finished.
Include ordinary posts
Hashtag searches returned old, popular posts. Searches sorted by date reached newer, ordinary posts. Those can form the comparison group, as long as they are not chosen using the features being studied.
Treat downloaded files as untrusted
Downloads only come from approved websites, follow checked redirects and stop at 250 MB. The file checker runs with tight limits: one process, local files only, no outside links and a hard time limit.
Keep the numbers checkable
Replaying saved answers corrected figures that had been worked out by hand, without new paid requests. Saved records, checksums and a replay command keep the basis for later checks.
Testing and build recordHow it was tested, and the build by the numbers.
Quality and reliability
- 147 tests in 12 files passed at the last recorded run; the code later had 14 test files. The tests use recorded data, so they do not prove the outside services were ready for live use.
- The tests cover search, downloads, spending limits, saved progress, the file checker, link-lifetime checks, replaying saved answers and the TwelveLabs connection.
- A stopped run can carry on where it left off, and each run keeps its own progress files. A paid result that is already saved is not requested again.
- Each planned video description must point to valid evidence, with timestamps in the right order.
By the numbers (build)
- 26 code changes (commits) over five days, from 15 to 19 September.
- 3 days to a measured search and download run.
- The first search run took 133 seconds; 60 chosen downloads passed in about 195 seconds.
- The checked files totalled 492 MB, and each video's length was within two seconds of its listed length.
Is it a fit?
Could this work for your team?
- You research content across a market. Agencies need evidence from more than a few client accounts. A report could carry the agency's own brand.
- Your creators need usable references. In-house teams want guidelines and examples that point back to the original evidence.
- You want a fair comparison. We would agree the market, the ordinary posts to compare with and how success is measured before drawing conclusions.
- You need direction, not guarantees. We would adapt the platforms, searches, feature list and reports. Findings can guide your next test; they cannot promise its result.
What will your next content decision be based on?
Conducted by Apurva · Not a sales call
Or write to care@brownmind.com