TubeMaster is a channel-operations workspace spanning Web UI, CLI, MCP, and API surfaces. It supports channel context, video browsing and selection/export, playlist operations, rules, metadata preview and guarded apply, transcript acquisition, quota visibility, and observational audit events. Each interface exposes a different subset; see interface boundaries.
- Configure Google Cloud OAuth + YouTube API
- Create
.env.localwith required credentials - Install and run locally
npm installnpm run dev
- Authenticate and verify access (CLI recommended first)
npm run cli:video-metadata -- auth loginnpm run cli:video-metadata -- auth whoami
Full walkthrough: docs/getting-started.md. The development server uses port 3102 so the OAuth callback remains stable.
| Interface | Entry point | Current scope |
|---|---|---|
| Web UI | http://localhost:3102 |
Browse/select/export videos, playlists, rules, analytics, quota, calendar, private upload, and Instagram/TikTok publishing with preview/confirmation |
| CLI | npm run cli:video-metadata -- <command> |
Auth/channel context, metadata/transcripts, playlists, guarded upload/recovery commands, read-only best-publish-time analysis, and separate quota reporting |
| MCP Server (stdio) | npm run mcp:video-metadata |
Context, metadata, transcripts, playlists, guarded upload/recovery tools, best-publish-time analysis, and Instagram/TikTok publishing; no login or registered quota tool |
| API Route Handlers | /api/youtube/*, /api/video-metadata/*, /api/social/*, /api/quota/usage |
Session-authenticated UI operations for metadata, transcripts, analytics, upload/scheduling, social publishing, and estimated quota usage |
Detailed usage by interface: docs/interfaces.md
Authenticated analytics, reporting, upload/recovery, scheduling, and social publishing foundations are already present. Analytics requires an OAuth grant with https://www.googleapis.com/auth/yt-analytics.readonly; existing users must re-authenticate after adding it to the authorization request. See analytics setup. Transcript indexing, embeddings, semantic search, broader editorial intelligence, and durable history remain separate roadmap increments—not capabilities promised in one release. TubeMaster does not autonomously publish content.
Metadata, transcript, and playlist services emit privacy-filtered lifecycle events to the configured logger. Events are observational: logger failures do not change API results. The default metadata logger writes JSON lines to stderr; playlist events require an injected logger. No audit database or built-in retention policy is provided in this slice; stderr retention depends on your process/log collector. See event vocabulary and fields.
npm run dev
npm run test
npm run lint# Playlist operations
npm run cli:video-metadata -- playlist create --title "Roadtrip 2026" --description "Videos del viaje" --expectedChannelId <CHANNEL_ID> --confirmed --privacyStatus unlisted
npm run cli:video-metadata -- playlist update --playlistId <PLAYLIST_ID> --expectedChannelId <CHANNEL_ID> --confirmed --description "Nueva descripción"
npm run cli:video-metadata -- playlist add --playlistId <PLAYLIST_ID> --videoIds <VIDEO_ID_1>,<VIDEO_ID_2> --expectedChannelId <CHANNEL_ID> --confirmed
# Metadata operations
npm run cli:video-metadata -- transcript --videoId <VIDEO_ID>
npm run cli:video-metadata -- preview --videoId <VIDEO_ID> --editorialPrompt "Hacé un título claro"
npm run cli:video-metadata -- apply --videoId <VIDEO_ID> --finalTitle "Nuevo título" --description "Nueva descripción" --expectedChannelId <CHANNEL_ID> --dryRun
# Upload recovery: staged multi-video private preview, then explicit confirmation
npm run cli:video-metadata -- upload multi --expectedChannelId <CHANNEL_ID> --items '[{"stagingFile":"video.mp4","title":"Video"}]' --dryRun
npm run cli:video-metadata -- upload multi --expectedChannelId <CHANNEL_ID> --items '[{"stagingFile":"video.mp4","title":"Video"}]' --confirmed --confirmationToken <TOKEN>
npm run cli:video-metadata -- upload reconcile --operationId <OPERATION_ID> --videoId <VIDEO_ID> --expectedChannelId <CHANNEL_ID>
npm run cli:video-metadata -- upload reconcile-many --expectedChannelId <CHANNEL_ID> --items '[{"operationId":"<OPERATION_ID>","videoId":"<VIDEO_ID>"}]'
npm run cli:video-metadata -- upload cancel --operationId <OPERATION_ID> --videoId <VIDEO_ID> --expectedChannelId <CHANNEL_ID> --dryRun
npm run cli:video-metadata -- upload cancel --operationId <OPERATION_ID> --videoId <VIDEO_ID> --expectedChannelId <CHANNEL_ID> --confirmed --confirmationToken <TOKEN>
# Read-only best publish times estimate (needs yt-analytics.readonly)
npm run cli:video-metadata -- best-times --timezone America/Argentina/Buenos_AiresGOOGLE_CLIENT_IDGOOGLE_CLIENT_SECRETNEXTAUTH_SECRETNEXTAUTH_URL
See full env setup + Google credentials mapping: docs/getting-started.md#2-local-environment-envlocal
YOUTUBE_TRANSCRIPT_PROVIDER(youtube-captionsby default)METADATA_GENERATOR_MODE(rule-basedby default,raw-jsonfor strict output checks)METADATA_GENERATOR_RAW_OUTPUT(used only when mode israw-json)CLI_OAUTH_CALLBACK_PORT(8787by default; if changed, update OAuth redirect URI accordingly)
- Stable JSON envelopes across CLI/MCP/core with typed errors and non-zero exit status on failures.
- Strict credential precedence: explicit
credentialRef→ active local context (data/auth-context.json) → typed auth error. - Fail-closed write operations (
apply, playlist mutations, multi-video upload execution, and return-to-private recovery) requiringexpectedChannelIdand explicit confirmation where applicable. - Recovery safety: reconciliation never retries a mutation; unknown and unsupported provider outcomes remain explicit, and return-to-private requires a dry-run preview plus matching confirmation token.
- Safe playlist partial results: add returns
attempted/added+failures[]; remove returnsrequested/removed+failures[]. - Transcript compatibility contract with stable
statusand additive diagnostics.
Troubleshooting these guardrails and auth errors: docs/troubleshooting.md
- Roadmap and future Shorts proposal: docs/roadmap.md
- Getting started (Google Cloud + local setup): docs/getting-started.md
- Web UI, CLI, MCP, API usage: docs/interfaces.md
- Social publishing setup (Instagram, TikTok): docs/social-publishing.md
- Common auth/API/env errors and fixes: docs/troubleshooting.md
TubeMaster is open source under the MIT License.
- Open an issue for bugs, contract changes, or feature requests.
- Open a PR with focused changes and clear reproduction/validation notes.
- Keep changes backward-compatible where possible, especially for CLI/MCP JSON contracts.
Read CONTRIBUTING.md for setup, validation, and PR expectations.
If you are integrating with agents, start the MCP server with:
npm run mcp:video-metadata

