# 直播伴侣虚拟摄像头（LiveCam Auto）

一个常驻后台的小软件：当检测到**抖音直播伴侣**运行时，自动启动虚拟摄像头并把本地预设视频循环推送到画面里；直播伴侣退出后自动关停虚拟摄像头，节省资源。

## 功能与实现逻辑

| 需求 | 实现方式 |
| --- | --- |
| 1. 软件常驻后台运行 | `app.py` 作为系统托盘程序后台常驻，可设置开机自启 |
| 2. 检测直播伴侣发起摄像头调用 | 监控直播伴侣进程 / 窗口（默认匹配 `livepartner.exe`、`直播伴侣`，可在配置里改） |
| 3. 自动加载本地视频并推送画面 | `streamer.py` 用 OpenCV 解码视频，逐帧送入虚拟摄像头（循环播放） |
| 4. 关闭后自动关停 | 直播伴侣进程退出后自动停止推流并释放虚拟摄像头；推流卡死会自动重启 |

> 说明：Windows 系统里虚拟摄像头必须先存在，直播伴侣才能在列表里选中它。因此本软件用"检测到直播伴侣运行就启动推流"作为触发信号（直播伴侣打开后默认会立即调用摄像头预览），这是最可靠的检测方式。

## 目录结构

```
livecam/
├── app.py              # 主程序：托盘界面 + 常驻后台
├── watcher.py          # 监控状态机：自动启动/关停推流
├── streamer.py         # 视频推流器（子进程）
├── utils.py            # 配置/日志/进程检测/开机自启等工具
├── config.json         # 配置文件
├── requirements.txt    # Python 依赖
├── install_deps.bat    # 一键安装依赖
├── start.vbs           # 双击后台启动
├── smoke_test.py       # 冒烟测试
└── logs/               # 运行日志（app.log、心跳文件）
```

## 安装步骤（一次性）

### 1. 安装 Python
安装 Python 3.10 或更高版本（64 位），安装时勾选 **Add python.exe to PATH**。
验证：命令行执行 `python --version` 能输出版本号。

### 2. 安装虚拟摄像头驱动（二选一，推荐 UnityCapture）
虚拟摄像头需要一个底层驱动，本软件才能把画面送进去：

- **方式 A：UnityCapture（推荐）**
  - 下载：`https://github.com/schellingb/UnityCapture` → Releases 下载最新版
  - 解压后以**管理员身份**运行 `Install.bat`（或按项目说明安装驱动）
  - 装好后系统摄像头列表里出现 **Unity Video Capture**
- **方式 B：OBS Studio**
  - 下载安装 OBS：`https://obsproject.com/zh-cn/download`
  - 安装完成后系统摄像头列表里出现 **OBS Virtual Camera**（无需打开 OBS）

### 3. 安装 Python 依赖
双击 `install_deps.bat`（自动使用国内镜像源，等待完成）。

### 4. 配置视频路径
编辑 `config.json`，把 `video_path` 改成你的视频绝对路径：

```json
{
  "video_path": "D:\\videos\\demo.mp4",
  ...
}
```

## 使用步骤

1. 双击 `start.vbs` 启动软件（后台运行，屏幕右下角出现摄像头托盘图标）。
2. 托盘菜单可：
   - 重新选择视频
   - 手动启动 / 停止虚拟摄像头
   - 开启「开机自动运行」
   - 查看运行状态、打开日志目录
3. 打开**抖音直播伴侣** → 直播设置/摄像头 → 摄像头设备选择 **Unity Video Capture**（或 **OBS Virtual Camera**）。
4. 之后每次开直播伴侣，画面自动播放预设视频；关闭直播伴侣后自动停止。

## 配置说明（config.json）

