Metadata-Version: 2.4
Name: quietlink
Version: 0.1.0
Summary: WebRTC 局域网屏幕共享系统，支持音视频传输
Project-URL: Homepage, https://github.com/anomalyco/quietlink
Project-URL: Documentation, https://github.com/anomalyco/quietlink#readme
Project-URL: Repository, https://github.com/anomalyco/quietlink
Project-URL: Issues, https://github.com/anomalyco/quietlink/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Multimedia :: Video :: Display
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.128.5
Requires-Dist: python-multipart>=0.0.22
Requires-Dist: uvicorn>=0.40.0
Requires-Dist: websockets>=16.0
Dynamic: license-file

# QuietLink - WebRTC 局域网屏幕共享

基于 WebRTC 的纯局域网屏幕共享系统，支持音视频传输，无需互联网连接。

**[English](README_EN.md)** | [![Demo](https://img.shields.io/badge/Demo-Live-green)](https://quietlink.onrender.com/)

## 在线体验

访问 [https://quietlink.onrender.com/](https://quietlink.onrender.com/) 体验在线 Demo。

## 功能特点

- 📺 **屏幕共享**：主机端可共享整个屏幕或单个窗口
- 🔊 **音频传输**：支持系统音频共享（Chrome/Edge），可选启用
- 👁️ **实时观看**：客户端可实时观看共享内容
- 🔒 **房间隔离**：6位数字房间码，确保私密性
- ✅ **授权机制**：主机需手动批准客户端加入请求
- 📴 **纯内网运行**：无需 STUN/TURN 服务器，无需互联网
- 📱 **移动端支持**：支持手机全屏观看，响应式设计
- 🎨 **美观界面**：现代化渐变设计，优秀的用户体验

## 快速开始

```bash
./start.sh [端口] [https]
```

参数说明：
- `端口`：服务器端口，默认 8080
- `https`：可选，启用 HTTPS（自动生成自签名证书）

示例：
```bash
# HTTP 模式
./start.sh

# HTTPS 模式
./start.sh 8443 https
```

## 云端部署

项目支持 Render 部署。

### Render 部署

1. 连接 GitHub 仓库到 Render
2. 创建新的 Web Service
3. 选择 Python 环境，自动检测依赖
4. 部署完成获得 `https://<app-name>.onrender.com` 地址

**注意**：当前项目设计为局域网使用。在公网环境部署后，WebRTC P2P 连接需要额外的 STUN/TURN 服务器支持。公网部署仅供体验，建议在内网环境使用以获得最佳性能。

## 系统要求

- Python 3.14+
- [uv](https://github.com/astral-sh/uv)（自动安装）

## 使用说明

### 共享端（Host）

1. 打开浏览器访问 `http://<服务器IP>:8080/host.html`
2. 勾选"共享系统音频"（可选，默认关闭）
3. 点击"开始屏幕共享"按钮
4. 选择要共享的屏幕或窗口
5. 系统生成6位房间码（如：123456）
6. 将房间码告知观看端
7. 收到加入请求时点击"同意"授权

### 观看端（Client）

1. 打开浏览器访问 `http://<服务器IP>:8080/client.html`
2. 输入房间码（如：123456）
3. 点击"加入"
4. 等待主机批准
5. 连接成功后可以点击"开启声音"播放音频（如果主机共享了音频）
6. 支持全屏观看

## 音频功能

### 主机端
- 默认不传输音频，保护隐私
- 勾选"共享系统音频"可启用音频传输
- Chrome/Edge 支持系统音频捕获
- Firefox 仅支持麦克风（不推荐）

### 客户端
- 默认静音，需要手动点击"开启声音"
- 可以随时点击静音/取消静音按钮控制音频
- 全屏模式下音频控制按钮仍然可用

### 注意事项
- 音频传输会增加网络带宽占用
- 首次使用时浏览器会请求音频权限
- 系统音频捕获需要用户明确授权

## 网络要求

**必须在同一局域网内**（同一网段，如 `192.168.1.x`）才能正常连接。

WebRTC 在同一网段内可以直接通过本地 IP 建立连接，无需 STUN/TURN 服务器。

## 端口说明

| 端口 | 用途 | 说明 |
|------|------|------|
| 8080 | HTTP/WebSocket | 信令服务和页面服务 |
| 8443 | HTTPS | 安全连接（可选） |

## 故障排查

### 连接成功但视频黑屏

1. 检查浏览器控制台是否有 ICE 错误
2. 在 Firefox 地址栏输入 `about:webrtc` 查看详细日志
3. 确认两端在同一网段

### 无声音

1. **主机端**：确认已勾选"共享系统音频"
2. **客户端**：点击"开启声音"按钮取消静音
3. 检查浏览器是否授予了音频播放权限
4. 确认使用的是 Chrome/Edge（支持系统音频）
5. 查看浏览器控制台是否有 `[Audio] Audio track received` 日志

### 音频捕获失败

1. 检查浏览器是否支持系统音频（Chrome/Edge）
2. 确认已授予音频捕获权限
3. 尝试刷新页面重新连接
4. 音频捕获失败不影响视频共享

### 客户端无法访问

1. 确认防火墙放行了 8080 端口：
   ```bash
   # Linux (iptables)
   sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
   ```

2. 检查 SELinux/AppArmor 设置

### 全屏按钮不可见

1. 刷新页面重新加载
2. 检查浏览器是否支持全屏 API
3. 尝试点击视频区域触发全屏

## 项目结构

```
.
├── main.py              # FastAPI 信令服务器
├── start.sh             # 启动脚本
├── pyproject.toml       # Python 依赖
├── certs/               # SSL 证书目录（gitignore）
│   ├── cert.pem
│   └── key.pem
└── static/
    ├── host.html        # 共享端页面
    └── client.html      # 观看端页面
```

## 技术栈

- **后端**：Python + FastAPI + WebSocket
- **前端**：原生 JavaScript + WebRTC API
- **依赖管理**：uv
- **音频编解码**：Opus（WebRTC 默认）

## 安全说明

- 音频默认禁用，保护用户隐私
- 房间码随机生成，防止暴力破解
- 主机需手动批准客户端加入
- 内网使用，无需暴露到公网
- 如需公网部署，请配置强密码和 HTTPS

## 浏览器兼容性

| 功能 | Chrome/Edge | Firefox | Safari |
|------|-------------|---------|--------|
| 视频共享 | ✅ | ✅ | ✅ |
| 系统音频 | ✅ | ❌ | ⚠️ 限制 |
| 麦克风音频 | ✅ | ✅ | ✅ |
| 全屏播放 | ✅ | ✅ | ✅ |
| 移动端 | ✅ | ✅ | ✅ |

## 许可证

MIT License
