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

> ⚠️ 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"