video-cast — 视频投屏到客厅 DLNA 设备
Overview
把本机视频文件投屏到局域网内的 DLNA 渲染器（如极米投影仪、智能电视）。工作流程：SSDP 发现设备 → 在本机启动常驻 HTTP 媒体服务 → 用 UPnP AVTransport 把媒体 URL 推送到设备并播放 → 提供播放控制。遇到设备不支持的编码/容器，自动用 ffmpeg 实时转码为 H.264+AAC 的 MPEG-TS 流。
平台限制：仅支持 macOS / Linux。脚本依赖 Unix 信号（os.kill）、pkill、start_new_session 等，Windows 不可用。
在 AI 助手中怎么用（推荐）
在 WorkBuddy 等 AI 助手中安装本技能后，不需要记命令，直接用自然语言对话即可触发。AI 会自动调用技能脚本完成投屏。示例：
投屏播放：
- 「把 ~/Movies/好时光.mp4 投到电视上」
- 「投屏 ~/Downloads/电影.mkv 到客厅投影仪」
- 「帮我把这个视频推到电视上播放：/Users/pangxiong/Desktop/demo.mp4」
播放控制：
- 「暂停投屏」
- 「继续播放」
- 「跳到 30 分钟」
- 「音量调到 50」
- 「停止投屏」
查看状态：
- 「现在投屏到什么进度了」
- 「看看最近的投屏历史」
AI 会根据你的话自动选择对应的子命令和参数。首次使用前，AI 会先帮你运行依赖安装脚本（setup.sh），之后直接说需求即可。
前置准备（首次使用必须）
运行依赖安装脚本，创建独立 Python 环境并安装 async_upnp_client；ffmpeg 仅转码需要，直投不需要，缺失时脚本只警告不中断：
bash ~/.workbuddy/skills/video-cast/scripts/setup.sh
运行投屏命令时，必须用技能自带的虚拟环境 Python（依赖装在这里）：
PY=~/.workbuddy/cache/video-cast-venv/bin/python
CAST=~/.workbuddy/skills/video-cast/scripts/cast.py
> 在 AI 助手中使用时，AI 会自动执行上述安装和命令调用，无需手动操作。下面各节供 AI 参考执行，也供高级用户手动使用。
投屏工作流
1. 发现设备
$PY $CAST discover
扫描局域网内支持 AVTransport 的 DLNA 渲染器，结果写入状态文件并打印列表。若搜不到，可扩大搜索范围：$PY $CAST discover --target ssdp:all --timeout 8。
2. 投屏播放
$PY $CAST cast <视频文件> # 单设备自动选中
$PY $CAST cast <视频文件> --device 极米 # 多设备时按名称子串指定
$PY $CAST cast <视频文件> --transcode # 强制转码（画面/声音异常时用）
$PY $CAST cast <视频文件> --direct # 强制直投（不转码，支持拖拽进度）
$PY $CAST cast <视频文件> --start 600 # 从第 600 秒开始（转码模式生效）
cast 会：在本机启动常驻后台媒体服务 → 检测格式决定直投或转码 → 推流到设备 → 自动开始播放。直投支持 Range 拖拽进度条；转码为实时流，不支持拖拽。投屏期间媒体服务常驻后台，control stop 会自动清理。
3. 播放控制
$PY $CAST control play # 继续播放
$PY $CAST control pause # 暂停
$PY $CAST control stop # 停止（同时清理本机媒体服务）
$PY $CAST control seek 00:10:00 # 跳转到 10 分钟（也支持纯秒数如 600）
$PY $CAST control volume 50 # 音量 0-100
$PY $CAST status # 查看当前播放状态与进度
$PY $CAST list # 查看最近的投屏历史记录
控制命令直接对设备发 UPnP 指令，是独立的短命令，无需保持 cast 进程。控制/状态命令会优先使用当前投屏会话记录的设备；如无活动会话则回退到 discover 发现的设备。
判断与决策规则
- 直投 vs 转码：默认自动判断。扩展名为 webm/wmv/asf/flv/rmvb/avi 或（有 ffprobe 时）视频编码为 vp9/av1/vc1/wmv/theora → 自动转码；其余直投。用户可用
--transcode/--direct强制覆盖。 - --start 限制：
--start N仅在转码模式下生效（从第 N 秒开始）。直投模式下传--start会打印警告但不生效，如需跳转请投屏后用control seek。 - 设备选择：
--device接受设备名称子串、UDN 或 location URL；不指定且仅一个设备时自动选中；多个设备时不指定会列出并提示用户用--device指明。 - 不兼容兜底：若设备只作播放器（DMP）不接受推送，投屏会失败，此时按
references/troubleshooting.md的「服务器模式」用 gerbera 架设媒体服务器让设备主动浏览。
排障参考
遇到发现失败、推流失败、播放异常、转码问题、极米特定情况时，查阅 references/troubleshooting.md，其中包含完整的排查表、服务器模式备选方案、极米特定说明与命令速查。
注意事项
- 电脑与设备必须同一局域网；macOS 首次运行若弹防火墙入站连接询问，需允许。
- 转码需要 ffmpeg（
brew install ffmpeg）；本机无 ffmpeg 时只能直投。 - 媒体服务日志在
~/.workbuddy/cache/server.log，状态文件在~/.workbuddy/cache/video-cast-state.json，投屏历史在~/.workbuddy/cache/video-cast-castlog.json。 - 异常残留的媒体服务进程可
pkill -f 'cast.py _serve'清理。
卸载与清理
不再使用本技能时，删除以下文件即可彻底清理：
pkill -f 'cast.py _serve' 2>/dev/null # 停掉残留媒体服务
rm -rf ~/.workbuddy/cache/video-cast-venv
rm -f ~/.workbuddy/cache/video-cast-state.json
rm -f ~/.workbuddy/cache/video-cast-castlog.json
rm -f ~/.workbuddy/cache/server.log
