ttclips

An automated, fully-local clip reposter for TikTok. It monitors YouTube channels, detects highlight moments, cuts them into vertical 9:16 clips with dead-center, word-synced karaoke captions, and posts them to TikTok on a schedule — without any TikTok API approval.

• Fully local and free — no clip-hosting service, no paid APIs required.
• AI-ranked highlights — whisper transcription + Gemini highlight ranking.
• Word-synced captions — the active word is bold/highlighted in real time.
• Cookie-based auth — no TikTok developer approval / API key needed.
• Self-healing — model fallback chains, cached downloads, graceful b-roll fallback.

Table of contents

• Features
• Requirements
• Installation
• Quickstart
• How it works
• Command-line reference
• Configuration
  • Target channels (config/channels.json)
  • Posting window (config/posting_window.json)
  • TikTok upload settings (config/tiktok.json)
  • Environment variables (.env)
• State and data
• Automation (Windows Task Scheduler)
• Frequently asked questions
• Development
• Releasing
• Legal & operational notes
• License

Features

• YouTube monitoring — polls channel RSS feeds and queues new videos that match your keyword filters.
• Highlight detection — faster-whisper transcribes the audio; Gemini ranks the strongest 20–70 second moments with hooks, captions and hashtags.
• Vertical clip production — FFmpeg crops to 1080×1920 (9:16) and burns in big, centered, word-synced captions that highlight each spoken word as it happens.
• Original content mode — Gemini writes a script, edge-tts narrates it, stock b-roll (Pexels) or an animated gradient backs the clip.
• Scheduled posting — up to 8 posts/day at configurable times, with catch-up for missed slots.
• Resilient uploads — Playwright-driven TikTok uploads with human-like delays, exponential backoff retries, and an isolated subprocess so a crashed upload can never take the scheduler down.
• Reusable state — never re-downloads a video or reposts the same moment.

Requirements

• Python 3.10+
• ffmpeg + ffprobe (required to merge streams and render clips):
  • Windows: winget install Gyan.FFmpeg
  • macOS: brew install ffmpeg
  • Debian/Ubuntu: sudo apt install ffmpeg
  • Alternative: set FFMPEG_BIN / FFPROBE_BIN in .env to point at your own binaries.
• Playwright Chromium — installed once, see Installation.
• A Gemini API key — free at https://aistudio.google.com/apikey.
• TikTok cookies (only needed for the upload step) — see Quickstart.

Installation

pip install ttclips

Then install the Playwright browser (one-time):

playwright install chromium

On Windows, pip install puts the ttclips command in %LOCALAPPDATA%\Programs\Python\Python312\Scripts (add it to PATH if the command isn't found).

Where config and data live

ttclips resolves its working directory as follows:

1. $TTCLIPS_HOME if set, otherwise
2. the current working directory.

All config/, data/ and .env paths are relative to that directory, so the same installation can run multiple independent projects.

Quickstart

1. Initialise a project folder

mkdir my-clips && cd my-clips
ttclips --init

This creates config/ (default channels, posting window, TikTok settings) and .env.example.

2. Configure secrets

cp .env.example .env    # Windows: copy .env.example .env

Edit .env and set at minimum:

GEMINI_API_KEY=your_gemini_api_key_here

Optionally set PEXELS_API_KEY (free at https://www.pexels.com/api/) to power stock-video backgrounds for generated clips. Without it, generated clips use an animated gradient background.

3. Provide TikTok cookies (for posting)

TikTok uploads use browser session cookies instead of an API key:

1. Log in to tiktok.com in Chrome.
2. Export cookies in Netscape format (e.g. the "Get cookies.txt LOCALLY" browser extension).
3. Save as data/cookies.txt in the project folder.

Re-export roughly monthly, as sessions drift.

4. Verify and run

ttclips --validate-session        # cookies OK?
ttclips --monitor                 # build the watch queue from YouTube feeds
ttclips --once --dry-run          # full pipeline, no upload
ttclips --once --slot 12:00       # post one slot now
ttclips --once --slot 12:00 --no-upload    # render only, don't post

How it works

YouTube RSS feeds ─────────────────▶ monitor (queue of new videos)
                                     │
                          yt-dlp + ffmpeg (download, merge, cache)
                                     ▼
                          faster-whisper (transcription + word timestamps)
                                     ▼
                          Gemini (probe → fallback chain) highlight ranking
                                     ▼
                          FFmpeg (crop 9:16 + centered karaoke captions)
                                     ▼
   two pipelines:    repost clips            OR        generated original clips
              Gemini highlights        Gemini script → edge-tts narration →
              cut_and_crop_clip        stock b-roll + captions
                                        (gradient fallback)
                                     ▼
                          Playwright → TikTok upload (cookies)

Default posting schedule (config/posting_window.json):

Command-line reference

Posting flags compose: --dry-run skips the upload, --no-upload renders the clip but doesn't post, and --post-file uploads an existing clip directly (recording it in data/posted.json so it is never reposted).

Configuration

Target channels (config/channels.json)

Each channel entry:

Top-level options:

Posting window (config/posting_window.json)

A list of {"time": "HH:MM", "type": "repost"|"generated", "hint": ""} slots. hint feeds the script prompt for generated-content slots.

TikTok upload settings (config/tiktok.json)

Environment variables (.env)

State and data

Automation

For unattended daily operation on Windows, register two tasks in Task Scheduler (set the task Start in folder to the project directory, or define TTCLIPS_HOME):

The scheduler posts each slot at most once per day. After the machine was off, run ttclips --catchup to fill the missed slots for today.

FAQ

pip uninstall ttclips

Development

git clone https://github.com/kamzysert3/ttclips.git
cd ttclips
python -m venv .venv
.\.venv\Scripts\activate        # Windows (PowerShell)
source .venv/bin/activate       # macOS/Linux
pip install -e .
playwright install chromium

One-command setup on Windows: powershell -ExecutionPolicy Bypass -File scripts\setup.ps1 (creates the venv, installs the package, Playwright, ffmpeg via winget, and .env from the example).

There is no formal test suite yet; run python -m ttclips --version and a ttclips --once --dry-run to smoke-test a local checkout.

Contributions are welcome via pull request — keep changes consistent with the existing structure and style, and keep pyproject.toml + ttclips/__init__.py versions in sync.

Releasing

Pushing a version tag builds the distributions and publishes them to PyPI automatically (GitHub Actions):

git add . && git commit -m "Release v1.0.1"
git tag v1.0.1
git push origin main --tags

The release pipeline verifies the tag matches the version in both pyproject.toml and ttclips/__init__.py, builds the wheel + sdist, runs twine check, and publishes via trusted publishing (OIDC) — no API tokens.

Legal & operational notes

• Copyright: Only repost content you have rights to. Clipping public channels without permission can violate YouTube ToS and creators' rights. Prefer channels that allow embedding/repurposing, or use the generated pipeline.
• TikTok ToS: browser automation to post content is personal-use and may not be permitted for commercial accounts — verify your own risk.
• UI changes: TikTok's uploader selectors can change; pin dependency versions and re-export cookies regularly.
• Free-tier limits: the Gemini free tier handles dozens of calls/day — comfortable for a few daily clips.

License

MIT — see the LICENSE file for full terms.