reeln-plugin-google

A reeln-cli plugin for Google platform integration — YouTube livestreams, uploads, playlists, and comments.

Install

pip install reeln-plugin-google

Or for development:

git clone https://github.com/StreamnDad/reeln-plugin-google
cd reeln-plugin-google
make dev-install

Google Cloud Setup

Before using this plugin, you need a Google Cloud project with OAuth credentials. Follow these steps exactly.

1. Create a GCP Project

1. Go to Google Cloud Console
2. Click the project dropdown (top-left) → New Project
3. Name it (e.g., reeln-livestream) and click Create
4. Select the new project from the dropdown

2. Enable the YouTube Data API v3

1. Go to APIs & Services → Library
2. Search for YouTube Data API v3
3. Click it and press Enable

3. Configure the OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Select External user type → Create
3. Fill in:
   • App name — anything (e.g., reeln)
   • User support email — your Gmail
   • Developer contact email — your Gmail
4. Click Save and Continue
5. On the Scopes page, click Add or Remove Scopes and add:
   • https://www.googleapis.com/auth/youtube
   • https://www.googleapis.com/auth/youtube.upload
   • https://www.googleapis.com/auth/youtube.force-ssl
6. Click Update → Save and Continue
7. On the Test users page, click Add Users and enter your Google email address
8. Click Save and Continue → Back to Dashboard

Testing vs Production mode: Your app starts in "Testing" mode with these limitations:

• Only the test users you added can authorize
• OAuth tokens expire every 7 days (you'll need to re-authorize)
• Maximum 100 test users

Once your setup is stable, you can publish to "Production" mode to remove token expiry and the user cap. Production apps requesting sensitive scopes require Google verification, but apps for personal use with limited users typically pass quickly.

4. Create OAuth 2.0 Client ID

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Name it (e.g., reeln-desktop) and click Create
5. Click Download JSON (the download icon)

5. Protect the Secrets File

The downloaded client_secrets.json contains your OAuth client ID and client secret. Treat it like a password.

# Move it somewhere safe outside your repo
mv ~/Downloads/client_secret_*.json ~/.config/reeln/client_secrets.json

# Restrict permissions (macOS/Linux)
chmod 600 ~/.config/reeln/client_secrets.json

Never commit this file to git. It allows anyone to impersonate your application and request access to YouTube accounts.

Plugin Configuration

Add the Google plugin to your reeln config. All capabilities are off by default — enable only what you need:

{
  "plugins": {
    "enabled": ["google"],
    "settings": {
      "google": {
        "client_secrets_file": "~/.config/reeln/client_secrets.json",
        "create_livestream": true,
        "manage_playlists": true,
        "upload_highlights": true,
        "upload_shorts": false,
        "privacy_status": "unlisted"
      }
    }
  }
}

Feature Flags

Every capability must be explicitly enabled. Nothing runs unless you set the flag to true.

Other Options

First Run

On the first reeln game init, the plugin opens a browser for OAuth consent:

1. Sign in with the Google account you added as a test user
2. Click Continue (past the "unverified app" warning)
3. Grant the requested YouTube permissions
4. The browser shows "The authentication flow has completed" — you can close it

Credentials are cached at ~/Library/Application Support/reeln/data/google/oauth.json (macOS) or ~/.local/share/reeln/data/google/oauth.json (Linux). The file is automatically chmod 600'd. Tokens auto-refresh on subsequent runs — you won't see the browser again unless tokens expire or you re-authenticate.

Troubleshooting

"Access blocked" or "Error 403: access_denied" You didn't add your Google email as a test user. Go to OAuth consent screen → Test users and add it.

"Quota exceeded" The YouTube Data API has a daily quota (default 10,000 units). Creating a livestream costs ~1,600 units. If you're hitting limits, check your quota dashboard.

Token expired after 7 days This happens in Testing mode. Either re-run to trigger the browser flow again, or publish your OAuth consent screen to Production mode (see Testing vs Production above).

"redirect_uri_mismatch" Your OAuth client type isn't set to Desktop app. Delete the credential and create a new one with the correct type.

How It Works

The plugin hooks into reeln-cli lifecycle events. Here's the typical game-day flow:

reeln game init
  └─ ON_GAME_INIT
       ├─ create_livestream → YouTube broadcast bound to your OBS stream key
       └─ manage_playlists  → per-game playlist (livestream auto-added if both enabled)

reeln highlights merge
  └─ ON_HIGHLIGHTS_MERGED
       └─ upload_highlights → upload merged video; auto-add to playlist if enabled

reeln render short
  └─ POST_RENDER (for each short)
       └─ upload_shorts → upload as YouTube Short (#Shorts appended to title)

reeln game finish
  ├─ ON_GAME_FINISH        → no-op (sibling plugins write to shared context)
  └─ ON_POST_GAME_FINISH   → append chapter markers to broadcast, reset state

Shared Context

The plugin writes results to context.shared so sibling plugins (e.g., a Discord notifier) can consume them:

The plugin also reads from shared context:

LLM Metadata

If an LLM plugin writes metadata to shared context before the upload hooks fire, the plugin uses it instead of auto-generating from game info:

Highlights — reads from shared["uploads"]["google"]:

Renders (Shorts / videos) — reads from shared["render_metadata"]:

Development

make dev-install    # uv venv + editable install with dev deps
make test           # pytest with 100% coverage
make lint           # ruff check
make format         # ruff format
make check          # lint + mypy + test

License

AGPL-3.0-only