TikTok Uploader

Upload, schedule, and batch-manage TikTok videos using the `tiktok-uploader` Python library (Playwright-based browser automation wrapping TikTok's web upload page).

## Setup

```bash
pip install tiktok-uploader
playwright install
```

## Authentication

The user **must** provide one of these. Ask if not yet configured:

| Method | How to get it |
|---|---|
| **Cookie file** (recommended) | Export `cookies.txt` from browser using the "Get cookies.txt LOCALLY" extension. |
| **Session ID** | DevTools → Application → Cookies → `.tiktok.com` → copy `sessionid` value. |
| **Cookie list** | List of dicts: `[{name, value, domain, path}]`. |

Session cookies expire — if uploads fail with auth errors, the user needs fresh cookies.

## Operations

### Upload a single video

```python
from tiktok_uploader.upload import TikTokUploader

with TikTokUploader(cookies="cookies.txt", headless=True) as uploader:
    success = uploader.upload_video(
        filename="video.mp4",
        description="Check this out #fyp #viral @friend ",
        visibility="everyone",   # "everyone" | "friends" | "only_you"
        comment=True,
        stitch=True,
        duet=True,
        cover="thumbnail.png",   # optional
    )
    print("Uploaded!" if success else "Failed.")
```

### Schedule a video

```python
from datetime import datetime, timezone

with TikTokUploader(sessionid="abc123...", headless=True) as uploader:
    uploader.upload_video(
        filename="video.mp4",
        description="Dropping soon! #scheduled ",
        schedule=datetime(2026, 3, 10, 14, 30, tzinfo=timezone.utc),
    )
```

Rules: must be 20 min – 10 days in the future; minutes are rounded to nearest 5.

### Batch upload

```python
videos = [
    {"path": "vid1.mp4", "description": "First #batch "},
    {"path": "vid2.mp4", "description": "Second", "schedule": datetime(2026, 3, 10, 15, 0, tzinfo=timezone.utc)},
    {"path": "vid3.mp4", "description": "Third", "visibility": "friends"},
]

with TikTokUploader(cookies="cookies.txt", headless=True) as uploader:
    failed = uploader.upload_videos(videos)
    if failed:
        print(f"{len(failed)} videos failed")
```

### Using the wrapper module

This skill ships a convenience wrapper at `scripts/tiktok_manager.py`:

```python
from scripts.tiktok_manager import TikTokManager

mgr = TikTokManager(cookies="~/cookies.txt")
# Upload
mgr.upload("video.mp4", description="Hello TikTok! #fyp ")
# Schedule
mgr.upload("video.mp4", description="Scheduled!", schedule="2026-03-10T14:30")
# Batch
mgr.upload_batch([
    {"path": "v1.mp4", "description": "First"},
    {"path": "v2.mp4", "description": "Second", "schedule": "2026-03-10T15:00"},
])
# Scan directory for uploadable videos
videos = TikTokManager.scan_videos("~/Videos/tiktok", recursive=True)
```

## Important Notes

- **Hashtags & @mentions**: Include in description, each tag followed by a space. Verify they exist.
- **Description limit**: ~150 characters.
- **Rate limiting**: TikTok throttles after many uploads. Space them out; wait hours if throttled.
- **Headless mode**: Set `headless=False` to watch the browser for debugging.
- **Proxy**: Pass `proxy={"host": "...", "port": "..."}` — Chrome only.
- **Supported formats**: .mp4, .mov, .avi, .wmv, .flv, .webm, .mkv, .m4v, .3gp, .3g2, .gif
- **Fragility**: Browser automation, not an official API. TikTok UI changes can break it.

## Troubleshooting

| Problem | Fix |
|---|---|
| Auth/login error | Cookies expired → export fresh cookies.txt |
| Upload hangs | Try `headless=False` to see what's happening |
| Throttled/rate limited | Wait a few hours between batches |
| Selector errors | tiktok-uploader may need an update (`pip install -U tiktok-uploader`) |