ttclips 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ttclips-1.0.0/LICENSE +21 -0
- ttclips-1.0.0/MANIFEST.in +4 -0
- ttclips-1.0.0/PKG-INFO +235 -0
- ttclips-1.0.0/README.md +204 -0
- ttclips-1.0.0/pyproject.toml +49 -0
- ttclips-1.0.0/requirements.txt +9 -0
- ttclips-1.0.0/setup.cfg +4 -0
- ttclips-1.0.0/ttclips/__init__.py +5 -0
- ttclips-1.0.0/ttclips/__main__.py +5 -0
- ttclips-1.0.0/ttclips/binutils.py +51 -0
- ttclips-1.0.0/ttclips/broll.py +142 -0
- ttclips-1.0.0/ttclips/clipper.py +168 -0
- ttclips-1.0.0/ttclips/config.py +90 -0
- ttclips-1.0.0/ttclips/downloader.py +128 -0
- ttclips-1.0.0/ttclips/encoder.py +431 -0
- ttclips-1.0.0/ttclips/gemini.py +187 -0
- ttclips-1.0.0/ttclips/generator.py +103 -0
- ttclips-1.0.0/ttclips/monitor.py +128 -0
- ttclips-1.0.0/ttclips/scaffold.py +64 -0
- ttclips-1.0.0/ttclips/scheduler.py +425 -0
- ttclips-1.0.0/ttclips/state.py +125 -0
- ttclips-1.0.0/ttclips/templates/channels.json +75 -0
- ttclips-1.0.0/ttclips/templates/env.example +51 -0
- ttclips-1.0.0/ttclips/templates/posting_window.json +12 -0
- ttclips-1.0.0/ttclips/templates/tiktok.json +16 -0
- ttclips-1.0.0/ttclips/uploader.py +577 -0
- ttclips-1.0.0/ttclips.egg-info/PKG-INFO +235 -0
- ttclips-1.0.0/ttclips.egg-info/SOURCES.txt +30 -0
- ttclips-1.0.0/ttclips.egg-info/dependency_links.txt +1 -0
- ttclips-1.0.0/ttclips.egg-info/entry_points.txt +5 -0
- ttclips-1.0.0/ttclips.egg-info/requires.txt +11 -0
- ttclips-1.0.0/ttclips.egg-info/top_level.txt +1 -0
ttclips-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kamsicho Raymond Nnaegbuna
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
ttclips-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ttclips
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Fully local TikTok clip reposter: YouTube highlight clips + generated shorts, auto-posted via Playwright.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Keywords: tiktok,youtube,shorts,clips,automation,yt-dlp,whisper,ffmpeg
|
|
7
|
+
Classifier: Development Status :: 3 - Alpha
|
|
8
|
+
Classifier: Environment :: Console
|
|
9
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
10
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Topic :: Multimedia :: Video
|
|
16
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: yt-dlp>=2024.1.1
|
|
21
|
+
Requires-Dist: faster-whisper>=1.0.0
|
|
22
|
+
Requires-Dist: google-genai>=1.0.0
|
|
23
|
+
Requires-Dist: edge-tts>=6.1.10
|
|
24
|
+
Requires-Dist: tiktok-uploader>=1.2.0
|
|
25
|
+
Requires-Dist: playwright>=1.58.0
|
|
26
|
+
Requires-Dist: httpx>=0.27
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: build>=1.2; extra == "dev"
|
|
29
|
+
Requires-Dist: twine>=5.0; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# ttclips — clip reposter for TikTok
|
|
33
|
+
|
|
34
|
+
Fully local, free pipeline: monitors YouTube channels, detects highlights (whisper
|
|
35
|
+
+ Gemini), crops clips to vertical 9:16 with **dead-center, word-synced highlight
|
|
36
|
+
captions**, and posts to TikTok through Playwright browser automation (cookie auth,
|
|
37
|
+
no API approval needed).
|
|
38
|
+
|
|
39
|
+
## How it works
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
YouTube RSS feeds ─────────▶ monitor.py (queue of new videos)
|
|
43
|
+
│
|
|
44
|
+
yt-dlp + ffmpeg (download, merge + cache reuse)
|
|
45
|
+
▼
|
|
46
|
+
faster-whisper (transcription + word timestamps)
|
|
47
|
+
▼
|
|
48
|
+
Gemini (probe → fallback chain) highlight ranking
|
|
49
|
+
▼
|
|
50
|
+
FFmpeg (crop 9:16 + big centered karaoke captions)
|
|
51
|
+
▼
|
|
52
|
+
2 pipelines: repost clips OR generated original clips
|
|
53
|
+
Gemini highlights + Gemini script → edge-tts narration →
|
|
54
|
+
cut_and_crop_clip stock b-roll + captions
|
|
55
|
+
(gradient fallback)
|
|
56
|
+
▼
|
|
57
|
+
Playwright → TikTok upload (cookies)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
8 posts/day schedule (`config/posting_window.json`):
|
|
61
|
+
|
|
62
|
+
| Time | Type |
|
|
63
|
+
|------|------|
|
|
64
|
+
| 08:00 | repost |
|
|
65
|
+
| 10:00 | repost |
|
|
66
|
+
| 12:00 | generated |
|
|
67
|
+
| 14:00 | repost |
|
|
68
|
+
| 16:00 | generated |
|
|
69
|
+
| 18:00 | repost |
|
|
70
|
+
| 20:00 | generated |
|
|
71
|
+
| 22:00 | repost |
|
|
72
|
+
|
|
73
|
+
## Install as a pip package
|
|
74
|
+
|
|
75
|
+
```powershell
|
|
76
|
+
pip install . # from a source checkout
|
|
77
|
+
ttclips --init # scaffold config/ + .env.example into the current dir
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Once published: `pip install ttclips`. The `ttclips` command resolves
|
|
81
|
+
`config/` + `data/` from the **current working directory**, or from
|
|
82
|
+
`$TTCLIPS_HOME` when that variable is set — so an installed CLI can run from
|
|
83
|
+
any empty folder:
|
|
84
|
+
|
|
85
|
+
```powershell
|
|
86
|
+
mkdir D:\ttclips && cd D:\ttclips
|
|
87
|
+
ttclips --init
|
|
88
|
+
# edit .env (GEMINI_API_KEY), then:
|
|
89
|
+
ttclips --monitor
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Running from a source checkout keeps working unchanged simply by cd-ing to the
|
|
93
|
+
repo root. Related console commands: `ttclips-gemini --probe` and
|
|
94
|
+
`ttclips-upload` (the internal upload child process).
|
|
95
|
+
|
|
96
|
+
## Releasing to PyPI (auto via GitHub Actions)
|
|
97
|
+
|
|
98
|
+
Pushing a tag `vX.Y.Z` automatically builds the wheel + sdist, runs
|
|
99
|
+
`twine check`, and publishes to PyPI (`.github/workflows/publish.yml`). A
|
|
100
|
+
separate validation workflow (`.github/workflows/ci.yml`) builds + checks the
|
|
101
|
+
package on every push to `main` and every PR — no secrets needed.
|
|
102
|
+
|
|
103
|
+
Release flow:
|
|
104
|
+
|
|
105
|
+
1. Bump the version in **both** `pyproject.toml` and `ttclips/__init__.py`
|
|
106
|
+
(the release workflow refuses to publish a mismatch).
|
|
107
|
+
2. Tag and push:
|
|
108
|
+
|
|
109
|
+
```powershell
|
|
110
|
+
git add . ; git commit -m "Release v0.1.0"
|
|
111
|
+
git tag v0.1.0
|
|
112
|
+
git push origin main --tags
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
3. Watch "Publish to PyPI" on GitHub → Actions. Once green, `pip install ttclips` works.
|
|
116
|
+
|
|
117
|
+
**First-time publisher setup (trusted publishing — no API token needed):**
|
|
118
|
+
|
|
119
|
+
- PyPI → [Account settings → Publishing](https://pypi.org/manage/account/publishing/)
|
|
120
|
+
→ **Add a pending publisher** with:
|
|
121
|
+
- Owner: `kamzysert3` · Repository: `ttclips` · Workflow name: **`publish.yml`**
|
|
122
|
+
- The workflow filename must match **exactly** — it's part of the OIDC claim.
|
|
123
|
+
- The first successful run creates the `ttclips` project on PyPI automatically.
|
|
124
|
+
|
|
125
|
+
## Setup (Windows)
|
|
126
|
+
|
|
127
|
+
1. **Python 3.10+** — verify with `python --version`.
|
|
128
|
+
2. `powershell -ExecutionPolicy Bypass -File scripts\setup.ps1`
|
|
129
|
+
- creates `.venv`, installs deps & Playwright chromium
|
|
130
|
+
- installs ffmpeg via winget if missing and adds its bin dir to your PATH so
|
|
131
|
+
yt-dlp's video+audio merge finds it
|
|
132
|
+
- copies `.env.example` → `.env`
|
|
133
|
+
3. Edit **`.env`** → set `GEMINI_API_KEY` (free at https://aistudio.google.com/apikey)
|
|
134
|
+
and `PEXELS_API_KEY` (free at https://www.pexels.com/api/ — powers stock
|
|
135
|
+
backgrounds behind generated clips; leave blank and generated clips keep the
|
|
136
|
+
gradient backplate).
|
|
137
|
+
4. **TikTok cookies**: log into tiktok.com in Chrome → use the *"Get cookies.txt
|
|
138
|
+
LOCALLY"* extension → export for tiktok.com → save as `data/cookies.txt`.
|
|
139
|
+
Re-export roughly monthly (sessions drift).
|
|
140
|
+
|
|
141
|
+
## Verify
|
|
142
|
+
|
|
143
|
+
```powershell
|
|
144
|
+
ttclips --validate-session # cookies OK?
|
|
145
|
+
ttclips --monitor # build watch queue
|
|
146
|
+
ttclips --once --dry-run # full pipeline, no upload
|
|
147
|
+
ttclips --once --slot 12:00 # post one slot now
|
|
148
|
+
ttclips --once --slot 12:00 --no-upload # render only
|
|
149
|
+
ttclips --post-file "data\clips\video.mp4" # post an already-generated clip
|
|
150
|
+
ttclips-gemini --probe # ping Gemini model status
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Closing flags: `--dry-run` = skip upload, `--no-upload` = render but don't post.
|
|
154
|
+
`--post-file <path>` (optional `--caption "..."`) uploads a clip that is already
|
|
155
|
+
generated, skipping the entire download/transcribe/rank/encode pipeline — handy
|
|
156
|
+
for retrying a stuck upload on a finished clip. On success it records a manual
|
|
157
|
+
entry in `data/posted.json`.
|
|
158
|
+
|
|
159
|
+
## Scheduled runs (Windows Task Scheduler)
|
|
160
|
+
|
|
161
|
+
| Task | Trigger | Action |
|
|
162
|
+
|------|---------|--------|
|
|
163
|
+
| ttclips-monitor | Daily 06:00 | refresh the watch queue (`--monitor`) |
|
|
164
|
+
| ttclips-poster | Hourly 07:00→23:00 | `--once` (posts only at configured slot times) |
|
|
165
|
+
|
|
166
|
+
The scheduler posts exactly once per slot per day; run `--catchup` after the
|
|
167
|
+
machine was off for a while to fill missed slots for today. `scripts/catchup.ps1`
|
|
168
|
+
wraps it. When registering a task, set its *Start in* folder to your ttclips
|
|
169
|
+
project dir (or define `TTCLIPS_HOME`) so `config/` and `data/` resolve.
|
|
170
|
+
|
|
171
|
+
## Configuration
|
|
172
|
+
|
|
173
|
+
- `config/channels.json` — channels to monitor. Fields per channel:
|
|
174
|
+
`name`, `channel_id`, `enabled`, `keywords` (empty = accept all uploads),
|
|
175
|
+
`max_moments` (how many clips to post per video, capped at 5).
|
|
176
|
+
- `config/posting_window.json` — the 8 daily slots (`time`, `type`, and a
|
|
177
|
+
`hint` for generated inspiration).
|
|
178
|
+
- `config/tiktok.json` — browser/headless/delay/retry settings, default hashtags,
|
|
179
|
+
caption template. Uploads run in an isolated subprocess with retries; waits grow
|
|
180
|
+
exponentially (`retry_wait_initial_sec`, `retry_wait_backoff`,
|
|
181
|
+
`retry_wait_max_sec`) after every failure. `user_agent` must stay a recent
|
|
182
|
+
desktop Chrome UA (the library default Chrome/58 gets TCP-reset by TikTok's
|
|
183
|
+
WAF); `upload_timeout_sec` gives page loads their budget.
|
|
184
|
+
- `.env` — secrets + models + styling:
|
|
185
|
+
- `GEMINI_MODEL` + `GEMINI_FALLBACK_MODELS` (comma list) — tried in order; the
|
|
186
|
+
runtime probes candidates at startup and promotes the healthiest model
|
|
187
|
+
- `GEMINI_RETRY_TIMEOUT` — hard cap on retrying a stuck model
|
|
188
|
+
- `WHISPER_MODEL` / `WHISPER_DEVICE`, `TTS_VOICE`, `COOKIES_FILE`
|
|
189
|
+
- `PEXELS_API_KEY` — stock-video b-roll search for generated clips (free key)
|
|
190
|
+
- caption knobs: `CAPTION_FONT_SIZE` (96), `CAPTION_ALIGNMENT` (5),
|
|
191
|
+
`CAPTION_MARGINV`, `CAPTION_OUTLINE`, `CAPTION_SHADOW`,
|
|
192
|
+
`CAPTION_WORDS_PER_LINE`, `HIGHLIGHT_COLOUR` (yellow), `IDLE_COLOUR` (grey)
|
|
193
|
+
|
|
194
|
+
## Captions
|
|
195
|
+
|
|
196
|
+
Captions are big (96pt), dead-centered, and karaoke-style: the word currently
|
|
197
|
+
being spoken is bold in the highlight colour while the rest of the line stays
|
|
198
|
+
grey. Repost clips use real whisper word timestamps; generated clips re-transcribe
|
|
199
|
+
their TTS narration with faster-whisper so the karaoke is word-synced too, in
|
|
200
|
+
exactly the same style as reposts.
|
|
201
|
+
|
|
202
|
+
## State
|
|
203
|
+
|
|
204
|
+
- `data/queue.json` — discovered videos awaiting processing
|
|
205
|
+
- `data/posted.json` — dedup history (never reposts the same moment twice)
|
|
206
|
+
- `data/downloads/` — merged mp4s (reused on retry, no re-download)
|
|
207
|
+
- `data/clips/` — rendered vertical clips
|
|
208
|
+
- `data/broll/` — cached stock backgrounds for generated clips
|
|
209
|
+
- `data/logs/ttclips.log` — full log
|
|
210
|
+
|
|
211
|
+
## Resilience
|
|
212
|
+
|
|
213
|
+
- **Gemini 503/429 overload**: the probe picks a healthy model at startup and the
|
|
214
|
+
fallback chain walks through remaining models; retries use jittered backoff
|
|
215
|
+
bounded by `GEMINI_RETRY_TIMEOUT`. Older flash models (2.x) return 404 for new
|
|
216
|
+
free-tier keys — use the ones listed in `.env.example`.
|
|
217
|
+
- **YouTube bot-checks**: intermittent "sign in to confirm you're not a bot". The
|
|
218
|
+
downloader fails loudly; merging is handled by the winget ffmpeg install.
|
|
219
|
+
- **Partial failures**: a failed Gemini post step doesn't waste a 150 MB download —
|
|
220
|
+
the cached merged mp4 is reused.
|
|
221
|
+
- **B-roll (generated clips)**: backgrounds come from the free Pexels Videos API
|
|
222
|
+
(`PEXELS_API_KEY`), searched with Gemini-chosen keywords, dimmed and cropped to
|
|
223
|
+
9:16. If the search, download, or render fails the clip falls back to an
|
|
224
|
+
animated gradient backplate, so a slot never dies.
|
|
225
|
+
|
|
226
|
+
## Notes & risks
|
|
227
|
+
|
|
228
|
+
- **Copyright**: only repost content you have rights to. Clipping public channels
|
|
229
|
+
without permission can violate YouTube ToS / creators' rights. Prefer channels
|
|
230
|
+
that allow embedding/repurposing, or lean on the generated pipeline.
|
|
231
|
+
- **TikTok bot detection**: keep `headless: false`; the human-like delays in
|
|
232
|
+
`config/tiktok.json` help. If TikTok serves a CAPTCHA the run fails loudly.
|
|
233
|
+
- **UI changes**: selectors in the TikTok uploader may break; pin versions.
|
|
234
|
+
- **Free tier limits**: the Gemini free tier handles dozens of calls/day — fine for
|
|
235
|
+
a few daily clips.
|
ttclips-1.0.0/README.md
ADDED
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# ttclips — clip reposter for TikTok
|
|
2
|
+
|
|
3
|
+
Fully local, free pipeline: monitors YouTube channels, detects highlights (whisper
|
|
4
|
+
+ Gemini), crops clips to vertical 9:16 with **dead-center, word-synced highlight
|
|
5
|
+
captions**, and posts to TikTok through Playwright browser automation (cookie auth,
|
|
6
|
+
no API approval needed).
|
|
7
|
+
|
|
8
|
+
## How it works
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
YouTube RSS feeds ─────────▶ monitor.py (queue of new videos)
|
|
12
|
+
│
|
|
13
|
+
yt-dlp + ffmpeg (download, merge + cache reuse)
|
|
14
|
+
▼
|
|
15
|
+
faster-whisper (transcription + word timestamps)
|
|
16
|
+
▼
|
|
17
|
+
Gemini (probe → fallback chain) highlight ranking
|
|
18
|
+
▼
|
|
19
|
+
FFmpeg (crop 9:16 + big centered karaoke captions)
|
|
20
|
+
▼
|
|
21
|
+
2 pipelines: repost clips OR generated original clips
|
|
22
|
+
Gemini highlights + Gemini script → edge-tts narration →
|
|
23
|
+
cut_and_crop_clip stock b-roll + captions
|
|
24
|
+
(gradient fallback)
|
|
25
|
+
▼
|
|
26
|
+
Playwright → TikTok upload (cookies)
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
8 posts/day schedule (`config/posting_window.json`):
|
|
30
|
+
|
|
31
|
+
| Time | Type |
|
|
32
|
+
|------|------|
|
|
33
|
+
| 08:00 | repost |
|
|
34
|
+
| 10:00 | repost |
|
|
35
|
+
| 12:00 | generated |
|
|
36
|
+
| 14:00 | repost |
|
|
37
|
+
| 16:00 | generated |
|
|
38
|
+
| 18:00 | repost |
|
|
39
|
+
| 20:00 | generated |
|
|
40
|
+
| 22:00 | repost |
|
|
41
|
+
|
|
42
|
+
## Install as a pip package
|
|
43
|
+
|
|
44
|
+
```powershell
|
|
45
|
+
pip install . # from a source checkout
|
|
46
|
+
ttclips --init # scaffold config/ + .env.example into the current dir
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Once published: `pip install ttclips`. The `ttclips` command resolves
|
|
50
|
+
`config/` + `data/` from the **current working directory**, or from
|
|
51
|
+
`$TTCLIPS_HOME` when that variable is set — so an installed CLI can run from
|
|
52
|
+
any empty folder:
|
|
53
|
+
|
|
54
|
+
```powershell
|
|
55
|
+
mkdir D:\ttclips && cd D:\ttclips
|
|
56
|
+
ttclips --init
|
|
57
|
+
# edit .env (GEMINI_API_KEY), then:
|
|
58
|
+
ttclips --monitor
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Running from a source checkout keeps working unchanged simply by cd-ing to the
|
|
62
|
+
repo root. Related console commands: `ttclips-gemini --probe` and
|
|
63
|
+
`ttclips-upload` (the internal upload child process).
|
|
64
|
+
|
|
65
|
+
## Releasing to PyPI (auto via GitHub Actions)
|
|
66
|
+
|
|
67
|
+
Pushing a tag `vX.Y.Z` automatically builds the wheel + sdist, runs
|
|
68
|
+
`twine check`, and publishes to PyPI (`.github/workflows/publish.yml`). A
|
|
69
|
+
separate validation workflow (`.github/workflows/ci.yml`) builds + checks the
|
|
70
|
+
package on every push to `main` and every PR — no secrets needed.
|
|
71
|
+
|
|
72
|
+
Release flow:
|
|
73
|
+
|
|
74
|
+
1. Bump the version in **both** `pyproject.toml` and `ttclips/__init__.py`
|
|
75
|
+
(the release workflow refuses to publish a mismatch).
|
|
76
|
+
2. Tag and push:
|
|
77
|
+
|
|
78
|
+
```powershell
|
|
79
|
+
git add . ; git commit -m "Release v0.1.0"
|
|
80
|
+
git tag v0.1.0
|
|
81
|
+
git push origin main --tags
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
3. Watch "Publish to PyPI" on GitHub → Actions. Once green, `pip install ttclips` works.
|
|
85
|
+
|
|
86
|
+
**First-time publisher setup (trusted publishing — no API token needed):**
|
|
87
|
+
|
|
88
|
+
- PyPI → [Account settings → Publishing](https://pypi.org/manage/account/publishing/)
|
|
89
|
+
→ **Add a pending publisher** with:
|
|
90
|
+
- Owner: `kamzysert3` · Repository: `ttclips` · Workflow name: **`publish.yml`**
|
|
91
|
+
- The workflow filename must match **exactly** — it's part of the OIDC claim.
|
|
92
|
+
- The first successful run creates the `ttclips` project on PyPI automatically.
|
|
93
|
+
|
|
94
|
+
## Setup (Windows)
|
|
95
|
+
|
|
96
|
+
1. **Python 3.10+** — verify with `python --version`.
|
|
97
|
+
2. `powershell -ExecutionPolicy Bypass -File scripts\setup.ps1`
|
|
98
|
+
- creates `.venv`, installs deps & Playwright chromium
|
|
99
|
+
- installs ffmpeg via winget if missing and adds its bin dir to your PATH so
|
|
100
|
+
yt-dlp's video+audio merge finds it
|
|
101
|
+
- copies `.env.example` → `.env`
|
|
102
|
+
3. Edit **`.env`** → set `GEMINI_API_KEY` (free at https://aistudio.google.com/apikey)
|
|
103
|
+
and `PEXELS_API_KEY` (free at https://www.pexels.com/api/ — powers stock
|
|
104
|
+
backgrounds behind generated clips; leave blank and generated clips keep the
|
|
105
|
+
gradient backplate).
|
|
106
|
+
4. **TikTok cookies**: log into tiktok.com in Chrome → use the *"Get cookies.txt
|
|
107
|
+
LOCALLY"* extension → export for tiktok.com → save as `data/cookies.txt`.
|
|
108
|
+
Re-export roughly monthly (sessions drift).
|
|
109
|
+
|
|
110
|
+
## Verify
|
|
111
|
+
|
|
112
|
+
```powershell
|
|
113
|
+
ttclips --validate-session # cookies OK?
|
|
114
|
+
ttclips --monitor # build watch queue
|
|
115
|
+
ttclips --once --dry-run # full pipeline, no upload
|
|
116
|
+
ttclips --once --slot 12:00 # post one slot now
|
|
117
|
+
ttclips --once --slot 12:00 --no-upload # render only
|
|
118
|
+
ttclips --post-file "data\clips\video.mp4" # post an already-generated clip
|
|
119
|
+
ttclips-gemini --probe # ping Gemini model status
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Closing flags: `--dry-run` = skip upload, `--no-upload` = render but don't post.
|
|
123
|
+
`--post-file <path>` (optional `--caption "..."`) uploads a clip that is already
|
|
124
|
+
generated, skipping the entire download/transcribe/rank/encode pipeline — handy
|
|
125
|
+
for retrying a stuck upload on a finished clip. On success it records a manual
|
|
126
|
+
entry in `data/posted.json`.
|
|
127
|
+
|
|
128
|
+
## Scheduled runs (Windows Task Scheduler)
|
|
129
|
+
|
|
130
|
+
| Task | Trigger | Action |
|
|
131
|
+
|------|---------|--------|
|
|
132
|
+
| ttclips-monitor | Daily 06:00 | refresh the watch queue (`--monitor`) |
|
|
133
|
+
| ttclips-poster | Hourly 07:00→23:00 | `--once` (posts only at configured slot times) |
|
|
134
|
+
|
|
135
|
+
The scheduler posts exactly once per slot per day; run `--catchup` after the
|
|
136
|
+
machine was off for a while to fill missed slots for today. `scripts/catchup.ps1`
|
|
137
|
+
wraps it. When registering a task, set its *Start in* folder to your ttclips
|
|
138
|
+
project dir (or define `TTCLIPS_HOME`) so `config/` and `data/` resolve.
|
|
139
|
+
|
|
140
|
+
## Configuration
|
|
141
|
+
|
|
142
|
+
- `config/channels.json` — channels to monitor. Fields per channel:
|
|
143
|
+
`name`, `channel_id`, `enabled`, `keywords` (empty = accept all uploads),
|
|
144
|
+
`max_moments` (how many clips to post per video, capped at 5).
|
|
145
|
+
- `config/posting_window.json` — the 8 daily slots (`time`, `type`, and a
|
|
146
|
+
`hint` for generated inspiration).
|
|
147
|
+
- `config/tiktok.json` — browser/headless/delay/retry settings, default hashtags,
|
|
148
|
+
caption template. Uploads run in an isolated subprocess with retries; waits grow
|
|
149
|
+
exponentially (`retry_wait_initial_sec`, `retry_wait_backoff`,
|
|
150
|
+
`retry_wait_max_sec`) after every failure. `user_agent` must stay a recent
|
|
151
|
+
desktop Chrome UA (the library default Chrome/58 gets TCP-reset by TikTok's
|
|
152
|
+
WAF); `upload_timeout_sec` gives page loads their budget.
|
|
153
|
+
- `.env` — secrets + models + styling:
|
|
154
|
+
- `GEMINI_MODEL` + `GEMINI_FALLBACK_MODELS` (comma list) — tried in order; the
|
|
155
|
+
runtime probes candidates at startup and promotes the healthiest model
|
|
156
|
+
- `GEMINI_RETRY_TIMEOUT` — hard cap on retrying a stuck model
|
|
157
|
+
- `WHISPER_MODEL` / `WHISPER_DEVICE`, `TTS_VOICE`, `COOKIES_FILE`
|
|
158
|
+
- `PEXELS_API_KEY` — stock-video b-roll search for generated clips (free key)
|
|
159
|
+
- caption knobs: `CAPTION_FONT_SIZE` (96), `CAPTION_ALIGNMENT` (5),
|
|
160
|
+
`CAPTION_MARGINV`, `CAPTION_OUTLINE`, `CAPTION_SHADOW`,
|
|
161
|
+
`CAPTION_WORDS_PER_LINE`, `HIGHLIGHT_COLOUR` (yellow), `IDLE_COLOUR` (grey)
|
|
162
|
+
|
|
163
|
+
## Captions
|
|
164
|
+
|
|
165
|
+
Captions are big (96pt), dead-centered, and karaoke-style: the word currently
|
|
166
|
+
being spoken is bold in the highlight colour while the rest of the line stays
|
|
167
|
+
grey. Repost clips use real whisper word timestamps; generated clips re-transcribe
|
|
168
|
+
their TTS narration with faster-whisper so the karaoke is word-synced too, in
|
|
169
|
+
exactly the same style as reposts.
|
|
170
|
+
|
|
171
|
+
## State
|
|
172
|
+
|
|
173
|
+
- `data/queue.json` — discovered videos awaiting processing
|
|
174
|
+
- `data/posted.json` — dedup history (never reposts the same moment twice)
|
|
175
|
+
- `data/downloads/` — merged mp4s (reused on retry, no re-download)
|
|
176
|
+
- `data/clips/` — rendered vertical clips
|
|
177
|
+
- `data/broll/` — cached stock backgrounds for generated clips
|
|
178
|
+
- `data/logs/ttclips.log` — full log
|
|
179
|
+
|
|
180
|
+
## Resilience
|
|
181
|
+
|
|
182
|
+
- **Gemini 503/429 overload**: the probe picks a healthy model at startup and the
|
|
183
|
+
fallback chain walks through remaining models; retries use jittered backoff
|
|
184
|
+
bounded by `GEMINI_RETRY_TIMEOUT`. Older flash models (2.x) return 404 for new
|
|
185
|
+
free-tier keys — use the ones listed in `.env.example`.
|
|
186
|
+
- **YouTube bot-checks**: intermittent "sign in to confirm you're not a bot". The
|
|
187
|
+
downloader fails loudly; merging is handled by the winget ffmpeg install.
|
|
188
|
+
- **Partial failures**: a failed Gemini post step doesn't waste a 150 MB download —
|
|
189
|
+
the cached merged mp4 is reused.
|
|
190
|
+
- **B-roll (generated clips)**: backgrounds come from the free Pexels Videos API
|
|
191
|
+
(`PEXELS_API_KEY`), searched with Gemini-chosen keywords, dimmed and cropped to
|
|
192
|
+
9:16. If the search, download, or render fails the clip falls back to an
|
|
193
|
+
animated gradient backplate, so a slot never dies.
|
|
194
|
+
|
|
195
|
+
## Notes & risks
|
|
196
|
+
|
|
197
|
+
- **Copyright**: only repost content you have rights to. Clipping public channels
|
|
198
|
+
without permission can violate YouTube ToS / creators' rights. Prefer channels
|
|
199
|
+
that allow embedding/repurposing, or lean on the generated pipeline.
|
|
200
|
+
- **TikTok bot detection**: keep `headless: false`; the human-like delays in
|
|
201
|
+
`config/tiktok.json` help. If TikTok serves a CAPTCHA the run fails loudly.
|
|
202
|
+
- **UI changes**: selectors in the TikTok uploader may break; pin versions.
|
|
203
|
+
- **Free tier limits**: the Gemini free tier handles dozens of calls/day — fine for
|
|
204
|
+
a few daily clips.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "ttclips"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Fully local TikTok clip reposter: YouTube highlight clips + generated shorts, auto-posted via Playwright."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
keywords = ["tiktok", "youtube", "shorts", "clips", "automation", "yt-dlp", "whisper", "ffmpeg"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: End Users/Desktop",
|
|
18
|
+
"Operating System :: Microsoft :: Windows",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.10",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Topic :: Multimedia :: Video",
|
|
24
|
+
"Topic :: Internet :: WWW/HTTP",
|
|
25
|
+
]
|
|
26
|
+
dependencies = [
|
|
27
|
+
"yt-dlp>=2024.1.1",
|
|
28
|
+
"faster-whisper>=1.0.0",
|
|
29
|
+
"google-genai>=1.0.0",
|
|
30
|
+
"edge-tts>=6.1.10",
|
|
31
|
+
"tiktok-uploader>=1.2.0",
|
|
32
|
+
"playwright>=1.58.0",
|
|
33
|
+
"httpx>=0.27",
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
[project.optional-dependencies]
|
|
37
|
+
dev = ["build>=1.2", "twine>=5.0"]
|
|
38
|
+
|
|
39
|
+
[project.scripts]
|
|
40
|
+
ttclips = "ttclips.scheduler:main"
|
|
41
|
+
ttclips-init = "ttclips.scaffold:main"
|
|
42
|
+
ttclips-gemini = "ttclips.gemini:main"
|
|
43
|
+
ttclips-upload = "ttclips.uploader:main"
|
|
44
|
+
|
|
45
|
+
[tool.setuptools.packages.find]
|
|
46
|
+
include = ["ttclips*"]
|
|
47
|
+
|
|
48
|
+
[tool.setuptools.package-data]
|
|
49
|
+
ttclips = ["templates/*"]
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Legacy requirements list — the source of truth is `pyproject.toml`
|
|
2
|
+
# (`pip install .` / `pip install -e .` reads dependencies from there).
|
|
3
|
+
yt-dlp>=2024.1.1
|
|
4
|
+
faster-whisper>=1.0.0
|
|
5
|
+
google-genai>=1.0.0
|
|
6
|
+
edge-tts>=6.1.10
|
|
7
|
+
tiktok-uploader>=1.2.0
|
|
8
|
+
playwright>=1.58.0
|
|
9
|
+
httpx>=0.27
|
ttclips-1.0.0/setup.cfg
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""Binary resolution helpers: locate ffmpeg/ffprobe for yt-dlp + encoder.
|
|
2
|
+
|
|
3
|
+
Resolution order: explicit env override (FFMPEG_BIN/FFPROBE_BIN) -> winget
|
|
4
|
+
Gyan.FFmpeg install -> system PATH. Returns None when nothing is found so
|
|
5
|
+
callers can fail loudly with a clear message.
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import glob
|
|
10
|
+
import logging
|
|
11
|
+
import os
|
|
12
|
+
import shutil
|
|
13
|
+
from functools import lru_cache
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
|
|
16
|
+
from ttclips.config import load_env
|
|
17
|
+
|
|
18
|
+
log = logging.getLogger(__name__)
|
|
19
|
+
|
|
20
|
+
ENV = load_env()
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def find_binary(env_key: str, name: str) -> str | None:
|
|
24
|
+
"""Resolve the path of *name* (e.g. 'ffmpeg.exe'), or None if unavailable."""
|
|
25
|
+
env_val = (ENV.get(env_key) or "").strip()
|
|
26
|
+
if env_val and Path(env_val).exists():
|
|
27
|
+
return env_val
|
|
28
|
+
# winget Gyan.FFmpeg layout: <Packages>/Gyan.FFmpeg*/ffmpeg-*-full_build/bin/
|
|
29
|
+
pkg_root = Path(os.environ.get("LOCALAPPDATA", "")) / "Microsoft" / "WinGet" / "Packages"
|
|
30
|
+
for candidate in glob.glob(str(pkg_root / "Gyan.FFmpeg*" / "*" / "bin" / name)):
|
|
31
|
+
return candidate
|
|
32
|
+
return shutil.which(name)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@lru_cache(maxsize=None)
|
|
36
|
+
def ffmpeg_bin() -> str | None:
|
|
37
|
+
return find_binary("FFMPEG_BIN", "ffmpeg.exe")
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@lru_cache(maxsize=None)
|
|
41
|
+
def ffprobe_bin() -> str | None:
|
|
42
|
+
return find_binary("FFPROBE_BIN", "ffprobe.exe")
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@lru_cache(maxsize=None)
|
|
46
|
+
def ffmpeg_dir() -> str | None:
|
|
47
|
+
"""Directory containing ffmpeg.exe (also holds ffprobe.exe), or None."""
|
|
48
|
+
bin_path = ffmpeg_bin()
|
|
49
|
+
if not bin_path:
|
|
50
|
+
return None
|
|
51
|
+
return str(Path(bin_path).parent)
|