Upstream proposal: opt-in YouTube subscription organization and private category playlists

[djbclark]

Published upstream for maintainer feedback: sidinsearch/superbrain#6

Proposal status

This is a request for design direction before any approval-dependent YouTube Data API code is proposed for merge. I have a fork prototype, but this issue is about agreeing on the product boundary and end state—not asking upstream to accept that implementation.

Why this would be useful

People with many YouTube subscriptions can have difficulty finding the videos they want to watch at a particular moment. SuperBrain already analyzes and organizes saved content. The proposed feature would let a user opt in to organizing videos related to their subscriptions into private, user-controlled topic playlists, making it easier to switch between interests and then return to YouTube to watch.

This is not a creator-growth, channel-ranking, surveillance, or replacement-playback feature. SuperBrain would provide private organization; playback would continue to open in YouTube or the system browser.

Proposed self-hosted end state

1. Connect an account deliberately. A self-hosting operator configures their own Google Cloud project and OAuth client. SuperBrain explains the requested access before OAuth and identifies the connected YouTube channel afterward.
2. Choose subscriptions in bulk. The user can select all subscriptions, many subscriptions with search/filter/multi-select, or rules that include future subscriptions. The normal workflow does not require channel-by-channel approval.
3. Preview and consent once to a defined automation. Before any YouTube write, SuperBrain shows the connected channel, proposed private playlist names, selected subscription scope, representative examples, and the classes of ongoing actions it will perform. One affirmative bulk consent can cover the selected channels and resulting playlist changes until the user pauses or revokes it. A materially expanded use would require new consent.
4. Synchronize safely in the background. Resumable, idempotent, quota-aware jobs create private category playlists and add or remove videos as the user's private categories change. The UI shows progress, quota delays, failures, and a completion summary rather than blocking or silently dropping work.
5. Keep the user in control. Users can preview or dry-run changes, correct categories, pause synchronization, disconnect/revoke YouTube access, and delete locally stored authorization data and playlist mappings.
6. Keep playback on YouTube. Official links continue to open in the YouTube app when available or the system browser otherwise. This feature does not download, proxy, replace, or modify playback.

Deployment and credential boundary

The initial upstream design should match SuperBrain's self-hosted model:

• Each operator supplies and controls their own Google Cloud project, OAuth credentials, quota, consent-screen configuration, and required Google/YouTube review.
• Upstream does not distribute a shared OAuth client secret, API project, refresh token, or quota pool.
• Credentials and user-specific mappings remain in the operator's deployment and are never committed to the repository.
• A centrally hosted multi-user service is out of scope for this proposal. That would require a separate design for application accounts, tenant isolation, encrypted per-user tokens, hosted privacy terms, deletion, abuse controls, shared quota, and production verification.

Intended API footprint

The proposed flow should use the smallest empirically verified scope set for the shipped operations. The expected YouTube Data API surface is:

• channels.list(mine=true) to identify the channel being authorized.
• subscriptions.list(mine=true) to populate the user's bulk-selection UI.
• playlists.list and playlists.insert to find or create private category playlists.
• playlistItems.list, playlistItems.insert, and playlistItems.delete to reconcile playlist membership idempotently.

The design would not use search.list or videos.insert.

Approval boundary

Accepting a design or merging open-source code would not grant quota or compliance approval to this project, a fork, or any operator. Google currently provides a default project quota; a deployment that needs quota beyond the default must complete its own audit and quota-extension process.

Accordingly:

• Contributions that are technically independent of enhanced YouTube Data API access can continue separately.
• No shared credentials, quota, or approval would be represented as transferring from one deployment to another.
• Approval-dependent API work should remain separate until upstream agrees on the design boundary and the relevant deployment has the required Google/YouTube approval.
• The implementation must clearly identify authorized write actions, the affected channel, and playlist visibility, and obtain express user consent before executing them.

Data and feature boundary

• Category suggestions are private, editable organizational aids for the authorizing user—not official YouTube categories, public scores, or channel profiles.
• Authorized subscription, channel, playlist, and mapping data is not exposed to other users.
• Browser cookies, Watch Later cookie import, scraping, media download, subtitle/audio download, and unrelated local research tools are outside this API proposal.
• The proposal does not change SuperBrain's existing analyzer design. Any future use of YouTube API data as model input should receive its own explicit policy and privacy review.

Suggested implementation sequence after design agreement

1. Document the self-hosted configuration, data flow, endpoint/scope inventory, and fail-closed feature boundary.
2. Add per-deployment OAuth connection and read-only channel/subscription discovery.
3. Add the bulk selection, preview, and recorded-consent UI without automatic writes.
4. Add private playlist creation and idempotent, resumable synchronization with quota controls.
5. Add pause, correction, disconnect/revoke, deletion, lifecycle tests, and reviewer-visible documentation.

Each stage should be independently reviewable, covered by focused tests, and avoid bundling fork-specific deployment configuration.

Questions for maintainers

1. Is private, opt-in subscription organization into category playlists a good fit for SuperBrain's upstream product direction?
2. Is the self-hosted, per-operator Google Cloud/OAuth model the right initial boundary?
3. Does the proposed one-time bulk consent plus ongoing pause/revoke controls match the intended user experience?
4. Should configurable private taxonomy be agreed first as a prerequisite, or should the OAuth/playlist design remain independent from it?
5. If the direction is acceptable, would you prefer a short design document PR before any implementation PRs?

Official references

• YouTube Data API quota and compliance audits
• YouTube API Services Developer Policies
• YouTube developer-policy guidance
• YouTube Data API reference