Gospel in ActionBiblical Truth. Cinematic Storytelling. Everyday Faith.

Documentation

YouTube integration

OAuth model, quota planning, publication pipeline, guardrails.

Phase 2 scope. Nothing here is implemented or claimed to work yet; this document fixes the design so implementation does not improvise.

1. APIs

API Purpose Notes
YouTube Data API v3 channel read, upload, metadata, thumbnails, playlists, captions unit-quota model
YouTube Analytics API views, impressions, CTR, watch time, retention, traffic sources, demographics separate quota from Data API; reports are not real-time
YouTube Reporting API (optional) bulk daily reports cheaper for large media accounts
OAuth 2.0 channel authorisation offline access + refresh token

Verify current quotas and endpoint scopes against Google's live documentation before coding; quotas and field availability change.

2. OAuth model

  • One Google Cloud project, one OAuth client, one refresh token per channel.
  • Scopes requested at minimum: https://www.googleapis.com/auth/youtube.upload, .../youtube.readonly, .../yt-analytics.readonly. Request youtube.force-ssl only if comment management is enabled later.
  • Refresh tokens live in a secrets manager or .env excluded from git. Never in the database, never in logs, never in prompts.
  • The operator's Google password is never requested or stored.
  • Token health check runs daily; a failed refresh disables publishing and raises an alert rather than retrying silently.

3. Quota planning (Data API)

Default allocation is 10,000 units/day. Planning figures to verify at implementation time:

Operation Units (approx.) Monthly need at 4 long-form + 20 Shorts
videos.insert 1,600 24 uploads × 1,600 = 38,400
thumbnails.set 50 1,200
videos.update 50 ~2,000
playlistItems.insert 50 ~1,200
captions.insert 400 9,600

Conclusion: a single-project default quota is not sufficient for 24 uploads/month. Either request a quota extension (standard process, requires justification) or use a resumable upload strategy distributed across days. This must be resolved before Phase 5 is declared ready. Do not design a schedule that assumes unlimited uploads.

4. Publication pipeline

  1. Publishing agent receives a project whose latest audit is publishable.
  2. Create Publication row with idempotency_key = project:{id}:upload:v{n}.
  3. Upload as private (or unlisted for review), with selfDeclaredMadeForKids=false.
  4. Set synthetic-content disclosure flag where the API/Studio supports it (altered or synthetic content). This is mandatory for AI narration/visuals.
  5. Set thumbnail, description, chapters, tags, playlist.
  6. Verify the upload: fetch the video back, assert title/description/thumbnail/privacy.
  7. Only then schedule the premiere or transition to PUBLISHED.
  8. Persist the returned youtube_video_id and the audit id used.

Retries: a 5xx or network failure after upload must first search recent uploads by title + hash to avoid duplicates before re-uploading.

5. Guardrails

Guard Default
Public publish disabled (GIA_ALLOW_PUBLIC_PUBLISH=false)
Dry-run enabled; private uploads, no scheduling
Blocking audits publish refused at the state-machine level
Human override requires reviewer, 20+ char rationale, explicit blocker acknowledgement
Cost cap per-video and monthly budgets checked before asset generation
Duplicate detection idempotency keys + content hash + recent-upload lookup
Kill switch POST /admin/halt (Phase 6) sets all projects to NEEDS_REVIEW and revokes publishing

6. Policy compliance

  • Original, value-bearing content; no mass-produced repetitive uploads.
  • No fabricated testimonies; testimonies require a documented source (licensed interview, published account, or the operator's own account) and are labelled accordingly.
  • No misleading titles or thumbnails; the title claim must be delivered in the first 30 seconds.
  • Scripture quotations only from the licensed translation recorded in the corpus manifest.
  • AI disclosure where required by YouTube policy and in the description.

7. Analytics ingestion

  • Daily: channel + per-video snapshots (28-day window and lifetime), stored append-only.
  • Weekly: pillar-level aggregation, retention by segment, traffic source mix, returning-viewer trend.
  • Mission-fit metric: share of new viewers who watch a second video, plus completion rate on Gospel presentation videos — not views alone.
  • Correlation is labelled as correlation. A/B conclusions require a controlled comparison; otherwise the report says "observed, not causal".

Source

Rendered from docs/YOUTUBE_INTEGRATION.md at build time. Return to the documentation index.