Metadata-Version: 2.4
Name: wanyi-watermark
Version: 2.0.0
Summary: 百分百一键去水印 - 视频链接解析与媒体资源提取MCP服务器，支持抖音/小红书/通用平台，附 CLI / WebUI / Skill 三种交付渠道
Project-URL: Homepage, https://github.com/Ryan7t/wanyi-watermark
Project-URL: Repository, https://github.com/Ryan7t/wanyi-watermark
Project-URL: Issues, https://github.com/Ryan7t/wanyi-watermark/issues
Author-email: wanyi <2368077712@qq.com>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: dashscope
Requires-Dist: fastapi
Requires-Dist: ffmpeg-python
Requires-Dist: imageio-ffmpeg
Requires-Dist: jinja2
Requires-Dist: mcp>=1.0.0
Requires-Dist: pillow
Requires-Dist: pillow-heif
Requires-Dist: requests
Requires-Dist: tqdm
Requires-Dist: uvicorn
Description-Content-Type: text/markdown

# Wanyi Watermark — 抖音 / 小红书智能无水印解析

这是一个面向抖音、小红书分享链接的媒体解析服务，提供 WebUI、HTTP API、CLI、MCP Server 和 Skill 多种使用方式。

项目的核心能力是：输入一段分享文案或链接，自动识别平台与内容类型，并返回可直接使用的无水印视频、原始图片、预览图片以及 Live Photo 动态视频。

> 无水印资源解析、图片提取和下载不需要任何 API 密钥。
> API 密钥只用于可选的“视频转文字”功能。

## 核心功能

| 平台 | 支持的内容 | 主要输出 |
| --- | --- | --- |
| 小红书 | 单图、多图、视频、单 Live Photo、多 Live Photo | 原始图片、预览图、真实 PNG、无水印视频、Live Photo MP4 |
| 抖音 | 无水印视频，兼容已有图文解析 | 无水印视频直链、图片列表、标题和文案 |
| 其他平台 | 通用解析兜底 | 页面中可识别的视频或图片资源 |

### 小红书全类型笔记

对于公开且分享令牌有效的小红书笔记，解析器会自动识别以下类型：

1. 单张静态图片笔记。
2. 多张静态图片笔记。
3. 视频笔记。
4. 单张 Live Photo 笔记。
5. 多张 Live Photo 笔记。

普通图片笔记会按原顺序返回：

- **original_url**：由笔记 **fileId** 还原的最高保真源文件，实际格式可能是 JPEG、PNG、WebP、HEIC 或 AVIF。
- **preview_url**：平台提供的浏览器预览资源，通常体积更小。
- PNG 下载能力：源文件是 PNG 时原样交付；其他格式在明确请求 PNG 时才进行真实转换，并保留源文件中的透明通道。

Live Photo 不重建苹果原生容器，只交付一一对应的两份资源：

- 静态原图。
- MP4 动态视频。

只有静态图与 MP4 都存在时，才会被计入完整 Live Photo。

### 抖音无水印视频

抖音处理器读取页面中的 **window._ROUTER_DATA**，自动判断视频或图文：

- 视频笔记返回无水印播放地址。
- 图文笔记继续返回有序图片列表。
- 保留标题、文案、封面等页面中能够获取的结构化信息。

### 智能解析流程

一次解析请求会完成以下工作：

1. 从分享文案中提取链接。
2. 根据域名识别抖音、小红书或通用平台。
3. 请求一次目标页面，并从页面状态中定位当前笔记。
4. 自动判断视频、静态图文或 Live Photo。
5. 返回统一 JSON，由 WebUI、CLI、MCP 和其他前端共同消费。

小红书页面请求默认使用桌面端 UA；遇到传输异常、空壳页面或目标笔记缺失时，会自动回退移动端 UA。解析器只接受目标笔记数据，不会误取页面中的推荐笔记。

### 官方资源直链与代理

接口会优先返回平台官方媒体直链。API 接入方建议采用以下策略：

1. 预览优先使用 **preview_url**。
2. 下载优先使用 **original_url** 或视频 **url**。
3. 只有遇到防盗链、跨域、格式不兼容或 CDN 直连失败时，才使用服务端 **/api/proxy**。

这样可以减少服务端带宽占用。WebUI 自带的代理同时支持防盗链请求、视频 Range、真实格式识别和按需 PNG 转换。

## 统一返回结构

### 小红书图片或 Live Photo

~~~json
{
  "status": "success",
  "schema_version": 2,
  "platform": "xiaohongshu",
  "type": "image",
  "note_id": "笔记 ID",
  "title": "标题",
  "caption": "文案",
  "image_count": 1,
  "live_photo_count": 1,
  "images": [
    {
      "index": 1,
      "kind": "live_photo",
      "url": "原始图片地址",
      "original_url": "原始图片地址",
      "preview_url": "预览图片地址",
      "is_live_photo": true,
      "live_video": {
        "url": "MP4 地址",
        "backup_urls": [],
        "codec": "h264"
      }
    }
  ]
}
~~~

### 视频

~~~json
{
  "status": "success",
  "schema_version": 2,
  "platform": "xiaohongshu",
  "type": "video",
  "title": "标题",
  "caption": "文案",
  "url": "无水印视频地址"
}
~~~

抖音与通用平台继续使用相同的 **status / platform / type / title / caption / url / images** 顶层约定。消费端应先判断 **type**，再读取 **url** 或 **images**。

## 启动 WebUI

### 环境要求

- Python 3.10 或更高版本。
- Windows、Linux 或 macOS。
- 仅解析和下载媒体时不需要 API 密钥。

### 方式一：使用 uv

在项目根目录执行：

~~~powershell
cd D:\code\uni\watermark\server\mcp-server
uv sync
uv run python web\app.py
~~~

启动成功后访问：

~~~text
http://localhost:8080
~~~

### 方式二：使用 venv 和 pip

Windows PowerShell：

~~~powershell
cd D:\code\uni\watermark\server\mcp-server
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e .
python web\app.py
~~~

Linux 或 macOS：

~~~bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .
python web/app.py
~~~

### 修改端口和日志级别

默认监听 **0.0.0.0:8080**。Windows PowerShell 示例：

~~~powershell
$env:PORT = "8081"
$env:WANYI_WEB_LOG_LEVEL = "DEBUG"
python web\app.py
~~~

然后访问 **http://localhost:8081**。

### WebUI 可用功能

- 单输入框自动识别抖音、小红书和通用平台。
- 展示标题、文案、无水印视频和完整图集。
- 小红书图片支持预览、原始格式下载和真实 PNG 下载。
- Live Photo 支持静态图与 MP4 配对展示、播放和下载。
- 视频代理支持 Range 请求，可正常拖动播放进度。
- 前后端使用同一个追踪 ID 输出中文耗时日志。

### 健康检查

~~~text
GET http://localhost:8080/api/health
~~~

正常响应示例：

~~~json
{
  "status": "ok",
  "api_key_configured": false,
  "asr_backend_default": "dashscope"
}
~~~

## HTTP API

### 智能解析

~~~text
POST /api/parse
Content-Type: application/json
~~~

请求体：

~~~json
{
  "url": "分享链接或包含链接的分享文案"
}
~~~

PowerShell 示例：

~~~powershell
$body = @{
  url = "在这里粘贴抖音或小红书分享链接"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:8080/api/parse" -Method Post -ContentType "application/json" -Body $body
~~~

### 媒体代理

~~~text
GET /api/proxy?url=<媒体地址>
GET /api/proxy?url=<图片地址>&format=original
GET /api/proxy?url=<图片地址>&format=png
~~~

- 不带 **format**：流式转发媒体，适合视频播放和普通预览。
- **format=original**：识别真实图片格式并使用正确扩展名交付。
- **format=png**：源 PNG 原样返回，其他可解码格式转换成真实 PNG。
- 图片格式处理上限为 128 MB。

在移动端或小程序接入时，应优先尝试官方直链，把代理作为失败兜底，避免所有媒体流量经过本服务。

## CLI

仅解析信息：

~~~powershell
python -m wanyi_watermark.cli -l "<分享链接>" -a info
~~~

下载并保留原始格式：

~~~powershell
python -m wanyi_watermark.cli -l "<分享链接>" -a download -o .\output --image-format original
~~~

将静态图片保存为真实 PNG：

~~~powershell
python -m wanyi_watermark.cli -l "<分享链接>" -a download -o .\output --image-format png
~~~

Live Photo 下载目录示例：

~~~text
output/
└── 笔记标题/
    ├── 01_image.heic
    ├── 01_live.mp4
    ├── 02_image.png
    └── 02_live.mp4
~~~

## MCP Server

启动 MCP Server：

~~~powershell
python -m wanyi_watermark
~~~

主要工具：

- **parse_douyin_link**：解析抖音视频或图文。
- **parse_xhs_link**：解析小红书视频、普通图文和 Live Photo。
- **parse_generic_link**：通用平台兜底解析。
- **extract_douyin_text**：可选的视频转文字工具，需要转写密钥。

Codex Desktop、Claude Desktop 等本地 MCP 配置示例：

~~~json
{
  "mcpServers": {
    "wanyi-watermark": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "D:/code/uni/watermark/server/mcp-server",
        "python",
        "-m",
        "wanyi_watermark"
      ]
    }
  }
}
~~~

