Downloader TikTok Videos

Overview

Downloader TikTok Videos downloads the latest video (or multiple videos) from a public TikTok account using yt-dlp. Read this documentation fully before writing any code or running commands.

Prerequisites

This skill requires yt-dlp (and optionally ffmpeg for audio/video merging).

⚠️ The commands below modify your host environment (install packages system-wide). Run them only if yt-dlp is not already installed and you are comfortable doing so.

pip install -U yt-dlp --break-system-packages   # Linux system Python
# or
pip install -U yt-dlp                           # virtualenv / macOS
yt-dlp --version                                # verify install

Operation Types

This skill supports four operation types. Determine which one(s) the user needs:

1. Quick Download — Download the latest video from an account
2. Bulk Download — Download the N most recent videos
3. Metadata Only — Retrieve info/stats without downloading the video
4. Direct Video URL — Download from a specific video URL

Workflows

1. Quick Download — Latest Video from an Account

When to use: User provides a @username or profile URL

Steps:

1. Normalize the username (strip @ if present)
2. Build the profile URL: https://www.tiktok.com/@{username}
3. Fetch metadata for the latest video (--playlist-items 1 --no-download)
4. Show the user the video info (title, date, duration)
5. Download with the optimal command
6. Confirm success and provide the file path

Command:

yt-dlp \
  --playlist-items 1 \
  --format "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  --output "./%(uploader_id)s_%(upload_date)s_%(id)s.%(ext)s" \
  "https://www.tiktok.com/@{username}"

Verify the result:

ls -lh ./*.mp4

2. Bulk Download — N Most Recent Videos

When to use: User wants multiple videos

Steps:

1. Ask how many videos (if not specified, default = 5)
2. Build the command with --playlist-items 1-N
3. Add --download-archive to avoid duplicates
4. Download with progress output
5. List downloaded files

Command:

yt-dlp \
  --playlist-items 1-{N} \
  --format "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  --download-archive ./tiktok_archive.txt \
  --output "./%(uploader_id)s/%(upload_date)s_%(id)s.%(ext)s" \
  "https://www.tiktok.com/@{username}"

3. Metadata Only

When to use: User wants video info without downloading

Read: references/metadata.md for all available fields and the full command

Quick command:

yt-dlp \
  --playlist-items 1 \
  --skip-download \
  --write-info-json \
  --print "%(uploader_id)s | %(upload_date)s | %(duration)ss | %(view_count)s views | %(title)s" \
  "https://www.tiktok.com/@{username}"

4. Direct Video URL

When to use: User provides a direct video URL

Command:

yt-dlp \
  --format "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  --output "./%(uploader_id)s_%(id)s.%(ext)s" \
  "{video_url}"

Common Errors

Error	Cause	Fix
HTTP Error 403	TikTok rate limiting	Add --sleep-interval 3 --max-sleep-interval 6
Unable to extract	Outdated yt-dlp	pip install -U yt-dlp --break-system-packages
Private account	Private account	Use --cookies-from-browser chrome if logged in ⚠️ exports session cookies — keep them private
No video formats	Geo-restriction	Add --geo-bypass
Sign in required	Restricted content	Provide cookies via --cookies cookies.txt ⚠️ treat this file like a password
Merge requires ffmpeg	ffmpeg missing	apt-get install ffmpeg -y

⚠️ Cookie security note: Browser cookies exported via --cookies-from-browser or cookies.txt contain active session tokens. Never share these files, commit them to version control, or pass them to untrusted scripts. Delete them after use if no longer needed.

Username Normalization

# Accepts all these formats:
# @myaccount  →  myaccount
# myaccount   →  myaccount
# https://www.tiktok.com/@myaccount  →  myaccount

def normalize(input_str):
    if "tiktok.com/@" in input_str:
        return input_str.split("tiktok.com/@")[-1].split("/")[0]
    return input_str.lstrip("@").strip()

Reference Files

Load these references as needed:

references/metadata.md

• When: Fetching metadata, working with JSON fields
• Contains: All available yt-dlp fields, print format examples, JSON export

references/advanced.md

• When: Watermark removal, cookies, proxy, custom headers
• Contains: Advanced techniques, restriction bypass, full yt-dlp options

KBLICENSE.txt

• When: Questions about usage rights or Terms of Service
• Contains: Usage conditions, permitted and prohibited uses

Output Guidelines

• Always display metadata before downloading (title, date, duration)
• Confirm the downloaded file path
• Show the final file size
• On error, propose the fix directly

Example Queries

Quick download:

• "Download the latest video from @someaccount"
• "Get the latest TikTok post from myaccount"
• "Download the last video from https://www.tiktok.com/@user"

Bulk download:

• "Download the 5 latest videos from @user"
• "Get the last 10 videos from @account"

Metadata:

• "Give me the info on the latest video from @user"
• "What is the title and date of the last post from @account"

Direct URL:

• "Download this TikTok video: https://www.tiktok.com/@user/video/123456"