# projection

**Repository Path**: ylwu/projection

## Basic Information

- **Project Name**: projection
- **Description**: 一个面向 VIDAA、HappyCast/乐播及其他 DLNA/UPnP MediaRenderer 的 Windows 桌面投屏工具。启动后自动搜索局域网设备，并把设备连接、媒体兼容性、字幕处理和播放记忆整合到同一条使用链路中。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 11
- **Forks**: 5
- **Created**: 2026-07-12
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: application-software

**Tags**: None

## README

# 随享投屏

简体中文 | [English](./README_EN.md)

一个面向 VIDAA、HappyCast/乐播及其他 DLNA/UPnP MediaRenderer 的 Windows 桌面投屏工具。启动后自动搜索局域网设备，并把设备连接、媒体兼容性、字幕处理和播放记忆整合到同一条使用链路中。

## 功能概览

- 自动发现电视，也可输入电视 IP 手动连接。
- 顶部播放器和播放列表始终可见，支持排序、暂停、继续、停止、跳转、音量和顺序续播。
- 文件、网址、FTP/FTPS、M3U8 及字幕相关结果统一加入播放列表，也可立即播放。
- 多个下载、解析、合并或转码任务按顺序逐个执行，可选择完成后留在列表或立即播放。
- 自动保存本地视频播放位置，并在下次打开时继续播放。

## 快速使用
1. 确保电脑和电视连接同一局域网，并在电视上开启可接收 DLNA 投屏的应用。
2. 在顶部选择自动发现的电视；若未发现，使用“手动连接”并输入电视 IP。
3. 选择文件，或在“网址投屏”中输入地址。内容会加入顶部播放列表。
4. 双击列表项或点击“立即播放”；可在顶部控制播放、跳转和音量。
5. 需要合并、下载、字幕或兼容处理时，在处理队列查看进度和完成结果。

## 普通用户下载

发行版已经内置 Python、FFmpeg，不需要另外安装运行环境：

- 推荐下载 `ProjectionTool-vX.X.X-Windows-x64.zip`，解压后运行 `ProjectionTool.exe`；启动更快，适合长期使用。
- 也可以直接下载 `ProjectionTool-vX.X.X-Windows-x64.exe`；它是单文件版本，无需解压，但每次启动需要先释放运行组件。


## 从源码启动

双击 [启动投屏工具.bat](./启动投屏工具.bat)，或把视频文件拖到这个批处理文件上直接打开。也可以在 PowerShell 中运行：

```powershell
git clone <仓库地址>
cd projection
python -m pip install -r requirements.txt
python app.py
```

## 投本地 M3U8

本地 M3U8 有两条入口：

- **直接加入播放列表**：在“文件投屏”选择单个 `.m3u8`，或点击“选择 M3U8 目录并加入”。工具递归检查主清单、子清单、媒体分片、初始化片段和本地密钥；就绪后可按列表顺序直接加载，不生成新文件。
- **批量合并为 MP4**：进入“处理队列”，点击“批量合并 M3U8”。在弹窗中可添加多个目录、移除目录并用“上移 / 下移”调整扫描顺序；确认后，各目录中的清单按目录顺序和文件名顺序加入后台队列，严格一次只处理一个。

单个 M3U8 也可从“文件投屏”载入后创建合并任务。合并结果会先以 pending 项占据播放列表中的原位置，完成后原位就绪，并遵循处理队列的“完成后加入列表 / 完成后立即播放”选择。H.264/AAC 通常只重新封装；编码不兼容时才转换为 H.264/AAC。

清单引用的文件必须位于主清单所在目录或其子目录；为避免读取意外文件，本地清单不接受网络地址和越出该目录的路径。处理不会修改原 M3U8 和分片，请保留全部分片到任务结束。引用在线分片时应改用“网址投屏”。

## 投网页视频

1. 在顶部选择一台已经发现或手动连接的 DLNA 电视。
2. 进入“网址投屏”，点击“粘贴并解析”，或输入 HTTP/HTTPS 地址后点击“解析视频”/按 Enter。
3. 查看解析状态和结果表，在“推荐 / 兼容 / HLS / 需电视支持”等结果中选择清晰度；推荐流会自动选中。
4. 点击“加入列表”按现有顺序排队，或点击“立即播放”将结果置顶并替换当前播放。临时地址过期或解析失败时，使用页面上的“重新解析”，必要时修改网址或复制错误详情。
5. 多条地址点击“批量网址 / FTP”，每行填写一个 HTTP、HTTPS、FTP 或 FTPS URL；HTTP/HTTPS 会严格串行解析，并先以 pending 项进入列表。


## FTP/FTPS 下载后播放

FTP/FTPS 地址可在“网址投屏”单条输入，也可通过“批量网址 / FTP”逐行添加。
FTP/FTPS 任务与其他处理任务共用严格串行队列。程序先完整下载到 `Videos\随享投屏输出`，下载期间列表项保持 pending，文件完成并安全落盘后才原位变为可播放项；不支持边下边播。URL 中的用户名和密码不会显示在播放列表或写入日志，也不会保存到配置中，请仍避免分享原始带凭据 URL。

## 处理队列与输出文件

“处理队列”统一承载 M3U8 合并、FTP/FTPS 下载、批量网址解析、兼容处理和硬字幕任务，并由单一后台工作线程严格串行执行。任务可排队和取消；对应播放列表项在提交时即以 pending 状态占位，成功后原位更新为本地文件或网页视频，失败/取消则原位显示失败，不会悄悄改变列表顺序。

提交任务前可选择：

- **完成后加入列表**：结果就绪后保留在原位置，等待按列表顺序播放。
- **完成后立即播放**：结果就绪后自动置顶，停止并跳过旧播放项，然后立即播放结果。

## 字幕说明

DLNA 协议没有统一规定电视必须显示 MKV 内嵌字幕、MP4 软字幕或外部 SRT。工具可以把字幕设为默认、把外部字幕随媒体地址一起声明，但最终是否显示仍由电视播放器决定。

“生成兼容副本”采用无损封装，速度快，但不能解决电视完全忽略软字幕的问题。“制作硬字幕版”会重新编码整个画面，因此耗时与视频时长、分辨率和显卡编码能力直接相关。硬字幕任务在“处理队列”查看，不存在独立的字幕任务页面。

## 端口检测如何工作

正常路径是 SSDP 自动发现，电视会主动返回自己的描述地址和端口。顶部“手动连接”弹窗是兜底方案，会检测：

- 常见设备端口：`80`、`3000`、`5000`、`7000`、`8000`、`8008`、`8060`、`8080`、`8888`。
- VIDAA/HappyCast 常见动态端口范围：默认 `49152-49200`，可在弹窗中修改。
- 开放端口上的常见 UPnP 描述文件，并从描述文件读取真实控制地址。

不要把范围设置成 `1-65535`。局域网电视检测没有必要做全端口扫描，耗时长，也容易被防火墙拦截。

## 常见问题
- **找不到电视？** 检查两台设备是否在同一局域网，关闭访客网络隔离，并允许程序通过 Windows 专用网络防火墙。
- **播放中断？** 尽量使用网线或 5 GHz Wi-Fi，并减少电脑上的大流量上传或下载。
- **字幕不显示？** 不同电视支持情况不同，请尝试硬字幕版本。
- **网页无法播放？** 地址可能已失效、受登录限制或使用 DRM；受保护内容不支持。
- **在哪里看日志？** `%LOCALAPPDATA%\ProjectionTool\logs\projection.log`。