Format Specification v0.10

Version 0.10 | January 2026 | Draft

1. Overview

A .brfr file is a ZIP archive containing structured multimedia content designed for single-screen, swipeable viewing on mobile devices.

2. File Structure

example.brfr (ZIP archive)
+-- manifest.json          # Required: content and metadata
+-- media/                  # Required: all referenced media files
    +-- 001.jpg
    +-- 002.png
    +-- ...

• The archive MUST contain manifest.json at root
• All media files MUST be in the media/ directory
• File paths in manifest are relative to archive root

3. Manifest Schema

{
  "version": "0.10",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Brief Title",
  "steps": [...]
}

Required Fields

Optional Fields

The id field is the brief's permanent identity. It survives export/import cycles and enables duplicate detection, cross-device sync, and collection tracking.

4. Steps

A step is one screen of content containing elements distributed across three vertical zones.

{
  "id": "a1b2c3d4",
  "elements": [
    { "type": "text", "zone": "top", "content": "Header", "preset": "heading" },
    { "type": "image", "media": "media/001.jpg" },
    { "type": "text", "zone": "bottom", "content": "Caption", "preset": "body" }
  ]
}

5. Zones

The zone property controls vertical positioning.

+------------------------------------------+
|  TOP ZONE                                |
|  [elements with zone: "top"]             |
+------------------------------------------+
|                                          |
|  CENTER ZONE                             |
|  [elements without zone]                 |
|                                          |
+------------------------------------------+
|  BOTTOM ZONE                             |
|  [elements with zone: "bottom"]          |
+------------------------------------------+

Elements within each zone render in array order, top to bottom.

6. Element Types

7. Text Element

{
  "type": "text",
  "zone": "top",
  "content": "Hello World",
  "preset": "heading",
  "color": "#10b981",
  "align": "center",
  "bold": true,
  "italic": false
}

Text Presets

8. Image Element

{
  "type": "image",
  "media": "media/photo.jpg",
  "fit": "contain",
  "rotation": 0,
  "alt": "Description for accessibility",
  "annotations": [...]
}

Fit Modes

• contain - Entire image visible, may letterbox (default)
• cover - Image fills container, may crop

9. Annotations

Annotations are visual overlays on images for instructional markup. All coordinates are normalized 0.0 to 1.0, where (0,0) is top-left and (1,1) is bottom-right.

Arrow

{
  "type": "arrow",
  "x1": 0.2, "y1": 0.3,
  "x2": 0.5, "y2": 0.6,
  "color": "#ef4444",
  "thickness": 3
}

Circle

{
  "type": "circle",
  "cx": 0.5, "cy": 0.5,
  "r": 0.1,
  "color": "#ef4444",
  "thickness": 3
}

Radius is relative to image width (0.1 = 10% of width).

Rectangle

{
  "type": "rect",
  "x": 0.1, "y": 0.2,
  "width": 0.3, "height": 0.2,
  "color": "#ef4444",
  "thickness": 3
}

Label

{
  "type": "label",
  "x": 0.5, "y": 0.3,
  "content": "1",
  "color": "#ffffff",
  "background": "#ef4444"
}

Renders as a pill-shaped badge centered on the coordinates.

Freehand

{
  "type": "freehand",
  "points": [[0.1, 0.2], [0.15, 0.22], [0.2, 0.21]],
  "color": "#ef4444",
  "thickness": 3
}

10. SVG Element

{
  "type": "svg",
  "content": "",
  "fit": "contain"
}

Requirements:

• Must have viewBox attribute
• Must be self-contained (no external references)
• No <script> tags or event handlers

11. Row Element

{
  "type": "row",
  "zone": "bottom",
  "layout": "even",
  "gap": 12,
  "items": [
    { "type": "text", "content": "Left" },
    { "type": "text", "content": "Right" }
  ]
}

Layouts

Items can be: text, image, svg, empty. No nested rows.

12. Semantic Colors

Shortcuts usable in any color field:

13. Reserved Fields

The following fields are reserved for future use. Readers should ignore them until formally specified.

• audio - Step-level audio narration
• audioDuration - Duration in seconds
• video - Step-level video content

14. Complete Example

{
  "version": "0.10",
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "title": "Install Light Switch",
  "created": "2026-01-18T10:00:00Z",
  "steps": [
    {
      "id": "step-001",
      "elements": [
        {
          "type": "text",
          "zone": "top",
          "content": "Step 1: Turn Off Power",
          "preset": "heading",
          "align": "center"
        },
        {
          "type": "image",
          "media": "media/breaker.jpg",
          "fit": "contain",
          "annotations": [
            { "type": "circle", "cx": 0.35, "cy": 0.6, "r": 0.08, "color": "#ef4444" },
            { "type": "arrow", "x1": 0.6, "y1": 0.4, "x2": 0.42, "y2": 0.55 }
          ]
        },
        {
          "type": "text",
          "zone": "bottom",
          "content": "Flip the breaker to OFF",
          "preset": "body",
          "align": "center"
        }
      ]
    }
  ]
}

See examples for downloadable sample files.