yt-dlp 实用工具集#

基于 yt-dlp 封装的 Python 脚本工具集，提供一键下载、自动转码功能。

脚本说明#

依赖#

Python 3.10+
FFmpeg

安装 yt-dlp 完整版：

1
pip install "yt-dlp[default]"

quick_grab.py — 快速获取视频#

下载任意网站视频，自动确保输出为 H.264 + AAC 的 MP4 文件。

特性：

自动检测并使用 GPU 硬件加速（NVIDIA NVENC / AMD AMF / Intel QSV），无 GPU 回退 CPU
探测源视频码率，按源码率匹配目标画质，避免转码后文件暴涨
支持断点续传，网络中断后重新运行可从上次位置继续
内置失败重试（10 次重试 + 指数退避）

基本用法：

1
# 下载最高画质（自动转码为 H.264 MP4）
2
python quick_grab.py "https://www.youtube.com/watch?v=VIDEO_ID"
3

4
# 指定输出目录
5
python quick_grab.py "URL" -d D:/Downloads
6

7
# 下载 720P
8
python quick_grab.py "URL" -q 720
9

10
# 仅下载音频
11
python quick_grab.py "URL" --audio
12

13
# 下载中英字幕
14
python quick_grab.py "URL" --subtitle
15

16
# 下载整个播放列表
17
python quick_grab.py "URL" --playlist
18

19
# 自定义编码质量（CRF 越小质量越高，默认 23）
20
python quick_grab.py "URL" --crf 18 --preset slow
21

22
# 强制使用 CPU 编码（禁用 GPU 加速）
23
python quick_grab.py "URL" --no-gpu
24

25
# 指定输出文件名
26
python quick_grab.py "URL" -o "my_video.mp4"

转码流程：

yt-dlp 下载视频（自动合并视频+音频流）
ffprobe 检测编码格式
如果已经是 H.264 + AAC + MP4 → 跳过（无需转码）
如果编码正确但容器非 MP4 → 仅 remux（无损，极快）
如果需要转码 → 自动探测源码率，按源码率匹配目标画质：
- NVENC：-rc vbr -cq -b:v {源码率}k -maxrate {源码率}k
- AMF/QSV：类似 VBR 码率控制
- CPU：高码率用 -b:v 码率模式，低/未知码率用 -crf 质量模式
- 低码率（< 2000k）自动降低 CRF 至 20 以保画质

quick_audio.py — 快速获取音频#

下载任意网站音频，转为 AAC 编码的 M4A 文件，兼容 iPhone / Android / Windows / Mac / 车载等所有主流播放器。

基本用法：

1
# 下载音频，输出 AAC/M4A (192kbps)
2
python quick_audio.py "https://www.youtube.com/watch?v=VIDEO_ID"
3

4
# 指定输出目录
5
python quick_audio.py "URL" -d D:/Downloads
6

7
# 320kbps 高音质
8
python quick_audio.py "URL" -b 320
9

10
# 输出 MP3 格式（兼容极老旧设备）
11
python quick_audio.py "URL" --mp3
12

13
# 下载整个播放列表的音频
14
python quick_audio.py "URL" --playlist

脚本内容#

quick_grab.py#

1
"""
2
快速获取 - 使用 yt-dlp 下载任意网站视频，确保输出 H.264 + AAC MP4
3

4
ffmpeg 调用链:
5
  1. yt-dlp 内部调用 ffmpeg 合并分离的视频/音频流 (自动, -c copy)
6
  2. 脚本调用 ffprobe 检测编码格式
7
  3. 自动检测 GPU (NVIDIA NVENC), 优先使用硬件加速转码
8
  4. 如需转码, 有 GPU 时用 h264_nvenc, 无 GPU 时用 libx264 + aac
9
  5. 如编码已正确但容器非 mp4, 仅做 remux (-c copy 到 mp4 容器)
10

11
用法:
12
    python quick_grab.py <URL>
13
    python quick_grab.py <URL> -d D:/Downloads
14
    python quick_grab.py <URL> --audio
15
    python quick_grab.py <URL> -q 720
16
    python quick_grab.py <URL> --crf 18 --preset slow   # 高质量转码
17
"""
18

19
import argparse
20
import io
21
import os
22
import subprocess
23
import sys
24

25
# Fix Windows console encoding
26
if sys.platform == "win32":
27
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
28
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
29

