yt-dlp: allow specifying a background colour for the poster tint
- ID
416bcf0- date
2026-08-30 20:19:16+00:00- author
Alex Chan <alex@alexwlchan.net>- parent
ddc1073- message
yt-dlp: allow specifying a background colour for the poster tint- changed files
3 files, 55 additions, 4 deletions
Changed files
CHANGELOG.md (1397 → 2055)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a625ab2..193a7ed 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,21 @@
# CHANGELOG
+## v14 - 2026-08-30
+
+* Allow specifying the background colour used to choose the tint colour in the chives video entity with the `--background` flag.
+
+ For example:
+
+ ```console
+ $ # A video on a white background has a brownish-pink tint colour
+ $ yt-dlp_alexwlchan "https://www.youtube.com/watch?v=ittj60VE6bU" --background="#ffffff"
+ {"entity": {"poster": {"tint_colour": "#a98376", …}, …}, …}
+
+ $ # A video on a dark background has a near-white tint colour
+ $ yt-dlp_alexwlchan "https://www.youtube.com/watch?v=ittj60VE6bU" --background="#222222"
+ {"entity": {"poster": {"tint_colour": "#fcfbf8", …}, …}, …}
+ ```
+
## v13 - 2026-08-21
* Update to yt-dlp 2026.8.19.
test_yt-dlp_alexwlchan.py (4952 → 5578)
diff --git a/test_yt-dlp_alexwlchan.py b/test_yt-dlp_alexwlchan.py
index 0dfe4c7..79c4cd0 100644
--- a/test_yt-dlp_alexwlchan.py
+++ b/test_yt-dlp_alexwlchan.py
@@ -148,3 +148,24 @@ def test_normalise_url(url: str, expected: str) -> None:
Tests for `normalise_url`.
"""
assert normalise_url(url) == expected
+
+
+@pytest.mark.parametrize(
+ "background, poster_tint_colour",
+ [
+ # A white background gets a brownish-pink
+ ("#ffffff", "#a98376"),
+ # A black background gets a near-white
+ ("#222222", "#fcfbf8"),
+ ],
+)
+def test_uses_background(background: str, poster_tint_colour: str) -> None:
+ """
+ The `download_video` function uses the background colour to select
+ the tint colour.
+ """
+ video_info = download_video(
+ url="https://www.youtube.com/watch?v=ittj60VE6bU", background=background
+ )
+
+ assert video_info["entity"]["poster"]["tint_colour"] == poster_tint_colour
yt-dlp_alexwlchan.py (9588 → 10044)
diff --git a/yt-dlp_alexwlchan.py b/yt-dlp_alexwlchan.py
index 3f7d896..c513382 100755
--- a/yt-dlp_alexwlchan.py
+++ b/yt-dlp_alexwlchan.py
@@ -4,6 +4,7 @@ yt-dlp_alexwlchan is a personal wrapper around yt-dlp that downloads a video
with my preferred settings.
"""
+import argparse
from datetime import datetime, timezone
import json
from pathlib import Path
@@ -196,7 +197,7 @@ def cleanup_paths(dir_path: Path) -> None:
p.move(dir_path / new_name)
-def download_video(url: str) -> VideoInfo:
+def download_video(url: str, background: str = "#222222") -> VideoInfo:
"""
Download a video with yt-dlp and return metadata about the video.
"""
@@ -284,7 +285,7 @@ def download_video(url: str) -> VideoInfo:
poster_path=thumbnail_path,
subtitles_path=subtitle_path,
source_url=url,
- background="#222222",
+ background=background,
),
"folder_path": tmp_dir,
"site": site,
@@ -307,12 +308,25 @@ class PathEncoder(json.JSONEncoder):
if __name__ == "__main__":
+ parser = argparse.ArgumentParser(
+ prog="yt-dlp_alexwlchan",
+ description="Download videos from YouTube and other sites.",
+ )
+ parser.add_argument("url")
+ parser.add_argument(
+ "--background",
+ help="Background colour to use when deriving the tint colour of the poster image.",
+ default="#222222",
+ )
+
+ args = parser.parse_args()
+
try:
- url = normalise_url(sys.argv[1])
+ url = normalise_url(args.url)
except IndexError:
sys.exit(f"Usage: {__file__} URL")
- video_info = download_video(url)
+ video_info = download_video(url, background=args.background)
json_string = json.dumps(video_info, indent=2, cls=PathEncoder, ensure_ascii=False)