Set up YouTube
Add YouTube channels, turn on live stream checks with an API key and sign in to see your subscriptions.
YouTube works in three steps, and each one adds more:
- Channels only. Up Next reads each channel’s RSS feed, which needs no account. Uploads from the last 7 days show in the feed. Set a channel’s
notify.uploadsinchannels.ymlto be notified about new ones. - An API key. Up Next also looks the videos up, so live streams show as live, with viewer counts, and scheduled streams as upcoming.
- Signing in with Google. Up Next also reads your subscriptions. Uploads and live streams from subscriptions that aren’t in
channels.ymlshow in their own group, andupnext channel addcan pick from them.
Signing in also covers the video lookups, so with step 3 you don’t need the API key from step 2.
Add channels
Add a channel by its ID, which starts with UC, or paste its /channel/ URL:
upnext channel add youtube UCxxxxxxxxxxxxxxxxxxxxxx
To find a channel’s ID, open the channel, select the description, then Share channel and Copy channel ID.
A channel you’ve just added doesn’t notify you about its existing uploads. Once you’ve signed in with Google, you can pick from your subscriptions instead. See Pick from your subscriptions.
Create a Google Cloud project
Both the API key and the sign-in come from a Google Cloud project:
- Open the Google Cloud console and create a project, such as
upnext. - Go to APIs & Services, then Library, find YouTube Data API v3 and select Enable.
Get an API key
Skip this if you’re going to sign in.
- In the project, go to APIs & Services, then Credentials.
- Select Create credentials, then API key.
- Edit the key, and under API restrictions pick Restrict key and choose YouTube Data API v3.
- Put it in
config.yml, then restart the daemon:
youtube:
api_key: your-api-key
systemctl --user restart upnext.service
Sign in with Google
Set up the consent screen
- In the project, open Google Auth Platform and select Get started.
- Fill in App information with an app name, such as
Up Next, and your email address. - Under Audience, choose External.
- Add your email address as the contact, agree to the policy and select Create.
- Go to Branding. Google needs a home page and a privacy policy before it publishes an app:
- Application home page:
https://upnext.timmo.dev - Application privacy policy link:
https://upnext.timmo.dev/privacy - Authorised domains:
timmo.dev - Leave the logo empty. Adding one means Google has to verify the app.
- Application home page:
- Select Save.
- Go to Audience and select Publish app, then Confirm.
Publishing matters. While an app is in testing, Google expires its sign-ins after 7 days, and you’d need to run upnext auth youtube every week. A published app that Google hasn’t verified works for up to 100 people, which is plenty for your own use. Google warns you that it isn’t verified when you sign in.
Create an OAuth client
- Go to Clients and select Create client.
- Choose Desktop app as the application type, and give it a name.
- Select Create, then copy the Client ID and Client secret.
- Put them in
config.yml, then restart the daemon:
youtube:
client_id: your-client-id.apps.googleusercontent.com
client_secret: your-client-secret
systemctl --user restart upnext.service
A desktop client doesn’t need a redirect URL. Up Next listens on http://127.0.0.1:8081 only while you sign in.
Sign in
upnext auth youtube
Your browser opens Google’s sign-in page:
- Pick your Google account. If you have a brand account for YouTube, pick that instead.
- Google says it hasn’t verified the app. Select Advanced, then Go to Up Next (unsafe). It’s your own app, so this is expected.
- Allow Up Next to view your YouTube account, then select Continue.
The command prints Signed in. once the daemon has read your subscriptions. The daemon keeps a refresh token in state.json. If Google stops accepting it, the YouTube status in the feed changes to auth-required. Run upnext auth youtube again.
Pick from your subscriptions
Once you’ve signed in, run upnext channel add with no channel ID to pick from your subscriptions:
upnext channel add youtube
Move with Up and Down, press Space to pick each channel, then Enter to add them. Add --open to open their live streams as soon as they start.
Channels in channels.yml come first, and they’re the only ones that notify you. Your other subscriptions still show, so you can see what’s new:
- Their uploads from the last 7 days go in the panel’s Other uploads group.
- Their live streams show after your channels’, ordered by viewers.
- Their scheduled streams don’t show.
Use a playlist for watch later
YouTube doesn’t let apps read or change its own Watch later list, so Up Next can use one of your playlists instead. Saved YouTube videos then go in that playlist, and you can add to it from YouTube on any device.
- On YouTube, create a playlist, such as
Up Next. Keep it private if you like. - Open it and copy its URL, or the ID after
list=. - Put it in
config.yml, then restart the daemon:
youtube:
watch_later_playlist: https://www.youtube.com/playlist?list=PLxxxxxxxxxxxxxxxx
systemctl --user restart upnext.service
Then sign in again, so Up Next can change playlists as well as read them:
upnext auth youtube
Google now asks to let Up Next manage your YouTube account, which is the narrowest permission that allows changing a playlist.
Once it’s set up:
- Videos in the playlist show in Watch later, checked every
youtube.poll_intervalseconds. The panel’s last row in Watch later opens the playlist on YouTube. upnext queue addand the panel’s Watch later menu item add YouTube videos to the playlist. Other links still go in the local queue.- Marking a video watched removes it from the playlist.
- A saved video only shows in Watch later, so saving a live stream or an upload moves it out of its other section.
- Deleted and private videos in the playlist are left out.
If you signed in before setting the playlist, the YouTube status changes to auth-required until you run upnext auth youtube again. Videos already in the local queue stay there.
Quota
The YouTube Data API gives each project 10,000 units of quota a day. Each check, every youtube.poll_interval seconds (600 by default), costs about:
- 1 unit per 50 subscriptions, to read them.
- 1 unit per 50 videos to look up. Up Next looks up every video in a
channels.ymlchannel’s feed, but only the last 7 days of uploads from other subscriptions. - 1 unit per 50 videos in the watch-later playlist, and 1 for its title, if you’ve set one. Adding or removing a video costs 50 units each time.
- While YouTube’s RSS feeds are down, 1 unit per channel in
channels.yml, to read its uploads through the API instead.
With a few hundred subscriptions that comes to around 2,000 units a day, well within the limit. The feeds tend to fail overnight, so set quiet_hours to cover those hours and checks slow to youtube.quiet_poll_interval while the fallback is costing more. If you do hit the limit, the YouTube status shows the error until quota resets at midnight Pacific time. Raise youtube.poll_interval to check less often.