Version One

tools/pyktok/README.md

@@ -0,0 +1,30 @@
+# Pyktok Helper
+
+A small wrapper around Pyktok to download a single TikTok video.
+
+Reference: Pyktok on PyPI — https://pypi.org/project/pyktok/
+
+## Setup
+
+```bash
+cd tools/pyktok
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+# Install browser drivers required by playwright
+python -m playwright install
+# On some systems you may also need OS deps:
+# python -m playwright install-deps
+```
+
+## Usage
+
+```bash
+# In the virtualenv
+python download_tt.py --url "https://www.tiktok.com/@user/video/123..." --out ./downloads
+# Prints the absolute path to the downloaded .mp4 on success
+```
+
+Notes:
+- Pyktok may require a logged-in browser session for certain videos. See Pyktok docs for `specify_browser` usage if needed.
+- This script emits only the final .mp4 path on stdout for easy consumption by Node.

tools/pyktok/download_tt.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+import argparse
+import os
+import sys
+import json
+from pathlib import Path
+
+try:
+    import pyktok as pyk  # type: ignore
+except Exception as e:
+    print(
+        f"Error: pyktok not installed. Run: pip install -r requirements.txt\n{e}",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Download TikTok video using Pyktok")
+    parser.add_argument('--url', required=True, help='TikTok share URL')
+    parser.add_argument('--out', default='downloads', help='Output directory (default: downloads)')
+    args = parser.parse_args()
+
+    out_dir = Path(args.out).resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # Change CWD to output dir so pyktok saves files here
+    os.chdir(out_dir.as_posix())
+
+    # Save video and a metadata CSV in the output directory
+    meta_csv = out_dir / 'tiktok_metadata.csv'
+    try:
+        pyk.save_tiktok(args.url, True, meta_csv.as_posix())
+    except Exception as e:
+        print(f"Error: download failed: {e}", file=sys.stderr)
+        sys.exit(3)
+
+    # Find the most recent mp4 in the output dir
+    mp4s = sorted(out_dir.glob('*.mp4'), key=lambda p: p.stat().st_mtime, reverse=True)
+    if not mp4s:
+        print('No video found', file=sys.stderr)
+        sys.exit(4)
+
+    # Attempt to retrieve description via JSON
+    description = ''
+    try:
+        data = pyk.alt_get_tiktok_json(args.url)
+        # recursive search for 'desc' or 'description'
+        def find_desc(obj):
+            if isinstance(obj, dict):
+                for k, v in obj.items():
+                    if isinstance(k, str) and k.lower() in ('desc', 'description', 'title') and isinstance(v, str):
+                        return v
+                    found = find_desc(v)
+                    if found:
+                        return found
+            elif isinstance(obj, list):
+                for it in obj:
+                    found = find_desc(it)
+                    if found:
+                        return found
+            return None
+        d = find_desc(data)
+        if isinstance(d, str):
+            description = d
+    except Exception:
+        description = ''
+
+    print(json.dumps({"video_path": mp4s[0].as_posix(), "description": description}, ensure_ascii=False))
+
+
+if __name__ == '__main__':
+    main()
+
+

tools/pyktok/requirements.txt

@@ -0,0 +1,5 @@
+pyktok==0.0.31
+playwright>=1.46.0
+requests>=2.31.0
+
+