diff --git a/README.md b/README.md index acbbfa50..a7e6a7dc 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/README_CN.md b/README_CN.md index 5ce3ee10..bd649501 100644 --- a/README_CN.md +++ b/README_CN.md @@ -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)。 diff --git a/docs/configuration/env-variables.mdx b/docs/configuration/env-variables.mdx index 8efe93e2..0b7fac35 100644 --- a/docs/configuration/env-variables.mdx +++ b/docs/configuration/env-variables.mdx @@ -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` | diff --git a/docs/docs.json b/docs/docs.json index 4b696218..4655860f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -44,6 +44,7 @@ "using-shumai/collections", "using-shumai/share-links", "using-shumai/nle-and-premiere", + "using-shumai/3d-asset-support", "using-shumai/gotenberg" ] }, diff --git a/docs/using-shumai/3d-asset-support.mdx b/docs/using-shumai/3d-asset-support.mdx new file mode 100644 index 00000000..3558d2db --- /dev/null +++ b/docs/using-shumai/3d-asset-support.mdx @@ -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. diff --git a/docs/using-shumai/gotenberg.mdx b/docs/using-shumai/gotenberg.mdx index f898d1f7..7eb939ec 100644 --- a/docs/using-shumai/gotenberg.mdx +++ b/docs/using-shumai/gotenberg.mdx @@ -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: