helios-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 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 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/