Files
2026-06-21 14:26:15 +08:00

171 lines
5.2 KiB
Python

"""封面下载器模块
负责下载 YouTube 视频封面/缩略图,
支持 JPG 和 PNG 格式,可自定义输出路径。
"""
import logging
import os
from pathlib import Path
from typing import Optional
import requests
import yt_dlp
from ..utils.user_agents import get_headers
logger = logging.getLogger(__name__)
class ThumbnailDownloader:
"""封面图下载器
负责下载 YouTube 视频的缩略图/封面图,
支持从 yt-dlp 提取或直接 HTTP 下载。
"""
# YouTube 缩略图质量后缀
QUALITY_SUFFIXES = [
"maxresdefault", # 最高分辨率 (1280x720)
"sddefault", # 标准分辨率 (640x480)
"hqdefault", # 高质量 (480x360)
"mqdefault", # 中等质量 (320x180)
"default", # 默认 (120x90)
]
def __init__(self) -> None:
"""初始化封面下载器"""
self._ydl_opts = {
"quiet": True,
"no_warnings": True,
"skip_download": True,
}
def download_thumbnail(
self,
url: str,
output_dir: str,
output_format: str = "jpg",
output_filename: str = "",
) -> Optional[str]:
"""下载视频封面图
Args:
url: YouTube 视频 URL
output_dir: 输出目录
output_format: 图片格式 (jpg 或 png)
output_filename: 输出文件名(不含扩展名),为空则使用视频标题
Returns:
下载成功的图片文件路径,失败返回 None
"""
try:
# 获取视频信息
with yt_dlp.YoutubeDL(self._ydl_opts) as ydl:
info = ydl.extract_info(url, download=False)
if info is None:
logger.error("无法获取视频信息用于封面下载")
return None
thumbnail_url = info.get("thumbnail", "")
video_title = info.get("title", "video")
if not thumbnail_url:
logger.error(f"未找到封面图 URL: {url}")
return None
# 确保输出目录存在
Path(output_dir).mkdir(parents=True, exist_ok=True)
# 确定输出文件名
if not output_filename:
safe_title = self._sanitize_filename(video_title)
output_filename = f"{safe_title}_cover"
output_path = Path(output_dir) / f"{output_filename}.{output_format}"
# 下载封面图
return self._download_image(thumbnail_url, str(output_path))
except Exception as e:
logger.error(f"封面下载失败: {e}")
return None
def download_thumbnail_hq(
self,
video_id: str,
output_path: str,
) -> Optional[str]:
"""下载高质量封面(使用 video_id)
直接通过 YouTube 图片服务器下载最高质量封面。
Args:
video_id: YouTube 视频 ID (11 位字符)
output_path: 输出文件完整路径
Returns:
下载成功的文件路径,失败返回 None
"""
# 尝试从高到低质量下载
for quality in self.QUALITY_SUFFIXES:
thumbnail_url = (
f"https://img.youtube.com/vi/{video_id}/{quality}.jpg"
)
result = self._download_image(thumbnail_url, output_path)
if result:
return result
logger.error(f"所有质量的封面图均下载失败: {video_id}")
return None
def _download_image(self, image_url: str, output_path: str) -> Optional[str]:
"""通过 HTTP 下载图片
Args:
image_url: 图片 URL
output_path: 输出文件完整路径
Returns:
下载成功的文件路径,失败返回 None
"""
try:
response = requests.get(
image_url, timeout=30, headers=get_headers()
)
response.raise_for_status()
# 确保输出目录存在
Path(output_path).parent.mkdir(parents=True, exist_ok=True)
with open(output_path, "wb") as f:
f.write(response.content)
file_size = os.path.getsize(output_path)
if file_size < 1000: # 文件太小,可能不是有效图片
logger.warning(f"封面图文件可能无效 (大小: {file_size} bytes)")
os.remove(output_path)
return None
logger.info(f"封面下载成功: {output_path} ({file_size} bytes)")
return output_path
except requests.RequestException as e:
logger.debug(f"封面下载 HTTP 错误 {image_url}: {e}")
return None
except Exception as e:
logger.error(f"封面下载异常: {e}")
return None
@staticmethod
def _sanitize_filename(filename: str) -> str:
"""清理文件名"""
import re
illegal_chars = r'[<>:"/\\|?*\x00-\x1f]'
sanitized = re.sub(illegal_chars, "_", filename)
sanitized = sanitized.strip(". ")
if len(sanitized) > 100:
sanitized = sanitized[:100]
return sanitized or "video"