How automatic uploading works

There is no scraping and no browser automation. Uploads go through the official YouTube Data API v3, using an API project you own and a one-time OAuth sign-in to your channel. PurffleShorts keeps the token locally and reuses it for every upload.

YouTube treats a vertical video of up to three minutes as a Short. PurffleShorts renders 1080×1920 at your chosen length (--duration 45, for example), so every upload lands in the Shorts feed.

One-time setup

Create a Google Cloud project

At console.cloud.google.com, create a new project for your channel.

Enable the YouTube Data API v3

In APIs & Services → Library, find YouTube Data API v3 and enable it.

Create a Desktop OAuth client

Configure the OAuth consent screen, then create an OAuth client ID of type Desktop app.

Save it as credentials.json

Download the client JSON and save it in the PurffleShorts folder as credentials.json. Keep it out of any public repository.

Authorise your channel

Run the command below and sign in with the Google account that owns the channel:

python -m purffle_shorts auth

Two Google rules worth knowing. While an OAuth app is in Testing status, Google expires its sign-ins after seven days — re-run auth, or publish the consent screen. And YouTube's API terms say videos uploaded from unverified API projects created after 28 July 2020 are restricted to private viewing until the project passes a compliance audit. Check Google's current wording before you rely on public uploads.

The daily quota, in plain numbers

Every API project gets a default of 10,000 units a day. One upload costs 1,600.

10,000 ÷ 1,600 = 6.25  →  6 uploads a day

That is why PurffleShorts defaults to YT_DAILY_LIMIT=6. It can render more than that; extra videos wait in a queue and upload after the quota resets at midnight Pacific time. On autopilot the queue is drained first, and production waits instead of piling up.

Release on a schedule

Instead of publishing the moment a render finishes, give it time slots:

PUBLISH_TIMES=09:00,14:00,19:00
TIMEZONE=Asia/Kolkata

Each video is uploaded as private and scheduled into the next free slot. Render a week in one sitting, review it, and let it release on its own. For a one-off, YT_PRIVACY accepts public, unlisted or private.

Metadata and cross-posting

Title, description, hashtags, tags and category are written by the AI in the same call as the script.
SYNTHETIC_MEDIA=true sets YouTube's altered or synthetic content disclosure. MADE_FOR_KIDS and PLAYLIST_ID are set too.
Each video's folder holds short.mp4, cover.jpg, captions.srt, script.json and metadata.json — ready to post to TikTok or Reels by hand. Auto-upload is YouTube only.
Several channels: one settings file each, run with --env-file .env.channel2.

Troubleshooting

What you see	Why	Fix
Videos stay `queued`	The day's quota is used up.	They upload after midnight Pacific. `upload --pending` retries now.
Sign-in stops working after a week	OAuth app still in Testing status.	Run `auth` again, or publish the consent screen.
Uploads stay private	Unverified API project.	Apply for the YouTube API compliance audit.
Not sure what is wrong		Run `doctor` — it checks the YouTube setup along with everything else.

python -m purffle_shorts history lists everything made so far, with links.