mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-19 14:16:29 +00:00
docs: update 3D asset and Gotenberg integration guides (#472)
This commit is contained in:
@@ -33,6 +33,7 @@ Shumai is an open-source Frame.io alternative built for creative teams to collab
|
||||
* **Custom Asset Metadata**: Define dynamic metadata fields tailored to your production pipeline.
|
||||
* **Share Link Watermarking**: Protect shared media with customizable text and image watermarks, and save watermark as reusable templates.
|
||||
* **Wide File Format Support**: Preview common creative file formats, including images (with PSD support), videos, audio, and documents, while allowing any file type to be uploaded and stored.
|
||||
* **3D Asset Turntable Previews**: Generate interactive 3D model turntable previews and videos for formats like GLB, GLTF, FBX, OBJ, STL, USD, and DAE using [turntable-renderer](https://docs.shumai.one/using-shumai/3d-asset-support).
|
||||
* **Office & Document PDF Proxying via Gotenberg**: Convert Word, PowerPoint, Excel, Markdown, HTML, and CSV documents to high-quality PDF proxies for in-browser previewing using [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg).
|
||||
* **NLE Export & Premiere Pro Plugin (Experimental)**: Export timestamped review comments to your favorite non-linear editor (Premiere Pro XML, DaVinci Resolve EDL, Final Cut Pro, Avid Media Composer) or use the experimental Premiere Pro UXP plugin to import media assets and auto-sync comments directly to sequence timeline markers. See [documentation](https://docs.shumai.one/using-shumai/nle-and-premiere).
|
||||
|
||||
|
||||
@@ -33,6 +33,7 @@ Shumai 是一个开源的 Frame.io 替代方案,专为创意团队打造,让
|
||||
* **自定义素材元数据**:可以按你的制作流程,自由定义动态元数据字段。
|
||||
* **分享链接水印**:通过可自定义的文字和图片水印保护共享媒体,并将水印配置保存为模板以便重复使用。
|
||||
* **丰富的文件格式支持**:支持预览常见创意文件格式,包括图片(支持 PSD)、视频、音频和文档,同时可上传和存储任意类型的文件。
|
||||
* **基于转盘渲染服务的 3D 资产预览**:通过集成 [turntable-renderer](https://docs.shumai.one/using-shumai/3d-asset-support) 支持为 GLB、GLTF、FBX、OBJ、STL、USD 和 DAE 等 3D 模型生成高质量的交互式转盘预览与视频。
|
||||
* **基于 Gotenberg 的文档 PDF 转码代理**:通过集成 [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg) 支持将 Word、PowerPoint、Excel、Markdown、HTML 和 CSV 文档高质量转换为 PDF 代理文件进行在线预览。
|
||||
* **非编剪辑导出与 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)。
|
||||
|
||||
|
||||
@@ -99,3 +99,29 @@ API keys to AI providers on startup.
|
||||
| `GEMINI_API_KEY` | API key for Google Gemini provider. | `AIzaSy...` |
|
||||
| `OPENAI_API_KEY` | API key for OpenAI provider. | `sk-proj-...` |
|
||||
| `ANTHROPIC_API_KEY` | API key for Anthropic provider. | `sk-ant-...` |
|
||||
|
||||
---
|
||||
|
||||
## External Integrations Config
|
||||
|
||||
Environment variables can configure external microservices globally. When set, these environment variables take precedence over any team-level settings configured in **Team Settings → Integrations**, and lock the corresponding settings fields in the WebUI to read-only.
|
||||
|
||||
### Gotenberg Document Converter
|
||||
|
||||
Used to convert Office documents, HTML, Markdown, and CSV files into high-fidelity PDF proxies for in-browser previewing. See the [Gotenberg Guide](/using-shumai/gotenberg) for setup instructions.
|
||||
|
||||
| Variable | Description | Example / Default |
|
||||
| :------------------------------ | :----------------------------------------------------------------------- | :---------------------- |
|
||||
| `GOTENBERG_URL` | Base URL of the external Gotenberg conversion API. | `http://gotenberg:3000` |
|
||||
| `GOTENBERG_BASIC_AUTH_USERNAME` | Username when Basic Authentication is enabled on the Gotenberg instance. | `admin` |
|
||||
| `GOTENBERG_BASIC_AUTH_PASSWORD` | Password when Basic Authentication is enabled on the Gotenberg instance. | `secret` |
|
||||
|
||||
### 3D Turntable Renderer
|
||||
|
||||
Used to convert 3D model files (GLB, OBJ, FBX, USD, STL, DAE) into interactive 360° turntable video proxies, posters, and hover sprites. See the [3D Asset Support Guide](/using-shumai/3d-asset-support) for setup instructions.
|
||||
|
||||
| Variable | Description | Example / Default |
|
||||
| :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :------------------------------- |
|
||||
| `TURNTABLE_RENDERER_URL` | Base URL of the external turntable-renderer service. | `http://turntable-renderer:3000` |
|
||||
| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | Username when Basic Authentication is enabled on the turntable renderer (alias: `TURNTABLE_RENDERER_USERNAME`). | `admin` |
|
||||
| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | Password when Basic Authentication is enabled on the turntable renderer (alias: `TURNTABLE_RENDERER_PASSWORD`). | `secret` |
|
||||
|
||||
@@ -44,6 +44,7 @@
|
||||
"using-shumai/collections",
|
||||
"using-shumai/share-links",
|
||||
"using-shumai/nle-and-premiere",
|
||||
"using-shumai/3d-asset-support",
|
||||
"using-shumai/gotenberg"
|
||||
]
|
||||
},
|
||||
|
||||
@@ -0,0 +1,158 @@
|
||||
---
|
||||
title: 3D Asset Support with Turntable Renderer
|
||||
description: Render interactive 3D model turntable previews, sprite scrubbing, and video proxies using turntable-renderer.
|
||||
---
|
||||
|
||||
3D models and mesh assets cannot always be rendered consistently or inspected reliably across diverse client web browsers and mobile devices. Shumai integrates with [turntable-renderer](https://github.com/shumaiOne/turntable-renderer) — a standalone service that executes isolated, headless Blender 5.2 LTS subprocesses — to convert 3D model uploads into standardized, high-fidelity turntable previews.
|
||||
|
||||
Turntable Renderer automatically produces:
|
||||
|
||||
- **1080×1080 Turntable Video (`turntable.mp4`)**: A 4-second, 24-frame, 6 fps video rotating the model 360° (15° per frame) clockwise under dark studio lighting with a pure black background.
|
||||
- **Poster Image (`poster.webp`)**: A crisp still poster for grid cards and immediate file display.
|
||||
- **Hover Sprite Sheet (`sprite.webp`)**: A fast scrubbing sheet allowing users to rotate and inspect the model directly from the file browser on hover.
|
||||
- **Interactive 3D Viewer**: A specialized web viewer featuring 360° ruler scrubbing, rotation angle control (0° to 345°), playback controls, and angle-specific review comments and visual markups.
|
||||
|
||||
---
|
||||
|
||||
## Supported File Types
|
||||
|
||||
When turntable-renderer is configured, Shumai automatically generates 3D turntable proxies for the following formats:
|
||||
|
||||
| Format / Standard | Extensions |
|
||||
| --------------------------- | --------------------------------- |
|
||||
| glTF / Binary glTF | `.glb`, `.gltf` |
|
||||
| Universal Scene Description | `.usd`, `.usda`, `.usdc`, `.usdz` |
|
||||
| Autodesk FBX | `.fbx` |
|
||||
| Wavefront OBJ | `.obj` |
|
||||
| Stereolithography (STL) | `.stl` |
|
||||
| COLLADA | `.dae` |
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Shumai supports configuring the turntable renderer either through the **WebUI** or via **Environment Variables**.
|
||||
|
||||
### 1. WebUI (Team Settings → Integrations)
|
||||
|
||||
Team owners can configure the turntable renderer directly from the web interface:
|
||||
|
||||
1. Navigate to **Team Settings** from the sidebar.
|
||||
2. Select the **Integrations** tab.
|
||||
3. Under **3D Turntable Renderer**, enter the **Server URL** (e.g. `http://turntable-renderer:3000` or `http://localhost:3003`).
|
||||
4. Enter the **Username** and **Password** if Basic Authentication is enabled on the service.
|
||||
5. Click **Test Connection** to verify that Shumai can communicate with the renderer and check the detected Blender version.
|
||||
6. Click **Save Changes**.
|
||||
|
||||
### 2. Environment Variables
|
||||
|
||||
You can also configure turntable-renderer globally across the system using environment variables on the machine running Shumai or the transcode workers:
|
||||
|
||||
| Variable | Required | Description |
|
||||
| ---------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
|
||||
| `TURNTABLE_RENDERER_URL` | Yes (to enable) | Base URL of the turntable renderer service, e.g. `http://turntable-renderer:3000`. |
|
||||
| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | No | Username when Basic Authentication is enabled (alias: `TURNTABLE_RENDERER_USERNAME`). |
|
||||
| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | No | Password when Basic Authentication is enabled (alias: `TURNTABLE_RENDERER_PASSWORD`). |
|
||||
|
||||
### Configuration Priority & Read-Only Mode
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Environment variables take highest priority.** If `TURNTABLE_RENDERER_URL` is set in your environment, Shumai will always use the environment variable configuration.
|
||||
>
|
||||
> When configured via environment variables, the settings in **Team Settings → Integrations** will display a **Configured via environment variables (Read-only)** badge, and the input fields will be locked to prevent accidental changes or configuration drift.
|
||||
|
||||
---
|
||||
|
||||
## Deploying Turntable Renderer
|
||||
|
||||
### Docker Quickstart
|
||||
|
||||
The easiest way to run `turntable-renderer` is using the prebuilt Docker image:
|
||||
|
||||
```bash
|
||||
docker run -d --rm \
|
||||
--name turntable-renderer \
|
||||
-p 3003:3000 \
|
||||
-v $(pwd)/data:/app/data \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
|
||||
shumaione/turntable-renderer:latest
|
||||
```
|
||||
|
||||
> **Note**: Host port `3003` maps to internal container port `3000`. Persistent temporary file storage is kept in `./data`.
|
||||
|
||||
### Docker Compose Setup
|
||||
|
||||
Add a `turntable-renderer` service to your `docker-compose.yaml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
turntable-renderer:
|
||||
image: shumaione/turntable-renderer:latest
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- '3003:3000'
|
||||
volumes:
|
||||
- ./data/turntable:/app/data
|
||||
environment:
|
||||
TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME: admin
|
||||
TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD: your_password
|
||||
```
|
||||
|
||||
Then point Shumai at it:
|
||||
|
||||
```bash
|
||||
TURNTABLE_RENDERER_URL=http://localhost:3003
|
||||
TURNTABLE_RENDERER_BASIC_AUTH_USERNAME=admin
|
||||
TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD=your_password
|
||||
```
|
||||
|
||||
_(If both Shumai and turntable-renderer run within the same Docker Compose network, use `http://turntable-renderer:3000` as the URL)._
|
||||
|
||||
### GPU Acceleration
|
||||
|
||||
A dedicated GPU is optional — turntable-renderer's CPU rendering pipeline is fast enough for modest hardware. When a GPU is passed into the container, it is automatically detected and leveraged.
|
||||
|
||||
#### Intel / AMD (Open Source Drivers)
|
||||
|
||||
Pass the DRI render node:
|
||||
|
||||
```bash
|
||||
docker run -d --rm \
|
||||
--name turntable-renderer \
|
||||
--shm-size=1gb \
|
||||
-p 3003:3000 \
|
||||
--device /dev/dri \
|
||||
-v $(pwd)/data:/app/data \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
|
||||
shumaione/turntable-renderer:latest
|
||||
```
|
||||
|
||||
#### NVIDIA (Proprietary Drivers)
|
||||
|
||||
Requires host driver 580+ and the NVIDIA Container Toolkit (`--runtime nvidia`):
|
||||
|
||||
```bash
|
||||
docker run -d --rm \
|
||||
--name turntable-renderer \
|
||||
--shm-size=1gb \
|
||||
-p 3003:3000 \
|
||||
--runtime nvidia \
|
||||
--gpus all \
|
||||
--device /dev/nvidia-modeset \
|
||||
-v $(pwd)/data:/app/data \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
|
||||
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
|
||||
shumaione/turntable-renderer:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Behavior Without Turntable Renderer
|
||||
|
||||
If turntable-renderer is not configured or unreachable:
|
||||
|
||||
- The 3D model upload completes successfully with status `processed`.
|
||||
- No turntable video proxy, sprite, or poster is generated.
|
||||
- The original raw 3D file is safely preserved and can be downloaded by team members.
|
||||
@@ -32,7 +32,22 @@ When Gotenberg is configured, Shumai automatically generates a PDF proxy for the
|
||||
|
||||
## Configuration
|
||||
|
||||
Gotenberg support is opt-in and controlled by the following environment variables on the machine running the transcode workers:
|
||||
Shumai supports configuring Gotenberg either through the **WebUI** or via **Environment Variables**.
|
||||
|
||||
### 1. WebUI (Team Settings → Integrations)
|
||||
|
||||
Team owners can configure Gotenberg directly from the web interface:
|
||||
|
||||
1. Navigate to **Team Settings** from the sidebar.
|
||||
2. Select the **Integrations** tab.
|
||||
3. Under **Gotenberg Document Converter**, enter the **Server URL** (e.g. `http://gotenberg:3000` or `http://localhost:3000`).
|
||||
4. Enter the **Username** and **Password** if Basic Authentication is enabled on the service.
|
||||
5. Click **Test Connection** to test communication with Gotenberg and verify its health.
|
||||
6. Click **Save Changes**.
|
||||
|
||||
### 2. Environment Variables
|
||||
|
||||
Gotenberg can also be configured globally across the system using environment variables on the machine running Shumai or the transcode workers:
|
||||
|
||||
| Variable | Required | Description |
|
||||
| ------------------------------- | --------------- | ---------------------------------------------------------------- |
|
||||
@@ -40,6 +55,15 @@ Gotenberg support is opt-in and controlled by the following environment variable
|
||||
| `GOTENBERG_BASIC_AUTH_USERNAME` | No | Username when Basic Authentication is enabled on Gotenberg. |
|
||||
| `GOTENBERG_BASIC_AUTH_PASSWORD` | No | Password when Basic Authentication is enabled on Gotenberg. |
|
||||
|
||||
### Configuration Priority & Read-Only Mode
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Environment variables take highest priority.** If `GOTENBERG_URL` is set in your environment, Shumai will always use the environment variable configuration.
|
||||
>
|
||||
> When configured via environment variables, the settings in **Team Settings → Integrations** will display a **Configured via environment variables (Read-only)** badge, and the input fields will be locked to prevent accidental changes or configuration drift.
|
||||
|
||||
### Deploying Gotenberg
|
||||
|
||||
### Docker Quickstart
|
||||
|
||||
You can start a Gotenberg container with a single command:
|
||||
|
||||
Reference in New Issue
Block a user