{"id":18605859,"url":"https://github.com/varshneydevansh/filtertube","last_synced_at":"2026-02-04T12:09:13.636Z","repository":{"id":189297853,"uuid":"680181846","full_name":"varshneydevansh/FilterTube","owner":"varshneydevansh","description":"Filter YouTube videos by keywords, channels, and categories ","archived":false,"fork":false,"pushed_at":"2026-01-28T16:36:00.000Z","size":2464,"stargazers_count":50,"open_issues_count":15,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-29T07:37:36.948Z","etag":null,"topics":["blocker","brave","brave-extension","browser-extension","edge-extension","extension","extension-chrome","filter","firefox-extension","youtube","youtubekids"],"latest_commit_sha":null,"homepage":"https://filtertube.in/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/varshneydevansh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-18T14:38:17.000Z","updated_at":"2026-01-28T16:35:57.000Z","dependencies_parsed_at":"2025-05-01T16:22:45.619Z","dependency_job_id":"207bede7-23cf-4c00-8d94-05a1d846b732","html_url":"https://github.com/varshneydevansh/FilterTube","commit_stats":null,"previous_names":["varshneydevansh/filtertube"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/varshneydevansh/FilterTube","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varshneydevansh%2FFilterTube","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varshneydevansh%2FFilterTube/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varshneydevansh%2FFilterTube/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varshneydevansh%2FFilterTube/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/varshneydevansh","download_url":"https://codeload.github.com/varshneydevansh/FilterTube/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varshneydevansh%2FFilterTube/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29084091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blocker","brave","brave-extension","browser-extension","edge-extension","extension","extension-chrome","filter","firefox-extension","youtube","youtubekids"],"created_at":"2024-11-07T02:23:21.795Z","updated_at":"2026-02-04T12:09:13.619Z","avatar_url":"https://github.com/varshneydevansh.png","language":"JavaScript","funding_links":["https://ko-fi.com/filtertube"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/varshneydevansh/FilterTube/blob/master/icons/icon-128.png\" alt=\"FilterTube Icon\"\u003e\n  \u003ch1\u003eFilterTube\u003c/h1\u003e\n  \u003cp\u003ePeace of Mind for your Digital Space\u003c/p\u003e\n\u003c/div\u003e\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/varshneydevansh/FilterTube)\n\n[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/filtertube)\n\n## Overview\n\nFilterTube is a browser extension that gives you control over your YouTube feed. Filter videos, shorts, channels, and comments using keywords and smart rules—all processing happens privately on your device.\n\n## Features\n\n### Content Filtering\n\n- **Block by Keyword**: Hide videos with specific words in the title.\n- **Block Channels**: Paste Channel Name, `@handle`, `UCID`, or even `c/CustomURL`—FilterTube normalizes them all.\n- **Hide Shorts**: Optional toggle to remove every Shorts shelf and player hand-off.\n- **Smart Matching**: Choose partial or whole-word matching to stay strict or flexible.\n- **Shelf \u0026 Playlist Cleanup**: Refilters shelves and playlists so blocked creators stay gone even after navigation.\n\n### Channel \u0026 Data Management\n\n- **Multi-Profile with PIN Locks**: Account + child profiles, each with independent filters/settings; optional PIN lock gates UI until unlocked.\n- **Profile-Scoped Backups**: Auto-backup and manual export respect the active profile. Default (Master) can export full; non-default exports active-only.\n- **Encrypted Backups**: PBKDF2-SHA256 (150k) + AES-GCM. Encryption auto-enables when the active profile has a PIN (or you pick “Encrypted” format); background verifies PIN before encrypting.\n- **Handle Enrichment Queue**: Newly imported channels are resolved slowly in the background to avoid hammering YouTube.\n- **Kids Mode Profiles**: Maintain a separate, safer rule set for YouTube Kids without mixing it with the main profile; optional “Apply Kids list on main YouTube” sync toggle.\n\n### Comment Control\n\n- **Hide All Comments**: Remove the comments section entirely for a cleaner interface.\n- **Filter Comments**: Hide specific comments containing unwanted keywords.\n\n### Release Awareness\n\n- **Release Notes Banner**: Non-intrusive toast in YouTube surfaces highlights new capabilities.\n- **“What’s New” Dashboard Tab**: Full changelog with deep links so you can jump straight to the feature that shipped.\n\n### Stats \u0026 Insights\n\n- **Time Saved**: See how much time you've saved by blocking distractions.\n- **Daily Tracker**: Count of videos hidden today.\n\n### Performance \u0026 Privacy\n\n- **Zero Flash**: Filters content *before* it renders on screen using proactive XHR interception.\n- **Instant Blocking**: 3-dot menus show correct channel names immediately—no \"Fetching...\" delays.\n- **Network Reduction**: Most channel identity comes from intercepted JSON, not page fetches.\n- **100% Private**: No data leaves your browser. No analytics. No tracking.\n\n### Proactive Channel Identity (v3.2.2)\n\nFilterTube now uses a **proactive, XHR-first** strategy to extract channel identity before rendering, enhanced with lag-free performance optimizations and improved user experience:\n\n- **XHR Interception**: Captures YouTube's JSON responses (`/youtubei/v1/next`, `/browse`, `/player`)\n- **Instant Stamping**: Broadcasts channel info across worlds to stamp DOM cards immediately\n- **Zero-Network Kids**: YouTube Kids works entirely without network fetches\n- **Smart Enrichment**: Post-block enrichment fills missing metadata at a controlled rate\n- **Optimistic UI**: Content hides instantly when blocked, with automatic restoration if needed\n- **Mobile Support**: Enhanced 3-dot menu injection for YouTube mobile with proper renderer handling\n- **Smooth Rendering**: Large channel lists render efficiently using idle scheduling and batching\n\nLearn more in [Proactive Channel Identity](docs/PROACTIVE_CHANNEL_IDENTITY.md).\n\n### Help \u0026 Documentation\n\n- **Help Page (Dashboard)**: In the new tab UI, a dedicated Help section explains every feature, import/export flow, and troubleshooting tip.\n- **Technical Docs**:\n  - [Channel Blocking System](docs/CHANNEL_BLOCKING_SYSTEM.md) – Architecture and data flow\n  - [Proactive Channel Identity](docs/PROACTIVE_CHANNEL_IDENTITY.md) – XHR interception and instant stamping\n  - [Developer Guide](docs/DEVELOPER_GUIDE.md) – Extending FilterTube for new YouTube features\n  - [Architecture](docs/ARCHITECTURE.md) – System design and cross-world messaging\n  - [YouTube Kids Integration](docs/YOUTUBE_KIDS_INTEGRATION.md) – Kids-specific optimizations\n\n## Installation\n\n### For Users\nThe easiest way to install FilterTube is via our official website:\n👉 **[Install FilterTube.in](https://filtertube.in)** (Available for Chrome, Firefox, Edge, Brave, Opera)\n\nPrefer a direct store link? Pick your browser:\n\n- **Chrome / Brave**: [Chrome Web Store listing](https://chromewebstore.google.com/detail/filtertube/cjmdggnnpmpchholgnkfokibidbbnfgc)\n- **Firefox**: [Firefox Add-ons listing](https://addons.mozilla.org/en-US/firefox/addon/filtertube/)\n- **Edge**: [Microsoft Edge Add-ons listing](https://microsoftedge.microsoft.com/addons/detail/filtertube/lgeflbmplcmljnhffmoghkoccflhlbem)\n\n### For Developers\nIf you want to contribute or build from source:\n\n1.  **Clone the repository**\n    ```bash\n    git clone https://github.com/varshneydevansh/FilterTube.git\n    cd FilterTube\n    npm install\n    ```\n\n2.  **Run in Developer Mode**\n    *   **Chrome/Edge/Brave**: `npm run dev:chrome`\n    *   **Firefox**: `npm run dev:firefox`\n\n3.  **Load Extension**\n    *   **Chrome**: Go to `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the `FilterTube` folder.\n    *   **Firefox**: Go to `about:debugging`, click **This Firefox**, then **Load Temporary Add-on**, and select `manifest.json`.\n\n### 📱 Firefox for Android\n1.  **Set up**: Connect your Android device to your computer via USB.\n2.  **Install**: Use the Firefox build zip produced by `npm run build:firefox`.\n3.  **Debug**: Follow Mozilla's guide to [debug extensions on Android](https://extensionworkshop.com/documentation/develop/developing-extensions-for-firefox-for-android/) using `web-ext` or remote debugging.\n\n## Usage\n\n### Basic Filtering\n1. Click the FilterTube icon in your browser toolbar\n2. Enter keywords to filter (comma-separated)\n3. Enter channel names, @handles, or channel/IDs to filter (comma-separated)\n4. Click \"Save\" to apply filters\n\n### Finding a Channel to Block\n1. Go to the channel's page on YouTube\n2. Copy the channel identifier from the URL:\n   - `https://www.youtube.com/@HandleName` → Use `@HandleName`\n   - `https://www.youtube.com/channel/UCxxxxxxxx` → Use `UCxxxxxxxx` or `channel/UCxxxxxxxx`\n3. Enter it in the Channels filter field\n\n### Comment Filtering\n1. Click the FilterTube icon\n2. Toggle \"Hide all comments\" to completely hide comments\n3. Or select \"Filter comments with keywords/channels\" to hide only matching comments\n\n## How It Works\n\nFilterTube filters unwanted content **before** it appears on your screen, giving you a clean YouTube experience.\n\nUnder the hood, FilterTube also maintains lightweight identity caches:\n\n- `channelMap`: `@handle` / `c/\u003cslug\u003e` / `user/\u003cslug\u003e` ↔ `UC...`\n- `videoChannelMap`: `videoId` → `UC...`\n\nOn both **YouTube Main** and **YouTube Kids**, FilterTube can often learn the canonical channel ID **without extra page fetches** by harvesting ownership data from the same JSON payloads YouTube already loads (notably `ytInitialPlayerResponse` and `/youtubei/v1/player`). Once learned, Shorts and Watch surfaces can resolve identity instantly on the next encounter.\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  YouTube loads video data                                   │\n│          ↓                                                  │\n│  FilterTube intercepts the data BEFORE it renders           │\n│          ↓                                                  │\n│  Checks against your keywords \u0026 channels                    │\n│          ↓                                                  │\n│  ┌──────────────┐              ┌──────────────┐             │\n│  │ Matches your │  →  HIDDEN   │ Doesn't match│  →  SHOWN   │\n│  │ filters      │              │ your filters │             │\n│  └──────────────┘              └──────────────┘             │\n│                                                             │\n│  Result: Clean YouTube feed with only content you want      │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### What Makes FilterTube Different\n\n**Lightning Fast** - Filters content before YouTube renders it, so you never see unwanted videos flash on screen\n\n**100% Private** - Everything happens in your browser. No data is sent to external servers.\n\n**Comprehensive** - Filters videos, shorts, playlists, channels, comments, and more across all YouTube pages\n\n**Reliable** - Uses a two-layer system: intercepts YouTube's data first, then monitors the page as backup\n\n### Future Features (Coming Soon)\n\n- **Semantic ML Filtering**: AI-powered filtering that understands video context, not just keywords\n- **Kids Mode**: PIN-protected safe environment with whitelisted channels only\n- **Smart Sync**: Automatic linking of channel @handles and IDs for better blocking\n\n## Privacy \u0026 Permissions\n\nWe believe in privacy by design.\n*   **Storage**: To save your settings locally.\n*   **Active Tab**: To scan the YouTube page you are viewing.\n*   **No External Requests**: FilterTube does not talk to any servers other than YouTube (for the content you requested).\n\n## 🎬 Shorts Blocking Experience\n\nFilterTube uses a robust hybrid blocking mechanism for YouTube Shorts.\n\n**Current behavior (v3.1.8):** Shorts blocking is often **near-instant** because FilterTube learns `videoId → UC...` mappings from intercepted YouTube JSON and persists them. This makes Shorts behave much more like regular videos on Home/Search.\n\n```ascii\n[User Clicks \"Block\"]\n        |\n        v\n+-------------------------------+\n| 1. Resolve UC ID (fast path)  |\n|    - DOM /channel/UC... OR    |\n|    - videoChannelMap cache OR |\n|    - Main-world JSON harvest  |\n+-------------------------------+\n               |\n               v\n+-----------------------+\n| 2. Block \u0026 Hide       |\n+-----------------------+\n```\n\n- **Robust Verification**: We resolve to a canonical `UC...` channel ID whenever possible so blocking applies across Shorts + long-form + posts.\n- **Zero Leakage**: By resolving the canonical ID, we ensure that blocking a Short also blocks the channel's long-form videos and posts.\n- **Smart Layouts**: Automatically adjusts the grid to prevent awkward blank spaces.\n\n\u003e [!NOTE]\n\u003e **What if the channel ID isn't available yet?**\n\u003e In rare cases where the card does not expose a `UC...` link and the mapping is not yet learned from intercepted JSON, FilterTube falls back to a slower network-based resolution (e.g., fetching a watch/shorts page) to guarantee correctness.\n\n## Support\n\nFound a bug or have a feature request? [Open an issue on GitHub](https://github.com/varshneydevansh/FilterTube/issues).\n\nWant to support the project? You can donate on Ko-fi: [ko-fi.com/filtertube](https://ko-fi.com/filtertube)\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes and improvements.\n\n---\n\n### Why FilterTube?\n\nYouTube's recommendation algorithms can sometimes surface unwanted content. FilterTube gives you control over what appears in your feed, allowing for a more focused and pleasant viewing experience without distractions or unwanted content.\n\n**It all started with this thread on Google's support forum:**\nWhen a parent said that he is helpless and his kid is just kept crying and screaming because of the content on YouTubeKids, and he asked me if I can create a tool to block videos by keyword or tag.\nAnd when Later YouTube Forum maintaner deleted mine and other parents comments and locked the thread, I decided to create FilterTube.\n\n[https://support.google.com/youtubekids/thread/54509605/how-to-block-videos-by-keyword-or-tag?hl=en](https://support.google.com/youtubekids/thread/54509605/how-to-block-videos-by-keyword-or-tag?hl=en)\n\nPerfect for:\n- **Parents** who want to protect their children from inappropriate content\n- **Students** who need to stay focused while researching\n- **Anyone** who wants a distraction-free YouTube experience\n\n## For Developers\n\n### Building from Source\n\n```bash\n# Install dependencies\nnpm install\n\n# Develop for Chrome/Edge/Brave/Opera\nnpm run dev:chrome\n\n# Develop for Firefox\nnpm run dev:firefox\n\n# Build packages for distribution\nnpm run build              # All browsers\nnpm run build:chrome       # Chrome only\nnpm run build:firefox      # Firefox only\n```\n\nFor detailed technical documentation, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/TECHNICAL.md](docs/TECHNICAL.md).\n\n## Maintainer Notes: Script Layout\n\nFilterTube runs code in two JavaScript contexts on YouTube:\n\n### Isolated World (content scripts: DOM + UI)\n\nThe following scripts are loaded as content scripts (see `manifest*.json` for the authoritative load order):\n\n- `js/shared/identity.js` – Shared channel identity helpers exposed as `window.FilterTubeIdentity`.\n- `js/content/menu.js` – Menu styles + menu DOM helpers.\n- `js/content/dom_helpers.js` – Small DOM helpers used by fallback logic.\n- `js/content/dom_extractors.js` – DOM extraction helpers (video IDs, durations, card lookup).\n- `js/content/dom_fallback.js` – DOM fallback filtering layer.\n- `js/content/block_channel.js` – 3-dot menu observer/entry-point (detect dropdown + locate clicked card).\n- `js/content_bridge.js` – Settings sync, bridge messaging, menu rendering/click handling, and blocking orchestration.\n\n### Main World (page context: data interception)\n\n- `js/seed.js` – Hook/override entry points for `ytInitialData`, `fetch`, and XHR.\n- `js/injector.js` – Coordinator + main-world search helpers (e.g., `ytInitialData` lookups).\n- `js/filter_logic.js` – Filtering engine that removes blocked content from YouTube’s JSON before render.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvarshneydevansh%2Ffiltertube","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvarshneydevansh%2Ffiltertube","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvarshneydevansh%2Ffiltertube/lists"}