* fix(transcode): ensure durable file exchange and crash recovery across workflow steps * fix(transcode): recognize AWS SDK NoSuchKey by name and add workflow E2E recovery test
Shumai
The best open-source Frame.io alternative for all your creative work.
Website | Docs | Demo | Discord | 中文
Features
Shumai is an open-source Frame.io alternative built for creative teams to collaborate and share media with ease:
- S3-Compatible & Local Storage: Store and serve creative assets securely using the local filesystem or any S3-compatible storage service, including AWS S3, Cloudflare R2, and MinIO.
- Frame-by-Frame Annotations & Comments: Leave precise feedback with frame-specific drawing tools and timestamped comments on both video and image assets.
- Secure Sharing & Collections: Create private share links and curated media collections for clients, stakeholders, and collaborators.
- Granular Access Control: Manage workspace permissions with team-level and project-level role-based access control.
- Durable Workflows via DBOS: Run background tasks and AI agent workflows orchestrated reliably by DBOS on PostgreSQL with automatic recovery and fault tolerance.
- Scalable Deployment on Kubernetes: Horizontally autoscale video transcoding on multiple instances. See EKS Deployment Example.
- 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, FBX, OBJ, STL, USD, and DAE using turntable-renderer.
- 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.
- Semantic Search: Find assets by visual or conceptual meaning using vector embeddings. See documentation.
- 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.
But Shumai goes beyond being a Frame.io alternative. With modern models like GPT-Image-2 and Seedance 2.5, AI can already handle a surprising amount of creative work. That means you can create or update videos and images from a simple prompt without having to jump back into Photoshop, Premiere or Houdini. That is why Shumai includes a powerful agent system:
AI is optional. You can use Shumai as a traditional Frame.io alternative and completely ignore the AI features if they aren't useful for your team.
- Agent as a Team Member: Mention a context-aware AI agent with
@mentionsdirectly in asset comments, just like a real teammate. - Agent as a One-to-One Assistant: Chat privately with the agent and ask it to help with tasks.
- Custom Skills & Tools: Extend the agent by registering custom scripts, tools, and automation skills.
- Model Context Protocol (MCP): Connect agents to external tools and APIs through remote MCP servers, with OAuth authentication and per-agent MCP access.
- Isolated Sandbox Execution: Run agent-submitted scripts safely in a sandboxed environment.
- AI Metadata Autofill: Automatically fill in custom metadata for new assets.
- Resource Quotas: Set usage limits on AI tokens, costs, and tool execution per member, role, or team-wide, with real-time tracking.
Here is a short demo video showing what the Shumai agent can do:
https://github.com/user-attachments/assets/1186067a-72c0-41b9-836f-987438f2332a
Shumai also brings project management into the creative workflow. A built-in Kanban board helps teams organize tasks, track progress, and collaborate in one place.
The ultimate goal is an agentic Kanban, where agents and team members can work together on tasks. This is still a work in progress: you can already create tasks for AI agents, but agents cannot act on those tasks yet.
Note
Media Processing & Storage: When uploading media, Shumai always preserves and stores your original raw file. Note that the file size shown in the system represents the original file size and does not include the size of any transcoded files. For all media types (both images and videos), Shumai creates a 300p WebP poster image to serve as the preview in the file list view. Additionally:
- For Images: Shumai generates a high-quality WebP proxy at the exact same resolution as your original file for optimized viewing.
- For Videos: It generates at least one proxy video (depending on your transcoding settings), alongside a sprite image and a small preview video (capped at 1600 frames) to enable fast timeline scrubbing and lightning-quick previews.
Installation
Below is a quickstart guide for running Shumai with local storage. For advanced configuration options (including S3-compatible storage and distributed worker orchestration), see our Documentation.
Option 1: Docker Compose
Docker Compose is the fastest way to get Shumai running. You do not need to clone the repository or install packages manually. Ensure you have Docker and Docker Compose installed, then follow these steps:
-
Create and navigate to a new directory for your configuration and data volumes:
mkdir shumai && cd shumai -
Download your preferred
docker-compose.yamlconfiguration based on your needs and available RAM:-
Lite (Suggested RAM: 2 GB+): Minimal deployment containing Shumai and PostgreSQL database.
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml -
With Embedding Server (Suggested RAM: 4 GB+): Adds local multimodal semantic search powered by
shumaiOne/embedding-server(EmbeddingGemma 2 740M).curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.embedding.yaml -
Full (Suggested RAM: 8 GB+): All-in-one setup including
embedding-server,turntable-renderer(3D previews), andGotenberg(document PDF proxying).curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.full.yaml
Note
By default, the Docker Compose setups use CPU software transcoding. If your server has a GPU (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, or Rockchip RKMPP) and you want to enable GPU hardware acceleration, check the Hardware Transcoding Guide.
-
-
Configure environment variables (optional):
-
SHUMAI_SERVER_PORTcontrols the port the Shumai server listens on. The default is3000. -
By default, Shumai uses the bundled local storage service in this Docker Compose setup. To use an external S3-compatible storage instead, configure the environment variables for your S3 provider. Here are examples for AWS S3 and Cloudflare R2:
AWS S3 Example:
STORAGE_BACKEND: s3 S3_BUCKET: your-bucket-name S3_ACCESS_KEY_ID: your-access-key-id S3_SECRET_ACCESS_KEY: your-secret-access-key AWS_ENDPOINT_URL_S3: https://s3.us-east-1.amazonaws.comCloudflare R2 Example:
STORAGE_BACKEND: s3 S3_BUCKET: your-bucket-name S3_REGION: auto S3_ACCESS_KEY_ID: your-access-key-id S3_SECRET_ACCESS_KEY: your-secret-access-key AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com -
By default,
AWS_ENDPOINT_URL_S3is set to:http://localhost:{SHUMAI_SERVER_PORT}, if you use local storage and expose Shumai on a custom host/port combination, setAWS_ENDPOINT_URL_S3to the external URL that browsers will use to upload files.For example, if you change the port mapping in
docker-compose.yamlfrom3000:3000to12345:3000and deploy on a server with IP address12.34.56.78, set:AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345This value must be reachable from client browsers and should include the externally exposed port.
-
-
Start the services in detached mode:
docker compose up -d -
Open your browser and access Shumai at
http://localhost:3000(orhttp://<your-server-ip>:3000for remote deployments).
Option 2: Run from Source (Development)
To set up Shumai locally for development:
- Clone the repository and install dependencies:
git clone https://github.com/shumaiOne/shumai.git cd shumai bun install - Start the
pgvectordatabase container:docker run --name shumai_postgres \ -e POSTGRES_USER=shumai \ -e POSTGRES_PASSWORD=shumai_password \ -e POSTGRES_DB=shumai_db \ -p 5432:5432 \ -d pgvector/pgvector:pg18 - Create a
.envfile at the root of the workspace:DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw= STORAGE_BACKEND=local SHUMAI_SERVER_PORT=3000 AWS_ENDPOINT_URL_S3=http://localhost:3000 - Generate i18n translation files:
bun run i18n:compileTip
During frontend development, you can run
bun run i18n:watchin a separate terminal to automatically recompile translation files whenever you edit strings inpackages/webui/messages/. - Apply the database schema migrations:
bun run db:migrate - Start the local development server:
bun run dev
Note
Looking to install Shumai globally via NPM or your package manager? See our NPM Installation Guide.
Command Line Interface (CLI)
Shumai provides a Command Line Interface (CLI) tool to manage projects, folders, and assets, upload files/folders, and create new versions directly from your terminal.
For more details on installation and usage, see the CLI Readme.

