Uppergraph

Uppergraph is a command-line interface (CLI) video compositing and rendering engine, designed to be part of animation studio pipelines. It uses HTML as a portable format, allowing artists and directors to review and composite scenes using standard web technologies.

Installation and Usage

Make sure you have run npm install uppergraph.

# Render a scene to mp4
npx uppergraph index.html -o output.mp4

# Render in Watch mode (re-renders when detecting changes in HTML)
npx uppergraph index.html -w

Scene Format (HTML)

Uppergraph parses an HTML file looking for custom elements. All other HTML elements will be ignored unless they are inside <ug-text>.

<ug-scene>

Defines the global render metadata.

• width: Video width (default: 1920)
• height: Video height (default: 1080)
• fps: Frames per second (default: 30)
• duration: Duration in seconds (default: 5)

Example: <ug-scene width="1280" height="720" fps="60" duration="10"></ug-scene>

Animation Attributes (Common)

Both <ug-video> and <ug-text> support dynamic transform properties. You can use fixed numbers or math expressions based on time t (in seconds).

• x: X position (e.g., 200 or t * 100)
• y: Y position
• scaleX: Horizontal scale (default: 1)
• scaleY: Vertical scale (default: 1)
• rotation: Rotation in degrees (e.g., t * 45)
• skewX: Horizontal skew in degrees
• skewY: Vertical skew in degrees
• originX: Horizontal origin point for transformations (e.g., 100 or w/2)
• originY: Vertical origin point for transformations
• z-index: Layer order (lower values go behind)

Note: All these properties can be JavaScript expressions using t (current time in seconds) and Math.

<ug-video>

Inserts a video layer into the composition.

• src: Path to the video relative to the HTML file.
• width / height: Forces the video to render at a specific resolution.

Video Filters (CamanJS and Native)

You can nest <ug-filter> elements inside <ug-video> to apply post-processing.

• chroma-key: Removes a specific background color (green screen) based on RGB Euclidean distance (Native, super fast).
• CamanJS Filters: Integrates the CamanJS library with filters like brightness, contrast, sepia, saturation, etc. Use the filter name as type and the amount as value.

<ug-video src="assets/greenscreen.mp4" z-index="1" x="t * 50">
  <ug-filter type="chroma-key" color="#00FF00"></ug-filter>
  <ug-filter type="brightness" value="10"></ug-filter>
  <ug-filter type="contrast" value="15"></ug-filter>
</ug-video>

<ug-audio>

Inserts an audio track into the composition through FFmpeg mixing. This element is not visually rendered but affects the final .mp4 file.

• src: Path to the audio file.
• delay: Audio delay in seconds before it starts playing.

<ug-audio src="assets/music.mp3" delay="2.5"></ug-audio>

<ug-text>

Inserts text or HTML content with full CSS support.

• Rendered via SVG foreignObject, therefore, respects the document's classes and <style>.
• Supports all dynamic attributes (x, y, scaleX, scaleY, rotation, skewX, skewY).

Animated text example:

<ug-text z-index="2" x="400 + Math.cos(t * 2) * 50" y="300" rotation="t * 90" class="my-class">
  Hello Uppergraph!
</ug-text>