仅使用资源解析工具时，不需要配置任何密钥。

## 可选能力：视频转文字

视频转文字是附加能力，不影响无水印资源解析。

| 后端 | 环境变量 | 特点 |
| --- | --- | --- |
| DashScope，默认 | **DASHSCOPE_API_KEY** | 阿里云百炼 paraformer-v2，视频 URL 直传 |
| SiliconFlow | **SILICONFLOW_API_KEY** | SenseVoice，需要下载媒体并提取音频，支持大文件分段 |

后端选择优先级：

~~~text
命令或请求中的显式 backend > ASR_BACKEND 环境变量 > dashscope
~~~

Windows PowerShell 配置示例：

~~~powershell
$env:DASHSCOPE_API_KEY = "your-api-key"
$env:ASR_BACKEND = "dashscope"
python web\app.py
~~~

使用 SiliconFlow：

~~~powershell
$env:SILICONFLOW_API_KEY = "your-api-key"
$env:ASR_BACKEND = "siliconflow"
python -m wanyi_watermark.cli -l "<视频分享链接>" -a extract -b siliconflow -o .\output
~~~

SiliconFlow 后端优先使用系统 ffmpeg；系统没有 ffmpeg 时，会使用 **imageio-ffmpeg** 内置二进制。超过 1 小时或 50 MB 的媒体会自动分段处理。

## 项目结构

~~~text
wanyi_watermark/
├── resolver.py                 # 平台识别与统一解析门面
├── douyin_processor.py         # 抖音页面解析
├── xiaohongshu_processor.py    # 小红书全类型笔记解析
├── image_formats.py            # 图片签名识别与真实 PNG 转换
├── media_fetch.py              # 媒体请求、Referer 与重试
├── cli.py                      # CLI
├── server.py                   # MCP Server
└── transcription.py            # 视频转文字统一入口

web/
├── app.py                      # FastAPI WebUI 与 HTTP API
├── templates/index.html
└── static/
~~~

**resolver.py** 是平台分发和统一返回结构的单一事实源。MCP、CLI、WebUI 和 Skill 均复用同一解析逻辑。

## 测试

~~~powershell
python -m pip install pytest
python -m pytest -q
node --check web\static\app.js
~~~

测试覆盖小红书桌面端/移动端状态结构、静态图、Live Photo 配对、请求回退、真实图片格式识别、PNG 转换、CLI 下载和 Web 图片代理。

## 部署提示

- 生产环境建议使用 Nginx、Caddy 或其他网关反向代理 WebUI 端口。
- API 消费端应优先使用解析结果中的官方媒体直链，服务端代理仅作为防盗链或格式兼容兜底。
- **/api/proxy** 会消耗本机带宽和 CPU，尤其是大图 PNG 转换和视频代理。
- 私密、删除、仅自己可见、分享令牌过期或平台风控拦截的笔记无法保证解析成功。
- 不要在代码或仓库中硬编码转写 API 密钥。

## 版本记录

### 2.0.0 - 2026-08-05

- 小红书解析升级为全类型笔记支持：单图、多图、视频、单 Live Photo 和多 Live Photo。
- 图片结果升级为 `schema_version: 2`，统一提供原图、预览图和按需真实 PNG 转换能力。
- Live Photo 只交付一一对应的“静态原图 + MP4 动态视频”。
- 官方媒体直链优先，服务端代理仅作为防盗链、跨域和格式兼容兜底。
- WebUI、CLI、MCP、Skill 和 HTTP API 统一复用解析门面。
- 新增 Pillow、pillow-heif 依赖，支持 PNG、HEIC、AVIF 等图片格式识别与转换。

## 法律与使用声明

- 本项目仅用于合法的学习、研究和个人内容管理场景。
- 使用者应遵守相关平台规则、法律法规和知识产权要求。
- 禁止使用本项目获取、传播无权访问或未经授权的内容。
- 使用者应自行承担运行和使用本项目产生的责任与风险。

## License

Apache License 2.0

## 致谢

本项目基于 [douyin-mcp-server](https://github.com/yzfly/douyin-mcp-server) 二次开发，并在此基础上增加小红书全类型笔记、统一解析门面、WebUI、CLI、媒体代理和双 ASR 后端。
