Streamlink 使用手册

Streamlink 超详细使用手册（2025-08 更新）

目录

1. 安装与环境准备
2. 第一次跑起来：5 行命令学会
3. 配置文件：一次设置，永久生效
4. 画质、代理、认证、录制——所有常用参数
5. 典型场景脚本（定时录制、多主播同时观看）
6. 插件管理与自定义
7. Windows GUI 与 OBS 插件补充
8. 故障排查 FAQ

---

1. 安装与环境准备

---

系统	推荐方法	一行命令 / 步骤
Windows 10/11	① 官方 MSI ② Chocolatey ③ Scoop	① 下载 streamlink-windows-builds 直接安装 ② choco install streamlink ③ scoop install streamlink
macOS	Homebrew	brew install streamlink
Linux Debian/Ubuntu	APT	sudo apt update && sudo apt install streamlink
通用	PyPI	pip install -U streamlink（需 Python ≥ 3.8）
开发版	Git	git clone https://github.com/streamlink/streamlink.git && cd streamlink && pip install -e .

验证：

streamlink --version

返回 streamlink 6.x.x 即成功。

---

2. 第一次跑起来：5 行命令学会

---

1. 打开终端 / CMD

2. 查看可用清晰度

   streamlink https://www.twitch.tv/shroud

   终端会回显：

   [cli][info] Found streams: audio_only, 160p, 360p, 480p, 720p60, 1080p60 (best)

3. 直接观看最佳画质

   streamlink https://www.twitch.tv/shroud best

   默认启动 VLC（已安装即可）。

4. 指定播放器

   streamlink -p "mpv" --player-args "--fs --cache=yes" https://www.twitch.tv/shroud 1080p60

5. 保存为本地文件

   streamlink -o ~/shroud_$(date +%F_%H-%M).ts https://www.twitch.tv/shroud best

   按 Ctrl+C 停止即自动完成 TS 文件。

---

3. 配置文件：一次设置，永久生效

---

Streamlink 启动时会按顺序读取：

• %APPDATA%\streamlink\config（Windows）
• ~/.streamlinkrc（Linux/macOS）
• 当前工作目录下的 streamlinkrc

示例 streamlinkrc（ini 风格）：

# 默认播放器
player=vlc
# 默认画质
default-stream=best
# 播放器额外参数
player-args=--file-caching=5000
# 代理
http-proxy=socks5://127.0.0.1:1080
# Twitch 免广告令牌（可选）
twitch-oauth-token=你的token

以后只需：

streamlink https://www.twitch.tv/shroud

---

4. 画质、代理、认证、录制——所有常用参数

---

需求	参数示例
列出画质	streamlink URL
指定画质	streamlink URL 720p,best
录制	-o 文件名.ts
仅提取地址	--stream-url（输出可直接喂给 ffmpeg）
代理	--http-proxy "http://user:pass@ip:port"
自定义 Header	--http-header "User-Agent=Mozilla/5.0"
设置缓冲	--hls-live-edge 1 --hls-segment-threads 4
Twitch 低延迟	--twitch-low-latency
YouTube 会员限定	--youtube-cookie "cookie字符串"
B 站登录	--bilibili-cookie "SESSDATA=xxx"
斗鱼（需第三方插件）	见第 6 节

完整列表：streamlink --help

---

5. 典型场景脚本

---

A. Linux/macOS 定时录播

#!/bin/bash
ROOM=$1
streamlink \
  --loglevel error \
  --retry-streams 30 \
  --retry-open 5 \
  -o "/mnt/nas/${ROOM}_$(date +%F_%H-%M).ts" \
  "https://www.twitch.tv/${ROOM}" best

放到 cron 每天 20:00 执行：

0 20 * * * /path/record.sh shroud

B. Windows 批处理同时多主播

@echo off
start cmd /k streamlink -o D:\Rec\shroud.ts https://www.twitch.tv/shroud best
start cmd /k streamlink -o D:\Rec\xqc.ts   https://www.twitch.tv/xqc   best

C. OBS 转播

1. 安装 OBS-StreamLink 插件
2. OBS → 来源 → + → Streamlink 源
3. 填 URL、选择画质 → 完成，OBS 即可直接拉流。

---

6. 插件管理与自定义

---

• 官方插件目录（随版本更新）：streamlink/plugins/
• 用户自定义目录：
  • Win: %APPDATA%\streamlink\plugins\
  • macOS/Linux: ~/.local/share/streamlink/plugins/

示例：手动修复斗鱼

1. 下载社区维护的 douyu.py 插件
2. 放入上述用户目录
3. 执行 streamlink https://www.douyu.com/123456 即可。

查看所有已加载插件：

streamlink --plugins

---

7. Windows GUI 与 OBS 插件补充

---

• Streamlink Twitch GUI（已归档，仍可用）
  提供图形界面选择主播/画质，底层仍调用 CLI。
  GitHub 下载 streamlink-twitch-gui.exe，首次运行自动关联本地 Streamlink。

• OBS-StreamLink
  适用于 OBS 29+，支持直接添加 Streamlink 源，无需命令行，适合转播、绿幕抠像等场景。

---

8. 故障排查 FAQ

---

错误信息	原因 & 解决
No plugin can handle URL	URL 拼写错误或平台尚未支持；更新 Streamlink 或手动放插件。
403 Client Error	需要登录或 IP 被限制；加 Cookie、代理或 VPN。
VLC 打不开	路径含空格未加引号；在配置里写完整 "C:\Program Files\VideoLAN\VLC\vlc.exe"。
录制 ts 文件音画不同步	使用 -f mp4 --ffmpeg-copyts 或后期 ffmpeg -c copy 再封装。
高 CPU	降低分辨率、用 --player-passthrough=hls 直接让播放器解码。
斗鱼/虎牙提示 Unable to open URL	官方插件已失效，等待社区更新或换第三方插件。

---