30

31
# ---------------------------------------------------------------------------
32
# ffmpeg / ffprobe helpers
33
# ---------------------------------------------------------------------------
34

35
def probe_codecs(filepath: str) -> tuple[str, str]:
36
    """用 ffprobe 检测视频和音频编码格式"""
37
    result = subprocess.run(
38
        ["ffprobe", "-v", "error",
39
         "-show_entries", "stream=codec_type,codec_name",
40
         "-of", "csv=p=0", filepath],
41
        capture_output=True, text=True, timeout=10,
42
        encoding="utf-8", errors="replace",
43
    )
44
    vcodec = acodec = "none"
45
    for line in result.stdout.strip().split("\n"):
46
        # ffprobe csv=p=0 输出格式: codec_name,codec_type (如 "h264,video")
47
        parts = line.strip().split(",")
48
        if len(parts) == 2:
49
            cname, ctype = parts
50
            if ctype == "video":
51
                vcodec = cname
52
            elif ctype == "audio":
53
                acodec = cname
54
    return vcodec, acodec
55

56

57
def remux_to_mp4(input_path: str) -> bool:
58
    """仅更换容器为 mp4 (不重新编码, 极快)"""
59
    output_path = os.path.splitext(input_path)[0] + ".mp4"
60
    if input_path == output_path:
61
        return True
62
    cmd = [
63
        "ffmpeg", "-i", input_path,
64
        "-c", "copy", "-movflags", "+faststart",
65
        "-y", output_path,
66
    ]
67
    result = subprocess.run(cmd)
68
    if result.returncode == 0 and os.path.isfile(output_path):
69
        os.remove(input_path)
70
        return True
71
    if os.path.isfile(output_path):
72
        os.remove(output_path)
73
    return False
74

75

76
def _detect_nvenc() -> bool:
77
    """检测 ffmpeg 是否支持 NVIDIA NVENC 硬件编码"""
78
    try:
79
        result = subprocess.run(
80
            ["ffmpeg", "-hide_banner", "-encoders"],
81
            capture_output=True, text=True, timeout=10,
82
            encoding="utf-8", errors="replace",
83
        )
84
        return "h264_nvenc" in result.stdout
85
    except (FileNotFoundError, subprocess.TimeoutExpired):
86
        return False
87

88

89
def _detect_hardware_encoder() -> str:
90
    """检测可用的硬件编码器, 返回编码器名称 (h264_nvenc / h264_amf / h264_qsv / libx264)"""
91
    try:
92
        result = subprocess.run(
93
            ["ffmpeg", "-hide_banner", "-encoders"],
94
            capture_output=True, text=True, timeout=10,
95
            encoding="utf-8", errors="replace",
96
        )
97
        for enc in ("h264_nvenc", "h264_amf", "h264_qsv"):
98
            if enc in result.stdout:
99
                return enc
100
    except (FileNotFoundError, subprocess.TimeoutExpired):
101
        pass
102
    return "libx264"
103

104

105
def _probe_source_bitrate(filepath: str) -> int:
106
    """获取源视频流码率 (kbps), 获取失败返回 0"""
107
    # 优先从流信息获取
108
    try:
109
        result = subprocess.run(
110
            ["ffprobe", "-v", "error",
111
             "-select_streams", "v:0",
112
             "-show_entries", "stream=bit_rate",
113
             "-of", "csv=p=0", filepath],
114
            capture_output=True, text=True, timeout=10,
115
            encoding="utf-8", errors="replace",
116
        )
117
        br = result.stdout.strip()
118
        if br and br not in ("N/A", ""):
119
            return int(br) // 1000  # bps → kbps
120
    except (FileNotFoundError, subprocess.TimeoutExpired, ValueError):
121
        pass
122
    # 回退: 从文件大小 × 时长估算
123
    try:
124
        result = subprocess.run(
125
            ["ffprobe", "-v", "error",
126
             "-show_entries", "format=duration",
127
             "-of", "csv=p=0", filepath],
128
            capture_output=True, text=True, timeout=10,
129
            encoding="utf-8", errors="replace",
130
        )
131
        duration = float(result.stdout.strip())
132
        file_size = os.path.getsize(filepath)
133
        return int(file_size * 8 / duration * 0.85 / 1000)  # 视频约占85%
