Add option `--xff`

Deprecates `--geo-bypass`, `--no-geo-bypass, `--geo-bypass-country`, `--geo-bypass-ip-block`

README.md

@@ -463,15 +463,11 @@ If you fork the project on GitHub, you can run your fork's [build workflow](.git
                                     specified by --proxy (or none, if the option
                                     is not present) is used for the actual
                                     downloading
-    --geo-bypass                    Bypass geographic restriction via faking
+    --xff VALUE                     How to fake X-Forwarded-For HTTP header to
-                                    X-Forwarded-For HTTP header (default)
+                                    try bypassing geographic restriction. One of
-    --no-geo-bypass                 Do not bypass geographic restriction via
+                                    "default" (Only when known to be useful),
-                                    faking X-Forwarded-For HTTP header
+                                    "never", a two-letter ISO 3166-2 country
-    --geo-bypass-country CODE       Force bypass geographic restriction with
+                                    code, or an IP block in CIDR notation
-                                    explicitly provided two-letter ISO 3166-2
-                                    country code
-    --geo-bypass-ip-block IP_BLOCK  Force bypass geographic restriction with
-                                    explicitly provided IP block in CIDR notation
 
 ## Video Selection:
     -I, --playlist-items ITEM_SPEC  Comma separated playlist_index of the items
@@ -2168,6 +2164,10 @@ While these options still work, their use is not recommended since there are oth
     --youtube-skip-hls-manifest      --extractor-args "youtube:skip=hls" (Alias: --no-youtube-include-hls-manifest)
     --youtube-include-dash-manifest  Default (Alias: --no-youtube-skip-dash-manifest)
     --youtube-include-hls-manifest   Default (Alias: --no-youtube-skip-hls-manifest)
+    --geo-bypass                     --xff "default"
+    --no-geo-bypass                  --xff "never"
+    --geo-bypass-country CODE        --xff CODE
+    --geo-bypass-ip-block IP_BLOCK   --xff IP_BLOCK
 
 
 #### Developer options

yt_dlp/__init__.py

@@ -396,12 +396,17 @@ def validate_options(opts):
         except Exception as err:
             raise ValueError(f'Invalid playlist-items {opts.playlist_items!r}: {err}')
 
-    geo_bypass_code = opts.geo_bypass_ip_block or opts.geo_bypass_country
+    opts.geo_bypass_country, opts.geo_bypass_ip_block = None, None
-    if geo_bypass_code is not None:
+    if opts.geo_bypass.lower() not in ('default', 'never'):
         try:
-            GeoUtils.random_ipv4(geo_bypass_code)
+            GeoUtils.random_ipv4(opts.geo_bypass)
         except Exception:
-            raise ValueError('unsupported geo-bypass country or ip-block')
+            raise ValueError(f'Unsupported --xff "{opts.geo_bypass}"')
+        if len(opts.geo_bypass) == 2:
+            opts.geo_bypass_country = opts.geo_bypass
+        else:
+            opts.geo_bypass_ip_block = opts.geo_bypass
+    opts.geo_bypass = opts.geo_bypass.lower() != 'never'
 
     opts.match_filter = match_filter_func(opts.match_filter, opts.breaking_match_filter)
 

yt_dlp/options.py

@@ -519,22 +519,27 @@ def create_parser():
         '--cn-verification-proxy',
         dest='cn_verification_proxy', default=None, metavar='URL',
         help=optparse.SUPPRESS_HELP)
+    geo.add_option(
+        '--xff', metavar='VALUE',
+        dest='geo_bypass', default="default",
+        help=(
+            'How to fake X-Forwarded-For HTTP header to try bypassing geographic restriction. '
+            'One of "default" (Only when known to be useful), "never", '
+            'a two-letter ISO 3166-2 country code, or an IP block in CIDR notation'))
     geo.add_option(
         '--geo-bypass',
-        action='store_true', dest='geo_bypass', default=True,
+        action='store_const', dest='geo_bypass', const='default',
-        help='Bypass geographic restriction via faking X-Forwarded-For HTTP header (default)')
+        help=optparse.SUPPRESS_HELP)
     geo.add_option(
         '--no-geo-bypass',
-        action='store_false', dest='geo_bypass',
+        action='store_const', dest='geo_bypass', const='never',
-        help='Do not bypass geographic restriction via faking X-Forwarded-For HTTP header')
+        help=optparse.SUPPRESS_HELP)
     geo.add_option(
-        '--geo-bypass-country', metavar='CODE',
+        '--geo-bypass-country', metavar='CODE', dest='geo_bypass',
-        dest='geo_bypass_country', default=None,
+        help=optparse.SUPPRESS_HELP)
-        help='Force bypass geographic restriction with explicitly provided two-letter ISO 3166-2 country code')
     geo.add_option(
-        '--geo-bypass-ip-block', metavar='IP_BLOCK',
+        '--geo-bypass-ip-block', metavar='IP_BLOCK', dest='geo_bypass',
-        dest='geo_bypass_ip_block', default=None,
+        help=optparse.SUPPRESS_HELP)
-        help='Force bypass geographic restriction with explicitly provided IP block in CIDR notation')
 
     selection = optparse.OptionGroup(parser, 'Video Selection')
     selection.add_option(