> ## Documentation Index
> Fetch the complete documentation index at: https://docs.altoura.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Media Upload

> Upload images, videos, audio, and 3D models from your computer directly into a training

## Overview

Most authored actions in Creator App refer to a piece of media — a panel shows an image, a step plays a video, a narration uses an audio clip, a scene includes a 3D object. **Media Upload** is how you get those files into the training.

Creator App uploads media **per action**: wherever an action has a media field, it also offers an **Upload** button. Uploads go straight to the asset library and are immediately available for reuse in any other action in the same organisation.

## Where You Upload Media

Media upload controls appear in any action parameter panel that accepts a media file:

| Action         | Media field           | Upload label                                                                                                    |
| -------------- | --------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Show Panel** | Image / Video / Audio | **Select image file** / **Select video file** / **Select audio file** + **Upload**                              |
| **Show Image** | Image                 | **Select image** + **Upload Image**                                                                             |
| **Play Video** | Video Asset           | **Select video** + **Upload**                                                                                   |
| **Play Audio** | Audio Asset           | Select from library (for uploads, use an action above that has an Upload button, or upload inside a Show Panel) |
| **Add Object** | 3D Object             | **Select 3D Object** + **Upload**                                                                               |

The ribbon's **Step → Media** group (**Pictures**, **Videos**, **Audio**) opens a media picker for selecting existing assets, but does not upload new files itself.

## Supported Formats

| Type         | Accepted file extensions |
| ------------ | ------------------------ |
| **Image**    | `.jpg`, `.jpeg`, `.png`  |
| **Video**    | `.mp4`                   |
| **Audio**    | `.mp3`, `.wav`, `.ogg`   |
| **3D Model** | `.glb`                   |

<Warning>
  The file picker restricts the visible file types based on the control you clicked. If you try to upload a file that does not match — for example a `.mov` file into the Video picker — Creator App shows:

  > *Unsupported file type. Allowed: .mp4*

  Convert the file to a supported format and try again.
</Warning>

## Uploading a File

<Steps>
  <Step title="Open an action that accepts media">
    For example, add a **Show Panel** action and expand its **Media Panel** section.
  </Step>

  <Step title="Choose the media type">
    Select **Show Image**, **Show Video**, or **Audio** (for Show Panel), or use the dedicated media field in actions like **Play Video** or **Add Object**.
  </Step>

  <Step title="Click Upload">
    Click the **Upload** button next to the media field. Your operating system's file picker opens, filtered to the accepted extensions.
  </Step>

  <Step title="Pick your file">
    Choose the file and confirm. Creator App shows the upload progress on the button:

    | State                  | Label                                     |
    | ---------------------- | ----------------------------------------- |
    | Reading / thumbnailing | **Processing...**                         |
    | Uploading              | **Uploading {n}%** (0 – 100)              |
    | Finishing              | **Finalizing...**                         |
    | Done                   | **Complete!**                             |
    | Failed                 | **Failed - Retry?** (hover for the error) |
  </Step>

  <Step title="Done">
    The new asset is registered in your organisation's asset library and automatically attached to the action you uploaded it from.
  </Step>
</Steps>

## Drag and Drop

The **Show Panel** editable preview (when you open a panel in the 3D viewer) supports drag-and-drop from the asset library:

* **Image / video field:** *Drop image/video from library or click to upload*
* **Audio field:** *Drop audio from library or click to upload*

Drag an asset out of the **Assets** sidebar panel and drop it onto the card. The same card opens an asset picker when you click it.

File uploads from your computer use the **Upload** button, not drag-and-drop onto these cards.

## Asset Library

After upload, files appear in the organisation's asset library and can be reused in any training. Open the **Assets** panel (sidebar tab) to browse existing assets. The panel has three tabs:

| Tab    | Assets                  |
| ------ | ----------------------- |
| Audio  | `.mp3`, `.wav`, `.ogg`  |
| Images | `.jpg`, `.jpeg`, `.png` |
| Videos | `.mp4`                  |

Use **Search assets...** to search by name, or the **Filter by Tags** control to narrow by asset tags.

<Note>
  3D models are listed separately. **Add Object** opens the 3D model picker; the static object catalog on the left of the authoring page is a separate, local catalog of objects shipped with Altoura.
</Note>

## Behind the Scenes

When you upload a media file, Creator App:

1. Validates the extension against the accepted list for the control.
2. Processes the file (for images and videos, a thumbnail is generated; for non-GLB 3D meshes, the asset processor converts them to GLB before upload).
3. Requests a **SAS token** from the server so it can upload directly to Azure Blob Storage.
4. Uploads the file with progress reported back to the button.
5. Uploads an associated `_thumb.png` when a thumbnail exists.
6. Registers the asset in your organisation by calling the assets API.
7. Attaches the new asset's GUID and version to the action parameter so the action now references the uploaded file.

This is why uploaded assets are immediately available in the library across all trainings in the same organisation.

## Common Upload Errors

| Error                                                             | Meaning                                                                                                   |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| *Unsupported file type. Allowed: …*                               | The file extension does not match the accepted list for that control                                      |
| *No organization ID available*                                    | Your session does not have an organisation context; sign out and sign back in                             |
| *Upload failed*                                                   | Network or server error during the upload; retry using **Failed - Retry?**                                |
| *Asset created but could not be retrieved*                        | Backend registered the asset but the follow-up fetch failed; refresh the page and the asset should appear |
| *Upload succeeded but UI update failed. Please refresh the page.* | Rare race condition; refresh and the asset will be in the library                                         |

## Best Practices

<Steps>
  <Step title="Compress before upload">
    Shrink images and videos to the smallest size that still looks good. Large files slow learners' load times, especially on mobile.
  </Step>

  <Step title="Name files clearly">
    Before uploading, rename your file to something descriptive (for example `engine-oil-cap-close-up.jpg`). The filename becomes the default asset name in the library.
  </Step>

  <Step title="Use tags to organise">
    After upload, apply tags to the asset in the library so reviewers can find it by `training-name`, `scene`, or `topic`.
  </Step>

  <Step title="Convert unusual formats in advance">
    `.mov`, `.webm`, `.aac`, and similar formats are not accepted by the file picker. Convert to `.mp4` (video) or `.mp3` (audio) first.
  </Step>

  <Step title="Test 3D models in a throwaway step first">
    GLBs vary wildly in complexity. Upload to a test state first and check performance before attaching the model to the production flow.
  </Step>

  <Step title="Reuse via the library instead of re-uploading">
    If the same logo, narration clip, or object appears in many places, upload it once and pick it from the library in subsequent actions.
  </Step>
</Steps>

## Limitations

* **No bulk upload** — Files are uploaded one at a time per action field.
* **No folders** — Assets are organised by type and tags, not by folder hierarchy.
* **No in-app trimming or cropping** — Edit media before upload.
* **File size limits are enforced server-side** — The client does not show a size cap, but the server may reject very large files. Compress before uploading if possible.

## Related

* **Show Panel** — The action with the most upload controls (image, video, audio all in one panel)
* **Play Video** — Upload a video to attach to a Play Video action
* **Play Audio** — Play back audio uploaded via Show Panel or other upload paths
* **Add Object** — Upload a `.glb` 3D model for a scene
* **Text-to-Speech** — An alternative way to produce narration without uploading an audio file