yt-pub-livesx — cuts YouTube livestreams into clips and publishes

What it is

A clip factory for your live streams

Fetches live streams from a source channel, identifies topics with AI, and publishes clips to a destination channel with a title, description, tags, and thumbnail. Designed to run as a multi-channel template, isolating credentials and quotas per instance.

✂️ AI topic-based clipping

Automatic transcription (YouTube captions) → topic analysis with Piramyd / Claude / OpenRouter → timestamps → clipping with FFmpeg.

✂️ Three video sources

YouTube live streams, import videos from a folder imports/ and syncs TikTok channels to YouTube — they all go through the same pipeline.

✂️ Master + N instances

1 master dashboard aggregates everything on port 8090; each channel is a copy of the template on a port 809N, with its own SQLite database, OAuth, and GCP project.

How it works

From livestream to published clip

Each channel’s scheduler downloads new live streams, transcribes, analyzes, clips, generates a thumbnail, and publishes via OAuth, logging everything in the local SQLite database. The dashboard controls it, and the master aggregates the data.

Lives (source channel)→ Transcription→ AI analysis→ Cut (FFmpeg)→ Thumbnail (AI)→ Publishing (destination channel)

1 channel = 1 instance

OAuth is per channel, and the YouTube Data API quota is per GCP project — separate instances ensure independent quotas and fault isolation.

Systemd per channel

Each pair yt-dashboard<N> + yt-scheduler<N> is independent: if one channel goes down, the others keep running.

Control dashboard

Clickable stats, schedules, a table of live streams by status, a unified clips tab, error reprocessing, and real-time scheduler status.

Prerequisites

What you need before getting started

Python 3.10+ and a few command-line tools. Each channel needs its own Google Cloud project with the YouTube Data API v3 enabled.

System tools

Python 3.10+, ffmpeg, yt-dlp, deno (yt-dlp’s JS runtime), curl, and Pillow.

# ubuntu/debian
sudo apt-get install -y python3 ffmpeg curl git
pipx install yt-dlp

Deno

Used internally by yt-dlp for some extractors.

curl -fsSL https://deno.land/install.sh | sh

GCP project per channel

YouTube Data API v3 enabled, OAuth Consent (External / Testing), and OAuth Client (Desktop App) with CLIENT_ID + CLIENT_SECRET + API Key.

# required scopes
youtube, youtube.upload

User guide · step by step

From the master to the first channel publishing

Installation is split into two parts: Part 1 brings up the master (once per machine); Part 2 creates one instance per channel from this template.

Part 1 — System setup

Checks dependencies, installs Python packages, and starts the master dashboard as a systemd user service on port 8090.

git clone https://github.com/inematds/yt-pub-livesx.git
cd yt-pub-livesx
./setup.sh  # http://localhost:8090

Part 2 — Add a channel

Asks the questions (press ENTER to accept the default), copies the template to ~/projetos/<nome>, generates the .env and creates the instance’s systemd services.

./scripts/setup-canal

Authenticate via OAuth

When the setup-canal to pause, run the yt-auth in another terminal, open the generated link and authorize with the account that owns the destination channel.

GWS_CONFIG_DIR=~/projetos/<nome>/config \
  python3 ~/projetos/<nome>/scripts/yt-auth
# callback saves tokens in config/credentials.enc

Cut a livestream

Manual generates the prompt; with --ai piramyd-api runs automatically; --dry-run only shows the topics; --publish clips and publishes.

yt-clip <video_id> --dry-run        # only shows topics
yt-clip <video_id> --ai piramyd-api  # automatic
yt-clip <video_id> --publish        # cuts and publishes

Generate a thumbnail and publish a single video

The scripts yt-thumbnail e yt-publish work outside the automated flow.

yt-thumbnail --title "Título do clip" --output thumb.jpg
yt-publish video.mp4 --title "Título" --description "Desc"

Operate from the dashboard

Each channel has its own dashboard on port 809N (default password Inema2026$$$, in config/.env). The master aggregates them all on 8090.

python3 dashboard/server.py 8091  # http://localhost:8091

Examples

Use cases

Designed to operate multiple channels at once, with optional code sync between instances.

Multiple channels in parallel

Instances lives1..livesN, each on its own port 809N, with independent schedulers and dashboards and a GCP project for each destination channel.

TikTok → YouTube sync

O tiktok_scanner scans TikTok channels, downloads the videos, and sends them to the pipeline queue to publish on the destination YouTube channel.

Import ready-made videos

Drop files into imports/ e o import_worker turns them into a pipeline queue — thumbnails and publishing included.

Deploy on a VPS with an SSH tunnel

Enable lingering, run both parts, and access the dashboards via ssh -L without exposing ports publicly.

New · Oct/2026

Viral live thumbnails, made by Codex

When a live is enriched, the AI writes the title, description, a punchy phrase and a scene. Codex (image_gen, via subscription) draws the art and the channel design goes on top: brand, font and colors stay the same.

Face when it makes sense

For opinion, test or reaction lives, the AI puts the host in the scene, using the channel background image as the face reference. You can also choose Always or Never.

Default banner as fallback

If Codex fails, the previous banner is used (fixed background + title). The style is chosen in the Enrich Lives tab of the dashboard.

Complete title and description

Lives with no title are enriched too. Lives with a title but no description on YouTube get only the description; title and thumbnail stay as they are.

Roadmap

Status and hardening

The pipeline is functional for internal use via SSH tunnel; the focus for improvement is dashboard security before any public exposure.

Works

Complete multi-channel pipelineLive streams, import, and TikTok → topic-based clipping → thumbnail → publishing, with a master and N instances and SQLite per channel.

In use

VPS operationsSystemd user services with lingering, backups of credentials.enc + .encryption_key + lives.db and cleanup of lives/.

To review

Dashboard securityNo rate limit on login, plaintext password in .env, no TLS or 2FA — a reverse proxy with HTTPS is recommended before exposing it.

Continuous

Code sync between instancesscripts/sync-instances propagates the template to opt-in instances.