From 750329b34337157d85698088b5f0ed92b7ca3844 Mon Sep 17 00:00:00 2001 From: darkzOGx Date: Tue, 20 Oct 2026 00:25:39 -0500 Subject: [PATCH] docs: rewrite README as a landing page and move deep guides to docs/ - Lead with what the project does, why it is different, and a Quick start; release notes now live only in CHANGELOG.md. - Add the missing `npx playwright install chromium` step (npm install does not download it, and the slideshow renderer needs it) and the OAuth test-user step behind 403 access_denied sign-ins. - Correct the media fallback description, the extension examples (real provider presets instead of an uninstalled SDK and a nonexistent contentTypes object), the project structure, the schedule, and the troubleshooting table, which now covers the issues raised in Discussions. - Move the feature walkthroughs to docs/features.md and the API examples plus a full route reference to docs/api.md. Co-Authored-By: Claude Opus 5.5 --- README.md | 663 +++++++++++++---------------------------------- docs/api.md | 182 +++++++++++++ docs/features.md | 155 +++++++++++ 3 files changed, 511 insertions(+), 489 deletions(-) create mode 100644 docs/api.md create mode 100644 docs/features.md diff --git a/README.md b/README.md index b01256b6..92f5d8bf 100644 --- a/README.md +++ b/README.md @@ -1,199 +1,60 @@ # YouTube Automation Agent -**The open-source AI agent that runs a YouTube channel end to end.** +**The open-source AI agent that runs a YouTube channel end to end, with you approving every video before it goes out.** -Research topics → write scripts → generate narration and visuals → assemble videos → optimize metadata → review → schedule → publish → learn from analytics and from what your audience says. +It researches topics, writes scripts, generates narration and visuals, assembles real MP4s, writes titles, descriptions and tags, schedules approved videos, and learns from analytics and from what your audience says. It runs on your own machine with your own API keys. [![CI](https://github.com/darkzOGx/youtube-automation-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/darkzOGx/youtube-automation-agent/actions/workflows/ci.yml) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) -[![Node.js 18+](https://img.shields.io/badge/node-18%2B-43853d.svg)](package.json) +[![Node.js 18.17+](https://img.shields.io/badge/node-18.17%2B-43853d.svg)](package.json) -## What's new on master +**Latest release:** v2.11.0 (October 13, 2026). See the [changelog](CHANGELOG.md) for release notes and what has landed on `master` since. -- **v2.11.0 (October 13, 2026):** Gemini thinking models now pass the readiness check, image-generation failures explain exactly what to fix, Analytics shows whole-channel YouTube statistics (including videos published outside YouTube Automation Agent), and the dashboard listens on this machine only by default. Set `HOST=0.0.0.0` together with `API_KEY` if you open it from other devices. See the [changelog](CHANGELOG.md). -- **v2.10.0 is now on master:** DarkzSEO discoverability audits, controlled growth experiments, and outcome-aware channel operation are available together in the approval-first workflow. - -### September 21, 2026 reliability hotfixes - -The latest production fixes are included in [`124a1ed`](https://github.com/darkzOGx/youtube-automation-agent/commit/124a1ed18e474878d5829812dd632e579adbd860) and [`d52b40d`](https://github.com/darkzOGx/youtube-automation-agent/commit/d52b40d94a007caf5e7f256378c0265ddcf09d2b): - -- **DarkzSEO works without Python:** the bundled advisory audit is now the default. YouTube Automation Agent no longer auto-selects sibling Python checkouts, and a missing or broken explicitly configured external runtime falls back to the bundled audit instead of reporting `No module named darkzseo`. -- **Narration repairs keep correct timing:** regenerated narration updates the scene duration from the replacement audio, preventing stale timing and long silent gaps after a rebuild. -- **Cleaner spoken narration:** internal CTA metadata and bracketed placeholders are excluded from speech, including placeholders that appear in the middle of a line. -- **Configured visual styles are respected:** scene generation and repair prompts no longer force the `ethereal` style when the channel uses another visual direction. -- **Complete scheduling controls:** Review Studio can reschedule a production, publish it now, or delete its schedule without deleting the generated content. Immediate uploads also use the correct YouTube publishing metadata. -- **Reliable desktop YouTube authorization:** OAuth uses the exact dynamically selected loopback address and port, while legacy hardcoded callback settings are normalized automatically. -- **Null-safe content generation:** a missing `strategyContext` no longer crashes content generation while reading its angle or keywords. - -These paths are covered by the 46-test system suite. Existing safety gates still block simulated video, missing narration, unresolved factual claims, and unconfirmed media rights from publishing. - -## What's new in v2.10.0 - -**YouTube Automation Agent now has a discoverability adapter layer.** v2.10.0 connects the production pipeline to DarkzSEO without merging the projects or weakening human review, then adds the evidence needed to prove what packaging and strategy actually work: - -- **DarkzSEO Discoverability Preflight:** send a canonical content package—not the private dashboard—through versioned GEO, AIO, AEO, and web-search checks after metadata and provenance are assembled. -- **Reviewable evidence:** persist stable rule IDs, severity, engine/schema identity, fingerprints, and operator decisions in SQLite. Keep a finding actionable or dismiss a false positive with a reason that carries into matching future audits. -- **Safe local adapter boundary:** run the bundled content checks without Python; optional external DarkzSEO checkouts still use JSON-only stdin/stdout without a shell or inherited API secrets. -- **Controlled Growth Experiments Studio:** rotate only approved title/thumbnail arms, measure real interval evidence, restore the control, and require a separate decision before adopting a winner. -- **Outcome & ROI Studio:** align the operator with a measurable KPI, target window, budget, and available revenue/cost evidence without converting missing economics into false zeroes. -- **Platform-ready foundation:** audits already retain their target platform, providing the durable contract for planned TikTok and Instagram/Reels publishing and analytics adapters. + -The content preflight works out of the box. Set `DARKZSEO_PATH` only when developing against a separate DarkzSEO 1.4+ checkout. If that optional external runtime is missing or broken, YouTube Automation Agent automatically uses the bundled audit. +## Why it's different -See the complete release history in [CHANGELOG.md](CHANGELOG.md). +- **You approve before anything is published.** Finished videos wait for fact review, media-rights confirmation, and your approval. Turning on autonomy doesn't skip those checks. +- **Real output only.** Simulated or placeholder media is clearly marked and can never be approved or uploaded. +- **Self-hosted.** Your keys, media, and channel data stay on your machine. +- **Learns from evidence, with your sign-off.** Lessons from analytics, retention curves, and comments shape future videos only after you approve them. +- **Your choice of providers.** Eight text providers or OpenRouter, five AI video providers, or free local slideshow rendering. -- **Self-hosted:** your credentials, media, and channel data stay under your control. -- **Approval-first:** nothing is scheduled until quality, rights, and human-review gates pass by default. -- **Strategy-driven:** give the Autonomous Channel Operator an objective, audience, pillars, cadence, and guardrails; it turns them into researched content plans and production runs. -- **Provider-flexible:** use Gemini, OpenAI, OpenRouter, Kimi, MiMo, GLM, DeepSeek, or MiniMax for text, plus Seedance, MiniMax H3, Gemini Omni Flash, Kling, Wan, or local FFmpeg for video. -- **Observable:** follow persistent generation jobs, failures, review state, publishing, and local activation milestones from the dashboard. +## Quick start - +You need: -## Quick start +- Node.js 18.17 or newer +- A Google account and YouTube Data API credentials ([setup steps](#youtube-required-free)) +- An API key for at least one [text provider](#text). Gemini has free tiers for text and narration. ```bash git clone https://github.com/darkzOGx/youtube-automation-agent.git cd youtube-automation-agent npm install +npx playwright install chromium # renders slideshow videos; on Linux add --with-deps npm run walkthrough npm start ``` -Open `http://localhost:3456`. The walkthrough explains each provider choice, tests credentials, and guides YouTube authorization. - -Already know what you are doing? `npm run setup` offers a shorter classic flow, and `.env.example` documents every setting. - -### Verify production readiness - -Before activating autonomous production, open **Production readiness** in the dashboard and choose **Run verified check**. The gate makes small live text and narration requests, verifies access to the connected YouTube channel, creates and decodes a temporary MP4 containing audio and video, and validates every queued upload's metadata. It never creates or uploads a YouTube video, and temporary probe assets are deleted after the run. - -AI image generation can incur a larger provider charge, so its live probe is a separate opt-in checkbox. Without that checkbox, image configuration is reported as verified, skipped, or using the built-in gradient fallback without making a paid image request. - -AI video verification has its own **Include paid video probe** checkbox. When enabled, YouTube Automation Agent creates the provider's shortest supported test clip, records the external task and model, downloads and decodes the MP4, then removes the temporary asset. It never silently tries a second paid provider. - -Results persist locally in SQLite with exact remediation steps. A recorded blocking failure stops autonomous generation and publishing until a later run passes; manual work remains available when readiness has never been checked or the last result is older than 24 hours. - -### Resume an interrupted production - -Every generation stage writes a local SQLite checkpoint. If a provider times out or the application restarts, the dashboard shows the saved-stage count and the first incomplete stage. Choose **Resume** to continue from there, or select an earlier stage when you intentionally want to regenerate that stage and everything after it. Saved files are validated before reuse; missing artifacts are regenerated automatically. - -Autonomous Operator runs preserve their research and editorial plan, so **Resume run** continues unfinished plan items instead of researching and generating completed videos again. Publishing remains fail-closed: if an upload may have reached YouTube but no video ID was returned, YouTube Automation Agent requires channel reconciliation before another upload attempt. +Then open `http://localhost:3456`. -### Repair one scene without starting over +1. **`npm run walkthrough`** explains each provider choice, tests your keys, and connects your YouTube channel. For a shorter flow, use `npm run setup`. Every setting is documented in [`.env.example`](.env.example). +2. **Check readiness.** In the dashboard, open **Production readiness** and choose **Run verified check**. It makes small live text and narration requests, checks access to your channel, and builds and decodes a test MP4, without uploading anything. +3. **Make videos.** Open **Autonomous operator**, describe the channel you want, and choose **Activate & run now**, or create a single video from the dashboard. Finished videos wait in **Pipeline** for your review and approval. -Every production now keeps a durable scene manifest with its narration, visual prompt, timing, provider/task identity, asset origin, rights state, evidence links, and revision history. Open **Scene Repair Studio** inside Review Studio to edit a scene, change its order, lock a scene that already works, upload a licensed replacement asset, or regenerate only that scene. - -Paid video regeneration always shows the provider and generated seconds and requires a separate confirmation. Uploaded assets require an explicit rights confirmation. Narration edits invalidate that scene's audio and factual review; live narration must be regenerated and any new factual claim must be reviewed against verified evidence before approval. - -Narration is fail-closed. YouTube Automation Agent records the TTS provider, model, external task when available, generation time, cost evidence, and failure reason for every scene. If narration is missing, simulated, stale, or failed, the production cannot be approved, scheduled, or published. Use **Regenerate narration only** to repair the audio without spending video-generation credits or replacing a visual. - -An intentionally silent production requires a separate operator confirmation and a stored reason of at least 10 characters. The override remains visible in Review Studio, can be reversed, and is included in the narration revision history. Silence is never inferred from a failed provider call. - -When the timeline is ready, **Rebuild final video** creates a new MP4 and scene-aware captions while preserving the previous final video path in the production record. Approval stays blocked while any scene is missing, generating, stale, failed, or waiting for rebuild. Approved or scheduled productions are locked against scene repair. - -### Repurpose an approved video into Shorts - -Open **Shorts Repurposing Studio** inside Review Studio and choose **Create 3 Short drafts**. YouTube Automation Agent selects self-contained windows from the durable scene timeline and preserves the exact source-scene IDs, start time, duration, rationale, title, description, tags, layout, and inherited review evidence for each candidate. Draft selection is local and does not call an AI provider. - -Choose a blurred-canvas, center-crop, or stacked-focus layout, then render a real 9:16 MP4 with mobile-safe burned captions and a separate SRT file. The source video and narration are reused, so the default workflow does not spend new image, video, or TTS credits. Changing the layout invalidates the prior render and requires a fresh local render. - -Every Short has its own approval and schedule. Scheduling remains blocked until the source production is approved, provenance is resolved, uploaded media rights are confirmed, every source scene is current, and the operator explicitly confirms the Short's privacy and publish time. Published Shorts retain their parent-production identity while their analytics use a separate Shorts baseline. - -### Review research and provenance - -Every production has an **Evidence desk** inside Review Studio. Autonomous research carries exact YouTube source metadata into the production, while AI-generated scripts list the factual claims that need review. Add any official articles, datasets, asset licenses, or other evidence that the script needs, verify each source, and connect it to the claims it supports. - -A claim can be approved only when it links to a verified source. Unsupported claims remain blocking, and an intentional waiver requires a reviewer note. Productions with no externally verifiable factual claims are marked as not requiring provenance review. The separate factual-review and media-rights attestations remain required before scheduling. - -Use the altered or synthetic media control only when the video contains realistic content that requires YouTube disclosure. The selected value is preserved in the publishing queue and included in the YouTube upload request. - -### Review discoverability guidance - -Every saved production receives an optional **DarkzSEO Discoverability Preflight** in Review Studio after metadata and provenance are assembled. The bundled content auditor reviews a canonical content package—not the private dashboard—and stores the engine version, schema version, severity summary, stable rule IDs, and individual findings in SQLite. - -Findings are advisory in this release. Keep a useful recommendation as actionable, or dismiss a false positive with a reviewer reason that carries forward to matching findings on later audits. The bundled audit requires no Python package and never silently changes scripts or metadata. - -To test a separate DarkzSEO 1.4+ checkout instead of the bundled auditor: - -```bash -DARKZSEO_PATH=../darkzseo/darkzseo.py npm start -``` +FFmpeg is installed with `npm install` through `ffmpeg-static`. Python is only needed to test an external DarkzSEO checkout. -The optional external adapter uses a shell-free Python child process, sends content JSON over stdin, and reads JSON-only stdout. The public PyPI `darkzseo` 1.3.3 package has a different site-audit CLI and is not used by YouTube Automation Agent. +## How it works -### What you need - -- Node.js 18+ -- A Google account and YouTube Data API credentials -- At least one AI text provider key -- FFmpeg, installed automatically through `ffmpeg-static` -- Python 3.9+ only when explicitly testing an external DarkzSEO checkout - -Gemini offers free access for supported text and TTS usage. Gemini AI image generation currently requires paid-tier access; without an image provider, YouTube Automation Agent can assemble gradient-based visuals instead. - -### Run the Autonomous Channel Operator - -Open **Autonomous operator** in the dashboard and describe the channel outcome—not a task list. Set the objective, audience, content pillars, publishing cadence, success metric, and boundaries, then choose **Activate & run now**. - -YouTube Automation Agent refreshes YouTube trend and configured-competitor signals, checks recent channel topics, creates an evidence-labeled editorial plan, and sends each planned video through strategy, script, thumbnail, SEO, production, and workflow management. Active strategies also guide scheduled generation at the requested weekly cadence. Operator runs, decisions, progress, and failures persist in SQLite and remain visible in the dashboard. - -By default, finished videos wait for factual review, media-rights confirmation, and approval. Once approved, the existing publishing agent schedules and uploads them. Turning on autonomy does not bypass those gates, and simulated videos still cannot publish. - -### Close the performance loop - -After publication, YouTube Automation Agent captures comparable 24-hour and 7-day performance snapshots. It evaluates CTR, retention, engagement, watch time, format, length, hook style, and title style against the channel's own history—not a universal view-count target. - -Open **Analytics → What the agent learned** to review the evidence and confidence behind each recommendation. Pending or rejected recommendations never influence generation. Once you approve one, the next Autonomous Channel Operator run includes it as an explicit planning constraint. Simulated analytics fallbacks are stored as unverified and are never eligible for baselines or recommendations. - -When an approved learning calls for better packaging, YouTube Automation Agent prepares a control plus title and thumbnail variants for new videos. Review Studio shows those options before approval; the selected combination is the only one handed to the publishing queue. YouTube Automation Agent does not silently swap live YouTube metadata. - -### Prove a growth recommendation - -Open **Analytics → Controlled Growth Experiments** after a video with approved-learning packaging variants is published. Create a draft plan with a 24–168 hour window per arm and a minimum-impressions threshold, review the exact title and thumbnail combinations, then separately approve and start the live test. - -YouTube Automation Agent records a cumulative analytics sample before and after each arm and evaluates only the interval delta. Every arm must reach the configured impression and click floor. The leading CTR must clear a 95% evidence threshold without a material retention regression or traffic-source shift; otherwise the result is explicitly **inconclusive**. Simulated analytics never advance an experiment. - -Arm rotations are limited to the plan you approved. After the final arm, YouTube Automation Agent restores the control title and thumbnail before presenting the result. Applying the winner is a separate confirmation; only then does the validated packaging pattern become an approved learning for future Autonomous Operator runs. Experiment state and evidence are stored in SQLite so restarts do not erase progress. - -### Align the channel with outcomes and ROI - -The Autonomous Operator strategy can define a measurable primary outcome—views, watch hours, net subscribers, engagement rate, or estimated revenue—plus a numeric target, evidence window, monthly production budget, and currency. The existing free-text outcome context remains available for goals that need human nuance. - -At each real analytics window, YouTube Automation Agent stores subscriber gains and losses, watch hours, monetization evidence when the channel exposes it, and known production costs from durable scene records. **Analytics → Outcome & ROI Studio** shows target progress, evidence coverage, net subscribers, estimated revenue, known cost, ROI, and comparisons by content pillar, format, and production provider. - -Missing evidence is explicit. A channel without monetization access shows revenue as unavailable rather than zero, and ROI stays unavailable until both revenue and complete cost evidence exist. When at least two comparable videos exist in each group, the learning engine can propose reallocating future content toward the pillar or format that best advances the configured outcome. That proposal remains pending until you approve it; YouTube Automation Agent never changes the strategy or budget silently. - -### Find the exact scene that lost viewers - -At each real analytics window, YouTube Automation Agent also requests YouTube's audience-retention curve and maps its 100 elapsed-time points onto the stored scene durations. Open **Analytics → Scene-aware retention** to see the curve divided by scene, compare absolute and relative retention, and inspect drop-off, rewatch, strong-hold, or steady signals for each beat. - -Retention snapshots are stored separately for long-form videos and Shorts. Missing, sparse, or simulated curves never enter this evidence layer. A scene finding creates a pending learning recommendation; it cannot guide future scripts, pacing, or scene structure until the operator approves it, and YouTube Automation Agent never rewrites a published video. Use **Refresh curve** for a read-only update from YouTube Analytics, or `GET /api/retention/:videoId` to inspect stored evidence. - -### Engage with your audience - -Open **Engagement** in the dashboard. YouTube Automation Agent syncs comments for recently published videos every four hours (more often for fresh videos) and classifies them into themes, sentiment, and questions. Likely spam, scams, and toxic comments are quarantined into a separate needs-attention list — YouTube Automation Agent never deletes or hides a comment; acting on flagged comments stays in YouTube Studio. - -Choose **Draft replies** to generate suggested answers in your channel's voice. Nothing posts automatically: every reply waits in the queue where you can edit, discard, or approve it, and approval requires an explicit confirmation. Posting requires re-authorizing YouTube once to grant the comment permission (`youtube.force-ssl`); until then the studio works in read-and-draft mode. A daily posting cap (default 50, `ENGAGEMENT_DAILY_REPLY_CAP`) keeps approval sessions bounded. - -When three or more commenters ask for the same thing, the analysis mines an **audience-requested idea** with comment permalinks as evidence. Like every other learning, it stays pending until you approve it — only then can the Autonomous Channel Operator plan a video that answers it. If no AI text provider is configured, comment sync still works, but the studio records only mechanical facts and never invents themes, drafts, or ideas. - -## From idea to published video - -| Stage | What YouTube Automation Agent does | What you control | +| Stage | What the agent does | What you control | | --- | --- | --- | | Research | Finds topics and builds a content strategy | Niche, audience, blocked topics | | Script | Writes the hook, narrative, CTA, and metadata | Voice, format, length, brand direction | | Production | Generates narration and visuals, then assembles a real MP4 | Provider choice and media fallbacks | -| Review | Runs quality checks and opens the video in Review Studio | Facts, media rights, edits, approval | +| Review | Runs quality checks and opens the video for review | Facts, media rights, edits, approval | | Publish | Schedules and uploads approved content | Privacy, timing, final decision | -| Learn | Captures 24-hour and 7-day evidence, measures the configured outcome and economics, then proposes the next move | Choose the KPI and approve or reject each learning before it guides planning | - -YouTube Automation Agent distinguishes real MP4 output from simulated placeholders. Simulated output cannot enter the approval or publishing path. - -For release history, see [CHANGELOG.md](CHANGELOG.md). - -## Architecture +| Learn | Captures 24-hour and 7-day evidence, measures your chosen outcome, then proposes the next move | Choose the KPI and approve or reject each lesson | ```mermaid graph TD @@ -211,375 +72,208 @@ graph TD I -->|feedback loop| A ``` -## How It Works +## Features -Each agent handles one stage of the pipeline: +Each item links to its walkthrough in the [feature guide](docs/features.md). -| Agent | Role | -|-------|------| -| **Content Strategy** | Analyzes YouTube trends, identifies topics, plans content calendar | -| **Script Writer** | Generates scripts with hooks, storytelling, CTAs | -| **Thumbnail Designer** | Creates thumbnails, runs A/B variations | -| **SEO Optimizer** | Keywords, titles, descriptions, tags | -| **Production** | Coordinates TTS audio, image assets, video assembly | -| **Discoverability** | Runs versioned, advisory GEO/AIO/AEO content audits through DarkzSEO | -| **Publishing** | Uploads, schedules, manages playlists | -| **Analytics** | Tracks performance, feeds insights back to strategy | +**Plan** +- [Autonomous Channel Operator](docs/features.md#autonomous-channel-operator): give it an objective, audience, content pillars, cadence, and limits. It researches trends and competitors, builds an evidence-labeled plan, and sends each video through production. +- [Outcome & ROI Studio](docs/features.md#outcome--roi-studio): set a target (views, watch hours, net subscribers, engagement, or revenue) and a budget, and track progress. Missing data shows as unavailable, never as zero. -## AI Providers +**Produce** +- [Production readiness](docs/features.md#production-readiness): a verified check of every provider, your channel, and video assembly before anything runs on its own. Paid image and video probes are separate opt-ins. +- [Resumable generation](docs/features.md#resumable-generation): every stage is checkpointed, so a crash or timeout resumes where it stopped instead of starting over. +- [AI video generation](docs/features.md#ai-video-generation): local slideshow by default; Seedance, MiniMax H3, Gemini Omni, Kling, or Wan for real clips, with a cap on paid seconds. +- [Shorts Repurposing Studio](docs/features.md#shorts-repurposing-studio): turn an approved video into three 9:16 Short drafts with burned-in captions, reusing existing media so no new generation credits are spent. -Every text provider below works out of the box — the system sets the SDK base URL for you. Pick one, or use OpenRouter to access everything through a single key. +**Review** +- **Content review:** quality checks, metadata editing, approval, and scheduling for each video. +- [Scene Repair Studio](docs/features.md#scene-repair-studio-and-narration): edit, reorder, lock, replace, or regenerate a single scene, then rebuild the video. +- [Evidence desk](docs/features.md#evidence-desk): link each factual claim in the script to a verified source before approval. +- [Discoverability preflight](docs/features.md#discoverability-preflight): advisory search and AI-answer checks from a bundled DarkzSEO audit. No Python needed. -```mermaid -graph LR - subgraph Direct - OA[OpenAI
GPT-6 family] - GM[Gemini
3.8 Flash / 4 Argon] - KM[Kimi
K3] - MM[MiMo
V2.6 Pro] - GL[GLM
GLM-5.3] - DS[DeepSeek
V4.1 Flash] - MX[MiniMax
M3.1 Flash] - end - subgraph Router - OR[OpenRouter
400+ models] - end - Direct --> YAA[YouTube Automation Agent] - Router --> YAA -``` +**Learn** +- [Learning loop](docs/features.md#learning-loop): compares each video's 24-hour and 7-day results with your channel's own history and proposes changes for you to approve. +- [Controlled growth experiments](docs/features.md#controlled-growth-experiments): test approved title and thumbnail variants on a live video. A winner needs a 95% evidence threshold, and the original is restored before you decide. +- [Scene-aware retention](docs/features.md#scene-aware-retention): see which scene lost viewers. -| Provider | Models | Base URL | Cost | -|----------|--------|----------|------| -| **OpenAI** | GPT-6.1 Sol, GPT-6 Astra, GPT-6 Luna | `api.openai.com/v1` | provider pricing | -| **OpenRouter** | 400+ models; curated defaults are validated against its live catalog | `openrouter.ai/api/v1` | varies by model | -| **Google Gemini** | Gemini 3.8 Flash, Gemini 4 Argon, 3.5 Flash-Lite | via `@google/genai` SDK | free tiers vary by model and modality; Gemini 4 Argon is paid only | -| **Kimi (Moonshot AI)** | Kimi K3, K2.7 Code, K2.6 | `api.moonshot.ai/v1` | provider pricing | -| **MiMo (Xiaomi)** | MiMo V2.6 Pro, V2.6 Flash | `api.xiaomimimo.com/v1` | provider pricing | -| **GLM (Zhipu AI)** | GLM-5.3, 5.3 Flash, 5.2 | `api.z.ai/api/paas/v4/` | provider pricing | -| **DeepSeek** | DeepSeek V4.1 Flash, V4 Pro | `api.deepseek.com` | provider pricing | -| **MiniMax** | MiniMax M3.1 Flash, M3 | `api.minimax.io/v1` | provider pricing | +**Engage** +- [Audience Engagement Studio](docs/features.md#audience-engagement-studio): comment sync, themes and questions, spam quarantine, reply drafts that post only after you approve them, and video ideas mined from repeated requests. -Additional integrations: ElevenLabs (Eleven v3 TTS), Replicate (Wan 2.7 video), and Anthropic Claude through OpenRouter (`anthropic/claude-fable-5.1`). To add another provider, see [Custom AI provider](#custom-ai-provider). +## AI providers -### AI video providers +### Text -Local slideshow rendering remains the default, so upgrading does not start paid video requests. Choose a provider in **Channel setup**, set a paid-seconds cap, then run the separately opted-in paid video readiness probe. +Pick one in the walkthrough, or set its key in `.env`. The SDK base URL is configured for you. -| Provider | Default model | Best fit | Clip limits | +| Provider | Models | Key | Env var | | --- | --- | --- | --- | -| ByteDance | `bytedance/seedance-2.5` through Replicate | Cinematic long scenes and large reference sets | 4–30 seconds | -| MiniMax | `MiniMax-H3` | Multimodal references, native stereo audio, optional 2K | 4–15 seconds | -| Google | `gemini-omni-1.1-flash` | Fast generation and conversational editing | 3–10 seconds | -| Kuaishou | `kling-v3-omni` | Storyboards and character/voice consistency | 3–15 seconds | -| Alibaba | Wan 2.7 task-specific models | Efficient generation, reference video, and continuation | 2–15 seconds | +| **Google Gemini** | Gemini 3.8 Flash, Gemini 4 Argon (paid only), 3.5 Flash-Lite | [AI Studio](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` | +| **OpenAI** | GPT-6.1 Sol, GPT-6 Astra, GPT-6 Luna | [platform.openai.com](https://platform.openai.com/api-keys) | `OPENAI_API_KEY` | +| **OpenRouter** | 400+ models through one key; curated defaults are checked against its live catalog | [openrouter.ai](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | +| **Kimi (Moonshot AI)** | Kimi K3, K2.7 Code, K2.6 | [platform.kimi.ai](https://platform.kimi.ai) | `MOONSHOT_API_KEY` | +| **MiMo (Xiaomi)** | MiMo V2.6 Pro, V2.6 Flash | [mimo.mi.com](https://mimo.mi.com) | `MIMO_API_KEY` | +| **GLM (Zhipu AI)** | GLM-5.3, 5.3 Flash, 5.2 | [z.ai](https://z.ai) | `GLM_API_KEY` | +| **DeepSeek** | DeepSeek V4.1 Flash, V4 Pro | [platform.deepseek.com](https://platform.deepseek.com/api_keys) | `DEEPSEEK_API_KEY` | +| **MiniMax** | MiniMax M3.1 Flash, M3 | [platform.minimax.io](https://platform.minimax.io/user-center/basic-information/interface-key) | `MINIMAX_TEXT_API_KEY` | -Long-form productions use hybrid assembly: YouTube Automation Agent generates bounded provider clips for the hook and important sections, fills the remaining timeline locally, mixes the existing narration, and keeps the generated caption file alongside the production. As soon as a provider returns its task ID, YouTube Automation Agent persists it before polling so interrupted jobs can resume that known task instead of submitting it again. - -## Configuration +Anthropic Claude is available through OpenRouter (`anthropic/claude-fable-5.1`). OpenRouter, Kimi, MiMo, GLM, DeepSeek, and MiniMax cover scripts only. Add a Gemini or OpenAI key for images and narration, or ElevenLabs for narration. -### API Keys +### Narration and images -#### YouTube Data API (required, free) +- **Narration** uses the first configured provider in this order: ElevenLabs (Eleven v3, needs `ELEVENLABS_API_KEY` and `ELEVENLABS_VOICE_ID`), OpenAI (`gpt-4o-mini-tts`), then Gemini (`gemini-3.8-flash-tts`). A video without working narration can't be approved. +- **Images** use OpenAI (GPT Image 2) and Gemini (`gemini-3.1-flash-image`, which needs billing enabled), each falling back to the other. With neither, slides use gradient backgrounds and thumbnails come from the built-in designer. -1. Create a project in [Google Cloud Console](https://console.cloud.google.com/) -2. Enable **YouTube Data API v3** -3. Create an OAuth 2.0 client (**Desktop app**, not Web application) -4. Save the JSON as `config/credentials.json`; YouTube Automation Agent uses its configured loopback redirect URI exactly +### Video -#### OpenAI +Local slideshow rendering is the default, so you never pay for video unless you choose a provider in **Channel setup** and set a paid-seconds cap. If a provider fails, the video falls back to the local slideshow. -1. Get a key from [platform.openai.com](https://platform.openai.com/) -2. Set `OPENAI_API_KEY` in `.env` +| Provider | Default model | Best fit | Clip limits | Env var | +| --- | --- | --- | --- | --- | +| ByteDance | `bytedance/seedance-2.5` through Replicate | Cinematic long scenes and large reference sets | 4–30 seconds | `REPLICATE_API_TOKEN` | +| MiniMax | `MiniMax-H3` | Multimodal references, native stereo audio, optional 2K | 4–15 seconds | `MINIMAX_API_KEY` | +| Google | `gemini-omni-1.1-flash` | Fast generation and conversational editing | 3–10 seconds | `GEMINI_API_KEY` | +| Kuaishou | `kling-v3-omni` | Storyboards and character/voice consistency | 3–15 seconds | `KLING_ACCESS_KEY`, `KLING_SECRET_KEY` | +| Alibaba | Wan 2.7 task-specific models | Efficient generation, reference video, and continuation | 2–15 seconds | `DASHSCOPE_API_KEY` | -#### OpenRouter (easiest — one key, all models) +Long videos use hybrid assembly: generated clips for the hook and key sections, with the rest of the timeline filled locally. See [AI video generation](docs/features.md#ai-video-generation). -1. Get a key from [openrouter.ai/keys](https://openrouter.ai/keys) -2. Set `OPENROUTER_API_KEY` in `.env` - -#### Google Gemini +## Configuration -1. Get a key from [Google AI Studio](https://aistudio.google.com/) -2. Set `GEMINI_API_KEY` in `.env` +### YouTube (required, free) -#### Kimi / MiMo / GLM / DeepSeek / MiniMax +1. Create a project in [Google Cloud Console](https://console.cloud.google.com/). +2. Enable **YouTube Data API v3**, and **YouTube Analytics API** for retention and outcome data. +3. Create an OAuth 2.0 client of type **Desktop app** (not Web application) and save the JSON as `config/credentials.json`. +4. Under **Google Auth Platform → Audience**, add the Google account that owns your channel as a **test user**. Otherwise sign-in fails with `Error 403: access_denied`. While the app is in Testing mode, Google expires the sign-in after 7 days. -| Provider | Get key at | Env var | -|----------|-----------|---------| -| Kimi (Moonshot AI) | [platform.kimi.ai](https://platform.kimi.ai) | `MOONSHOT_API_KEY` | -| MiMo (Xiaomi) | [mimo.mi.com](https://mimo.mi.com) | `MIMO_API_KEY` | -| GLM (Zhipu AI) | [z.ai](https://z.ai) | `GLM_API_KEY` | -| DeepSeek | [platform.deepseek.com](https://platform.deepseek.com/api_keys) | `DEEPSEEK_API_KEY` | -| MiniMax | [platform.minimax.io](https://platform.minimax.io/user-center/basic-information/interface-key) | `MINIMAX_TEXT_API_KEY` (`MINIMAX_API_KEY` is the H3 video key) | +### Environment variables -### Environment Variables +`npm run walkthrough` writes your configuration for you. To edit it by hand, copy [`.env.example`](.env.example) to `.env`; it documents every setting. The essentials: ```env -# AI provider — pick one (or use OpenRouter for access to all) -OPENAI_API_KEY=sk-... -# OPENROUTER_API_KEY=sk-or-... -# GEMINI_API_KEY=... -# MOONSHOT_API_KEY=... -# MIMO_API_KEY=... -# GLM_API_KEY=... -# DEEPSEEK_API_KEY=... -# MINIMAX_TEXT_API_KEY=... # MiniMax M3 text - -# Optional: premium TTS +# One text provider (see the table above) +GEMINI_API_KEY=... + +# Optional: narration, images, and AI video # ELEVENLABS_API_KEY=... # ELEVENLABS_VOICE_ID=... - -# Optional: AI video generation -# VIDEO_PROVIDER=slideshow # auto, seedance, minimax_h3, google_omni, kling, wan -# VIDEO_GENERATION_MODE=hybrid +# OPENAI_API_KEY=sk-... +# VIDEO_PROVIDER=slideshow # auto, seedance, minimax_h3, google_omni, kling, wan # VIDEO_MAX_GENERATED_SECONDS=60 -# REPLICATE_API_TOKEN=... # Seedance 2.5 -# MINIMAX_API_KEY=... # MiniMax H3 -# KLING_ACCESS_KEY=... -# KLING_SECRET_KEY=... -# DASHSCOPE_API_KEY=... # Wan 2.7 - -# App config -NODE_ENV=production + +# App PORT=3456 -# HOST=127.0.0.1 # default: this machine only; use 0.0.0.0 for LAN access (set API_KEY too) +# HOST=127.0.0.1 # default: this machine only +# API_KEY=some-long-random-string CHANNEL_NAME=Your Channel Name -TARGET_AUDIENCE=Your target audience -YOUTUBE_REGION=US DEFAULT_PRIVACY_STATUS=private - -# Optional recovery tuning (defaults shown) -MAX_CONCURRENT_JOBS=1 -GENERATION_STAGE_MAX_ATTEMPTS=2 -GENERATION_RETRY_BASE_MS=1000 - -# Optional: protect mutating API routes (POST /generate, /publish) -# API_KEY=some-long-random-string - -# Optional anonymous activation milestones (off by default; HTTPS endpoint required) -# ANONYMOUS_TELEMETRY_ENABLED=false -# ANONYMOUS_TELEMETRY_ENDPOINT=https://your-collector.example/events ``` -### Activation measurement and privacy - -The dashboard calculates setup, first-real-MP4, approval, publication, and repeat-generation milestones locally from SQLite and files on disk. A video counts only when a non-simulated `.mp4` with an MP4 container signature still exists. - -Anonymous milestone reporting is disabled by default and has no built-in collector. It activates only when you explicitly set both telemetry variables. The allowlisted payload contains the milestone name and time, YouTube Automation Agent version, OS family, Node major version, and a random installation ID. It never includes credentials, channel data, prompts, topics, titles, filenames, or video contents. - -## Automation Schedule - -```mermaid -gantt - title Daily Pipeline - dateFormat HH:mm - axisFormat %H:%M - - section Content - Generate content (strategy + script + thumbnail + SEO) :06:00, 2h +The dashboard listens on `127.0.0.1` by default. If you set `HOST=0.0.0.0` to reach it from other devices, also set `API_KEY`, which every request that changes something must then send in the `x-api-key` header. - section Publishing - Process publishing queue :crit, 08:00, 14h +## Automation - section Analytics - Collect analytics :09:00, 1h - Run optimizations :22:00, 1h -``` +The scheduler starts with `npm start` and uses the server's local time. -The scheduler runs automatically after `npm start`. Content generation at 06:00, publishing queue processed every 15 minutes, analytics at 09:00, optimization at 22:00. Weekly strategy reviews run on Sundays. +| When | What runs | +| --- | --- | +| Daily at 06:00 | Content generation, following the active channel strategy's cadence | +| Every 15 minutes | Publishing queue | +| Daily at 09:00 | Analytics collection | +| Daily at 22:00 | Optimization | +| Every 4 hours | Comment sync and growth-experiment refresh | +| Sundays at 08:00 | Weekly strategy review | -When an active channel strategy exists, the 06:00 generation check uses its cadence and launches an autonomous research-and-production run when the content buffer needs work. Without an active strategy, the original topic-selection flow remains in place. +Details are in the [feature guide](docs/features.md#automation-schedule). -Daily analytics collection backfills each real publication's 24-hour and 7-day evidence windows. Recommendations require at least two real measurements, and format or style comparisons require at least two videos in each compared group. +## HTTP API -## API +The dashboard server also exposes an HTTP API: ```bash -# health check curl http://localhost:3456/health -# queue a video-generation job (send x-api-key if API_KEY is set in .env) curl -X POST http://localhost:3456/generate \ -H "Content-Type: application/json" \ -H "x-api-key: $API_KEY" \ -d '{"topic": "Top 10 Life Hacks", "style": "list"}' -# inspect the returned background job curl http://localhost:3456/api/jobs/:jobId +``` -# resume a failed/interrupted job from its first incomplete checkpoint -curl -X POST http://localhost:3456/api/jobs/:jobId/resume \ - -H "Content-Type: application/json" \ - -H "x-api-key: $API_KEY" \ - -d '{}' - -# intentionally regenerate a selected stage and everything after it -curl -X POST http://localhost:3456/api/jobs/:jobId/resume \ - -H "Content-Type: application/json" \ - -H "x-api-key: $API_KEY" \ - -d '{"stage":"thumbnail"}' - -# inspect the latest production-readiness evidence -curl http://localhost:3456/api/readiness - -# run harmless live probes; add {"includePaidMedia":true} only to test paid image generation -curl -X POST http://localhost:3456/api/readiness/run \ - -H "Content-Type: application/json" \ - -H "x-api-key: $API_KEY" \ - -d '{"includePaidMedia":false}' - -# save a channel strategy -curl -X PUT http://localhost:3456/api/operator/strategy \ - -H "Content-Type: application/json" \ - -H "x-api-key: $API_KEY" \ - -d '{"objective":"Own practical AI automation for small teams","audience":"Small business operators","contentPillars":["AI workflows","Automation playbooks"],"cadencePerWeek":2,"videosPerRun":2,"defaultFormat":"tutorial","defaultLength":"medium","primaryKpi":"subscribers","targetValue":100,"targetWindowDays":28,"monthlyBudget":250,"outcomeCurrency":"USD","status":"draft"}' - -# activate the saved strategy and start a background operator run -curl -X POST http://localhost:3456/api/operator/start \ - -H "Content-Type: application/json" \ - -H "x-api-key: $API_KEY" \ - -d '{}' - -# resume an interrupted operator run from its saved plan -curl -X POST http://localhost:3456/api/operator/runs/:runId/resume \ - -H "x-api-key: $API_KEY" - -# view schedule -curl http://localhost:3456/schedule - -# get analytics -curl http://localhost:3456/analytics +See the [API reference](docs/api.md) for every route. -# get the goal-aligned Outcome & ROI Studio summary -curl http://localhost:3456/api/outcomes +## Troubleshooting -# approve an evidence-backed learning for future autonomous plans -curl -X POST http://localhost:3456/api/learning/recommendations/:recommendationId/approve \ - -H "x-api-key: $API_KEY" +| Problem | Fix | +| --- | --- | +| `Missing credentials for: an AI provider` | Configure any one text provider with `npm run walkthrough` or `npm run credentials:setup`. OpenAI isn't required. | +| Google sign-in shows `Error 403: access_denied` | Add your Google account as a test user under **Google Auth Platform → Audience**. | +| No video is produced, or it's marked simulated | Read the ✗ lines in the startup capability check. Make sure you ran `npx playwright install chromium` and that FFmpeg is available (`npm install` fetches it, or set `FFMPEG_PATH`). | +| Images or thumbnails are missing | Image generation needs OpenAI, or Gemini with billing enabled. The content review panel shows the provider's exact error. | +| Narration failed (for example, ElevenLabs HTTP 400) | Check the key, its credits, and that `ELEVENLABS_VOICE_ID` is a voice in your account, then use **Regenerate narration only**. | +| `Error loading sharp module` on Android/Termux | Update to the latest `master`, then run `rm -rf node_modules && npm install --cpu=wasm32`. | +| The publishing queue runs but nothing publishes | Approved videos publish at their scheduled time (default: the next day at 2 PM). | +| YouTube API quota exceeded | Check quotas in Google Cloud Console and reduce posting frequency. | +| Content generation failed | Check your keys and credits, the job's error in the dashboard, and `logs/`. | -# inspect controlled experiments and eligible published videos -curl http://localhost:3456/api/experiments +For debug logging, run `LOG_LEVEL=debug NODE_ENV=development npm start`. Questions and setup help go in [Discussions](https://github.com/darkzOGx/youtube-automation-agent/discussions). -# create and approve a packaging test plan (start/adopt are separate confirmed actions) -curl -X POST http://localhost:3456/api/experiments \ - -H "Content-Type: application/json" -H "x-api-key: $API_KEY" \ - -d '{"productionId":"production-id","armDurationHours":48,"minImpressions":1000}' -curl -X POST http://localhost:3456/api/experiments/:experimentId/approve \ - -H "Content-Type: application/json" -H "x-api-key: $API_KEY" \ - -d '{"confirmed":true}' +## Project structure -# inspect, edit, and approve content before scheduling -curl http://localhost:3456/api/content/:contentId -curl -X POST http://localhost:3456/api/content/:contentId/approve \ - -H "Content-Type: application/json" \ - -H "x-api-key: $API_KEY" \ - -d '{"privacyStatus":"private","factChecked":true,"rightsConfirmed":true}' ``` - -## Production Pipeline - -```mermaid -flowchart LR - subgraph TTS["Audio Generation"] - direction TB - EL[ElevenLabs v3] -.->|fallback| OA[OpenAI TTS] - OA -.->|fallback| SIM1[Simulation] - end - - subgraph IMG["Image Generation"] - direction TB - GPT[GPT Image 2] -.->|fallback| SIM2[Simulation] - end - - subgraph VID["Video Assembly"] - direction TB - WAN[Wan 2.7 I2V] -.->|fallback| PW[Playwright Slideshow] - PW -.->|fallback| SIM3[Simulation] - end - - TTS --> MIX[FFmpeg Mux] - IMG --> VID - VID --> MIX - MIX --> OUT[Final Video] +youtube-automation-agent/ +├── agents/ # one file per pipeline agent (strategy, script, thumbnail, SEO, production, publishing, analytics) +├── dashboard/ # web dashboard served by index.js +├── database/ # SQLite schema and access layer +├── schedules/ # cron-based automation +├── utils/ # AI text, media, and video providers; operator, readiness, engagement, and other services +├── config/ # credential files (examples are committed) +├── data/ # generated content and the local database +├── docs/ # feature guide, API reference, design notes +├── examples/ # verified real output from the community +├── index.js # Express server and agent startup +├── walkthrough.js # guided setup (npm run walkthrough) +├── setup.js # classic setup (npm run setup) +└── test.js # system test suite (npm test) ``` -Each stage has graceful fallbacks. If a paid API key isn't configured, the system simulates that step so the rest of the pipeline still runs. - ## Extending -### Custom AI provider - -```javascript -// utils/ai-service.js -const Anthropic = require('@anthropic-ai/sdk'); - -class ClaudeAIService { - constructor(apiKey) { - this.client = new Anthropic({ apiKey }); - } - async generateContent(prompt) { - const message = await this.client.messages.create({ - model: 'claude-fable-5-1', - max_tokens: 1024, - messages: [{ role: 'user', content: prompt }] - }); - return message.content[0].text; - } -} -``` +### Add a text provider -### Custom content types +Any provider with an OpenAI-compatible chat completions API can be added as a preset in `utils/ai-text-service.js`: ```javascript -// agents/content-strategy-agent.js -const contentTypes = { - 'podcast': { - duration: '10-15 minutes', - style: 'conversational', - thumbnail: 'podcast-style' - }, -}; +deepseek: { + name: 'DeepSeek', + baseURL: 'https://api.deepseek.com', + defaultModel: 'deepseek-flash', + models: ['deepseek-flash', 'deepseek-v4-pro'], + envKey: 'DEEPSEEK_API_KEY', +}, ``` -## Project Structure +Then add a matching entry to `AI_PROVIDER_GUIDE` in `walkthrough.js` and a setup option in `utils/credential-manager.js`, and run `npm test`. The walkthrough test fails if any provider is missing a complete guide. -``` -youtube-automation-agent/ -├── agents/ # one file per agent -├── config/ # credentials, example configs -├── database/ # SQLite schema and access layer -├── data/ # generated content and assets -├── schedules/ # cron-based automation -├── utils/ # AI services, autonomous operator, logging, credential management -├── .github/ # CI workflow (lint + tests on every push/PR) -└── index.js # Express server + agent initialization -``` +### Add a video provider -## Troubleshooting +Video providers live in `utils/video-providers.js`. Each one extends `VideoProvider`, implements `isAvailable`, `createTask`, `getTask`, and `downloadResult`, and is registered in `VideoProviderRegistry`. -| Problem | Fix | -|---------|-----| -| `Missing credentials for: an AI provider` | Configure any one provider with `npm run credentials:setup` — OpenAI is not required | -| `'ffmpeg' is not recognized` / no .mp4 produced | Run `npm install` (fetches the bundled binary), or install FFmpeg and set `FFMPEG_PATH` | -| Video marked `simulated`, nothing uploads | Check the ✗ lines in the startup capability check — a key or FFmpeg is missing | -| "Processing publish queue" but nothing publishes | The queue log now shows what's waiting; content publishes at its scheduled time (default: next day 2 PM) | -| YouTube API quota exceeded | Check quotas in Google Cloud Console; reduce posting frequency | -| Content generation failed | Verify API keys and credits; check `logs/` | -| Publishing failed | Re-authenticate YouTube OAuth tokens; check video format | +## Contributing -Enable debug logging: +See [CONTRIBUTING.md](CONTRIBUTING.md) for ground rules (short version: one focused concern per PR, no lockfile churn, lint and tests must pass). For questions and setup help, use [Discussions](https://github.com/darkzOGx/youtube-automation-agent/discussions); Issues are for bugs. ```bash -NODE_ENV=development DEBUG_MODE=true npm start +git clone +cd youtube-automation-agent +npm install +npm run lint # CI runs this on every PR +npm test ``` -## More Tools by darkzOGx - -If this was useful, check out: - -- [darkzloop](https://github.com/darkzOGx/darkzloop): terminal agent runner that turns any LLM into a disciplined software engineer (FSM control, model-agnostic, BYO auth) -- [darkzBOX](https://github.com/darkzOGx/darkzBOX): open-source Instantly.ai clone with smart automated email replies -- [open-sales-researcher](https://github.com/darkzOGx/open-sales-researcher): autonomous B2B company research. Works with Claude Code, Cursor, Copilot. -- [darkzseo](https://github.com/darkzOGx/darkzseo): SEO tooling +Made something real with it? Share verified output in [examples](examples/README.md). ## Built by @@ -587,41 +281,32 @@ If this was useful, check out: If YouTube Automation Agent saves you time, a star helps it reach more developers. -## Contributing - -See [CONTRIBUTING.md](CONTRIBUTING.md) for ground rules (short version: one focused concern per PR, no lockfile churn, lint + tests must pass). For questions and setup help, use [Discussions](https://github.com/darkzOGx/youtube-automation-agent/discussions) — Issues is for bugs. +More from darkzOGx: -1. Fork the repo -2. Create a feature branch -3. Make changes and add tests -4. Submit a PR - -```bash -git clone -cd youtube-automation-agent -npm install -npm run lint # must pass — CI runs this on every PR -npm test -``` +- [darkzloop](https://github.com/darkzOGx/darkzloop): terminal agent runner that turns any LLM into a disciplined software engineer (FSM control, model-agnostic, BYO auth) +- [darkzBOX](https://github.com/darkzOGx/darkzBOX): open-source Instantly.ai clone with smart automated email replies +- [open-sales-researcher](https://github.com/darkzOGx/open-sales-researcher): autonomous B2B company research. Works with Claude Code, Cursor, Copilot. +- [darkzseo](https://github.com/darkzOGx/darkzseo): SEO tooling +- [ConstructionBids.ai](https://constructionbids.ai): AI scans every federal, state & local public works bid and matches you to contracts you'll win. ## License -MIT — see [LICENSE](LICENSE). +MIT. See [LICENSE](LICENSE). ## Acknowledgments -- [OpenAI](https://openai.com/) — GPT-6.1 Sol, GPT Image 2, GPT-4o-mini-tts -- [OpenRouter](https://openrouter.ai/) — unified multi-model API -- [Google](https://ai.google.dev/) — Gemini 3.8 Flash, Gemini 4 Argon, Gemini 3.1 Flash Image, Gemini 3.8 Flash TTS -- [Google Cloud](https://console.cloud.google.com/) — YouTube Data API -- [Moonshot AI](https://www.moonshot.ai/) — Kimi K3 -- [Xiaomi](https://mimo.mi.com/) — MiMo V2.6 Pro -- [Zhipu AI](https://z.ai/) — GLM-5.3 -- [DeepSeek](https://www.deepseek.com/) — DeepSeek V4.1 Flash -- [MiniMax](https://www.minimax.io/) — MiniMax M3 text and H3 video -- [ElevenLabs](https://elevenlabs.io/) — Eleven v3 TTS -- [Replicate](https://replicate.com/) — Wan 2.7 video generation -- [ConstructionBids.ai](https://constructionbids.ai) - AI scans every federal, state & local public works bid and matches you to contracts you'll win. +- [Google](https://ai.google.dev/): Gemini 3.8 Flash, Gemini 4 Argon, Gemini 3.1 Flash Image, Gemini 3.8 Flash TTS, Gemini Omni Flash, and the YouTube Data and Analytics APIs +- [OpenAI](https://openai.com/): GPT-6.1 Sol, GPT Image 2, gpt-4o-mini-tts +- [OpenRouter](https://openrouter.ai/): unified multi-model API +- [Moonshot AI](https://www.moonshot.ai/): Kimi K3 +- [Xiaomi](https://mimo.mi.com/): MiMo V2.6 Pro +- [Zhipu AI](https://z.ai/): GLM-5.3 +- [DeepSeek](https://www.deepseek.com/): DeepSeek V4.1 Flash +- [MiniMax](https://www.minimax.io/): MiniMax M3 text and H3 video +- [ElevenLabs](https://elevenlabs.io/): Eleven v3 TTS +- [Replicate](https://replicate.com/): Seedance 2.5 and Wan 2.7 hosting +- [Kuaishou Kling](https://kling.ai/): Kling 3.0 Omni +- [Alibaba Cloud Model Studio](https://modelstudio.console.alibabacloud.com/): Wan 2.7 --- diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..7ee399a7 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,182 @@ +# HTTP API + +The dashboard server exposes an HTTP API on the same port, `http://localhost:3456` by default. It listens on `127.0.0.1` unless you set `HOST`. When `API_KEY` is set in `.env`, every request that changes something must send it in the `x-api-key` header. + +## Common requests + +```bash +# health check +curl http://localhost:3456/health + +# queue a video-generation job +curl -X POST http://localhost:3456/generate \ + -H "Content-Type: application/json" \ + -H "x-api-key: $API_KEY" \ + -d '{"topic": "Top 10 Life Hacks", "style": "list"}' + +# inspect the returned background job +curl http://localhost:3456/api/jobs/:jobId + +# resume a failed/interrupted job from its first incomplete checkpoint +curl -X POST http://localhost:3456/api/jobs/:jobId/resume \ + -H "Content-Type: application/json" \ + -H "x-api-key: $API_KEY" \ + -d '{}' + +# intentionally regenerate a selected stage and everything after it +curl -X POST http://localhost:3456/api/jobs/:jobId/resume \ + -H "Content-Type: application/json" \ + -H "x-api-key: $API_KEY" \ + -d '{"stage":"thumbnail"}' + +# inspect the latest production-readiness evidence +curl http://localhost:3456/api/readiness + +# run harmless live probes; add {"includePaidMedia":true} only to test paid image generation +curl -X POST http://localhost:3456/api/readiness/run \ + -H "Content-Type: application/json" \ + -H "x-api-key: $API_KEY" \ + -d '{"includePaidMedia":false}' + +# save a channel strategy +curl -X PUT http://localhost:3456/api/operator/strategy \ + -H "Content-Type: application/json" \ + -H "x-api-key: $API_KEY" \ + -d '{"objective":"Own practical AI automation for small teams","audience":"Small business operators","contentPillars":["AI workflows","Automation playbooks"],"cadencePerWeek":2,"videosPerRun":2,"defaultFormat":"tutorial","defaultLength":"medium","primaryKpi":"subscribers","targetValue":100,"targetWindowDays":28,"monthlyBudget":250,"outcomeCurrency":"USD","status":"draft"}' + +# activate the saved strategy and start a background operator run +curl -X POST http://localhost:3456/api/operator/start \ + -H "Content-Type: application/json" \ + -H "x-api-key: $API_KEY" \ + -d '{}' + +# resume an interrupted operator run from its saved plan +curl -X POST http://localhost:3456/api/operator/runs/:runId/resume \ + -H "x-api-key: $API_KEY" + +# view schedule +curl http://localhost:3456/schedule + +# get analytics +curl http://localhost:3456/analytics + +# get the goal-aligned Outcome & ROI Studio summary +curl http://localhost:3456/api/outcomes + +# approve an evidence-backed learning for future autonomous plans +curl -X POST http://localhost:3456/api/learning/recommendations/:recommendationId/approve \ + -H "x-api-key: $API_KEY" + +# inspect controlled experiments and eligible published videos +curl http://localhost:3456/api/experiments + +# create and approve a packaging test plan (start/adopt are separate confirmed actions) +curl -X POST http://localhost:3456/api/experiments \ + -H "Content-Type: application/json" -H "x-api-key: $API_KEY" \ + -d '{"productionId":"production-id","armDurationHours":48,"minImpressions":1000}' +curl -X POST http://localhost:3456/api/experiments/:experimentId/approve \ + -H "Content-Type: application/json" -H "x-api-key: $API_KEY" \ + -d '{"confirmed":true}' + +# inspect, edit, and approve content before scheduling +curl http://localhost:3456/api/content/:contentId +curl -X POST http://localhost:3456/api/content/:contentId/approve \ + -H "Content-Type: application/json" \ + -H "x-api-key: $API_KEY" \ + -d '{"privacyStatus":"private","factChecked":true,"rightsConfirmed":true}' +``` + +## Route reference + +### Status and dashboard + +| Method | Route | Purpose | +| --- | --- | --- | +| GET | `/health` | Health check | +| GET | `/api/dashboard` | Data behind the dashboard | +| GET | `/schedule` | Publishing schedule | +| GET | `/analytics` | Analytics summary | +| GET | `/api/analytics/channel` | Whole-channel YouTube snapshot | +| GET | `/api/readiness` | Latest production-readiness result | +| POST | `/api/readiness/run` | Run the readiness check | +| PUT | `/api/settings` | Update settings | +| PUT | `/api/profile` | Update the channel profile | +| POST | `/api/automation/:action` | `pause` or `resume` scheduled automation | +| POST | `/api/notifications/:notificationId/read` | Mark a notification as read | + +### Generation jobs and ideas + +| Method | Route | Purpose | +| --- | --- | --- | +| POST | `/generate` | Queue a video-generation job | +| GET | `/api/jobs/:jobId` | Job status and progress | +| POST | `/api/jobs/:jobId/resume` | Resume from the first incomplete stage, or from `stage` | +| POST | `/api/jobs/:jobId/cancel` | Cancel a job | +| POST | `/api/ideas` | Add a content idea | +| PATCH | `/api/ideas/:ideaId` | Edit an idea | +| POST | `/api/ideas/:ideaId/generate` | Generate a video from an idea | + +### Content review and publishing + +| Method | Route | Purpose | +| --- | --- | --- | +| GET, PATCH | `/api/content/:productionId` | Read or edit a production | +| POST | `/api/content/:productionId/approve` | Approve for scheduling | +| POST | `/api/content/:productionId/reject` | Reject a production | +| POST | `/api/content/:productionId/retry` | Start a new generation job for this production | +| POST | `/api/content/:productionId/publish-now` | Publish immediately | +| PATCH, DELETE | `/api/content/:productionId/schedule` | Reschedule, or remove the schedule without deleting content | +| POST | `/publish/:contentId` | Publish a production or a Short | +| PUT | `/api/content/:productionId/provenance` | Update the evidence desk | +| POST | `/api/content/:productionId/discoverability/run` | Run the discoverability preflight | +| PATCH | `/api/discoverability/findings/:findingId` | Keep or dismiss a finding | +| GET | `/api/content/:productionId/asset/:kind` | Download `video`, `thumbnail`, `captions`, or `script` | + +### Scenes and narration + +| Method | Route | Purpose | +| --- | --- | --- | +| PATCH | `/api/content/:productionId/scenes/:sceneId` | Edit a scene | +| GET | `/api/content/:productionId/scenes/:sceneId/asset` | Scene asset | +| GET | `/api/content/:productionId/scenes/:sceneId/estimate` | Estimate for regenerating a scene | +| POST | `/api/content/:productionId/scenes/:sceneId/regenerate` | Regenerate one scene | +| POST | `/api/content/:productionId/scenes/:sceneId/narration` | Regenerate one scene's narration | +| POST | `/api/content/:productionId/scenes/reorder` | Reorder scenes | +| POST | `/api/content/:productionId/scenes/rebuild` | Rebuild the final video | +| POST | `/api/content/:productionId/narration/silence` | Set or clear an intentional-silence override | + +### Shorts + +| Method | Route | Purpose | +| --- | --- | --- | +| POST | `/api/content/:productionId/shorts/propose` | Create Short drafts | +| PATCH | `/api/content/:productionId/shorts/:clipId` | Edit a Short draft | +| POST | `/api/content/:productionId/shorts/:clipId/render` | Render a Short | +| POST | `/api/content/:productionId/shorts/:clipId/approve` | Approve and schedule a Short | +| GET | `/api/content/:productionId/shorts/:clipId/asset/:kind` | Download a Short's `video` or `captions` | + +### Operator, learning, and experiments + +| Method | Route | Purpose | +| --- | --- | --- | +| PUT | `/api/operator/strategy` | Save the channel strategy | +| POST | `/api/operator/start` | Activate the strategy and start a run | +| POST | `/api/operator/pause` | Pause the operator | +| POST | `/api/operator/runs/:runId/resume` | Resume a run from its saved plan | +| POST | `/api/operator/runs/:runId/cancel` | Cancel a run | +| POST | `/api/learning/recommendations/:recommendationId/:action` | `approve` or `reject` a recommendation | +| GET, POST | `/api/experiments` | List experiments, or create a test plan | +| POST | `/api/experiments/:experimentId/:action` | `approve`, `start`, `refresh`, `adopt`, or `cancel` | +| GET | `/api/outcomes` | Outcome & ROI summary | +| GET | `/api/retention/:videoId` | Stored scene-aware retention | +| POST | `/api/retention/:videoId/refresh` | Refresh the retention curve from YouTube | + +### Engagement + +| Method | Route | Purpose | +| --- | --- | --- | +| GET | `/api/engagement/:videoId` | Comment insights for a video | +| POST | `/api/engagement/:videoId/sync` | Sync comments now | +| POST | `/api/engagement/:videoId/draft-replies` | Draft suggested replies | +| PATCH | `/api/engagement/replies/:draftId` | Edit a draft reply | +| POST | `/api/engagement/replies/:draftId/approve` | Approve and post a reply | diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 00000000..264e030c --- /dev/null +++ b/docs/features.md @@ -0,0 +1,155 @@ +# Feature guide + +Detailed walkthroughs of each part of YouTube Automation Agent. For installation and configuration, start with the [README](../README.md). + +- [Production readiness](#production-readiness) +- [Autonomous Channel Operator](#autonomous-channel-operator) +- [Resumable generation](#resumable-generation) +- [AI video generation](#ai-video-generation) +- [Scene Repair Studio and narration](#scene-repair-studio-and-narration) +- [Shorts Repurposing Studio](#shorts-repurposing-studio) +- [Evidence desk](#evidence-desk) +- [Discoverability preflight](#discoverability-preflight) +- [Learning loop](#learning-loop) +- [Controlled growth experiments](#controlled-growth-experiments) +- [Outcome & ROI Studio](#outcome--roi-studio) +- [Scene-aware retention](#scene-aware-retention) +- [Audience Engagement Studio](#audience-engagement-studio) +- [Automation schedule](#automation-schedule) +- [Activation measurement and privacy](#activation-measurement-and-privacy) + +Review Studio, mentioned throughout, is the **Content review** panel for each video. + +## Production readiness + +Before activating autonomous production, open **Production readiness** in the dashboard and choose **Run verified check**. The gate makes small live text and narration requests, verifies access to the connected YouTube channel, creates and decodes a temporary MP4 containing audio and video, and validates every queued upload's metadata. It never creates or uploads a YouTube video, and temporary probe assets are deleted after the run. + +AI image generation can incur a larger provider charge, so its live probe is a separate opt-in checkbox. Without that checkbox, image configuration is reported as verified, skipped, or using the built-in gradient fallback without making a paid image request. + +AI video verification has its own **Include paid video probe** checkbox. When enabled, the agent creates the provider's shortest supported test clip, records the external task and model, downloads and decodes the MP4, then removes the temporary asset. It never silently tries a second paid provider. + +Results persist locally in SQLite with exact remediation steps. A recorded blocking failure stops autonomous generation and publishing until a later run passes; manual work remains available when readiness has never been checked or the last result is older than 24 hours. + +## Autonomous Channel Operator + +Open **Autonomous operator** in the dashboard and describe the channel outcome, not a task list. Set the objective, audience, content pillars, publishing cadence, success metric, and boundaries, then choose **Activate & run now**. + +The operator refreshes YouTube trend and configured-competitor signals, checks recent channel topics, creates an evidence-labeled editorial plan, and sends each planned video through strategy, script, thumbnail, SEO, production, and workflow management. Active strategies also guide scheduled generation at the requested weekly cadence. Operator runs, decisions, progress, and failures persist in SQLite and remain visible in the dashboard. + +By default, finished videos wait for factual review, media-rights confirmation, and approval. Once approved, the publishing agent schedules and uploads them. Turning on autonomy does not bypass those gates, and simulated videos still cannot publish. + +## Resumable generation + +Every generation stage writes a local SQLite checkpoint. If a provider times out or the application restarts, the dashboard shows the saved-stage count and the first incomplete stage. Choose **Resume** to continue from there, or select an earlier stage when you intentionally want to regenerate that stage and everything after it. Saved files are validated before reuse; missing artifacts are regenerated automatically. + +Autonomous Operator runs preserve their research and editorial plan, so **Resume run** continues unfinished plan items instead of researching and generating completed videos again. Publishing remains fail-closed: if an upload may have reached YouTube but no video ID was returned, the agent requires channel reconciliation before another upload attempt. + +## AI video generation + +Local slideshow rendering is the default, so upgrading does not start paid video requests. The slideshow is rendered in headless Chromium (install it once with `npx playwright install chromium`) and assembled with FFmpeg. Generated images fill each slide; slides without an image use a gradient background. + +To generate real clips, choose a provider in **Channel setup**, set a paid-seconds cap, then run the separately opted-in paid video readiness probe. The supported providers and their clip limits are listed in the [README](../README.md#video). + +Long-form productions use hybrid assembly: the agent generates bounded provider clips for the hook and important sections, fills the remaining timeline locally, mixes the existing narration, and keeps the generated caption file alongside the production. As soon as a provider returns its task ID, the agent persists it before polling, so interrupted jobs can resume that known task instead of submitting it again. If a provider fails, the production falls back to the local slideshow. + +## Scene Repair Studio and narration + +Every production keeps a durable scene manifest with its narration, visual prompt, timing, provider/task identity, asset origin, rights state, evidence links, and revision history. Open **Scene Repair Studio** inside Review Studio to edit a scene, change its order, lock a scene that already works, upload a licensed replacement asset, or regenerate only that scene. + +Paid video regeneration always shows the provider and generated seconds and requires a separate confirmation. Uploaded assets require an explicit rights confirmation. Narration edits invalidate that scene's audio and factual review; live narration must be regenerated and any new factual claim must be reviewed against verified evidence before approval. + +Narration is fail-closed. The agent records the TTS provider, model, external task when available, generation time, cost evidence, and failure reason for every scene. If narration is missing, simulated, stale, or failed, the production cannot be approved, scheduled, or published. Use **Regenerate narration only** to repair the audio without spending video-generation credits or replacing a visual. + +An intentionally silent production requires a separate operator confirmation and a stored reason of at least 10 characters. The override remains visible in Review Studio, can be reversed, and is included in the narration revision history. Silence is never inferred from a failed provider call. + +When the timeline is ready, **Rebuild final video** creates a new MP4 and scene-aware captions while preserving the previous final video path in the production record. Approval stays blocked while any scene is missing, generating, stale, failed, or waiting for rebuild. Approved or scheduled productions are locked against scene repair. + +## Shorts Repurposing Studio + +Open **Shorts Repurposing Studio** inside Review Studio and choose **Create 3 Short drafts**. The agent selects self-contained windows from the durable scene timeline and preserves the exact source-scene IDs, start time, duration, rationale, title, description, tags, layout, and inherited review evidence for each candidate. Draft selection is local and does not call an AI provider. + +Choose a blurred-canvas, center-crop, or stacked-focus layout, then render a real 9:16 MP4 with mobile-safe burned captions and a separate SRT file. The source video and narration are reused, so the default workflow does not spend new image, video, or TTS credits. Changing the layout invalidates the prior render and requires a fresh local render. + +Every Short has its own approval and schedule. Scheduling remains blocked until the source production is approved, provenance is resolved, uploaded media rights are confirmed, every source scene is current, and the operator explicitly confirms the Short's privacy and publish time. Published Shorts retain their parent-production identity while their analytics use a separate Shorts baseline. + +## Evidence desk + +Every production has an **Evidence desk** inside Review Studio. Autonomous research carries exact YouTube source metadata into the production, while AI-generated scripts list the factual claims that need review. Add any official articles, datasets, asset licenses, or other evidence the script needs, verify each source, and connect it to the claims it supports. + +A claim can be approved only when it links to a verified source. Unsupported claims remain blocking, and an intentional waiver requires a reviewer note. Productions with no externally verifiable factual claims are marked as not requiring provenance review. The separate factual-review and media-rights attestations remain required before scheduling. + +Use the altered or synthetic media control only when the video contains realistic content that requires YouTube disclosure. The selected value is preserved in the publishing queue and included in the YouTube upload request. + +## Discoverability preflight + +Every saved production receives an optional **DarkzSEO Discoverability Preflight** in Review Studio after metadata and provenance are assembled. The bundled content auditor reviews a canonical content package (not the private dashboard) with versioned GEO, AIO, AEO, and web-search checks, and stores the engine version, schema version, severity summary, stable rule IDs, and individual findings in SQLite. + +Findings are advisory. Keep a useful recommendation as actionable, or dismiss a false positive with a reviewer reason that carries forward to matching findings on later audits. The bundled audit requires no Python package and never silently changes scripts or metadata. + +To test a separate DarkzSEO 1.4+ checkout (requires Python 3.9+) instead of the bundled auditor: + +```bash +DARKZSEO_PATH=../darkzseo/darkzseo.py npm start +``` + +The optional external adapter uses a shell-free Python child process, sends content JSON over stdin, and reads JSON-only stdout. If that runtime is missing or broken, the agent falls back to the bundled audit. The public PyPI `darkzseo` 1.3.3 package has a different site-audit CLI and is not used. + +## Learning loop + +After publication, the agent captures comparable 24-hour and 7-day performance snapshots. It evaluates CTR, retention, engagement, watch time, format, length, hook style, and title style against the channel's own history, not a universal view-count target. + +Open **Analytics → What the agent learned** to review the evidence and confidence behind each recommendation. Pending or rejected recommendations never influence generation. Once you approve one, the next Autonomous Channel Operator run includes it as an explicit planning constraint. Simulated analytics fallbacks are stored as unverified and are never eligible for baselines or recommendations. + +When an approved learning calls for better packaging, the agent prepares a control plus title and thumbnail variants for new videos. Review Studio shows those options before approval; the selected combination is the only one handed to the publishing queue. The agent does not silently swap live YouTube metadata. + +## Controlled growth experiments + +Open **Analytics → Controlled Growth Experiments** after a video with approved-learning packaging variants is published. Create a draft plan with a 24–168 hour window per arm and a minimum-impressions threshold, review the exact title and thumbnail combinations, then separately approve and start the live test. + +The agent records a cumulative analytics sample before and after each arm and evaluates only the interval delta. Every arm must reach the configured impression and click floor. The leading CTR must clear a 95% evidence threshold without a material retention regression or traffic-source shift; otherwise the result is explicitly **inconclusive**. Simulated analytics never advance an experiment. + +Arm rotations are limited to the plan you approved. After the final arm, the agent restores the control title and thumbnail before presenting the result. Applying the winner is a separate confirmation; only then does the validated packaging pattern become an approved learning for future Autonomous Operator runs. Experiment state and evidence are stored in SQLite so restarts do not erase progress. + +## Outcome & ROI Studio + +The Autonomous Operator strategy can define a measurable primary outcome (views, watch hours, net subscribers, engagement rate, or estimated revenue) plus a numeric target, evidence window, monthly production budget, and currency. The free-text outcome context remains available for goals that need human nuance. + +At each real analytics window, the agent stores subscriber gains and losses, watch hours, monetization evidence when the channel exposes it, and known production costs from durable scene records. **Analytics → Outcome & ROI Studio** shows target progress, evidence coverage, net subscribers, estimated revenue, known cost, ROI, and comparisons by content pillar, format, and production provider. + +Missing evidence is explicit. A channel without monetization access shows revenue as unavailable rather than zero, and ROI stays unavailable until both revenue and complete cost evidence exist. When at least two comparable videos exist in each group, the learning engine can propose reallocating future content toward the pillar or format that best advances the configured outcome. That proposal remains pending until you approve it; the agent never changes the strategy or budget silently. + +## Scene-aware retention + +At each real analytics window, the agent also requests YouTube's audience-retention curve and maps its 100 elapsed-time points onto the stored scene durations. Open **Analytics → Scene-aware retention** to see the curve divided by scene, compare absolute and relative retention, and inspect drop-off, rewatch, strong-hold, or steady signals for each beat. + +Retention snapshots are stored separately for long-form videos and Shorts. Missing, sparse, or simulated curves never enter this evidence layer. A scene finding creates a pending learning recommendation; it cannot guide future scripts, pacing, or scene structure until the operator approves it, and the agent never rewrites a published video. Use **Refresh curve** for a read-only update from YouTube Analytics, or `GET /api/retention/:videoId` to inspect stored evidence. + +## Audience Engagement Studio + +Open **Engagement** in the dashboard. The agent syncs comments for recently published videos every four hours (more often for fresh videos) and classifies them into themes, sentiment, and questions. Likely spam, scams, and toxic comments are quarantined into a separate needs-attention list. The agent never deletes or hides a comment; acting on flagged comments stays in YouTube Studio. + +Choose **Draft replies** to generate suggested answers in your channel's voice. Nothing posts automatically: every reply waits in the queue where you can edit, discard, or approve it, and approval requires an explicit confirmation. Posting requires re-authorizing YouTube once to grant the comment permission (`youtube.force-ssl`); until then the studio works in read-and-draft mode. A daily posting cap (default 50, `ENGAGEMENT_DAILY_REPLY_CAP`) keeps approval sessions bounded. + +When three or more commenters ask for the same thing, the analysis mines an **audience-requested idea** with comment permalinks as evidence. Like every other learning, it stays pending until you approve it; only then can the Autonomous Channel Operator plan a video that answers it. If no AI text provider is configured, comment sync still works, but the studio records only mechanical facts and never invents themes, drafts, or ideas. + +## Automation schedule + +The scheduler starts with `npm start` and uses the server's local time. + +| When | Job | +| --- | --- | +| Daily at 06:00 | Generate content. With an active channel strategy, this follows its cadence and launches an autonomous research-and-production run when the content buffer needs work; otherwise the original topic-selection flow runs. | +| Every 15 minutes | Process the publishing queue | +| Daily at 09:00 | Collect analytics and backfill each real publication's 24-hour and 7-day evidence windows | +| Daily at 22:00 | Run optimizations | +| Every 4 hours | Sync audience comments (on the hour) and refresh growth experiments (at half past) | +| Sundays at 08:00 | Weekly strategy review | +| Saturdays at 03:00 | Database maintenance | + +Recommendations require at least two real measurements, and format or style comparisons require at least two videos in each compared group. + +## Activation measurement and privacy + +The dashboard calculates setup, first-real-MP4, approval, publication, and repeat-generation milestones locally from SQLite and files on disk. A video counts only when a non-simulated `.mp4` with an MP4 container signature still exists. + +Anonymous milestone reporting is disabled by default and has no built-in collector. It activates only when you explicitly set both `ANONYMOUS_TELEMETRY_ENABLED` and `ANONYMOUS_TELEMETRY_ENDPOINT`. The allowlisted payload contains the milestone name and time, YouTube Automation Agent version, OS family, Node major version, and a random installation ID. It never includes credentials, channel data, prompts, topics, titles, filenames, or video contents.