Assets

Portable references

Assets are metadata and stable references. Neonix JSON V2 stores file identity and media metadata rather than the file contents inside the authoring document.

{
  "assets": [
    {
      "kind": "image",
      "id": "logo",
      "uri": "/assets/logo.png",
      "mimeType": "image/png",
      "width": 640,
      "height": 360,
      "integrity": "sha256-..."
    },
    {
      "kind": "font",
      "id": "inter-regular",
      "uri": "https://fonts.neonix.video/inter/Inter_18pt-Regular.ttf",
      "mimeType": "font/ttf",
      "weight": 400,
      "style": "normal",
      "integrity": "sha256-..."
    }
  ]
}

Four asset kinds

Identity boundary

Layers point to assets by id. Loading and delivery happen after the document has been validated.

Two delivery modes

Neonix supports two ways to deliver image, video and audio sources. Choose a public URL when the file is intentionally shareable. Use Neonix storage when the asset belongs to a workspace or should stay private.

1. Public URL

Use an absolute URL from a CDN or public object domain that you control:

{
  "assets": [
    {
      "kind": "image",
      "id": "public-logo",
      "uri": "https://cdn.example.com/brand/logo.png",
      "mimeType": "image/png",
      "width": 640,
      "height": 360
    },
    {
      "kind": "video",
      "id": "public-intro",
      "uri": "https://cdn.example.com/video/intro.mp4",
      "mimeType": "video/mp4",
      "duration": 5000,
      "fps": 30
    },
    {
      "kind": "audio",
      "id": "public-music",
      "uri": "https://cdn.example.com/audio/music.mp3",
      "mimeType": "audio/mpeg",
      "duration": 5000
    }
  ]
}

For public video and audio, the origin should support byte-range requests and return the correct Content-Type. If the media is drawn into a canvas during preview, configure CORS on the media origin as well; a public URL alone does not grant browser canvas access.

Public URLs are suitable for assets that can be downloaded by anyone. Do not put access tokens, signed query strings or private storage-provider endpoints in a public document.

2. Neonix private storage

Upload workspace media from the authenticated Assets screen. Neonix validates the file, records its metadata and prepares the supported derivatives before making it available to the project.

In authoring JSON, layers reference a private asset by assetId:

{
  "id": "user-video-layer",
  "type": "video",
  "payload": { "assetId": "<asset-id>" },
  "frame": { "width": 960, "height": 540 },
  "timing": { "start": 0, "duration": 5 }
}

The editor resolves the asset through the current signed-in workspace session. The private delivery URL, storage provider and upload credentials are implementation details and should not be copied into authoring JSON or public HTML.

For private media, Neonix supports the original image/video/audio source, a generated video poster and an extracted audio derivative when processing has completed. Video and audio playback uses range-aware delivery internally; no direct storage access or storage-provider CORS configuration is required for the authenticated app flow.

Delivery checklist

• Public image: stable HTTPS URL and correct image MIME type.
• Public video/audio: HTTPS, correct MIME type and HTTP Range support.
• Canvas preview from another origin: allow the Neonix origin with CORS.
• Private Neonix asset: upload it from Assets and reference it by asset id; do not hardcode a storage-provider endpoint.
• Video with sound: use the original video URI and its variant=audio derivative when the project needs a separate audio track.

Private workspace fonts

User fonts follow a dedicated authenticated flow from the Assets screen. Neonix validates each font, reads its family/weight/style metadata and makes it available to the signed-in workspace. Workspace fonts are never exposed through the public system-font CDN.

After a font is ready, select its family, weight and style in the editor or Neonix JSON V2. The editor and authenticated preview resolve the private font bytes with the current workspace session; export uses the same catalog entry. Do not copy private font references into public HTML or publish workspace fonts as public files.

System fonts and the public CDN

Neonix system fonts are served through the public font CDN:

https://fonts.neonix.video/{family}/{filename}

Example:

https://fonts.neonix.video/inter/Inter_18pt-Regular.ttf
https://fonts.neonix.video/inter/Inter_18pt-Bold.ttf

The CDN is a delivery endpoint for known objects. It does not expose a browser directory listing, so requesting the CDN root or a family folder is not the way to discover fonts.

Google Fonts-compatible CSS API

For browser HTML, request the required family and weights through the CSS endpoint:

<link rel="stylesheet" href="https://fonts.neonix.video/css2?family=Inter:wght@400;700;900&display=swap">

Then use the canonical family name in CSS:

body {
  font-family: "Inter", sans-serif;
  font-weight: 700;
}

The CSS endpoint resolves the requested family, weight and style to the matching public font object. It does not rename the font's internal family metadata.

Get every available font

Call GET /api/v1/fonts without authentication to list all public system fonts:

curl https://www.neonix.video/api/v1/fonts

The signed-in editor also includes workspace fonts in its private font picker. Use the public catalog and CDN only for system fonts; workspace fonts remain private to the current workspace and should not be copied into public HTML.

Font asset versus text style

The font catalog identifies the bytes. The text span selects the family and style:

{
  "font": {
    "families": ["Inter", "sans-serif"],
    "size": 64,
    "weight": 700,
    "style": "normal"
  }
}

Do not put a storage URL in families. Use the family name in Neonix JSON V2 and use @font-face with the CDN URL in HTML. The compiler and export path can then resolve the same family, weight and style deterministically.

See Text for font selection, fallback and @font-face examples.