Circle to Search + Song Finder

Enterprise Manifest V3 Chromium Extension for Multi-Engine Visual Search, Tab Audio Music Recognition & On-Screen Translation

Engineered by Farhan Muh Tasim (AKA frnAlt / Gtajisan)

---

📌 Executive Summary & Evolution

Circle to Search + Song Finder brings Google's Android-exclusive Circle to Search gesture interaction and real-time tab audio music recognition to desktop Chromium browsers (Google Chrome, Microsoft Edge, Brave, Opera, Vivaldi).

💡 Project Background & Evolution

1. Google's Circle to Search: Google introduced Circle to Search exclusively for select Android flagship devices. However, it locks users into Google Search, lacks local OCR privacy, and cannot recognize tab audio.
2. The Android Open-Source App: Developer Farhan Muh Tasim (@frnAlt) created the open-source Android app frnAlt/CircleToSearch to provide multi-engine visual search and offline OCR for any Android device.
3. The Web Extension Port: This project ports the visual drawing overlay into a high-performance Manifest V3 Browser Extension, integrating tab audio music identification inspired by fillwithjoy1/circle-to-search.

---

📸 Complete Extension Visual Showcase

1. Freehand Circle & Box Selection (Alt+S) Draw smooth glowing circles or drag boxes over any webpage	2. Tab Audio Music Finder (Alt+M) Live equalizer spectrum & song identification card
3. On-Screen Local OCR & Instant Translation Extract selectable text & translate into target languages	4. Extension Options & Theme Customizer Configure stroke colors, neon aura, search engines & keys

---

✨ Core Features & Technical Capabilities

• ⭕ Freehand Circle & Box Drawing Overlay:
  • Injects a high-performance transparent canvas overlay upon pressing hotkeys (Alt+S / Cmd+Shift+S).
  • Supports smooth glowing Freehand Circle / Lasso drawing and Rectangular Drag selection modes.
  • Automatically calculates selection bounds with high-DPI display scaling (window.devicePixelRatio).
• 🔍 Multi-Engine Reverse Image Search:
  • Instantly search selected regions using Google Lens, Bing Visual Search, Yandex Images, or TinEye.
• 🎵 Tab Audio Music Recognition (Alt+M):
  • Captures tab audio streams using chrome.tabCapture.
  • Displays a live animated audio spectrum visualizer during sampling.
  • Identifies songs using AudD & Shazam APIs and renders track cards with album art, artist details, and direct links to Spotify, YouTube, and Apple Music.
• 📝 On-Device Local OCR:
  • Extracts text from images, videos, canvas, or locked web elements without cloud tracking.
• 🌐 Instant On-Screen Translation:
  • Translates foreign text from selected screen regions into target languages (English, Spanish, German, French, Chinese, Japanese, etc.).
• 🎨 Shadow DOM Style Isolation:
  • Encapsulated inside #cts-extension-overlay-root shadow root so host web page styles never interfere with extension drawing or modals.
• ⚙️ Customizable Aesthetics & Preferences:
  • Custom stroke color presets (Google Blue, Emerald Green, Crimson Red, Cyberpunk Cyan, Neon Purple), glowing aura toggles, and hotkey configurations.

---

🏗️ Architecture & Data Flow

flowchart TD
    User([User Keypress Alt+S / Alt+M]) --> BG[background.js Service Worker]
    BG -->|Injects / Messages| CS[content.js Shadow DOM Overlay]
    CS -->|Draw Circle / Drag Box| Canvas[HTML5 Canvas 2D]
    Canvas -->|Sends Bounds & DPR| BG
    BG -->|Capture Viewport| Screenshot[chrome.tabs.captureVisibleTab]
    BG -->|Sends Screenshot & Path| Offscreen[offscreen.js Canvas Worker]
    Offscreen -->|Crop Snippet| CroppedImg[PNG Image Blob]
    
    CroppedImg -->|Search Action| Lens[Google Lens / Bing / Yandex]
    CroppedImg -->|OCR / Translate Action| OCRWorker[Local Tesseract & Translate API]
    
    BG -->|Tab Audio StreamId| OffscreenAudio[offscreen.js Audio Recorder]
    OffscreenAudio -->|Query Audio Sample| AudD[AudD / Shazam Music API]
    AudD -->|Song Metadata| MusicWidget[Content Script Spectrum Widget]

Loading

---

⌨️ Keyboard Shortcuts

