YouTube Queue

Live app: https://branets-dasha.github.io/youtube-queue-app/

A purely client-side, single-page web app that turns your YouTube subscription feed into a chronological queue that plays in succession.

Features:

• Loads all videos from your subscriptions back to a chosen cutoff point.
• Plays videos in a built-in YouTube player, automatically advancing through the queue.
• Advances the cutoff as the videos are watched or skipped, so handled videos are eventually pruned and never come back.
• Remembers the watch position per video.
• Videos can be marked to skip, or play at a certain speed.
• Channel customization: ignore or set default playback speed.
• Keyboard support.
• Data is stored locally. Nothing is sent to any server other than Google's.

Built by Claude. This app was designed and built end to end by Claude (Anthropic's Claude Code, Opus) — from the initial architecture through every feature, refactor, and bug fix — working at its owner's direction. The whole codebase is Claude's work.

Anyone can use this app hosted at https://branets-dasha.github.io/youtube-queue-app/ or host it wherever they please.

No backend. No framework. No build step. No bundler. Plain HTML, CSS, and ES modules.

The only external network resources are:

1. The Google Identity Services script (https://accounts.google.com/gsi/client).
2. The YouTube Data API v3 (https://www.googleapis.com/youtube/v3), for loading subscriptions and enabling "like" button.
3. The YouTube IFrame Player API (https://www.youtube.com/iframe_api), for the on-page player.

To use the app you need to provide your own Google OAuth Client ID (see below). Your OAuth access token lives in memory only — it is never written to localStorage or IndexedDB. There is no client secret and no API key anywhere; the OAuth token authorizes every call.

The OAuth scope is https://www.googleapis.com/auth/youtube.force-ssl ("see, edit, and permanently delete your YouTube videos, ratings, comments and captions"). Such a permissive scope is needed to enable the "like" button. All the other operations the app does using YouTube Data API are read-only.

Part 1 — For users: using the hosted app

The app runs entirely in your browser. It fetches your data using the YouTube Data API. The API needs to know which app (client) is contacting it — to count request quotas and other things. I personally use a test Client ID that does not have the capacity to support many users, so each user brings their own Client ID from their own free Google Cloud project. The setup is a bit complicated, but you only need to do it once.

1. Create your OAuth 2.0 Client ID (Web application)

1. Go to the Google Cloud Console and create or select a project (the button next to "Google Cloud").
2. Go to APIs and services → Library, enable the YouTube Data API v3.
3. Go to OAuth consent screen and configure it (User type: External is fine). In the Audience tab add your own Google account under Test users. In the Data access tab add the scope https://www.googleapis.com/auth/youtube.force-ssl — it covers reading your subscriptions/uploads and liking videos from the player.
4. Go to the Clients tab and create a new client.

   • Application type: Web application.

   • Under Authorized JavaScript origins, add exactly:

     https://branets-dasha.github.io
     

   • You do not need to set an Authorized redirect URI for the token model.

5. Click Create and copy the Client ID (it looks like 1234567890-abcdefg.apps.googleusercontent.com).

2. First run

1. Open https://branets-dasha.github.io/youtube-queue-app/.
2. Paste your Client ID into the setup panel and save it. The panel shows the exact origin it is running on, so you can confirm it matches what you registered.
3. Pick a start cutoff (defaults to 7 days ago). Everything published at or before this instant is treated as already handled and will never enter your queue.
4. Click Sign in and approve the YouTube permission in the Google popup. Because the app is unverified and the scope is sensitive, Google shows a "Google hasn't verified this app" screen — click Advanced → continue. Signing in only authorizes; it does not auto-fetch.
   • Since the OAuth token is memory-only, you'll re-approve on each fresh load of the page.
5. Click Fetch new or Refresh all to pull videos from your subscriptions into the queue. The app does not auto-refresh, so you'll need to use one of these buttons manually whenever you want to re-scan your subscriptions.
   • Fetch new loads new videos to the point of the last saved video. It's cheaper in terms of quota.
   • Refresh all loads videos all the way back to the cutoff. Use it to pull videos from newly subscribed channels, or if you want to update saved data.
   • Neither button will duplicate the items or reset their status.

Connect the player to your YouTube account (optional)

The embedded video player is a cross-origin YouTube iframe — it's a window into youtube.com from the app page. If tracking prevention is enabled (in modern browsers it's often on by default), the browser will not send cookies belonging to youtube.com to that iframe. It means that the player will not recognize your YouTube login, and will run signed-out, showing ads even if you have YouTube Premium.

Disable tracking prevention for the app's page to connect the player to your YouTube account. This step is optional — playback works without it. It only affects account-connected / Premium (ad-free) playback. Note that connecting the player does not make your watches count toward a video's public view count — see Limitations. To connect the player, allow YouTube's third-party cookies for the app:

• Edge: turn off Tracking prevention for https://branets-dasha.github.io — via the site-info / shield icon in the address bar, or Settings → Privacy, search, and services → Tracking prevention → Exceptions. Alternatively, allow-list [*.]youtube.com under cookies.
• Chrome / others: allow third-party cookies for the site — via the cookie / tune icon in the address bar — or add a site exception for [*.]youtube.com.

This is separate from signing into the app. Signing in with Google OAuth only authorizes the Data API (your subscriptions, marking, likes) — it does not sign the player in. Whether the player recognizes your account and Premium depends entirely on whether your browser lets the youtube.com iframe use its cookies as a third party.

Quota notes

Each YouTube Data API call spends quota units associated with your Client. The default daily quota is 10,000 units. If you hit it you'll see a friendly "daily quota reached" message; it resets at midnight Pacific time.

The app is deliberately quota-frugal. It uses the following methods:

• subscriptions.list — gets a list of subscribed channels. 1 unit per page (page size is 50 results max).
• playlistItems.list — gets channel videos. 1 unit per page, requested per channel, paging stops once it reaches the cutoff point (for "Refresh all") or the point of the last saved video + 6h buffer (for "Fetch new"). Upload playlist ids are derived cheaply by replacing the leading UC of a channel id with UU (no extra call); the rare non-UC channel costs one additional channels.list request. Adding a playlist to the stash pages through it too (1 unit per 50 videos), plus one playlists.list for its title.
• videos.list?part=contentDetails,status,snippet — backfills video durations, descriptions and embeddability, and on "Refresh all" confirms that a video its channel's listing no longer returned is really gone before deleting it. Batched ≤ 50 ids per call, 1 unit each.
• videos.rate (the Like button) — roughly 50 units per like/unlike.

Data & privacy

• Access token: in memory only; discarded when you close/refresh the tab. Re-requested on demand and silently refreshed when a call returns 401 or the token is near expiry. Signing out revokes it with Google.
• Persisted in localStorage:
  • yqa_client_id — your OAuth Client ID.
  • yqa_start_cutoff — the floor (deletion/fetch boundary).
  • yqa_cutoff — the live handled-prefix cutoff marker.
  • yqa_channels — channel id → { title, avatarUrl } map for avatars.
  • yqa_channel_prefs — channel id → { ignored?, speed? } from the Channels page (absent when nothing is set).
  • yqa_playback_speed — the current player speed.
  • yqa_default_speed — the "Default speed" setting (absent when off).
  • yqa_hide_marked — the "Hide skipped" toggle.
• Persisted in IndexedDB: your video records in database yqa, keyed by videoId, in two object stores — videos and stash. IndexedDB is required — if it can't be opened the app stops with an error.
• The like state is stored locally and is never fetched back from YouTube, so a like/unlike you make directly on YouTube will not be reflected here.
• Nothing is ever sent to any server other than Google's.

To reset, use Change Client ID / Change cutoff in the toolbar, or clear the site's storage in your browser dev tools.

Known limitations

• Watching a video here does not count toward its public view count. YouTube only counts a playback that's started with the player's native play button; this app starts playback programmatically (its own controls plus auto-advance) through the IFrame API, which that rule excludes.
• Likes made on YouTube are not reflected here. The like state is tracked locally (never fetched), so liking/unliking directly on YouTube won't show up in the app. But liking/unliking in the app will be properly reflected on YouTube regardless of initial state.
• Resume only covers in-app playback position (tracked by the embedded player); it does not sync with YouTube's own watch history.
• Shorts are detected by a heuristic (duration ≤ 90s) — there is no separate Shorts filter, and the API exposes no true isShort flag, so the "Shorts" badge can be wrong for edge cases.
• One tab per page. A second tab of the same page stops with a "close the other tab and reload" message so the two can't write over each other. Different pages are fine open at once — the queue and the stash write separate stores, and the Channels page writes no videos at all.
• Mixes and Watch Later can't be added to the stash. The YouTube Data API doesn't list their videos; copy them into a playlist of your own and add that instead.
• Non-embeddable videos can't play in the on-page player and open on YouTube instead; auto-advance skips them.
• YouTube's own player controls are behind one key. Tab deliberately skips the video frame: focus inside a cross-origin frame swallows every keypress, so the app's shortcuts — Esc included — stop working the moment it lands there. Press \ to put focus inside the frame on purpose: YouTube's own keys then work at once (c toggles captions), and Tab reaches its settings menu — caption language, audio track, quality. Shift+Tab brings you back from any of its controls; straight after \, press Tab once first (Tab forward is a long walk through the related-videos drawer). The app's shortcuts are off while you're inside.
• YouTube's uploads playlist can lag real-time by a short interval, so a very fresh upload may take a few minutes to appear on refresh.

Part 2 — For developers: running it yourself

Serving locally

There is no build step — it's static HTML, CSS, and ES modules — but OAuth via Google Identity Services will not work if you open index.html directly as a file:// URL. You must serve the folder over http://localhost.

Pick one (run from inside this project directory):

# Python 3
python -m http.server 5173

# or Node
npx serve -l 5173

# or
npx http-server -p 5173

Then open:

http://localhost:5173

For local development, register your localhost origin instead of the hosted one: in your OAuth client's Authorized JavaScript origins, add http://localhost:5173 (or whichever port you serve on — localhost is a valid OAuth origin). Make sure the port matches. You can register both the localhost origin and the https://branets-dasha.github.io origin on the same Client ID.

Project layout

File	Purpose
index.html	DOM skeleton + loads GIS, the IFrame API (via player.js), and js/subscriptions-page.js
stash.html	DOM skeleton for the stash page; loads GIS, the IFrame API (via player.js), and js/stash-page.js
channels.html	Standalone channel-list page (per-channel prefs); loads js/channels-page.js
styles.css	Light/dark, responsive two-pane styling; player container query
README.md	This file
js/config.js	Constants (API base, OAuth scope, storage keys, IndexedDB names, limits)
js/store.js	Persistence: IndexedDB video CRUD + localStorage for id/cutoff/settings/channels
js/migrations.js	All data migrations, in one place (records, channel prefs, localStorage keys)
js/migrations.test.mjs	Node unit tests for js/migrations.js (run: node js/migrations.test.mjs)
js/auth.js	GIS token client: init, request/refresh/revoke, in-memory token
js/api.js	YouTube fetch: subscriptions, uploads, videos.list details, videos.rate; errors
js/queue.js	PURE queue logic (no browser globals; Node-importable & unit-testable)
js/queue.test.mjs	Node unit tests for js/queue.js (run: node js/queue.test.mjs)
js/player.js	YouTube IFrame Player API wrapper (load/play, speed, seek, resume, fullscreen)
js/ui.js	XSS-safe DOM building (cards, player meta) and state screens
js/toast.js	Top-right toast notifications (progress / success / error / info)
js/page-chrome.js	Chrome shared by every page: tab lock, fatal-storage screens, curtain, iframe focus guard
js/subscriptions-page.js	Wiring: auth → fetch → store → queue → ui/player, event binding, shortcuts
js/stash-page.js	Stash page wiring: add by link, store → queue → ui/player, event binding, shortcuts

Testing the pure logic in Node

js/queue.js references no browser globals, so it is imported directly by the test file. Run the suite from the repo root:

node js/queue.test.mjs
node js/migrations.test.mjs