youtubepro README

The project's README from github.com/AgriciDaniel/youtubepro. As one markdown file: README.md.

YouTube Pro logo

YouTube Pro

Research, understand, write, and package a YouTube video in one local-first workflow.

YouTube Pro is an evidence-grounded workspace for YouTube research, idea selection, script writing, and thumbnail creation. It combines public YouTube Data API v3 records with Gemini analysis while keeping API keys on the server.

YouTube Pro is an independent project. It is not affiliated with, endorsed by, or sponsored by YouTube or Google. YouTube and Google product names are trademarks of their respective owners.

Product tour

Research analytics

Search a topic, inspect the returned public-data snapshot, compare momentum and publication patterns, review data coverage, and continue into AI-assisted insights and ideas.

YouTube Pro research analytics with video performance, momentum, duration, and publication graphs

Source videos

Review every video included in the active public-data snapshot, with thumbnails, channel information, views, publication timing, likes, and comments visible in one grid.

YouTube Pro source-video grid showing every video used in the research snapshot

AI Insights

Turn the active snapshot into a scan-first research brief with audience questions, opportunity themes, recommended moves, and a clear separation between observed evidence, inference, and metrics that require YouTube Studio.

YouTube Pro AI Insights with visual summaries, evidence balance, and an expandable evidence ledger

Script teleprompter

Turn a selected idea into an editable script, then read it in a focused teleprompter with pace, size, cue, undo, and playback controls.

YouTube Pro teleprompter with playback and reading controls

Thumbnail Creator

Describe the outcome once, add optional references or advanced controls, generate a readable 16:9 thumbnail, and create variations from the same workflow.

YouTube Pro Thumbnail Creator with a generated thumbnail preview and minimal creation controls

These screenshots come from a live local development build using public YouTube metadata. They are not generated interface mockups.

Workflow

The product follows one continuous workflow:

  1. Research: Search up to 50 public YouTube videos, review the overview, analytics, coverage, and every returned video.
  2. AI Insights: Gemini analyzes the exact active research snapshot. Claims retain their snapshot identity and source video IDs, or are explicitly labeled as aggregate inference or as requiring YouTube Studio.
  3. Grounded Ideas: Ideas generate automatically after valid Insights. Select one idea, then explicitly proceed to Script Writer.
  4. Script Writer: Generate and edit a script from the selected idea package and its evidence. Section and paragraph regeneration use the same bounded evidence context.
  5. Thumbnail Creator: Use the selected promise and thumbnail concept, outcome-oriented presets, editable controls, and up to three permitted references.

There is no standalone Ideas screen. The legacy /ideas path redirects to the Ideas section inside Research.

Each press of New Workflow creates a separate local project. The sidebar keeps the eight most recent workflows in browser IndexedDB, lets the user rename or delete them, and reopens the last active Research, Script, or Thumbnail step. Research snapshots, generated ideas, editable scripts, thumbnail briefs, and generated thumbnail results are restored together. Uploaded reference images are intentionally not retained, so permission and file selection are fresh for every later generation.

Requirements

Copy the example configuration and fill it locally:

cp .env.example .env
npm install
npm run dev

The server listens on 127.0.0.1:5000 by default. Open http://127.0.0.1:5000.

You can instead start without keys and enter them in Settings. Settings writes replacements to the ignored .env file with owner-only permissions. Saved values are never returned to the browser. Settings accepts direct loopback, same-origin requests only and rejects normal forwarded or reverse-proxy requests.

Configuration

Variable Purpose Default
YOUTUBE_API_KEY YouTube Data API v3 search and enrichment Required for Research
GEMINI_API_KEY Gemini text and image generation Required for AI features
GEMINI_TEXT_MODEL Research, Ideas, Script, and regeneration model gemini-3.7-flash
GEMINI_IMAGE_MODEL Thumbnail generation model gemini-3.1-flash-image
PORT Local HTTP port 5000
HOST Bind address 127.0.0.1