134
    except (FileNotFoundError, subprocess.TimeoutExpired, ValueError, OSError):
135
        return 0
136

137

138
def transcode(input_path: str, crf: int = 23, preset: str = "medium",
139
              use_gpu: bool = True) -> bool:
140
    """转码为 H.264 + AAC MP4 (参考源码率匹配画质, 优先硬件加速)"""
141
    base, ext = os.path.splitext(input_path)
142
    output_path = base + "_h264_tmp.mp4"
143

144
    # 探测源视频码率
145
    source_kbps = _probe_source_bitrate(input_path)
146
    # CRF 根据源码率调整: 低码率用更高质量
147
    crf_value = 20 if 0 < source_kbps < 2000 else crf
148
    # 缓冲区 = 码率 × 2
149
    buf_kbps = source_kbps * 2 if source_kbps > 0 else 0
150

151
    # 选择编码器
152
    encoder = _detect_hardware_encoder() if use_gpu else "libx264"
153

154
    # --- NVENC ---
155
    if encoder == "h264_nvenc":
156
        _preset_map = {
157
            "ultrafast": "p1", "superfast": "p1", "veryfast": "p2",
158
            "faster": "p3", "fast": "p4", "medium": "p4",
159
            "slow": "p5", "slower": "p7", "veryslow": "p7",
160
        }
161
        nvenc_preset = _preset_map.get(preset, "p4")
162
        if source_kbps > 0:
163
            print(f"    [GPU/NVENC] 源码率: {source_kbps}k | 目标: {source_kbps}k | cq={crf_value} | preset={nvenc_preset}")
164
            cmd = [
165
                "ffmpeg", "-i", input_path,
166
                "-c:v", "h264_nvenc", "-preset", nvenc_preset,
167
                "-rc", "vbr", "-cq", str(crf_value),
168
                "-b:v", f"{source_kbps}k", "-maxrate", f"{source_kbps}k", "-bufsize", f"{buf_kbps}k",
169
                "-c:a", "aac", "-b:a", "192k",
170
                "-movflags", "+faststart", "-y", output_path,
171
            ]
172
        else:
173
            print(f"    [GPU/NVENC] 未知源码率 | cq={crf_value} | preset={nvenc_preset}")
174
            cmd = [
175
                "ffmpeg", "-i", input_path,
176
                "-c:v", "h264_nvenc", "-preset", nvenc_preset,
177
                "-rc", "vbr", "-cq", str(crf_value),
178
                "-c:a", "aac", "-b:a", "192k",
179
                "-movflags", "+faststart", "-y", output_path,
180
            ]
181

182
    # --- AMD AMF ---
183
    elif encoder == "h264_amf":
184
        if source_kbps > 0:
185
            print(f"    [GPU/AMF] 源码率: {source_kbps}k | 目标: {source_kbps}k")
186
            cmd = [
187
                "ffmpeg", "-i", input_path,
188
                "-c:v", "h264_amf", "-quality", "speed", "-rc", "vbr",
189
                "-b:v", f"{source_kbps}k", "-maxrate", f"{source_kbps}k", "-bufsize", f"{buf_kbps}k",
190
                "-c:a", "aac", "-b:a", "192k",
191
                "-movflags", "+faststart", "-y", output_path,
192
            ]
193
        else:
194
            print(f"    [GPU/AMF] 未知源码率")
195
            cmd = [
196
                "ffmpeg", "-i", input_path,
197
                "-c:v", "h264_amf", "-quality", "speed", "-rc", "vbr",
198
                "-c:a", "aac", "-b:a", "192k",
199
                "-movflags", "+faststart", "-y", output_path,
200
            ]
201

202
    # --- Intel QSV ---
203
    elif encoder == "h264_qsv":
204
        if source_kbps > 0:
205
            print(f"    [GPU/QSV] 源码率: {source_kbps}k | 目标: {source_kbps}k | quality={crf_value}")
206
            cmd = [
207
                "ffmpeg", "-i", input_path,
208
                "-c:v", "h264_qsv", "-preset", "medium",
209
                "-b:v", f"{source_kbps}k", "-maxrate", f"{source_kbps}k", "-bufsize", f"{buf_kbps}k",
210
                "-global_quality", str(crf_value),
211
                "-c:a", "aac", "-b:a", "192k",
212
                "-movflags", "+faststart", "-y", output_path,
213
            ]
