🎬 yt-cap-eagle

Save YouTube thumbnails to Eagle with a single keystroke

---

Press ⌘⇧Y on any YouTube video page to preview and save the highest-quality thumbnail directly to Eagle.

🇯🇵 日本語版 README はこちら

✨ Features

	Feature	Description
🖼️	Hi-res thumbnails	Automatically resolves the best quality: maxresdefault → sddefault → hqdefault
⌨️	Keyboard shortcut	⌘⇧Y / Ctrl+Shift+Y to instantly show the preview
👁️	Preview before save	Confirm the thumbnail, then Enter to save or Escape to cancel
📂	Flexible destination	Enter for default folder, ⌘Enter for inbox
🎯	Broad URL support	Works on regular videos, Shorts, and youtu.be short links
🔧	Settings page	Configure Eagle API connection and default folder via the extension options

🔧 Tech Stack

Chrome Extension (Manifest V3)
├── TypeScript 5.4          … Type-safe development
├── Eagle Web API V1        … Thumbnail registration
├── Chrome Scripting API    … Content script injection
├── Chrome Storage API      … Persistent settings
└── Chrome Notifications    … Save completion alerts

🚀 Setup

Prerequisites

• Eagle installed and running
• Node.js installed
• Google Chrome or any Chromium-based browser

Installation

# 1. Clone the repository
git clone https://github.com/P0KEBAN/yt-cap-eagle.git
cd yt-cap-eagle

# 2. Install dependencies
npm install

# 3. Build TypeScript
npm run build

Load into Chrome

1. Open chrome://extensions
2. Enable Developer mode (toggle in the top-right corner)
3. Click "Load unpacked"
4. Select the cloned folder

Tip

After making code changes, run npm run build and click the reload button on chrome://extensions.

📖 Usage

                ┌──────────────────────────────┐
                │   Open a YouTube video page   │
                └──────────────┬───────────────┘
                               │
                               ▼
                ┌──────────────────────────────┐
                │   ⌘⇧Y  or  toolbar button    │
                └──────────────┬───────────────┘
                               │
                               ▼
                ┌──────────────────────────────┐
                │   Thumbnail preview appears   │
                └──────────────┬───────────────┘
                               │
                    ┌──────────┴──────────┐
                    ▼                     ▼
          ┌─────────────────┐   ┌─────────────────┐
          │  Enter: Save     │   │  Escape: Cancel │
          │  ⌘Enter: Inbox   │   │                 │
          └─────────────────┘   └─────────────────┘

Initial Setup

1. Right-click the extension icon → select "Options"
2. Configure the Eagle API connection
3. Click "Test connection" to verify

Note

If the shortcut doesn't work, go to chrome://extensions/shortcuts and manually set the shortcut for yt-cap. The suggested_key in the manifest is only a suggestion and may not be automatically assigned by Chrome.

Changing the Default Save Folder

You can change the thumbnail save destination by setting the "Default folder ID" in the options page.

1. In the Eagle app, right-click the folder you want to save to
2. Select "Copy Link"
3. From the copied URL (e.g. http://localhost:41595/folder?id=XXXXX), copy the XXXXX part (the folder ID)
4. Paste it into the "Default folder ID" field in the options page and save

Tip

Leave the folder ID empty to save to Eagle's default location.

📁 Project Structure

yt-cap-eagle/
├── 📄 manifest.json        … Chrome extension manifest (MV3)
├── 📦 package.json          … npm config & build scripts
├── ⚙️ tsconfig.json         … TypeScript configuration
├── 🎨 icons/                … Extension icons (16/48/128px)
├── 📂 src/
│   ├── background.ts       … Service Worker (main logic)
│   ├── content.ts           … Content script (preview UI)
│   ├── i18n.ts              … Internationalization (en/ja)
│   ├── options.html         … Options page HTML
│   ├── options.ts           … Options page logic
│   ├── options.css          … Options page styles
│   ├── overlay.css          … Preview overlay styles
│   └── types.ts             … Type definitions
├── 📂 dist/                 … Build output (generated)
└── 📂 docs/                 … Dev notes & specs

🛠️ Development

# Type-check only
npm run typecheck

# Build
npm run build

⚠️ Known Limitations

• Saving will fail if the Eagle desktop app is not running
• Only works on YouTube pages
• Thumbnails may not be available for private or age-restricted videos

📄 License

This project is licensed under the MIT License.

---

⬆ Back to top

Made with ❤️ for Eagle users