Broadcast Kit
A self-contained, agent-facing publisher kit. Clone, install, log in once per platform, publish. Optional polish + scoring layer for content optimization sprints.
Publishers: Douyin (full Playwright + scheduled + queue verify + metrics), XHS (Playwright note publish), X (NyxID-brokered or direct API), Reddit (Playwright stealth + Cloudflare bypass · old.reddit OP-reply + anon shadowban detection), Discourse (generic — n8n forum / huggingface community / any self-hosted Discourse · Topic JSON API shadowban detection).
Optimizers (optional): content_brain (LLM diagnostic, dbskill-style), market_role (vendored marketing-persona prompts), reviewer (10-dim severity audit with bundled rubrics), variants (A/B generate+rank), virality_check (Higgsfield CLI + bitgrit API), miss_analysis (top-K corpus + LLM diff), engagement_score (HeavyRanker + weighted composite scoring), playbook (sprint schema), public_copy_gate (deterministic caption/topic release gate).
For agents reading this for the first time
Start at CATALOG.md — agent-readable menu of every callable part with input/output shapes, when-to-use, and copy-paste recipes. If a user asks you to grow an account, polish a draft, or set up a content sprint, CATALOG.md tells you which parts to pick and in what order.
For internal staff (non-developers)
Read docs/internal-onboarding.md. It walks through broadcast-kit setup, broadcast-kit doctor, then the known-good path: publish an already finished video through Douyin/XHS. Source-to-video through NotebookLM + SlideSync is supported when those external tools are installed.
Quick orientation:
- What it is — a Python package with
broadcast-kit <command> CLI. Each platform's Playwright code lives in broadcast_kit/publishers/<platform>/. No external repo dependency.
- What you need on the host — Python 3.11+, Chromium (
python -m playwright install chromium), ffmpeg (for Douyin cover gen), a display (Playwright runs non-headless).
- Where state lives —
state/<platform>/auth.json (gitignored). First login is interactive; subsequent runs reuse the cookie.
- What you must NOT do — don't pass raw API keys into manifests or docs; don't
--force-republish without checking the inventory; don't run a live publish without confirming the verdict triple (Douyin) or the note-manager verification (XHS); don't bypass publish_decision: hold from content_brain.
- No daemon shipped — you (the consuming agent) decide when to wake. Use launchd / cron / your own loop. CATALOG.md Recipe B shows the full closed-loop sequence.
Install
pip install .
python -m playwright install chromium
For the advanced NotebookLM + SlideSync source-to-video path:
pip install '.[source-to-video]'
First-time login (per platform)
python -m broadcast_kit.publishers.douyin.cli login --fresh
python -m broadcast_kit.publishers.xhs.cli login --fresh
broadcast-kit-reddit login --fresh --account <handle>
broadcast-kit-discourse login --fresh --account <handle> --instance https://community.n8n.io
Each opens a non-headless Chromium. Scan QR / finish login. Press Enter in the terminal. storage_state is saved to state/<platform>/auth.json. Check validity later with ... login (no --fresh).
Top-level CLI
broadcast-kit doc-to-batch # markdown/dir/repo → content-batch
broadcast-kit render-narration # storyboard handoff
broadcast-kit render-video # SlideSync preflight
broadcast-kit publish # one manifest → platform
broadcast-kit produce-publish # known-good video or generated video → polish → publish
broadcast-kit registry-to-manifest # publish-registry → platform manifest
broadcast-kit fetch-metrics # creator-center scraper / API call
broadcast-kit enrich-metrics # raw metrics + registry → scored feedback jsonl
broadcast-kit doctor # read-only local capability check
broadcast-kit optimize ... # content_brain | reviewer | variants | engagement
Recommended setup check:
broadcast-kit doctor
broadcast-kit doctor --live-login-check
Each Playwright publisher also exposes its own python -m broadcast_kit.publishers.<platform>.cli.
Optimize (optional polish layer)
# Structured LLM diagnostic — audience, hooks, titles, ai-taste, publish_decision
broadcast-kit optimize content-brain --draft draft.yaml
# 10-dimension severity-weighted audit (bundled rubric per platform)
broadcast-kit optimize reviewer --draft draft.yaml --max-rounds 3
# Generate N variants and pick the best by reviewer score
broadcast-kit optimize variants --draft draft.yaml --n 3
# Score post-publish metrics with HeavyRanker (X) or platform-neutral composite weights
broadcast-kit optimize engagement --metrics metrics.jsonl --scorer composite