214
        else:
215
            print(f"    [GPU/QSV] 未知源码率 | quality={crf_value}")
216
            cmd = [
217
                "ffmpeg", "-i", input_path,
218
                "-c:v", "h264_qsv", "-preset", "medium",
219
                "-global_quality", str(crf_value),
220
                "-c:a", "aac", "-b:a", "192k",
221
                "-movflags", "+faststart", "-y", output_path,
222
            ]
223

224
    # --- CPU libx264 ---
225
    else:
226
        if source_kbps > 0 and source_kbps >= 2000:
227
            print(f"    [CPU/x264] 源码率: {source_kbps}k | 目标: {source_kbps}k | preset={preset}")
228
            cmd = [
229
                "ffmpeg", "-i", input_path,
230
                "-c:v", "libx264", "-preset", preset,
231
                "-b:v", f"{source_kbps}k", "-maxrate", f"{source_kbps}k", "-bufsize", f"{buf_kbps}k",
232
                "-c:a", "aac", "-b:a", "192k",
233
                "-movflags", "+faststart", "-y", output_path,
234
            ]
235
        else:
236
            print(f"    [CPU/x264] 未知/低码率 | crf={crf_value} | preset={preset}")
237
            cmd = [
238
                "ffmpeg", "-i", input_path,
239
                "-c:v", "libx264", "-preset", preset, "-crf", str(crf_value),
240
                "-c:a", "aac", "-b:a", "192k",
241
                "-movflags", "+faststart", "-y", output_path,
242
            ]
243

244
    result = subprocess.run(cmd)
245

246
    if result.returncode == 0 and os.path.isfile(output_path):
247
        os.replace(output_path, base + ".mp4")
248
        # 清理原始文件 (如果扩展名不同)
249
        original = input_path
250
        if os.path.isfile(original) and original != base + ".mp4":
251
            os.remove(original)
252
        return True
253

254
    if os.path.isfile(output_path):
255
        os.remove(output_path)
256
    return False
257

258

259
# ---------------------------------------------------------------------------
260
# yt-dlp helpers
261
# ---------------------------------------------------------------------------
262

263
def _progress_hook(d: dict):
264
    """yt-dlp 下载进度回调"""
265
    if d["status"] == "downloading":
266
        pct = d.get("_percent_str", "?")
267
        spd = d.get("_speed_str", "?")
268
        eta = d.get("_eta_str", "?")
269
        print(f"\r  下载中: {pct} | 速度: {spd} | 剩余: {eta}", end="", flush=True)
270
    elif d["status"] == "finished":
271
        print("\n  下载完成，正在合并...")
272

273

274
def _find_output_file(ydl, info: dict) -> str | None:
275
    """根据 yt-dlp info 定位实际输出文件"""
276
    expected = ydl.prepare_filename(info)
277
    if os.path.isfile(expected):
278
        return expected
279
    # 合并后扩展名可能变为 mp4
280
    base, _ = os.path.splitext(expected)
281
    for ext in (".mp4", ".mkv", ".webm", ".ts"):
282
        if os.path.isfile(base + ext):
283
            return base + ext
284
    return None
285

286

287
# ---------------------------------------------------------------------------
288
# 主流程
289
# ---------------------------------------------------------------------------
290

291
def grab(url: str, output_dir: str = ".", output_name: str | None = None,
292
         audio_only: bool = False, quality: int | None = None,
293
         playlist: bool = False, subtitle: bool = False,
294
         crf: int = 23, preset: str = "medium", use_gpu: bool = True) -> int:
295
    """下载视频并确保 H.264 + AAC MP4 输出"""
296
    try:
297
        import yt_dlp
298
    except ImportError:
299
        print("错误: 未安装 yt-dlp，请先执行 pip install yt-dlp")
300
        return 1
301

302
    os.makedirs(output_dir, exist_ok=True)
303

304
    outtmpl = (os.path.join(output_dir, output_name) if output_name
305
               else os.path.join(output_dir, "%(title)s.%(ext)s"))
306

307
    ydl_opts: dict = {
308
        "outtmpl": outtmpl,
309
        "progress_hooks": [_progress_hook],
310
        # 断点续传 & 重试
311
        "continuedl": True,
312
        "retries": 10,
313
        "fragment_retries": 10,
314
        "file_access_retries": 10,
315
        "retry_sleep_functions": {"http": 5, "fragment": 5, "file_access": 3},
316
    }
