SignalYouTube captions for channels you manage
This is an owner-authorized partial feature. It does not replace public transcript services. Captions are available only to the SignalShelf account that connected the channel.
Authorization and access
Connect a YouTube channel from Dashboard → Connections. SignalShelf uses Google OAuth and the official YouTube Data API captions.list and captions.download methods. Google requires the authorizing account to have permission to edit the video.
The required youtube.force-ssl scope is broad: Google describes it as permission to view, edit, and permanently delete YouTube videos, ratings, comments, and captions. SignalShelf stores an encrypted refresh token, uses it only for this owner-caption flow, and does not use it to modify or delete YouTube content.
Request and response
Use GET /v1/youtube/video/transcript with url. Optional language selects a matching available caption language. original_audio=true selects captions matching YouTube’s identified original audio language and takes precedence over language. If no matching track exists, the response contains transcript: null and costs zero SignalShelf credits.
A successful fresh transcript costs one SignalShelf credit. Accepted account-scoped cache hits are free. Response segments include text, startMs, endMs, and startTimeText, plus transcript_only_text and language.
If YouTube reports quotaExceeded or a recognized rate limit, SignalShelf returns HTTP 429 and refunds the reserved SignalShelf credit. The response does not imply the provider quota has reset; check the Google API Console or request additional YouTube Data API quota.
GET https://signalshelf.dev/v1/youtube/video/transcript?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DYOUR_VIDEO_ID
x-api-key: YOUR_SERVER_SIDE_KEYQuota and retention
A successful request can use up to 251 YouTube Data API quota units: one for videos.list, 50 for captions.list, and 200 for captions.download. Requests without a matching track use fewer units. SignalShelf reserves a default shared limit of 20 transcript attempts per UTC day to protect the Google project quota; an operator may configure YOUTUBE_OWNER_TRANSCRIPTS_DAILY_LIMIT from 1 to 35. The cap counts attempts even when YouTube returns an error because provider quota may already have been used.
Transcript cache entries are scoped by SignalShelf user and expire within seven days. They are deleted when that user disconnects the channel. Teams do not receive access to another member’s connected channel or cached transcripts. Google authorization is refreshed on a live fetch; stored data older than 30 days is not served without reauthorization.
Operator setup and production gate
Create a separate Google OAuth web application, enable YouTube Data API v3, and register https://signalshelf.dev/api/auth/youtube-owner/callback as an authorized redirect URI. Set YOUTUBE_OWNER_OAUTH_CLIENT_ID, YOUTUBE_OWNER_OAUTH_CLIENT_SECRET, and a 64-character hexadecimal YOUTUBE_OWNER_TOKEN_ENCRYPTION_KEY. Keep credentials outside the repository.
Production is unavailable until the Google app is verified and YouTube source, privacy, retention, and paid-use reviews are complete. The owner must explicitly set both YOUTUBE_SOURCE_AUTHORIZED=true and YOUTUBE_OWNER_CAPTIONS_AUTHORIZED=true only after those checks. A locally simulated route is not evidence of live Google behavior, app approval, or public-video parity.
YOUTUBE_OWNER_OAUTH_CLIENT_ID=
YOUTUBE_OWNER_OAUTH_CLIENT_SECRET=
YOUTUBE_OWNER_TOKEN_ENCRYPTION_KEY=
# Set only after approval and review
YOUTUBE_SOURCE_AUTHORIZED=false
YOUTUBE_OWNER_CAPTIONS_AUTHORIZED=false