The Settings page exposes the server allowlist and its current descriptions. Models are not hardcoded by the client. Changing the allowlist in server/gemini-models.ts changes the available Settings options.

Data and request limits

Privacy and access model

Gemini image outputs include Google's invisible SynthID provenance. The application does not add a visible watermark and does not claim SynthID can be disabled.

Commands

npm run dev       # development server
npm test          # contract and provider-behavior tests
npm run check     # TypeScript check
npm run build     # production client and server build
npm start         # run the production build

Continuous integration runs the test suite, TypeScript check, and production build on every pull request and push to main.

Technology

Quotas and costs

YouTube search is quota-expensive compared with video and channel enrichment. Gemini limits and pricing vary by model and account. Check the current official documentation before changing models or making the server remotely accessible:

License

YouTube Pro is open source under the Apache License 2.0.

Contributing and security

See CONTRIBUTING.md for the local quality gate. Report security issues privately according to SECURITY.md, never in a public issue.

youtubepro (AgriciDaniel/youtubepro)

express
Searching Database…

421 ·GitHub
Youtubepro
What is this?YouTube Pro is a local-first workspace that combines public YouTube Data API v3 records with Gemini AI analysis to help you research topics, get grounded content ideas, write scripts, and generate thumbnails for a YouTube video.
Is this a hosted web app or something I run myself locally?It is a self-hosted Node.js/Express server with a React frontend that you run on your own machine; by default it only binds to localhost and is not offered as a cloud SaaS.
How do I get it running?You need Node.js 22.12 or newer, then copy the example configuration file locally and fill in your keys (or leave them blank and add them later in Settings) before starting the server, which listens on 127.0.0.1:5000.
Do I need my own YouTube and Gemini API keys?Yes, a YouTube Data API v3 key is required for Research and a Gemini API key is required for Insights, Ideas, Script Writer, and Thumbnail Creator; you can start without keys and enter them later in Settings.
Are there any usage limits I should know about?Research searches are capped at 50 videos and 200-character queries, thumbnail references are limited to three images under 5MB each, and billable YouTube/Gemini routes are throttled to 10 requests per client per 60 seconds since this is a single-process local server.
Where does my data and API keys actually go?API keys are written server-side into a gitignored .env file with owner-only permissions and are never returned to the browser; recent workflow history lives only in your browser's IndexedDB and request/response bodies are never logged.
How does the research-to-thumbnail workflow actually flow?You search up to 50 public videos, Gemini turns that exact snapshot into an Insights brief, Grounded Ideas are generated from valid Insights, one idea becomes an editable Script, and the same selected idea and evidence feed the Thumbnail Creator. Each 'New Workflow' click starts a fresh local project kept in the sidebar's recent history.
Why self-host instead of using a cloud SaaS version?Keeping everything local-first means API keys and history never leave your machine; the Settings page only accepts direct loopback requests, and the README explicitly warns against exposing the server to the internet without adding your own authentication and rate limiting.
Does the AI just make things up about my videos?No, Gemini Insights are scoped to the exact active research snapshot, and every claim is labeled as observed evidence, aggregate inference, or something that would require YouTube Studio to confirm, so speculative claims are explicitly separated from facts.
Do the generated thumbnails carry any watermark?Gemini image outputs include Google's invisible SynthID provenance marker; the app does not add a visible watermark and does not claim SynthID can be disabled.
What are similar projects?printfilm, ace-step-ui, gpt_image_playground, waoowaoo, moyin-creator, rankme.fast, empire, OpenStock
Which topics is it in?shadcn-ui, express, youtube, content-creation, tailwindcss, vite, image-generation, gemini, generative-ai, local-first, web-app, research
Creator
AgriciDaniel
Size
3.9 MB
Stars
421
Updated
CommitAug 27Releasev1.0.0Aug 24
Age
1mo
Commits · 90 Days