317

318
    # 格式选择
319
    if audio_only:
320
        ydl_opts["format"] = "bestaudio/best"
321
        ydl_opts["postprocessors"] = [{
322
            "key": "FFmpegExtractAudio",
323
            "preferredcodec": "best",
324
        }]
325
    elif quality:
326
        ydl_opts["format"] = (
327
            f"bestvideo[height<={quality}]+bestaudio"
328
            f"/best[height<={quality}]/best"
329
        )
330
        ydl_opts["merge_output_format"] = "mp4"
331
    else:
332
        ydl_opts["format"] = "bestvideo+bestaudio/best"
333
        ydl_opts["merge_output_format"] = "mp4"
334

335
    if not playlist:
336
        ydl_opts["noplaylist"] = True
337
    if subtitle:
338
        ydl_opts["writesubs"] = True
339
        ydl_opts["writeautomaticsub"] = True
340
        ydl_opts["subtitleslangs"] = ["zh", "en"]
341

342
    print(f"\n正在获取: {url}\n")
343

344
    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
345
        info = ydl.extract_info(url, download=True)
346

347
    if info is None:
348
        print("错误: 无法获取视频信息")
349
        return 1
350

351
    # --- 后处理: 确保 H.264 + AAC MP4 ---
352
    if audio_only:
353
        print("\n音频模式，跳过视频编码检查。")
354

355
    else:
356
        # 收集所有需要检查的文件
357
        if "entries" in info:
358
            entries = [e for e in info["entries"] if e]
359
        else:
360
            entries = [info]
361

362
        print("\n[ 编码检查 ]")
363
        for entry in entries:
364
            filepath = _find_output_file(ydl, entry)
365
            if not filepath:
366
                continue
367

368
            vcodec, acodec = probe_codecs(filepath)
369
            name = os.path.basename(filepath)
370
            print(f"  {name}")
371
            print(f"    视频编码: {vcodec} | 音频编码: {acodec}")
372

373
            is_h264 = vcodec == "h264"
374
            is_aac = acodec in ("aac", "none")
375
            is_mp4 = filepath.lower().endswith(".mp4")
376

377
            if is_h264 and is_aac and is_mp4:
378
                print("    ✓ 已是 H.264 + AAC MP4，跳过")
379

380
            elif is_h264 and is_aac and not is_mp4:
381
                print("    → 编码正确，封装为 MP4...")
382
                if remux_to_mp4(filepath):
383
                    print("    ✓ 封装完成 (remux, 无损)")
384
                else:
385
                    print("    ✗ 封装失败，保留原始文件")
386

387
            else:
388
                print(f"    → 需要转码 ({vcodec}/{acodec} → h264/aac)...")
389
                if transcode(filepath, crf=crf, preset=preset, use_gpu=use_gpu):
390
                    print("    ✓ 转码完成")
391
                else:
392
                    print("    ✗ 转码失败，保留原始文件")
393

394
    print("\n全部完成!")
395
    return 0
396

397

398
def main():
399
    p = argparse.ArgumentParser(
400
        description="快速获取 - 下载任意网站视频 (H.264 + AAC MP4)",
401
    )
402
    p.add_argument("url", help="视频 URL")
403
    p.add_argument("-o", "--output", help="输出文件名")
404
    p.add_argument("-d", "--output-dir", default=".", help="输出目录 (默认: 当前目录)")
405
    p.add_argument("-a", "--audio", action="store_true", help="仅下载音频")
406
    p.add_argument("-q", "--quality", type=int, help="最高分辨率 (如 720, 1080)")
407
    p.add_argument("-p", "--playlist", action="store_true", help="下载整个播放列表")
408
    p.add_argument("-s", "--subtitle", action="store_true", help="下载字幕")
409
    p.add_argument("--crf", type=int, default=23,
410
                   help="H.264 CRF 质量值 (默认: 23, 范围 0-51, 越小质量越高)")
411
    p.add_argument("--preset", default="medium",
412
                   choices=["ultrafast", "superfast", "veryfast", "faster",
413
                            "fast", "medium", "slow", "slower", "veryslow"],
414
                   help="编码速度预设 (默认: medium)")
