Repository navigation
Expand file tree
/
Copy pathReadme-en
More file actions
393 lines (269 loc) · 17.3 KB
/
Copy pathReadme-en
File metadata and controls
393 lines (269 loc) · 17.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
# 🛡️ YouTube Channel Filter (YTcF)
[](https://greasyfork.org/en/scripts/547742-youtube-channel-filter-ytcf)
[](https://greasyfork.org/en/scripts/547742-youtube-channel-filter-ytcf)
[](LICENSE)
[](https://github.com/hubig21/YouTube-Gatekeeper/issues)
[](https://www.tampermonkey.net/)
> Take back control of your YouTube feed — build a clean, focused, kid-friendly viewing environment.
👉 **[Install YouTube Channel Filter from Greasy Fork](https://greasyfork.org/en/scripts/547742-youtube-channel-filter-ytcf)** (requires the [Tampermonkey](https://www.tampermonkey.net/) or Violentmonkey browser extension)
[繁體中文 README →](README.md)
---
## 💡 Why YTcF?
YouTube's algorithm often surfaces content that's irrelevant, low-quality, or repetitive. YTcF hands control back to you — beyond classic channel and keyword filtering, it adds precise per-page-type filtering rules, automatic collaboration-video splitting, and a hard-block mode, suited to everything from distraction-free browsing to family/kids-safe setups.
## ✨ Key Features
- **🚫 Channel blocklist / whitelist**: Match by UC ID, `@handle`, channel name, or Regex
- **🎬 Single-video blocklist**: Block a specific video by ID without touching the rest of the channel
- **🤝 Smart collaboration-video parsing**: Automatically splits cross-channel collab videos so you can block just one participant
- **⭐ Whitelist-only mode**: One toggle for a minimal, trusted-channels-only, kid-friendly view
- **🔤 Keyword groups + Regex**: Match title and/or description, with advanced regular expression support
- **⏱️ Multi-dimensional filters**: Duration, view count, upload date, language (BCP-47), live/upcoming, members-only, fundraisers
- **🎯 Filter Scope matrix** (advanced): 11 rule types × page types (home, subscriptions, search, watch, channel, etc.), independently toggled
- **🛡️ Direct-access hard block**: Force-pause and overlay-block when a blocked channel/video is opened via a direct URL or external link
- **🖱️ Quick actions**: Hover action bar, native ⋮ menu integration, global floating button
- **🔬 Diagnostics**: Per-card lifecycle tracing and a 10,000-entry debug log ring buffer, so bug reports come with real evidence
- **💾 Full backup/export/share**: Complete JSON backup, CSV export, one-click shareable links
See the full user guide below for detailed usage.
---
# 🔍 YouTube Channel Filter — User Guide
> Version: v1.4.7 · Tampermonkey / Violentmonkey userscript
---
## Table of Contents
1. [Quick Start](#quick-start)
2. [Interface Overview](#interface-overview)
3. [Features](#features)
- [Blocklist](#-blocklist)
- [Whitelist](#-whitelist)
- [Video Blocklist](#-video-blocklist)
- [Keyword Filter](#-keyword-filter)
- [Settings](#️-settings)
- [Stats / History](#-stats--history)
- [Import / Export](#-import--export)
4. [Advanced Features](#advanced-features)
- [Filter Scope (Advanced)](#filter-scope-advanced)
- [Regex Mode](#regex-mode)
- [Kids Mode Setup](#kids-mode-setup)
5. [Quick Actions](#quick-actions)
6. [PIN Lock](#pin-lock)
7. [Bug Reports & Diagnostics](#bug-reports--diagnostics)
8. [Notes](#notes)
---
## Quick Start
1. Install [Tampermonkey](https://www.tampermonkey.net/) or Violentmonkey browser extension
2. Install this userscript from [Greasy Fork](https://greasyfork.org/en/scripts/547742-youtube-channel-filter-ytcf)
3. Open YouTube — a **🔍** button will appear in the top navigation bar
4. Left-click 🔍 to open the management panel and start using
---
## Interface Overview
The management panel contains the following tabs:
| Tab | Description |
|-----|-------------|
| 🚫 Blocklist | Manage channels to hide |
| ⭐ Whitelist | Manage trusted channels (works with whitelist-only mode) |
| 🎬 Video Blocklist | Block specific video IDs |
| 🔤 Keywords | Filter videos by title / description |
| ⚙️ Settings | Global settings and filter conditions |
| 📊 Stats | View filtering statistics |
| 📋 History | View filtered video history |
| 💾 Import/Export | Backup and restore settings |
| 🎯 Filter Scope | Specify which pages each rule applies to (enable in Settings first) |
---
## Features
### 🚫 Blocklist
Add channels you don't want to see. Cards from those channels will be automatically hidden on the homepage, subscriptions feed, search results, and other listing pages.
**How to add:**
- **Manual input**: Fill in the channel name (required) and `@handle` (optional) in the panel form, then click Add
- **Quick button**: Hover over a video card — an action bar slides up from the bottom. Click 🚫 to block instantly
- **Three-dot menu**: If set to "Three-dot menu" mode, click the video's ⋮ menu and select "YTcF: Hide this channel"
**Tags**: Each channel can have tags for easier categorization (e.g., "Ad accounts", "Farm channels").
---
### ⭐ Whitelist
Add channels you trust or want to protect. Whitelisted channels are never affected by any filter rule — they won't be caught by the blocklist, keywords, or any other filter.
**Whitelist-only mode**: Enable "Show only whitelisted channels" in ⚙️ Settings. Once enabled, all channels except those in the whitelist will be hidden. Ideal for parental controls or a minimal viewing experience.
---
### 🎬 Video Blocklist
Block specific video IDs without needing to block the entire channel. Common use cases: hiding specific controversial videos or blocking episodes you're not interested in.
- Accepts a video ID (11 characters) or a full YouTube URL
- Once added, the block is **always enforced** and is not controlled by the Filter Scope matrix
- Accessing the video directly via URL will also show a block screen (requires "Force Block" to be enabled in Settings)
---
### 🔤 Keyword Filter
Filter videos based on keywords found in their title or description. Keywords are managed in **groups** — each group can be individually enabled or disabled.
**Creating a keyword group:**
1. Click "+ Add Group" and enter a group name
2. Select the scope: title, description, or both
3. Add keywords within the group
4. Make sure the group toggle is set to "Enabled"
**Group priority**: Groups higher in the list take priority. Drag to reorder.
---
### ⚙️ Settings
| Setting | Description |
|---------|-------------|
| Show Toast notifications | Whether to show popup notifications after actions |
| Quick action style | Choose between "Quick Buttons" (hover bar) or "Three-dot menu" (integrated into YouTube's ⋮ menu) |
| Show only whitelisted channels | Whitelist-only mode |
| Video duration | Filter videos shorter or longer than a specified length (seconds) |
| Live / Upcoming | Hide live streams or upcoming premieres |
| Members-only videos | Hide members-only or members-first videos |
| View count | Filter by view count (below or above a threshold) |
| Upload date | Hide videos that are too old or too new |
| Language filter | Filter or show only specific languages |
| Channel posts | Hide channel community posts |
| Fundraiser | Hide videos marked as fundraisers |
| Force Block (direct URL access) | Block access to blocked channels/videos even when navigating directly by URL |
| Enable Filter Scope (Advanced) | Reveals the "🎯 Filter Scope" tab |
| PIN Lock | Set a password to protect the management panel |
---
### 📊 Stats / History
- **Stats**: View trigger counts per rule and top blocked channels
- **History**: Browse recently filtered videos with reasons for filtering
---
### 💾 Import / Export
Supports full backup and individual exports. Formats include CSV (blocklist, whitelist, keywords) and JSON (all settings, video blocklist).
**Backup tip**: Enable "Auto Backup" in Settings to automatically export your full settings to the download folder on a schedule.
---
## Advanced Features
### Filter Scope (Advanced)
Filter Scope lets you specify which YouTube page types each filter rule applies to. It's designed for users who need fine-grained control.
#### How to Enable
1. Go to ⚙️ **Settings**
2. Scroll to the bottom and check "**Enable Filter Scope (Advanced)**"
3. Click "💾 Save Settings"
4. A new "🎯 **Filter Scope**" tab will appear — click it to configure
#### Understanding the Matrix
The interface shows an **11 rules × 7 pages** matrix:
**Page types:**
| Type | Description |
|------|-------------|
| 🏠 Home | YouTube homepage |
| 📨 Subscriptions | Subscriptions feed |
| 🔍 Search | Search results page |
| 🎬 Watch page | Recommendations sidebar while watching a video |
| 📺 Channel page | When visiting a specific channel |
| 🔥 Trending | Trending videos page |
| 📄 Other | Any other page |
**Rule types:**
Channel Blocklist, Video Blocklist, Keywords, Members-only, Live/Upcoming, Fundraiser, Upload Date, View Count, Language, Duration, Channel Posts.
#### How to Use
- **Click a cell**: Toggle the rule on/off for that page type (active = colored, inactive = gray)
- **"✓ All On" at row end**: Enable this rule for all page types
- **"✕ All Off" at row end**: Disable this rule for all page types
- **"Reset all to enabled" button**: Restore defaults (all rules apply to all pages)
- **Current page**: Highlighted with a special style so you can see where you are in the matrix
#### Example Use Cases
**Example 1 — Allow seeing blocked channels on their own channel page**
> Uncheck "Channel Blocklist" × "Channel page"
> → When visiting a blocked channel's page, their videos are still visible; but they remain hidden on the homepage and other listing pages
**Example 2 — Apply keyword filter only on the homepage**
> For the "Keywords" rule, keep only "Home" checked, uncheck all other pages
> → Keyword filters won't interfere when you're specifically searching for something
**Example 3 — Don't filter live streams on the subscriptions feed**
> Uncheck "Live / Upcoming" × "Subscriptions"
> → Live streams from subscribed channels will appear in your subscriptions feed, but not on the homepage
---
### Regex Mode
Keyword groups support JavaScript Regular Expressions, giving you more flexible pattern matching for video titles and descriptions.
#### How to Enable
When adding a keyword inside a group, check the "**Regex**" checkbox to enable regex mode for that keyword.
#### Rules
- **No need** to wrap the pattern in `/` slashes or add flags like `/i`
- Matching is **case-insensitive** by default
- Backslashes (`\`) can be entered directly — no extra escaping needed
#### Common Examples
| Pattern | Description |
|---------|-------------|
| `(ad\|sponsored\|paid)` | Title contains "ad", "sponsored", or "paid" |
| `(stock\|invest\|crypto)` | Title mentions any finance-related term |
| `EP\.?\d+` | Episode number formats: EP1, EP.1, EP 1, etc. |
| `^(?!.*official).*$` | Title does **not** contain "official" (negative lookahead) |
| `\d{4}` | Title contains a 4-digit number (e.g., a year) |
| `(LIVE\|STREAM\|streaming)` | Various live stream indicators |
#### Tips
- Regex applies only to the **individual keyword** where it's enabled; other keywords in the same group continue to use plain text matching
- If a pattern has invalid syntax (e.g., unmatched parentheses), the keyword automatically falls back to plain text matching
- For best performance, prefer `(a|b|c)` patterns over complex lookaheads
---
### Kids Mode Setup
By combining multiple features, you can create a "whitelist-only + automatic dangerous content filtering" child-friendly browsing environment.
> ⚠️ **Important Disclaimer:** This script only filters video cards on listing pages (homepage, search, recommendations). It cannot block direct URL navigation to a video, and it cannot analyze the actual content of videos. **Strongly recommended to use alongside YouTube Kids, parental control software (e.g., Google Family Link), or router-level DNS filtering.**
#### Complete Setup Steps
**Step 1 — Build a whitelist**
Go to the ⭐ **Whitelist** tab and add every channel your child is allowed to watch.
For example: @PBSKids, @SesameStreet, @CocomelonOfficial
**Step 2 — Enable whitelist-only mode**
Go to ⚙️ **Settings** and turn on "⭐ Show only whitelisted channels".
After enabling, all channels except those in the whitelist will be hidden.
**Step 3 — Block live streams**
In Settings, under "📡 Live / Upcoming", enable both:
- Hide live streams
- Hide upcoming / scheduled premieres
Live chat in streams is a common risk vector — block them entirely.
**Step 4 — Create a dangerous content keyword group**
Go to 🔤 **Keywords**, create a group named "Dangerous Content", and set scope to "Title":
Add keywords such as:
```
violence, blood, horror, adult, gambling, weapons, drugs
```
For more efficiency, enable Regex mode and enter:
```
(violence|gore|horror|adult|gambling|18\+|explicit)
```
**Step 5 (Recommended) — Restrict video age**
In Settings, enable "📅 Upload Date" and set it to hide videos uploaded more than 30 days ago.
This helps prevent the algorithm from surfacing old controversial content.
**Step 6 (Recommended) — Language filter**
In Settings, enable "🌐 Language Filter", choose "Show only selected languages", and check only your child's native language.
This effectively filters out most foreign-language content.
**Step 7 (Recommended) — Set a PIN lock**
In Settings, set up a "PIN Lock" to prevent your child from changing the filter settings.
#### Advanced Setup with Filter Scope
After enabling Filter Scope (Advanced), you can fine-tune kids mode further:
- **Home, Subscriptions, Search**: Enable all rules
- **Watch page sidebar**: Enable all rules to prevent inappropriate recommendations while watching
- **Channel page**: You can relax the "Channel Blocklist" rule so parents can still browse a specific channel to review it
---
## Quick Actions
| Action | Description |
|--------|-------------|
| Left-click 🔍 in top bar | Open management panel |
| Right-click 🔍 in top bar | Toggle filter on / off |
| Hover over a video card | Quick action bar slides up from the bottom (Button mode) |
| Click a video's ⋮ menu | YTcF options appear (Three-dot menu mode) |
| Tampermonkey extension menu | Provides "Open Panel" and "Toggle Filter" options |
**Two quick action modes (switchable in Settings):**
- **Quick Buttons**: Hovering a video reveals a bottom bar with "🚫 Hide Channel", "⭐ Add to Whitelist", and "🎬 Block Video" buttons
- **Three-dot menu**: The same three options are injected into YouTube's native ⋮ context menu for a more seamless look
---
## PIN Lock
Enable PIN Lock in the ⚙️ Settings panel under "PIN Lock":
- Once set, opening the management panel requires entering the PIN
- While locked, all tabs and the global on/off toggle are disabled
- The panel automatically re-locks when closed
- The "Remove from blocklist" button on the Blocker overlay screen also requires PIN verification (independently — it does not inherit the panel's unlocked state)
---
## Bug Reports & Diagnostics
If you run into flickering, filters not working, or delayed card updates:
1. Open the management panel and switch to the User Guide tab, or use "🔬 Enable Diagnostic Mode" from the Tampermonkey extension menu
2. Click "🪲 Start Recording Issue" and reproduce the problem
3. Click "⏹️ Stop & Export Log" to download the diagnostic log (`ytcf-diag-xxx.log`)
4. Open a report on [GitHub Issues](https://github.com/hubig21/YouTube-Gatekeeper/issues) and attach the log file
---
## Notes
- The script only filters **video cards on listing pages** — it does not affect the actual content of videos being played
- YouTube Shorts are not in scope; use a dedicated Shorts filter script (e.g., Hide YouTube Shorts, UnHook) alongside this one
- When a channel page contains no UC ID, matching relies primarily on `@handle` and channel name
- If a blocked channel's cards still appear, try refreshing the page or clicking "Save Settings" in the panel
- Settings are stored in the browser's localStorage — please export a backup before clearing browser data
---
## 📜 License
This project is licensed under the [MIT License](LICENSE).
Author: **MayoHu** · GitHub: [YouTube-Gatekeeper](https://github.com/hubig21/YouTube-Gatekeeper)
---
## 🙏 Acknowledgements
Thanks to the following contributors for long-term testing, bug reports, and suggestions:
**Core Reporters**
- **Azazello** — In-depth testing of early versions, extensive bug reports, and Regex feature suggestions
- **JourneyOver** — Key usage-scenario feedback and feature suggestions
- **Fox Huang** — Helped test filtering compatibility with Chinese-language channels
**Community Reporters** (Greasy Fork & GitHub, in order reported)
CherryBlossom_TW · NightOwlGamer · 台灣小確幸 · PixelWalker88 · SakuraNeko · MapleDrift · CoralSeeker · ZephyrTides · LanternFish99 · QuietMountain · TealDragonfly · GlassHarmonics · SilverFernLeaf · NoodleArchitect · CrimsonTideTV · WanderlustFreq · TeaLeafReader · MossyPebble42 · StarlightCoast · VinylWhisper
☕ If this script has been useful to you, consider supporting development via [Liberapay](https://liberapay.com/MayoHu_xu4fu/donate).