| 字段 | 说明 | 默认 |
| --- | --- | --- |
| `video_path` | 要播放的视频文件绝对路径 | 空 |
| `loop` | 是否循环播放 | `true` |
| `output_width` / `output_height` | 推流分辨率（建议 1280x720） | `1280` / `720` |
| `fps` | 推流帧率 | `30` |
| `backend` | `auto` / `unitycapture` / `obs` | `auto` |
| `device` | 指定摄像头设备名（`null` 用第一个可用设备） | `null` |
| `target_processes` | 触发检测的进程名/关键词 | `["livepartner.exe", "直播伴侣"]` |
| `check_interval` | 检测间隔（秒） | `2` |
| `auto_start_streaming_when_partner_detected` | 检测到直播伴侣自动启动 | `true` |
| `stop_streaming_when_partner_gone` | 直播伴侣退出自动停止 | `true` |
| `start_with_windows` | 开机自启（托盘里切换，自动同步） | `false` |

## 运行原理

```
┌──────────────────────────────────────────────┐
│ app.py（托盘常驻）                            │
│  └─ watcher.py 状态机（每 2 秒检测一次）       │
│       ├─ 直播伴侣运行 → 启动 streamer.py       │
│       └─ 直播伴侣退出 → 停止 streamer.py       │
│                │                             │
│                ▼                             │
│  streamer.py（子进程）                        │
│   OpenCV 读视频 ──► pyvirtualcam ──► 虚拟摄像头驱动 │
│                        （UnityCapture / OBS）│
└──────────────────────────────────────────────┘
              ▲
              │ 直播伴侣在摄像头列表选择该设备
```

## 常见问题

1. **直播伴侣里看不到虚拟摄像头**：确认已安装 UnityCapture 或 OBS 驱动，且驱动安装时用了管理员权限；确认软件托盘菜单里状态是"推流中"。
2. **画面没有声音**：虚拟摄像头只传输画面。声音请在直播伴侣里选择"麦克风/系统声音"；如需播放视频原声，可另装虚拟声卡（如 VB-Audio Virtual Cable）并在直播伴侣里选择它。
3. **画面卡顿/模糊**：调低 `output_width/height`（如 1280x720）和 `fps`（如 24），或换分辨率更匹配的视频。
4. **杀毒软件拦截**：安装驱动时如被杀毒软件提示，请选择允许；本软件为开源依赖，无恶意行为。
5. **想换触发方式**：如你的直播伴侣进程名不同，在 `target_processes` 里加关键词即可（任务管理器里可查进程名）。

## 生成 / 使用 exe 可执行程序

### 一键打包
双击 `build.bat`，等待完成，产物在 `dist\LiveCamAuto\` 文件夹中（约 150MB）。

### 在电脑上直接使用
1. 把 **整个 `dist\LiveCamAuto` 文件夹**复制到目标电脑（不要只复制 exe）。
2. 双击 `LiveCamAuto.exe`（无需安装 Python）→ 右下角出现托盘图标。
3. 首次运行会自动在 exe 同目录生成 `config.json`，用记事本编辑 `video_path` 填入你的视频路径（或在托盘菜单里「选择视频」）。
4. 托盘菜单 →「开机自动运行」可开启开机自启（写注册表，指向 exe 本身）。
5. 在直播伴侣的摄像头列表里选择虚拟摄像头设备（Unity Video Capture / OBS Virtual Camera）。

> 说明：
> - 打包版把"推流子进程"也打进了同一个 exe（内部用 `--streamer` 参数启动），所以复制一个文件夹即可，无需额外文件。
> - 杀毒软件可能对 PyInstaller 打包的程序误报，如遇拦截请选择"允许"；介意的话可从源码运行（见上文安装步骤）。
> - 重新打包只需改代码后再次运行 `build.bat`。

## 免责与合规声明

- 本软件仅用于技术学习与合法用途（如测试、演示、内容创作）。
- 用预录视频冒充真人实时出镜，可能违反抖音等平台的**服务条款**，导致限流、封号；若用于冒充身份、诈骗等违法行为，由使用者承担全部法律责任。请务必合规使用。
- 项目依赖的开源组件：pyvirtualcam、OpenCV、psutil、pystray 等，均为各自的开源许可。