415
    p.add_argument("--no-gpu", action="store_true",
416
                   help="禁用 GPU 加速, 强制使用 CPU 软编码")
417

418
    args = p.parse_args()
419
    sys.exit(grab(
420
        url=args.url,
421
        output_dir=args.output_dir,
422
        output_name=args.output,
423
        audio_only=args.audio,
424
        quality=args.quality,
425
        playlist=args.playlist,
426
        subtitle=args.subtitle,
427
        crf=args.crf,
428
        preset=args.preset,
429
        use_gpu=not args.no_gpu,
430
    ))
431

432

433
if __name__ == "__main__":
434
    main()

quick_audio.py#

1
"""
2
快速获取音频 - 使用 yt-dlp 下载任意网站音频，转为 AAC 编码的 M4A 文件
3

4
输出 M4A (AAC) — 兼容 iPhone / Android / Windows / Mac / 车载 / 所有主流播放器。
5
可选 --mp3 输出 MP3 格式以兼容极老旧设备。
6

7
用法:
8
    python quick_audio.py <URL>
9
    python quick_audio.py <URL> -d D:/Downloads
10
    python quick_audio.py <URL> -b 320       # 320kbps 高音质
11
    python quick_audio.py <URL> --mp3         # 输出 MP3 格式
12
"""
13

14
import argparse
15
import io
16
import os
17
import subprocess
18
import sys
19

20
# Fix Windows console encoding
21
if sys.platform == "win32":
22
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
23
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
24

25

26
# ---------------------------------------------------------------------------
27
# helpers
28
# ---------------------------------------------------------------------------
29

30
def _progress_hook(d: dict):
31
    """yt-dlp 下载进度回调"""
32
    if d["status"] == "downloading":
33
        pct = d.get("_percent_str", "?")
34
        spd = d.get("_speed_str", "?")
35
        eta = d.get("_eta_str", "?")
36
        print(f"\r  下载中: {pct} | 速度: {spd} | 剩余: {eta}", end="", flush=True)
37
    elif d["status"] == "finished":
38
        print("\n  下载完成，正在处理音频...")
39

40

41
def _find_file(ydl, info: dict) -> str | None:
42
    """定位 yt-dlp 实际输出的文件"""
43
    expected = ydl.prepare_filename(info)
44
    if os.path.isfile(expected):
45
        return expected
46
    base, _ = os.path.splitext(expected)
47
    for ext in (".m4a", ".mp3", ".ogg", ".opus", ".webm", ".wav", ".flac", ".wma", ".aac"):
48
        if os.path.isfile(base + ext):
49
            return base + ext
50
    return None
51

52

53
def _probe_audio_codec(filepath: str) -> str:
54
    """检测音频编码格式"""
55
    result = subprocess.run(
56
        ["ffprobe", "-v", "error",
57
         "-select_streams", "a:0",
58
         "-show_entries", "stream=codec_name",
59
         "-of", "csv=p=0", filepath],
60
        capture_output=True, text=True, timeout=10,
61
        encoding="utf-8", errors="replace",
62
    )
63
    return result.stdout.strip() or "unknown"
64

65

66
def _convert(input_path: str, bitrate: int = 192, output_mp3: bool = False) -> bool:
67
    """转码音频为 AAC/M4A 或 MP3"""
68
    base, _ = os.path.splitext(input_path)
69
    target_ext = ".mp3" if output_mp3 else ".m4a"
70
    output_path = base + "_tmp" + target_ext
71

72
    if output_mp3:
73
        codec = "libmp3lame"
74
        quality_arg = ["-b:a", f"{bitrate}k"]
75
        print(f"    → 转码为 MP3 ({bitrate}kbps)...")
76
    else:
77
        codec = "aac"
78
        quality_arg = ["-b:a", f"{bitrate}k"]
79
        print(f"    → 转码为 AAC/M4A ({bitrate}kbps)...")
80

81
    cmd = [
82
        "ffmpeg", "-i", input_path,
83
        "-c:a", codec, *quality_arg,
84
        "-movflags", "+faststart",
85
        "-y", output_path,
86
    ]
87
    result = subprocess.run(cmd)
88

89
    if result.returncode == 0 and os.path.isfile(output_path):
90
        final_path = base + target_ext
91
        os.replace(output_path, final_path)
92
        # 清理原始文件
