/studio

name: helios-studio
description: Studio tool for developing and previewing Helios compositions. Use when you want to launch the interactive development environment or manage assets.

Helios Studio

The Helios Studio is a Vite-based development server and preview environment. It provides a hot-reloading environment for building compositions and acts as the "Editor" interface for Helios projects.

Quick Start

Run the studio from your project root:

npx @helios-project/cli studio

This will start a local server (typically at `http://localhost:5173`) where you can view and debug your composition.

Features

Playback & Preview

• **Interactive Timeline:** Scrub through your animation frame-by-frame.
• **Hot Reloading:** Preserves timeline state (current frame) when you edit code.
• **Audio Controls:** Volume slider and Mute toggle.
• **Safe Area Guides:** Toggle Action/Title Safe guides and Crosshair.
• **Keyboard Shortcuts:**
• `Space`: Play/Pause
• `Arrow Left/Right`: Step 1 frame
• `Shift + Arrow`: Step 10 frames
• `Home`: Seek to start
• `I` / `O`: Set In / Out points (Playback Range)
• `L`: Toggle Loop

MCP Server

The Studio runs a Model Context Protocol (MCP) server, allowing AI agents to:

• Inspect composition schemas.
• Update input props.
• Trigger renders.
• Create new compositions.

Props Editor

The Props Editor generates a UI based on your `HeliosSchema`.

• **Groups:** Organize props into collapsible sections using the `group` schema property.
• **Schema-Aware Inputs:**
• `number`: Slider (if min/max set), Stepped Slider (if step set).
• `color`: Color picker.
• `boolean`: Toggle switch.
• `string`: Text input or Enum dropdown.
• `image`, `video`, `audio`, `font`: Asset selector with preview.
• `model`: 3D Model selector (.glb, .gltf).
• `json`: JSON file selector.
• `shader`: Shader file selector (.glsl).
• **Recursive Support:** Generates nested UIs for `object` and `array` types.
• **Drag & Drop:** Drag assets from the Assets Panel directly into compatible inputs.
• **Metadata Editing:** Click "Edit Composition" to change Width, Height, FPS, and Duration.

Assets Management

• **Assets Panel:** View and manage files in your `assets/` directory.
• **Upload:** Drag & drop files onto the panel to upload them.
• **Previews:** Rich previews for video (hover-play), audio, fonts, and images.
• **Supported Types:**
• Images: jpg, png, svg, webp
• Audio: mp3, wav, ogg
• Video: mp4, webm
• 3D: glb, gltf
• Data: json
• Shaders: glsl, vert, frag

Render Management

• **Renders Panel:** Trigger server-side renders directly from the UI.
• **Configuration:** Select format (MP4/WebM), resolution, and codec.
• **Progress:** Track render progress and cancel jobs if needed.
• **Persistent Jobs:** Render history persists across server restarts.
• **Client-Side Export:** Export directly from the browser using WebCodecs.

Environment Variables

• `HELIOS_PROJECT_ROOT`: Override the root directory scanning path.

  HELIOS_PROJECT_ROOT=./my-project npx @helios-project/cli studio

Common Issues

• **Port in Use:** If 5173 is taken, Vite will try the next available port. Check the terminal output.
• **File Not Found:** Ensure your composition HTML file exists in the directory or subdirectories of the root.

Source Files

• CLI Command: `packages/cli/src/commands/studio.ts`
• Studio App: `packages/studio/`