docs: update 3D asset and Gotenberg integration guides (#472)

This commit is contained in:
Yiling-J
2026-10-12 16:55:20 +08:00
committed by GitHub
parent f952318b34
commit 0f9d213b1d
6 changed files with 212 additions and 1 deletions
+1
View File
@@ -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).
+1
View File
@@ -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)。
+26
View File
@@ -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` |
+1
View File
@@ -44,6 +44,7 @@
"using-shumai/collections",
"using-shumai/share-links",
"using-shumai/nle-and-premiere",
"using-shumai/3d-asset-support",
"using-shumai/gotenberg"
]
},
+158
View File
@@ -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.
+25 -1
View File
@@ -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: