Get started

Fly-through video

A camera flies along a route over the Mountaya map, then the page records it as a video file. Plain TypeScript, no React, no studio.

A route over the map with a burnt-in elevation profile

The files

Every file the app needs, as it builds in the SDK repository. Vite needs no configuration for it.

From examples/elements-video/package.json
{
  "name": "@mountaya/example-elements-video",
  "version": "0.0.0",
  "private": true,
  "license": "MIT",
  "description": "A fly-through video from plain GeoJSON, with no studio and no React.",
  "type": "module",
  "scripts": {
    "build": "vite build",
    "dev": "vite",
    "lint": "tsc --noEmit"
  },
  "dependencies": {
    "@mountaya/client": "0.1.0",
    "@mountaya/elements": "0.1.0",
    "maplibre-gl": "6.18.0",
    "mediabunny": "~1.61.6"
  },
  "devDependencies": {
    "typescript": "7.0.2",
    "vite": "8.3.4"
  }
}
From examples/elements-video/index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta content="width=device-width, initial-scale=1" name="viewport" />
    <title>Mountaya: a fly-through from GeoJSON</title>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
      #map {
        height: 100%;
      }
      #controls {
        position: absolute;
        top: 16px;
        left: 16px;
        z-index: 1;
        display: flex;
        gap: 8px;
        align-items: center;
        font: 14px system-ui, sans-serif;
      }
    </style>
  </head>
  <body>
    <div id="controls">
      <button id="preview" type="button">Preview</button>
      <button id="record" type="button">Record</button>
      <span id="status">idle</span>
    </div>
    <div id="map"></div>
    <script src="/src/main.ts" type="module" ></script>
  </body>
</html>
From examples/elements-video/src/route.ts
import type { RouteGeometry } from "@mountaya/elements/camera";

/**
 * A line and its elevations, which is all a flight is anchored to.
 *
 * Synthetic rather than fetched, so the example builds and runs with no network and no credential
 * beyond the one the map's tiles need. Substitute whatever you already hold: a GPX import, a
 * directions result, a `LineString` out of your own database. `itineraryToRouteGeometry` in
 * `@mountaya/elements/camera` is the adapter for a Mountaya itinerary specifically.
 */
export const tourDuMontBlanc: RouteGeometry = {
  elevations: [
    1035, 1072, 1109, 1146, 1183, 1219, 1256, 1292, 1328, 1365, 1400, 1436, 1471, 1506, 1541, 1575,
    1609, 1642, 1676, 1708, 1740, 1772, 1803, 1834, 1864, 1893, 1922, 1951, 1978, 2005, 2031, 2057,
    2082, 2106, 2130, 2152, 2174, 2195, 2215, 2235, 2254, 2271, 2288, 2304, 2319, 2334, 2347, 2359,
    2371, 2382, 2391, 2400, 2408, 2414, 2420, 2425, 2429, 2432, 2434, 2435, 2435, 2434, 2432, 2429,
    2425, 2420, 2414, 2408, 2400, 2391, 2382, 2371, 2359, 2347, 2334, 2319, 2304, 2288, 2271, 2254,
    2235, 2215, 2195, 2174, 2152, 2130, 2106, 2082, 2057, 2031, 2005, 1978, 1951, 1922, 1893, 1864,
    1834, 1803, 1772, 1740, 1708, 1676, 1642, 1609, 1575, 1541, 1506, 1471, 1436, 1400, 1365, 1328,
    1292, 1256, 1219, 1183, 1146, 1109, 1072, 1035,
  ],
  line: [
    [6.87, 45.83],
    [6.87285, 45.83059],
    [6.8757, 45.83118],
    [6.87854, 45.83176],
    [6.88137, 45.83235],
    [6.8842, 45.83294],
    [6.887, 45.83353],
    [6.8898, 45.83412],
    [6.89257, 45.83471],
    [6.89531, 45.83529],
    [6.89804, 45.83588],
    [6.90073, 45.83647],
    [6.9034, 45.83706],
    [6.90603, 45.83765],
    [6.90862, 45.83824],
    [6.91118, 45.83882],
    [6.91369, 45.83941],
    [6.91616, 45.84],
    [6.91858, 45.84059],
    [6.92096, 45.84118],
    [6.92328, 45.84176],
    [6.92556, 45.84235],
    [6.92777, 45.84294],
    [6.92993, 45.84353],
    [6.93202, 45.84412],
    [6.93406, 45.84471],
    [6.93603, 45.84529],
    [6.93793, 45.84588],
    [6.93977, 45.84647],
    [6.94153, 45.84706],
    [6.94323, 45.84765],
    [6.94485, 45.84824],
    [6.94639, 45.84882],
    [6.94786, 45.84941],
    [6.94925, 45.85],
    [6.95056, 45.85059],
    [6.95179, 45.85118],
    [6.95294, 45.85176],
    [6.95401, 45.85235],
    [6.95499, 45.85294],
    [6.95588, 45.85353],
    [6.95669, 45.85412],
    [6.95742, 45.85471],
    [6.95805, 45.85529],
    [6.9586, 45.85588],
    [6.95905, 45.85647],
    [6.95942, 45.85706],
    [6.9597, 45.85765],
    [6.95989, 45.85824],
    [6.95998, 45.85882],
    [6.95999, 45.85941],
    [6.95991, 45.86],
    [6.95974, 45.86059],
    [6.95947, 45.86118],
    [6.95912, 45.86176],
    [6.95868, 45.86235],
    [6.95815, 45.86294],
    [6.95753, 45.86353],
    [6.95682, 45.86412],
    [6.95602, 45.86471],
    [6.95514, 45.86529],
    [6.95418, 45.86588],
    [6.95313, 45.86647],
    [6.95199, 45.86706],
    [6.95078, 45.86765],
    [6.94948, 45.86824],
    [6.9481, 45.86882],
    [6.94664, 45.86941],
    [6.94511, 45.87],
    [6.9435, 45.87059],
    [6.94182, 45.87118],
    [6.94007, 45.87176],
    [6.93824, 45.87235],
    [6.93635, 45.87294],
    [6.93439, 45.87353],
    [6.93237, 45.87412],
    [6.93028, 45.87471],
    [6.92813, 45.87529],
    [6.92593, 45.87588],
    [6.92367, 45.87647],
    [6.92135, 45.87706],
    [6.91898, 45.87765],
    [6.91657, 45.87824],
    [6.91411, 45.87882],
    [6.9116, 45.87941],
    [6.90905, 45.88],
    [6.90646, 45.88059],
    [6.90384, 45.88118],
    [6.90118, 45.88176],
    [6.89849, 45.88235],
    [6.89577, 45.88294],
    [6.89303, 45.88353],
    [6.89026, 45.88412],
    [6.88747, 45.88471],
    [6.88467, 45.88529],
    [6.88185, 45.88588],
    [6.87901, 45.88647],
    [6.87617, 45.88706],
    [6.87333, 45.88765],
    [6.87048, 45.88824],
    [6.86762, 45.88882],
    [6.86478, 45.88941],
    [6.86193, 45.89],
    [6.8591, 45.89059],
    [6.85627, 45.89118],
    [6.85346, 45.89176],
    [6.85067, 45.89235],
    [6.84789, 45.89294],
    [6.84514, 45.89353],
    [6.84241, 45.89412],
    [6.83971, 45.89471],
    [6.83705, 45.89529],
    [6.83441, 45.89588],
    [6.83181, 45.89647],
    [6.82925, 45.89706],
    [6.82673, 45.89765],
    [6.82425, 45.89824],
    [6.82182, 45.89882],
    [6.81943, 45.89941],
    [6.8171, 45.9],
  ],
};
From examples/elements-video/src/main.ts
import { Mountaya } from "@mountaya/client/browser";
import { MountayaMap } from "@mountaya/elements";
import {
  cameraPlanGenerators,
  type RouteGeometry,
  VideoFlightEngine,
} from "@mountaya/elements/camera";
import { convertProportion } from "@mountaya/elements/units";
import { MapLibreViewClient, VideoRunEngine } from "@mountaya/elements/video";
import "@mountaya/elements/styles.css";

import { tourDuMontBlanc } from "./route.js";

/**
 * A fly-through video over a line you already hold, and nothing else.
 *
 * This example exists to be a manifest. Its `package.json` names `@mountaya/client`,
 * `@mountaya/elements` and a renderer (no `@mountaya/studio`, no `@mountaya/studio-react`, no
 * React at all), and `npm run build:examples` compiles it with a real bundler. That build is the
 * boundary claim: the orchestration between a camera plan and a map is `VideoFlightEngine`, which
 * the elements publish, so a fly-through needs no studio, no tool bus and no wizard.
 *
 * It is also the shortest statement of the engine's contract. `getSnapshot` and `subscribe` are
 * what a UI reads; the commands are what it writes; `dispose` is what it calls on the way out.
 * There is no framework here, which is the point: the same three lines are a React
 * `useSyncExternalStore`, a Vue `shallowRef`, or the two click listeners below.
 */