93
        if os.path.isfile(input_path) and input_path != final_path:
94
            os.remove(input_path)
95
        return True
96

97
    if os.path.isfile(output_path):
98
        os.remove(output_path)
99
    return False
100

101

102
# ---------------------------------------------------------------------------
103
# 主流程
104
# ---------------------------------------------------------------------------
105

106
def grab_audio(url: str, output_dir: str = ".", output_name: str | None = None,
107
               bitrate: int = 192, playlist: bool = False,
108
               output_mp3: bool = False) -> int:
109
    """下载音频并转为 AAC/M4A 或 MP3"""
110
    try:
111
        import yt_dlp
112
    except ImportError:
113
        print("错误: 未安装 yt-dlp，请先执行 pip install yt-dlp")
114
        return 1
115

116
    os.makedirs(output_dir, exist_ok=True)
117

118
    target_ext = ".mp3" if output_mp3 else ".m4a"
119
    outtmpl = (os.path.join(output_dir, output_name) if output_name
120
               else os.path.join(output_dir, "%(title)s.%(ext)s"))
121

122
    ydl_opts: dict = {
123
        "outtmpl": outtmpl,
124
        "format": "bestaudio/best",
125
        "progress_hooks": [_progress_hook],
126
        # 断点续传 & 重试
127
        "continuedl": True,
128
        "retries": 10,
129
        "fragment_retries": 10,
130
        "file_access_retries": 10,
131
        "retry_sleep_functions": {"http": 5, "fragment": 5, "file_access": 3},
132
    }
133

134
    if not playlist:
135
        ydl_opts["noplaylist"] = True
136

137
    target_format = "MP3" if output_mp3 else "AAC/M4A"
138
    print(f"\n正在获取音频 ({target_format}, {bitrate}kbps): {url}\n")
139

140
    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
141
        info = ydl.extract_info(url, download=True)
142

143
    if info is None:
144
        print("错误: 无法获取音频信息")
145
        return 1
146

147
    # 收集条目
148
    if "entries" in info:
149
        entries = [e for e in info["entries"] if e]
150
    else:
151
        entries = [info]
152

153
    # 目标编码
154
    target_codec = "mp3" if output_mp3 else "aac"
155

156
    print(f"\n[ 音频检查 ]")
157
    for entry in entries:
158
        filepath = _find_file(ydl, entry)
159
        if not filepath:
160
            print(f"  ⚠ 未找到文件: {entry.get('title', '?')}")
161
            continue
162

163
        name = os.path.basename(filepath)
164
        codec = _probe_audio_codec(filepath)
165
        _, ext = os.path.splitext(filepath)
166
        is_target = (codec == target_codec and ext.lower() == target_ext)
167

168
        print(f"  {name}")
169
        print(f"    编码: {codec}")
170

171
        if is_target:
172
            print(f"    ✓ 已是目标格式 ({target_codec}{target_ext})，跳过")
173
        else:
174
            _convert(filepath, bitrate=bitrate, output_mp3=output_mp3)
175
            print(f"    ✓ 转码完成 → {target_codec}{target_ext}")
176

177
    print("\n全部完成!")
178
    return 0
179

180

181
def main():
182
    p = argparse.ArgumentParser(
183
        description="快速获取音频 - 下载任意网站音频 (AAC/M4A 或 MP3)",
184
    )
185
    p.add_argument("url", help="音频/视频 URL")
186
    p.add_argument("-d", "--output-dir", default=".", help="输出目录 (默认: 当前目录)")
187
    p.add_argument("-o", "--output", help="输出文件名")
188
    p.add_argument("-b", "--bitrate", type=int, default=192,
189
                   help="音频码率 kbps (默认: 192, 建议: 128/192/256/320)")
190
    p.add_argument("-p", "--playlist", action="store_true", help="下载整个播放列表")
191
    p.add_argument("--mp3", action="store_true",
192
                   help="输出 MP3 格式 (默认: AAC/M4A)")
193
    args = p.parse_args()
194

195
    sys.exit(grab_audio(
196
        url=args.url,
197
        output_dir=args.output_dir,
198
        output_name=args.output,
199
        bitrate=args.bitrate,
200
        playlist=args.playlist,
201
        output_mp3=args.mp3,
202
    ))
203

204

205
if __name__ == "__main__":
206
    main()