# screen_server

**Repository Path**: frankzhang/screen_server

## Basic Information

- **Project Name**: screen_server
- **Description**: screen_server 是一个跨平台（支持 OpenHarmony 和 Android）的高性能屏幕录制与推流服务端
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-08-25
- **Last Updated**: 2025-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# screen_server

## 项目简介

`screen_server` 是一个跨平台（支持 OpenHarmony 和 Android）的高性能屏幕录制与推流服务端。其核心设计是通过统一的 `Device` 接口采集设备屏幕，将采集到的原始帧编码为 H264 流，并通过线程安全队列缓冲后推送给 socket 客户端，极大降低丢帧风险，适合远程桌面、投屏、自动化测试等场景。

---

## 主要特性

- **统一的 Device 接口**：支持多平台（OpenHarmony/Android）屏幕采集与编码，便于扩展。
- **高效线程安全队列**：采集线程与推送线程解耦，避免因网络波动导致的丢帧。
- **H264 实时推流**：编码后数据通过 TCP socket 实时推送，客户端可直接解码播放。
- **支持多客户端并发**：每个客户端独立队列与线程，互不影响。
- **丰富的设备信息查询**：支持查询设备型号、分辨率、DPI、系统版本等。

---

## 核心架构

### Device 接口

所有平台采集实现都继承自 `Device` 抽象类，接口定义如下：

```cpp
class Device {
public:
    virtual ~Device() = default;
    virtual bool startScreenCapture() = 0;
    virtual void stopScreenCapture() = 0;
    virtual void registerDataCallback(DataCallback cb) = 0;
    virtual void unregisterDataCallback(DataCallback cb) = 0;
    virtual DeviceInfo getDeviceInfo() = 0;
};
```

- **startScreenCapture/stopScreenCapture**：启动/停止屏幕采集与编码。
- **registerDataCallback**：注册数据回调，采集到的每一帧 H264 数据通过回调推送。
- **getDeviceInfo**：获取设备详细信息。

平台实现包括：
- `AndroidDevice`：基于 `screenrecord` 采集并编码。
- `OHOSDevice`：基于 OpenHarmony 多媒体采集与编码 API。

### 线程安全队列防丢帧

主流程采用如下设计：

1. **采集线程**：采集并编码为 H264 后，通过回调将数据 `push` 到队列。
2. **推送线程**：独立线程从队列 `pop` 数据，通过 socket 发送给客户端。
3. **队列满/慢消费时自动阻塞采集，防止内存暴涨和丢帧。**

核心代码片段（见 `src/main.cpp`）：

```cpp
struct FrameQueue {
    std::queue<std::vector<uint8_t>> queue;
    std::mutex mtx;
    std::condition_variable cv;
    bool stopped = false;

    void push(const std::vector<uint8_t>& frame);
    bool pop(std::vector<uint8_t>& frame);
    void stop();
};
```

---

## 通信协议

- **命令类型（客户端->服务端）**
    - `CMD_QUERY_DEVICE_INFO`：查询设备信息
    - `CMD_START_SCREEN_CAPUTRE`：开始录屏
    - `CMD_STOP_SCREEN_CAPUTRE`：停止录屏
    - `CMD_EXIT`：关闭服务端

- **数据包类型（服务端->客户端）**
    - `PKT_DEVICE_INFO`：设备信息
    - `PKT_SCREEN_FRAME`：H264帧数据
    - `PKT_ERROR`：错误信息

---

## 构建方法

### OpenHarmony

1. 安装 OpenHarmony Native SDK 并配置环境变量。
2. 执行 PowerShell 脚本自动编译（支持 arm/aarch64/x86_64）：

```powershell
# 默认SDK路径和架构
./build_ohos.ps1
# 或自定义
./build_ohos.ps1 -SDK_PATH "E:\OpenHarmony\Sdk\15" -ARCH "aarch64"
```

- 输出文件：`release/ohos`
- 编译后自动 strip，体积更小。

### Android

1. 安装 Android NDK 并配置 `ANDROID_NDK_HOME` 环境变量。
2. 执行 PowerShell 脚本自动编译：

```powershell
./build_android.ps1
```

- 输出文件：`release/android`
- 编译后自动 strip，体积更小。

---

## 客户端测试

推荐使用 `test/screen_client.py`（依赖 PySide6、PyAV）：

```bash
cd test
python -m venv venv
venv\Scripts\activate
pip install PySide6 av

# android
python screen_client.py android

# ohos
python screen_client.py ohos
```

- 支持 OpenHarmony/Android 设备自动检测与连接。
- 实时显示推流画面，支持分辨率切换。

---

## 典型用例

- **远程桌面/投屏**：低延迟高质量屏幕推流。
- **自动化测试**：多设备并发采集与回放。
- **监控与录制**：可扩展为录像、云端分析等场景。

---

## 目录结构

```
src/         # 核心C++源代码
include/     # 头文件，含Device接口
test/        # Python客户端与协议测试
release/     # 编译输出
build_*.ps1  # 跨平台自动构建脚本
```

---

## 贡献与扩展

- 欢迎基于 `Device` 接口扩展更多平台采集实现。
- 可自定义回调、协议、推流方式等。

---

如需详细协议、二次开发或遇到问题，欢迎提 issue 或 PR！