Open-source, self-hostable YouTube analytics and intelligence for creators, teams, and developers. The project aims to turn YouTube channel and video data into useful diagnostics, comparisons, alerts, and eventually actionable recommendations without locking creator data into a proprietary analytics service.
Status: early development. The V0.1 contract is intentionally small and will evolve.
- One workspace for channel, video, audience, traffic, and content-performance analytics.
- Explain why a metric changed, not only display the number.
- Normalize YouTube API data into stable internal metrics that can be tested and extended.
- Support privacy-conscious self-hosting from the beginning.
- Keep provider/API boundaries explicit so the product can evolve without coupling the UI to raw YouTube responses.
This repository uses pnpm workspaces. The web application and core domain packages are separated so analytics logic can be tested independently of the UI.
youtube-intelligence/
├─ apps/
│ ├─ web/ # Next.js dashboard + local API/OAuth backend
│ └─ extension/ # Chrome MV3 side-panel extension
├─ packages/
│ ├─ analytics-core/ # deterministic scores + diagnoses
│ ├─ youtube/ # Data/Analytics/Reporting API adapters
│ └─ db/ # storage contracts + PostgreSQL migration
├─ docs/
│ ├─ ARCHITECTURE.md
│ ├─ IMPLEMENTATION_PLAN.md
│ ├─ METRICS.md
│ └─ ROADMAP.md
├─ .env.example
├─ CONTRIBUTING.md
└─ LICENSE
The platform deliberately separates the three relevant Google/YouTube APIs:
| API | Role in YouTube Intelligence |
|---|---|
| YouTube Data API v3 | Public/resource metadata: channels, videos, playlists, search/discovery metadata, titles, thumbnails, durations, and public counters where available. |
| YouTube Analytics API | Authorized, query-oriented analytics for a channel/content owner: watch time, views, audience, traffic-source and geography/device dimensions, and other supported reports. |
| YouTube Reporting API | Authorized bulk reporting for larger historical/operational datasets. It creates reporting jobs and downloads generated report files rather than serving interactive queries. |
Data API access is not a substitute for Analytics authorization. Private creator analytics require OAuth consent and the appropriate YouTube scopes.
Prerequisites:
- Node.js 22 or newer.
- pnpm 10.x (the repository pins the package manager version).
- A Google Cloud project with the required YouTube APIs enabled.
- OAuth 2.0 credentials for private channel analytics.
pnpm install
cp .env.example apps/web/.env.local
# Fill GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and APP_SECRET.
pnpm build
pnpm devOn Windows PowerShell, copy the environment template with Copy-Item .env.example apps/web/.env.local.
For the Chrome extension flow, register http://localhost:3000/api/extension/auth/callback as an authorized redirect URI in the Google OAuth client. The original web callback is http://localhost:3000/api/auth/youtube/callback.
Load the unpacked extension from apps/extension/dist after pnpm build, then open http://localhost:3000/api/extension/auth/start once to connect the Google account that owns the channel. See docs/EXTENSION_LIVE_TEST.md for the complete live-test procedure.
The current web dashboard can still run in demo mode before Google credentials are configured. The extension analysis endpoints never fabricate private analytics: when OAuth or a metric is unavailable, they return an explicit unavailable/not-connected state.
Self-hosting is a first-class deployment target. OAuth client secrets, access tokens, refresh tokens, raw private analytics, and user identifiers must never be committed to Git. Deployments should encrypt sensitive credentials at rest, minimize requested OAuth scopes, use TLS outside localhost, and provide an explicit way to disconnect an account and delete stored creator data.
The application should collect only data needed for enabled features. Telemetry must be opt-in or clearly documented before V1, and self-hosted installations should be able to run without sending creator analytics to a project-operated service.
- V0.1 — Foundation: Chrome side-panel live analysis, OAuth connection, channel/video ingestion, normalized core metrics, deterministic channel-relative diagnostics, basic dashboard/query surfaces, and local/self-hosted setup.
- V0.2 — Diagnostics: time-series comparisons, traffic/source breakdowns, retention-oriented views where supported, anomaly detection, metric explanations, exports.
- V0.3 — Intelligence: benchmarks against the creator's own history, packaging/content diagnostics, configurable alerts, recommendation evidence and confidence.
- V0.5 — Operations: Reporting API bulk pipelines, larger histories, scheduled ingestion, team/workspace foundations, stronger backup/restore and deployment tooling.
- V1 — Stable platform: versioned internal contracts, production-grade auth/data lifecycle, extensible intelligence modules, documented deployment/upgrade path, accessibility and reliability targets.
See docs/ROADMAP.md for acceptance goals and docs/ARCHITECTURE.md for system boundaries.
Metric names can be deceptively similar across YouTube surfaces. YouTube Intelligence keeps source, grain, dimensions, time zone, and freshness attached to metric values and avoids silently combining incompatible definitions. See docs/METRICS.md.
Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Please keep secrets and private channel data out of issues, fixtures, screenshots, and logs.
MIT — see LICENSE.
YouTube Intelligence is an independent open-source project and is not affiliated with, endorsed by, or sponsored by YouTube or Google. YouTube and Google product names are trademarks of their respective owners. API use remains subject to the applicable Google/YouTube developer policies and terms.