Feature	Windows / Linux	macOS	Action
Circle to Search	Alt + S	Cmd + Shift + S	Open visual selection overlay on active tab
Song Finder	Alt + M	Cmd + Shift + M	Sample tab audio and identify playing song
Close Overlay	Esc	Esc	Dismiss active overlay or music widget

---

📊 Feature Comparison Matrix

Feature	Official Google CTS (Android)	Standard Extensions	Circle to Search Web Extension
Cross-Platform (Win/Mac/Linux)	❌	❌	✅
Supported Browsers	N/A	Chrome Only	Chrome, Edge, Brave, Opera, Vivaldi
Freehand Circle Drawing	✅	❌	✅
Multi-Engine Visual Search	❌ (Google Only)	❌	✅ (Google Lens, Bing, Yandex, TinEye)
Tab Audio Song Recognition	❌	❌	✅ (Alt+M)
Instant On-Screen Translation	✅	❌	✅
Offline Local OCR	❌ (Cloud Only)	❌	✅
Copy Snippet to Clipboard	❌	❌	✅
Open Source	❌	❌	✅ (MIT License)

---

📂 Repository Directory Sitemap

CircleToSearch/
├── manifest.json         # Manifest V3 configuration & permissions
├── background.js        # Background service worker (commands, tabCapture, IPC)
├── content.js           # Shadow DOM overlay, canvas drawing & action bar
├── content.css          # Encapsulated CSS styles for overlay, widgets & modals
├── offscreen.html       # Offscreen DOM context for canvas & audio
├── offscreen.js         # Canvas cropping, freehand clipping, audio recorder & OCR
├── options.html         # Customization settings interface
├── options.js           # Settings persistence via chrome.storage.sync
├── options.css          # Options page design system
├── popup.html           # Extension toolbar popup
├── popup.js             # Extension toolbar popup logic
├── popup.css            # Toolbar popup styling
├── icons/               # 16px, 32px, 48px, 128px PNG icons
├── docs/screenshots/    # Showcase graphics & documentation assets
├── CONTRIBUTING.md      # Open-source contribution guidelines
└── .github/workflows/   # CI/CD Release Automation (release.yml)

---

🚀 Quick Start / Local Installation

Method A: Download Release Package (ZIP or TAR.GZ)

1. Download either circle-to-search-extension.zip or the non-zip tarball circle-to-search-extension.tar.gz from the Latest Release.
2. Extract the archive to a local folder.
3. Open your browser's extensions page (chrome://extensions, edge://extensions, or brave://extensions).
4. Toggle Developer mode in the top right corner.
5. Click Load unpacked and select the unzipped circle-to-search-extension folder.

Method B: Clone Source Code

1. Clone the Repository:

   git clone https://github.com/frnAlt/CircleToSearch.git
   cd CircleToSearch

2. Open Extensions Page: chrome://extensions / edge://extensions / brave://extensions
3. Enable Developer Mode: Toggle Developer mode in the top right corner.
4. Load Unpacked: Click Load unpacked and select the CircleToSearch directory containing manifest.json.
5. Start Using: Press Alt+S for Circle to Search, or Alt+M for Music Search!

---

🤖 Automated Release CI/CD Pipeline

The project includes an automated GitHub Actions workflow (.github/workflows/release.yml).

When a release tag is pushed:

git tag v1.1.0
git push origin v1.1.0

The GitHub Actions runner automatically:

1. Performs JavaScript syntax verification.
2. Bundles all extension assets into standard .zip (circle-to-search-extension.zip) and non-zip .tar.gz (circle-to-search-extension.tar.gz) release archives.
3. Creates a published GitHub Release and attaches both release assets automatically via softprops/action-gh-release@v2.

---

👨‍💻 Developer & Maintainer Information

This open-source project is developed and maintained by Farhan Muh Tasim, known across developer platforms as frnAlt and Gtajisan.

• Lead Developer: Farhan Muh Tasim
• Primary GitHub Account: frnAlt (https://github.com/frnAlt)
• Developer Handle / Alias: Gtajisan (https://github.com/gtajisan)
• Primary Source Base: frnAlt/CircleToSearch
• Feature Reference: fillwithjoy1/circle-to-search

---

🤝 Contributing

We welcome open-source contributions! Please review our CONTRIBUTING.md guide for details on local development setups, syntax checks, and pull request guidelines.

---

📄 License

Distributed under the MIT License. See LICENSE for details.