diff --git a/README.md b/README.md index c526ec2f..8579d063 100644 --- a/README.md +++ b/README.md @@ -233,3 +233,9 @@ For more details on installation and usage, see the [CLI Readme](apps/cli/README ## MCP Server Shumai includes a built-in MCP server at `/mcp`, so external agents such as Claude Code, Cursor, or Kiro can browse and organize your projects with an API token. See the [MCP server guide](docs/developer/mcp-server.mdx) for setup. + +--- + +## Community + +Thanks to [LINUX DO](https://linux.do/) for providing a community for open-source discussions and feedback. diff --git a/README_CN.md b/README_CN.md index efcea715..d494eec7 100644 --- a/README_CN.md +++ b/README_CN.md @@ -5,7 +5,7 @@

Shumai

- 为创意工作打造的开源协作平台。 + 开源版 阅流 / 分秒帧 - 专为创意与视频团队打造的审片与管理平台。

@@ -16,38 +16,39 @@

- 官方网站 | 文档 | 在线演示 | English + 官方网站 | 文档(英文) | 在线演示 | English

![Shumai 应用截图](docs/screenshot.webp) ## 功能 -Shumai 是一个开源的 Frame.io 替代方案,专为创意团队打造,让大家能更轻松地协作、审片和分享素材: +Shumai 是一个专为广告,短剧,漫剧等各类创意团队打造的开源协作管理平台,功能上类似阅流和分秒帧,提供了协作、审片和分享等各种功能: -* **支持 S3 和本地存储**:你可以把创意素材安全地存到本地文件系统,或者任意兼容 S3 的存储服务里,比如 AWS S3、Cloudflare R2、MinIO 等。 -* **逐帧标注和评论**:支持按帧进行精确反馈,可以直接在视频和图片素材上画重点、写评论,还能留下时间戳。 -* **安全分享和合集管理**:可以生成私密分享链接,也能整理成精选合集,方便给客户、同事和合作方查看。 +* **支持 S3 和本地存储**:你可以把创意素材安全地存放在本地硬盘或者任意兼容 S3 的存储服务里,比如 阿里云 OSS 或 MinIO 等。 +* **帧级别标注和评论**:支持按帧进行精确反馈,同时支持直接在视频上进行标注,让团队成员能更精确地Get到你的想法。 +* **安全的分享**:可以生成私密分享链接,同时还支持给分享的图片/视频添加自定义水印,并将水印配置保存为模板以便重复使用。方便给客户、同事和合作方查看。 * **细粒度权限控制**:支持按团队、项目设置角色权限,方便管理不同成员的访问范围。 -* **基于 DBOS 的持久化工作流**:后台任务与 AI 工作流基于 PostgreSQL 由 DBOS 统一持久化编排与调度,具备自动恢复和容错能力。 -* **Kubernetes 弹性扩缩容部署**:支持在多个实例上横向自动扩缩容视频转码工作负载。详见 [EKS 部署示例](eks/README.md)。 +* **基于 DBOS 的持久化工作流**:视频转码任务由 DBOS 统一持久化编排与调度,具备自动恢复和容错能力。 +* **弹性扩缩容部署**:支持在多个实例上横向自动扩缩容视频转码工作负载。详见 [EKS 部署示例](eks/README.md)。 * **自定义素材元数据**:可以按你的制作流程,自由定义动态元数据字段。 -* **分享链接水印**:通过可自定义的文字和图片水印保护共享媒体,并将水印配置保存为模板以便重复使用。 * **丰富的文件格式支持**:支持预览常见创意文件格式,包括图片(支持 PSD)、视频、音频和文档,同时可上传和存储任意类型的文件。 -* **基于转盘渲染服务的 3D 资产预览**:通过集成 [turntable-renderer](https://docs.shumai.one/using-shumai/3d-asset-support) 支持为 GLB、FBX、OBJ、STL、USD 和 DAE 等 3D 模型生成高质量的交互式转盘预览与视频。 -* **基于 Gotenberg 的文档 PDF 转码代理**:通过集成 [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg) 支持将 Word、PowerPoint、Excel、Markdown、HTML 和 CSV 文档高质量转换为 PDF 代理文件进行在线预览。 -* **语义搜索**:支持按画面内容或概念含义搜索素材,底层基于向量嵌入技术。详见[相关文档](https://docs.shumai.one/using-shumai/semantic-search)。 -* **非编剪辑导出与 Premiere 插件(实验性)**:支持将时间戳审阅评论导出至常用非编软件(Premiere Pro XML、DaVinci Resolve EDL、Final Cut Pro、Avid Media Composer),或使用实验性的 Premiere Pro 原生 UXP 插件导入媒体素材并将评论自动同步为时间轴标记。详见[相关文档](https://docs.shumai.one/using-shumai/nle-and-premiere)。 +* **3D 素材预览**:通过集成 [turntable-renderer](https://docs.shumai.one/using-shumai/3d-asset-support) 支持给 GLB、FBX、OBJ、STL、USD 和 DAE 等 3D 模型生成高质量的交互式转盘预览。 +* **Office 与文档在线预览**:通过集成 [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg),自动将 Word、PPT、Excel、Markdown、HTML 和 CSV 高质量转换为 PDF,直接在浏览器里丝滑预览。 +* **语义搜索**:支持按画面内容或概念含义搜索素材,详见[相关文档](https://docs.shumai.one/using-shumai/semantic-search)。 +* **非编剪辑导出与 Premiere 插件(测试版)**:支持将时间戳审阅评论导出至常用非编软件(Premiere Pro XML、DaVinci Resolve EDL、Final Cut Pro、Avid Media Composer),或使用实验性的 Premiere Pro 原生 UXP 插件导入媒体素材并将评论自动同步为时间轴标记。详见[相关文档](https://docs.shumai.one/using-shumai/nle-and-premiere)。 * **内置 MCP 服务端与 CLI 工具**:支持通过 `/mcp` 将外部 AI Agent 接入 Shumai,或使用 `shumai-cli` 在终端中管理项目、素材、评论与元数据。 -但 Shumai 不仅仅只满足于 Frame.io 的开源替代。随着 GPT-Image-2、Seedance 2.5 这类强大模型的问世,AI已经生成产品级的图片/视频。很多时候,你只要给一句提示词,就能直接生成或修改图片和视频,而不用再打开 Photoshop、Premiere 或者 Houdini。也正因为这样,Shumai 才把 AI Agent 做成了核心能力: +Shumai 不仅仅只满足于「阅流」和「分秒帧」的开源替代。随着 GPT-Image-2、Seedance 2.5 这类强大视频/图片生成模型的问世,AI已经能够生成产品级的创意素材。只需要一句提示词,AI就能直接生成或修改图片和视频,而不用再打开 Photoshop、Premiere 或者 Houdini。因此Shumai也添加了Agent相关功能: -* **Agent 就像团队成员**:你可以在素材评论区里直接用 `@` 提到 AI Agent,像拉一个真实同事进来一起看稿一样。 +> **AI 功能完全可选。** 你完全可以把 Shumai 当作纯粹的开源版「阅流 / 分秒帧」来用;如果团队不需要 AI,直接忽略即可。 + +* **Agent 是你的团队成员**:你可以在素材评论区里直接用 `@` 提到 AI Agent,像拉一个真实同事进来一起看稿一样。 * **Agent 也能当你的私聊助手**:你可以单独和它聊天,让它帮你查东西、做任务。 -* **自定义技能和工具**:你可以给 Agent 接上自己的脚本、工具和自动化能力。 -* **Model Context Protocol (MCP) 支持**:通过远程 MCP 服务端为 Agent 接入外部工具与 API,支持 OAuth 鉴权与按 Agent 独立分配访问权限。 +* **自定义技能和工具**:你可以给 Agent 添加自己的脚本、工具和自动化能力。 +* **接入外部 MCP 工具 (Model Context Protocol)**:通过远程 MCP 服务端为 Agent 接入外部工具与 API,支持 OAuth 鉴权与按 Agent 独立分配访问权限。 * **沙箱隔离执行**:Agent 生成的脚本会在隔离环境里运行,更安全。 -* **AI 自动补全元数据**:新素材上传后,系统可以自动帮你补一些元数据。 +* **AI 自动打标与补全元数据**:新素材上传后,AI 可根据画面内容自动识别并填写自定义元数据字段,省去手动归档打标的麻烦。 * **资源配额**:支持按成员、角色或全团队对 AI Token、成本和工具调用设置使用上限与实时用量监控。 下面是一个简短的 demo 视频,展示了 Shumai Agent 能做什么: @@ -67,15 +68,17 @@ Shumai 也将项目管理融入了创意工作流程。 内置的看板可以帮 > * **图片:** 会生成一份与原图分辨率完全一致的高质量 WebP 转码版本,在保证画质的同时提升浏览性能。 > * **视频:** 会根据转码配置生成至少一个代理视频,同时生成雪碧图(Sprite)和一段最长 1600 帧的低分辨率转码视频,用于实现快速拖动时间轴和即时视频预览。 +如果你有任何反馈或想法,欢迎在 [Issue #329](https://github.com/shumaiOne/shumai/issues/329) 中和我们交流。如果 Shumai 对你有帮助,希望能给我们点个 ⭐,或者安利给身边做视频/创意的朋友。 + --- ## 安装指南 -以下是使用本地存储运行 Shumai 的快速上手指南。如需了解高级配置(包括 S3 兼容存储配置、分布式 worker 编排等),请参阅我们的[官方文档](https://docs.shumai.one/getting-started/overview)。 +以下是使用本地存储的快速安装指南。如需了解高级配置(包括 S3 兼容存储配置、分布式 worker 编排等),请参阅我们的[官方文档](https://docs.shumai.one/getting-started/overview)。 ### 方案一:使用 Docker Compose(推荐)
- + 复制这个提示词,让agent帮你安装 ``` @@ -93,38 +96,38 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA ```
-使用 Docker Compose 是运行 Shumai 最快的方式。您无需克隆仓库,也不需要手动安装依赖包。请确保电脑上已安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/),然后按照以下步骤操作: +使用 Docker Compose 是运行 Shumai 最快的方式。你无需克隆仓库,也不需要手动安装依赖包。请确保电脑上已安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/),然后按照以下步骤操作: -1. 创建并进入一个新目录,用于存放配置文件和数据卷: +1. 创建一个新文件夹,用于存放配置文件和数据: ```bash mkdir shumai && cd shumai ``` -2. 根据您的需求和机器可用内存,下载对应的 `docker-compose.yaml` 配置文件: +2. 根据你的需求和机器可用内存,下载对应的 `docker-compose.yaml` 配置文件(注意所有镜像都是阿里云源,想要使用dockerhub源请参考不带aliyun的compose文件): - * **精简版(建议内存:2 GB+)**:包含 Shumai 核心应用与 PostgreSQL 数据库。 + * **轻量版(建议内存:2 GB+)**:包含 Shumai 核心应用与 PostgreSQL 数据库。 ```bash curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.yaml ``` - * **含嵌入向量服务版(建议内存:4 GB+)**:新增基于 `shumaiOne/embedding-server` (`EmbeddingGemma 2 740M`) 的本地多模态语义搜索能力。 + * **集成语义搜索版(建议内存:4 GB+)**:新增基于 `shumaiOne/embedding-server` (`EmbeddingGemma 2 740M`) 的本地多模态语义搜索能力。 ```bash curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.embedding.yaml ``` - * **完整版(建议内存:8 GB+)**:一站式全功能套件,包含 `embedding-server`、`turntable-renderer`(3D 模型交互转盘预览)与 `Gotenberg`(文档与表格 PDF 代理转码)。 + * **完整版(建议内存:8 GB+)**:一站式全功能版本,包含 `embedding-server`、`turntable-renderer`(3D 模型交互转盘预览)与 `Gotenberg`(文档与表格 PDF 代理转码)。 ```bash curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.full.yaml ``` > [!NOTE] - > 默认的 Docker Compose 配置使用基于 CPU 的软件转码。如果您的服务器配备了支持的显卡(NVIDIA NVENC、Intel QuickSync、AMD/Intel VA-API 或 Rockchip RKMPP)并需要开启 GPU 硬件加速转码,请参考 [硬件加速转码配置文档](https://docs.shumai.one/configuration/hardware-transcoding)。 + > 默认的 Docker Compose 配置使用基于 CPU 的软件转码。如果你的服务器支持硬件加速(NVIDIA NVENC、Intel QuickSync、AMD/Intel VA-API 或 Rockchip RKMPP),请参考 [硬件加速转码配置文档](https://docs.shumai.one/configuration/hardware-transcoding)。 3. 配置环境变量(可选): -* `SHUMAI_SERVER_PORT` 用于控制 Shumai 服务监听的端口,默认值为 `3000`。 -* 默认情况下,该 Docker Compose 部署会自动启用集成的本地存储。若想切换至外部 S3 兼容存储,请在 `environment` 中配置 S3 提供商的环境变量。以下是 AWS S3 和 Cloudflare R2 的配置示例: + * `SHUMAI_SERVER_PORT` 用于控制 Shumai 服务监听的端口,默认值为 `3000`。 + * 默认情况下,该 Docker Compose 部署会自动启用集成的本地存储。若想切换至外部 S3 兼容存储,请在 `environment` 中配置 S3 提供商的环境变量。以下是 AWS S3 和 Cloudflare R2 的配置示例: **AWS S3 示例:** ```yaml @@ -146,8 +149,8 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA ``` -* 默认情况下 `AWS_ENDPOINT_URL_S3` 指向 `http://localhost:{SHUMAI_SERVER_PORT}`。如果您使用本地存储,但希望在自定义的主机名或端口上公开访问 Shumai,请务必将 `AWS_ENDPOINT_URL_S3` 修改为浏览器访问该服务时所使用的外部 URL。 -例如,如果您将 `docker-compose.yaml` 中的端口映射从 `3000:3000` 修改为了 `12345:3000`,且服务部署在 IP 为 `12.34.56.78` 的服务器上,请进行如下设置: +* 默认情况下 `AWS_ENDPOINT_URL_S3` 指向 `http://localhost:{SHUMAI_SERVER_PORT}`。如果你使用本地存储,但希望在自定义的主机名或端口上公开访问 Shumai,请务必将 `AWS_ENDPOINT_URL_S3` 修改为浏览器访问该服务时所使用的外部 URL。注意就算不使用S3存储(STORAGE_BACKEND: local)也需要正确配置该环境变量。 +例如,如果你将 `docker-compose.yaml` 中的端口映射从 `3000:3000` 修改为了 `12345:3000`,且服务部署在 IP 为 `12.34.56.78` 的服务器上,请进行如下设置: ``` AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345 @@ -164,17 +167,17 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA ``` -5. 打开浏览器,访问 `http://localhost:3000` 即可开始使用(若是远程部署,请访问 `http://<您的服务器IP>:3000`)。 +5. 打开浏览器,访问 `http://localhost:3000` 即可开始使用(若是远程部署,请访问 `http://<你的服务器IP>:3000`)。 #### **扩展转码 Worker(并行处理)** 默认情况下,Docker Compose 部署会按顺序逐个处理视频转码任务。这是出于系统设计考虑,因为视频转码属于计算密集型任务,容易耗尽可用的 CPU 或 GPU 资源。 -但在批量上传(例如一次性上传 100+ 个视频)或处理需要耗费数小时的大型摄像机原始素材时,长时间的转码任务可能会阻塞后续文件的处理。此时,您可以通过增加额外的机器来横向扩展转码吞吐量。每台机器依然按顺序执行任务,但增加 worker 实例能够显著提升整体的并行处理能力。 +但在批量上传(例如一次性上传 100+ 个视频)或处理需要耗费数小时的大型原始视频素材时,长时间的转码任务可能会阻塞后续文件的处理。此时,你可以通过增加额外的机器来横向扩展转码吞吐量。每台机器依然按顺序执行任务,但增加 worker 实例能够显著提升整体的并行处理能力。 Shumai 提供了独立的转码 Worker 镜像(支持 Docker Hub 与阿里云镜像源): -1. **连接准备**:启动一台临时机器,确保其能够正常访问您的 PostgreSQL 数据库和存储后端(例如 S3 或共享存储)。 +1. **连接准备**:启动一台临时机器,确保其能够正常访问你的 PostgreSQL 数据库和存储。 2. **启动 Worker**:配置相同的数据库与存储连接凭据并运行容器: **阿里云镜像(国内推荐):** @@ -189,8 +192,6 @@ Shumai 提供了独立的转码 Worker 镜像(支持 Docker Hub 与阿里云 crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai-transcode:latest ``` - *如使用 Docker Hub,镜像为 [`shumaione/shumai-transcode:latest`](https://hub.docker.com/r/shumaione/shumai-transcode)。* - Worker 启动后会自动接入任务队列,并与主实例并行消费并处理积压的转码任务。 3. **随时停止**:当转码队列处理完毕(或不再需要额外的算力)时,只需停止或移除 Worker 容器: @@ -199,11 +200,11 @@ Shumai 提供了独立的转码 Worker 镜像(支持 Docker Hub 与阿里云 docker stop shumai_transcode_worker ``` - 主 Shumai 服务的运行不会受到任何影响,亦无停机时间。 + 主 Shumai 服务的运行不会受到任何影响,不需要停机。 ### 方案二:源码编译运行(开发环境) -如果您希望在本地参与 Shumai 的开发,请按以下步骤配置开发环境: +如果你希望在本地参与 Shumai 的开发,请按以下步骤配置开发环境: 1. 克隆代码仓库并安装依赖项: ```bash @@ -257,10 +258,16 @@ Shumai 提供了独立的转码 Worker 镜像(支持 Docker Hub 与阿里云 ## 命令行工具 (CLI) -Shumai 自带一个功能完备的命令行工具(CLI),支持您直接在终端里高效管理项目、文件夹、资产,批量上传文件/目录,以及快速创建新版本。 +Shumai 自带一个功能完备的命令行工具(CLI),支持你直接在终端里高效管理项目、文件夹、素材,批量上传文件/目录,以及快速创建新版本。 -关于 CLI 的安装与详细使用指南,请参阅 [CLI Readme](https://www.google.com/search?q=apps/cli/README.md)。 +关于 CLI 的安装与详细使用指南,请参阅 [CLI Readme](apps/cli/README.md)。 ## MCP 服务器 -Shumai 内置 MCP 服务器(地址为 `/mcp`),Claude Code、Cursor、Kiro 等外部智能体可以使用 API 令牌连接,浏览并整理您的项目。配置方法请参阅 [MCP 服务器指南](docs/developer/mcp-server.mdx)。 +Shumai 内置 MCP 服务器(地址为 `/mcp`),Claude Code、Cursor、Kiro 等外部智能体可以使用 API 令牌连接,浏览并整理你的项目。配置方法请参阅 [MCP 服务器指南](docs/developer/mcp-server.mdx)。 + +--- + +## 社区 + +感谢 [LINUX DO](https://linux.do/) 提供开源交流社区,欢迎佬友交流使用体验与改进建议。