Working with Assets: Uploading Images, Videos & Logos

Workshop Studio supports four types of media assets: images, videos, logos, and audio. This guide covers how to get files into the system, how they are referenced in your script, and what happens to them during rendering.

Adding a Media Block

Inside any scene, press / and choose the media type you need:

  • Image — PNG, JPEG, GIF, WebP, SVG
  • Video — MP4, WebM
  • Logo — Same formats as image, but treated as a branding element with different default sizing

Each media block shows two controls:

  1. A text input for pasting a URL directly.
  2. An upload button (📎) for selecting a file from your device.

Uploading a File

Click the 📎 Upload button on any media block. A file picker opens, filtered to accepted formats for that block type.

Once you select a file:

  1. The button shows a live percentage — ⏳ 42% — so you know the upload is progressing.
  2. A thin progress bar fills across the bottom of the button.
  3. On success, the button flashes ✅ Done for two seconds, then resets.
  4. On failure, the button shows ❌ Failed with a tooltip containing the error message.

After upload, the text input is populated with the asset URL returned by the server. This URL is what gets embedded in your .ws source.

Upload timeout is 5 minutes by default. For very large video files on slow connections, the upload will keep running — the progress percentage tells you it has not stalled.

## Video Backgrounds

Scenes can use uploaded videos as fullscreen backgrounds. In the Studio UI, add a background setting to your scene and use the video syntax:

ws
Scene "Hero Shot"
  background: video "https://your-server/assets/clip-id.mp4"
  background-speed: 0.8
  background-opacity: 0.6

When a scene has a video background reference that has not been uploaded yet, the UI shows a ⚠️ warning icon with an Upload Video button. Upload the file and the reference resolves automatically.

Background Video Settings

Setting Default Purpose
background-speed: 1.0 Playback rate multiplier (0.1–2.0). Values below 1.0 create slow motion.
background-opacity: 1.0 Transparency (0–1). Lower values let the background color show through.
audio-mode: muted Whether the video's audio track plays: muted, speech-primary, or ambient.
audio-gain: 1.0 Volume multiplier for the video's audio (0–1).

Inline Media Elements

Media elements placed inside a scene are positioned and animated like any other element. They respect the scene's intent and mood settings.

ws
Scene "Product"
  show image "product-hero.jpg"
    fit: fill
    position: center
    enter: scale
    size: display
  show logo "brand.svg"
    position: lower-right
    size: caption
    opacity: 0.7
    layer: front

The fit Setting

Controls how media fills its bounding box:

Value Behavior
fill Cover the entire box, cropping edges if needed. Best for hero images.
fit Contain within the box, adding letterboxing if aspect ratios differ. Best for logos and diagrams.
bleed Extend slightly beyond the box for an edge-to-edge effect.

Asset Lifecycle

Understanding the asset lifecycle prevents surprises during rendering:

1. Upload

Files are uploaded to the server via the upload button. The server stores the file and returns a URL that you can reference in your script.

2. Reference

The returned URL is embedded in your .ws source. When you compile or render, the compiler resolves every asset reference and verifies the file is available.

3. Render

During rendering, the server ensures all assets are accessible to the render engine. Uploaded files are served from the same server instance, so there is no external dependency.

4. Cleanup

Uploaded assets are temporary. After a configurable time-to-live the server deletes the file. If you need to re-render after the TTL has expired, upload the asset again.

Asset storage is designed for the render pipeline, not permanent hosting. For production workflows where you need assets to persist, host files on your own CDN or storage service and reference those URLs in your script.

## Using External URLs

You do not have to upload files through the Studio. You can reference any publicly accessible URL in your script:

ws
show image "https://cdn.example.com/hero.jpg"
show video "https://storage.example.com/clip.mp4"

The server will resolve these URLs during rendering. For best reliability, use URLs from fast, high-availability storage (CDN, S3, etc.).

Accepted Formats

Block Type Accepted Formats
Image PNG, JPEG, GIF, WebP, SVG
Logo PNG, JPEG, GIF, WebP, SVG
Video MP4, WebM
Music (Film-level) MP3, WAV

Asset Validation

The system validates asset references before rendering. If a referenced file does not exist on the server, the render is rejected with a descriptive error message telling you which asset to upload. In preview mode, missing assets are downgraded to warnings so you can still see the layout while you work.

Troubleshooting

Upload shows ❌ Failed immediately Check that the file is under the size limit. The server rejects files that are too large. Contact your administrator for the configured maximum.

Upload percentage stalls at 0% The server may be unreachable. Check your network connection and verify the API base URL in the Studio configuration.

Render completes but media is missing from the video The asset URL in your script may have expired (TTL cleanup). Re-upload the file and update the reference. For reliable production workflows, use permanent external URLs.

Video background shows as solid color The video file may not have been uploaded yet. Look for the ⚠️ icon next to the background setting and click Upload Video.