const PUBLISHABLE_KEY = "pk_…";

/** How long a recording's download address outlives the click that saves it. */
const OBJECT_URL_REVOKE_DELAY_MS = 40_000;

const mountaya = new Mountaya({ credential: { publishableKey: PUBLISHABLE_KEY } });

const map = new MountayaMap({
  client: mountaya,
  container: "map",
  // The flight reads the drawing buffer back frame by frame, so the buffer has to survive the
  // browser's present step. MapLibre reads this once at construction and it cannot be toggled
  // later, which is why a recording surface is built for recording rather than switched into it.
  maplibre: { canvasContextAttributes: { preserveDrawingBuffer: true } },
});

/**
 * The map as the flight drives it.
 *
 * `MapLibreViewClient` carries the terrain warms and the DEM readout, and the `video` seam it is
 * given carries the preview and the capture. Two objects because recording is the optional
 * half: a map that only draws a route never constructs the seam and never resolves an encoder.
 * It is the map client with no edit engine, so this page installs no drawing library.
 */
const client = new MapLibreViewClient(map, {
  video: new VideoRunEngine(map.raw, map.events),
});

/** A route is a flattened line plus its elevations, whatever your own data already is. */
const route: RouteGeometry = tourDuMontBlanc;

const flight = new VideoFlightEngine({
  map: client,
  plan: cameraPlanGenerators.overview(route, { targetDurationMs: 20_000 }),
});
flight.setRoute(route);
flight.setProfile({ enabled: true, length: "metric", slope: "percentage" });

const status = document.querySelector("#status");
const preview = document.querySelector("#preview");
const record = document.querySelector("#record");

/**
 * The flight's progress as the status line states it: a ratio of the whole flight, read as a
 * whole percent through the one conversion every `@mountaya/*` package shares.
 */
const progressLabel = (fraction: number): string =>
  `${Math.round(convertProportion(fraction, "ratio", "percent"))}%`;

/**
 * The whole of the binding: read the snapshot, write the DOM, subscribe.
 *
 * A framework binding is this function plus its framework's own subscribe primitive. Nothing about
 * the engine knows which one it is.
 */
const render = (): void => {
  const { status: state } = flight.getSnapshot();

  if (status) {
    status.textContent =
      state.kind === "idle"
        ? "idle"
        : state.kind === "recording"
          ? `${state.phase} ${progressLabel(state.fraction)}`
          : `${state.kind} ${progressLabel(state.fraction)}`;
  }
};

flight.subscribe(render);
render();

preview?.addEventListener("click", () => {
  void flight.preview();
});

record?.addEventListener("click", () => {
  void flight.record().then((result) => {
    if (!result.ok) {
      if (status) {
        status.textContent = `no video: ${result.reason}`;
      }

      return;
    }

    // Saved the way any blob is. The engine keeps the last recording (`flight.recording`), so
    // saving a second time costs nothing: a download is not a re-encode. The address is revoked
    // a while after the click, since a browser reads it after the click's task ends and a revoke
    // in the same task can cancel the download.
    const url = URL.createObjectURL(result.blob);
    const anchor = document.createElement("a");
    anchor.download = `flight.${result.extension}`;
    anchor.href = url;
    anchor.click();
    setTimeout(() => URL.revokeObjectURL(url), OBJECT_URL_REVOKE_DELAY_MS);
  });
});

// The three objects this page owns, torn down in the order they depend on each other.
// `flight.dispose()` aborts whatever is running and drops its listeners, and `client.dispose()`
// removes the listeners it attached to the map; neither destroys the map, because each was
// handed one and does not own it.
// Every engine of `@mountaya/elements` keeps that one-way dependency, so the page that built the
// map destroys it, last.
window.addEventListener("pagehide", () => {
  flight.dispose();
  client.dispose();
  map.destroy();
});

Run it

Replace pk_… in src/main.ts with a publishable key carrying the tiles scope, then:

npm install
npm run dev

Press Preview to fly the route, then Record to save the video.

The same app is examples/elements-video in the SDK repository.

Next steps

Last updated