` can be turned interactive using `Interactive`:
+
+```tsx title="Interactive elements"
+
+ Hello
+
+```
+
+This allows styles and keyframes to be set in the Studio. Be sensible, if a component has many elements, the timeline might get messy.
+
+## Prefer inline text
+
+If text is fixed and only used once, write it directly inside the interactive element instead of extracting it into a constant.
+
+```tsx title="Inline text"
+// 👍 Fixed copy stays editable
+
+ Remotion Best Practices
+
+```
+
+Use a prop or variable only when the text is dynamic or reused.
+
+## Give interactive elements a descriptive name
+
+Add a `name` prop to elements to make them easily identifyable.
+Avoid computed names, hardcode them.
+
+```tsx title="Interactive names"
+<>
+
+ Launch day
+
+
+
+
+ Launch day
+
+
+```
+
+## Keep all CSS styles inline
+
+The best way is to just pass a plain object to `style` - no referring to constants, no object spreading, no math.
+
+```tsx title="Interactive example"
+
+ Hello World!
+
+```
+
+```tsx title="❌ Bad for interactivity"
+const baseStyle = useMemo(() => {
+ return {
+ fontSize: 12 // ❌ Non-inline styles are not supported
+ }
+}, []);
+
+
+ Hello World!
+
+```
+
+## Animate using `interpolate()`
+
+Write animations as inline `interpolate()` calls on the property that changes.
+The output range, easing, extrapolation and `output` property should use hardcoded values.
+
+The input range may additionally use `durationInFrames`, `fps`, `width` and `height` destructured directly from `useVideoConfig()`. Bare identifiers such as `durationInFrames`, multiplication with a number such as `2 * fps` or `fps * 2`, and subtraction of a number such as `durationInFrames - 1` are supported.
+
+```tsx title="Inline values"
+const {fps, durationInFrames} = useVideoConfig();
+
+// 👍 Inline values can be standardized and keyframed
+
+```
+
+```tsx title="❌ Bad interactivity"
+const translateY = interpolate(frame, [0, 30], [0, 120]); // ❌ Math should be directly in the markup
+
+
+```
+
+## Use `scale`, `translate`, `rotate` CSS properties
+
+Avoid the `transform` CSS property.
+If possible, use `scale`, `rotate` and `translate` instead because only they are interactively editable.
+
+## Keep composition metadata inline
+
+When scaffolding a composition, keep `width`, `height`, `fps`, `durationInFrames` and `defaultProps` inline and make no type assertions.
+
+The Props editor can save visual edits back to your code when `defaultProps` is an inline object literal on `
` or ``.
+
+```tsx
+// 👍 Static values are in , dynamic values are in calculateMetadata()
+const calculateMetadata = useMemo(async () => {
+ const dimensions = await getDimensions(); // just an example
+ return {width: dimensions.width, height: dimensions.height};
+});
+
+
+Remotion
+
diff --git a/remotion-best-practices/remotion-maps/REFERENCE.md b/remotion-best-practices/remotion-maps/REFERENCE.md
new file mode 100644
index 0000000..6ce8b2c
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/REFERENCE.md
@@ -0,0 +1,36 @@
+---
+name: remotion-maps
+description: Remotion Map animation knowledge
+version: 4.0.526
+---
+
+# Remotion Maps
+
+Choose exactly one technique from the intended shot, then load only that technique's `TECHNIQUE.md`.
+Every technique directory is self-contained and may be removed without breaking the others.
+
+## [Static map](techniques/static-map/TECHNIQUE.md)
+
+- Requires you grab a satellite image and mount it in a `
+Remotion
+
diff --git a/remotion-best-practices/remotion-maps/techniques/cesium/TECHNIQUE.md b/remotion-best-practices/remotion-maps/techniques/cesium/TECHNIQUE.md
new file mode 100644
index 0000000..b58e4a4
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/cesium/TECHNIQUE.md
@@ -0,0 +1,89 @@
+# CesiumJS — 3D flyovers in Remotion
+
+Instructions for achieving map animations with "flight-simulator" perspective in Remotion.
+
+## Modes
+
+| Mode | Data | Use for |
+| ----------- | ----------------------------------------------------- | ------------------------------------------------------ |
+| `landscape` | MapTiler `terrain-quantized-mesh-v2` + `satellite-v2` | Mountains, gorges, rivers, coastlines and rural routes |
+| `city` | Google Photorealistic 3D Tiles | Cities, architecture and recognizable landmarks |
+
+Do not use footprint extrusions for city flyovers. They produce crude building blocks rather than
+textured architecture.
+
+## Credentials
+
+For `landscape`, set:
+
+```text
+REMOTION_MAPTILER_KEY=...
+```
+
+Create a MapTiler key at https://cloud.maptiler.com/account/keys/.
+
+For `city`, set:
+
+```text
+REMOTION_GOOGLE_MAPS_API_KEY=...
+```
+
+Create a billing-enabled Google Map Tiles API key by following
+https://developers.google.com/maps/documentation/tile/get-api-key. Enable the **Map Tiles API** and
+restrict the key to that API. Ensure its application restriction permits local headless Remotion
+requests.
+
+## Build the flight
+
+1. Copy `assets/CesiumFlythrough.tsx`, a path JSON and `assets/example-Root.tsx` into the Remotion
+ project, or import the component directly.
+2. Supply the camera route as `[longitude, latitude][]`. Use only meaningful control points; do not hand-author dozens of tiny corrections.
+3. Leave `pathSmoothingPasses={3}` initially. The component applies repeated Chaikin corner cutting, turning straight-then-corner input into a continuous swerve. Increase to `4` for a softer route or reduce to `2` when the camera must follow a tight corridor.
+4. Set absolute camera altitudes for the location. City cameras normally fly lower than landscape
+ cameras.
+5. Render a middle-frame still before rendering the full video.
+
+```tsx
+((resolve, reject) => {
+ if ((window as any).Cesium) return resolve((window as any).Cesium);
+ (window as any).CESIUM_BASE_URL = CDN;
+ const css = document.createElement('link');
+ css.rel = 'stylesheet';
+ css.href = `${CDN}Widgets/widgets.css`;
+ document.head.appendChild(css);
+ const script = document.createElement('script');
+ script.src = `${CDN}Cesium.js`;
+ script.onload = () => resolve((window as any).Cesium);
+ script.onerror = () =>
+ reject(new Error(`Failed to load CesiumJS ${CESIUM_VER}`));
+ document.head.appendChild(script);
+ });
+
+export const CesiumFlythrough: React.FC = ({
+ mode = 'landscape',
+ path = terrainPath as LngLat[],
+ pathSmoothingPasses = 3,
+ altitudeStart = 4600,
+ altitudeEnd = 4300,
+ lookAheadKm = 1.5,
+ travelKm = 13,
+ pitchFromNadir = 76,
+ verticalExaggeration = 1.1,
+ maximumScreenSpaceError = 8,
+}) => {
+ const containerRef = useRef(null);
+ const started = useRef(false);
+ const viewerRef = useRef(null);
+ const tilesetRef = useRef(null);
+ const frame = useCurrentFrame();
+ const {durationInFrames, fps, width, height} = useVideoConfig();
+ const [ready, setReady] = useState(false);
+ const [handle] = useState(() =>
+ delayRender(`cesium init: ${mode}`, {timeoutInMilliseconds: 120000}),
+ );
+ const walker = useMemo(
+ () => makePathWalker(smoothFlightPath(path, pathSmoothingPasses)),
+ [path, pathSmoothingPasses],
+ );
+
+ const setCamera = (C: any, viewer: any, progress: number) => {
+ const maxTravel = Math.max(0, walker.lengthKm - lookAheadKm * 2);
+ const cameraDistance = Math.min(travelKm, maxTravel) * progress;
+ const camera = walker.along(cameraDistance);
+ const aim = walker.along(cameraDistance + lookAheadKm);
+ const aim2 = walker.along(cameraDistance + lookAheadKm * 2);
+ const heading = bearing(camera, aim);
+ let headingDelta = bearing(aim, aim2) - heading;
+ while (headingDelta > Math.PI) headingDelta -= 2 * Math.PI;
+ while (headingDelta < -Math.PI) headingDelta += 2 * Math.PI;
+ viewer.camera.setView({
+ destination: C.Cartesian3.fromDegrees(
+ camera[0],
+ camera[1],
+ lerp(altitudeStart, altitudeEnd, progress),
+ ),
+ orientation: {
+ heading,
+ pitch: C.Math.toRadians(-(90 - pitchFromNadir)),
+ roll: clamp(headingDelta * BANK_GAIN, -MAX_BANK, MAX_BANK),
+ },
+ });
+ };
+
+ const tilesAreLoaded = (viewer: any) => {
+ if (mode === 'landscape') return viewer.scene.globe.tilesLoaded;
+ return Boolean(tilesetRef.current?.tilesLoaded);
+ };
+
+ const settle = (viewer: any) =>
+ new Promise((resolve) => {
+ let stable = 0;
+ let ticks = 0;
+ const tick = () => {
+ viewer.render();
+ ticks++;
+ stable = tilesAreLoaded(viewer) ? stable + 1 : 0;
+ if (stable > 8 || ticks > 600) {
+ viewer.render();
+ resolve();
+ } else {
+ setTimeout(tick, 8);
+ }
+ };
+ tick();
+ });
+
+ useEffect(() => {
+ if (started.current) return;
+ started.current = true;
+ (async () => {
+ if (mode === 'landscape' && !MAPTILER_KEY) {
+ throw new Error(
+ 'Set REMOTION_MAPTILER_KEY. Create a key at https://cloud.maptiler.com/account/keys/',
+ );
+ }
+ if (mode === 'city' && !GOOGLE_MAPS_API_KEY) {
+ throw new Error(
+ 'Set REMOTION_GOOGLE_MAPS_API_KEY. Create a Map Tiles API key at https://developers.google.com/maps/documentation/tile/get-api-key',
+ );
+ }
+ if (mode === 'city' && durationInFrames / fps > 30) {
+ throw new Error(
+ 'Google Photorealistic 3D Tiles compositions must not exceed 30 seconds',
+ );
+ }
+
+ const C = await loadCesium();
+ const viewer = new C.Viewer(containerRef.current, {
+ baseLayer: false,
+ baseLayerPicker: false,
+ geocoder: false,
+ homeButton: false,
+ sceneModePicker: false,
+ navigationHelpButton: false,
+ animation: false,
+ timeline: false,
+ fullscreenButton: false,
+ infoBox: false,
+ selectionIndicator: false,
+ contextOptions: {webgl: {preserveDrawingBuffer: true}},
+ });
+ if (mode === 'landscape') {
+ viewer.imageryLayers.addImageryProvider(
+ new C.UrlTemplateImageryProvider({
+ url: `https://api.maptiler.com/tiles/satellite-v2/{z}/{x}/{y}.jpg?key=${MAPTILER_KEY}`,
+ maximumLevel: 20,
+ }),
+ );
+ viewer.terrainProvider = await C.CesiumTerrainProvider.fromUrl(
+ `https://api.maptiler.com/tiles/terrain-quantized-mesh-v2/?key=${MAPTILER_KEY}`,
+ {requestVertexNormals: true},
+ );
+ viewer.creditDisplay.addStaticCredit(
+ new C.Credit(
+ '© MapTiler ',
+ true,
+ ),
+ );
+ }
+ if (mode === 'city') {
+ viewer.scene.globe.show = false;
+ const tileset = await C.Cesium3DTileset.fromUrl(
+ `https://tile.googleapis.com/v1/3dtiles/root.json?key=${GOOGLE_MAPS_API_KEY}`,
+ {
+ showCreditsOnScreen: true,
+ maximumScreenSpaceError,
+ },
+ );
+ viewer.scene.primitives.add(tileset);
+ tilesetRef.current = tileset;
+ }
+
+ viewer.useDefaultRenderLoop = false;
+ viewer.scene.skyAtmosphere.show = true;
+ viewer.scene.fog.enabled = true;
+ viewer.scene.globe.enableLighting = false;
+ viewer.scene.verticalExaggeration = verticalExaggeration;
+ (window as any).__CESIUM_FLYOVER__ = {C, mode};
+ viewerRef.current = viewer;
+ setCamera(C, viewer, 0);
+ await settle(viewer);
+ setReady(true);
+ continueRender(handle);
+ })().catch((error) => cancelRender(error));
+ }, [durationInFrames, fps, handle, mode]);
+
+ useEffect(() => {
+ if (!ready) return;
+ const frameHandle = delayRender(`cesium ${mode} frame ${frame}`, {
+ timeoutInMilliseconds: 60000,
+ });
+ const C = (window as any).__CESIUM_FLYOVER__.C;
+ const viewer = viewerRef.current;
+ const progress = durationInFrames <= 1 ? 0 : frame / (durationInFrames - 1);
+ setCamera(C, viewer, progress);
+ settle(viewer).then(() => continueRender(frameHandle));
+ }, [ready, frame, durationInFrames, mode]);
+
+ return (
+
+
+ {mode === 'city' ? (
+
+ For promotional purposes only
+
+ ) : null}
+
+ );
+};
diff --git a/remotion-best-practices/remotion-maps/techniques/cesium/assets/cesium-path.json b/remotion-best-practices/remotion-maps/techniques/cesium/assets/cesium-path.json
new file mode 100644
index 0000000..32b60ba
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/cesium/assets/cesium-path.json
@@ -0,0 +1,299 @@
+[
+ [94.986139893537, 29.76417312959953],
+ [94.98637054463002, 29.764163024004816],
+ [94.98661427422437, 29.764153025681516],
+ [94.9868698103708, 29.764142908388347],
+ [94.98713600736019, 29.764132461562934],
+ [94.98741179569139, 29.76412145291623],
+ [94.9876962466277, 29.764109663422126],
+ [94.98798853462426, 29.764096898390772],
+ [94.98828790834106, 29.764082995679242],
+ [94.98859364523021, 29.764067827511347],
+ [94.98890509685035, 29.764051279216236],
+ [94.98922167960325, 29.76403324759024],
+ [94.98954294512464, 29.76401367774424],
+ [94.9898685550894, 29.76399255290906],
+ [94.99019820264337, 29.76396985787546],
+ [94.9905316178847, 29.763945606334815],
+ [94.9908685732739, 29.763919866576575],
+ [94.99120886105722, 29.763892700951896],
+ [94.99155229116181, 29.7638641665054],
+ [94.99189872300363, 29.76383429811986],
+ [94.99224811692223, 29.763803085651237],
+ [94.99260053337049, 29.763770509641105],
+ [94.99295601118384, 29.76373658086857],
+ [94.99331456742908, 29.763701322339223],
+ [94.99367598745215, 29.763664830647013],
+ [94.99404000156176, 29.763627219082974],
+ [94.99440635968021, 29.763588592698778],
+ [94.99477481502787, 29.76354905236459],
+ [94.9951451006731, 29.763508748648892],
+ [94.99578766204738, 29.763462125646818],
+ [94.99643710580968, 29.763412119743368],
+ [94.99709296623192, 29.763358988682928],
+ [94.99775479298779, 29.763302979031952],
+ [94.99842214521965, 29.763244327404465],
+ [94.99909470569231, 29.763183258547627],
+ [94.9997722961385, 29.76312010454948],
+ [95.00045474013422, 29.763055184243758],
+ [95.00114189582168, 29.762988795623112],
+ [95.00183368970049, 29.762921207778405],
+ [95.0025300799095, 29.76285270023514],
+ [95.00323103443773, 29.762783549665084],
+ [95.00393658318124, 29.76271400155497],
+ [95.00464681949704, 29.76264432424487],
+ [95.00536183331896, 29.76257477740286],
+ [95.00608171146906, 29.762505612813378],
+ [95.00680653793428, 29.762437075077955],
+ [95.00753639864557, 29.762369398844733],
+ [95.00827137837749, 29.762302811854063],
+ [95.00901153006761, 29.762237519590354],
+ [95.00975680776318, 29.76217368790719],
+ [95.01050716875933, 29.762111478518566],
+ [95.0112626067996, 29.76205102042169],
+ [95.01202312290016, 29.761992432502932],
+ [95.01278871942189, 29.76193583156792],
+ [95.01355940108247, 29.761881333165324],
+ [95.01433525277555, 29.761829093407865],
+ [95.01511636205572, 29.761779224166457],
+ [95.01590278872715, 29.76173180995877],
+ [95.0166868810408, 29.76168612055982],
+ [95.01746871725406, 29.761642332250204],
+ [95.0182483756254, 29.76160062131038],
+ [95.01902596675926, 29.761561177619345],
+ [95.019801682618, 29.761524238306453],
+ [95.02057570378254, 29.76149004865798],
+ [95.02134818878243, 29.761458838563573],
+ [95.02211921065114, 29.761430763930672],
+ [95.02288888930805, 29.761405973069504],
+ [95.02365734467304, 29.761384614290225],
+ [95.02442469666667, 29.761366835902948],
+ [95.02519095257038, 29.761352731197437],
+ [95.02595602043016, 29.761342344990513],
+ [95.02671980829304, 29.761335722099044],
+ [95.02748221022355, 29.76133286485609],
+ [95.02824308111781, 29.761333684556867],
+ [95.02900227020879, 29.761338090875398],
+ [95.02975960629327, 29.76134599002589],
+ [95.03051480114966, 29.76135728786741],
+ [95.03126749207338, 29.761371921751238],
+ [95.03201723576402, 29.761389829130785],
+ [95.03276363398774, 29.761410893146387],
+ [95.03350632277824, 29.761434973117545],
+ [95.03424521675927, 29.76146183394706],
+ [95.03498037607913, 29.761491215377145],
+ [95.035711917426, 29.761522866578012],
+ [95.03643998610582, 29.761556530192124],
+ [95.03716475930274, 29.761591886465347],
+ [95.03788653744915, 29.761628566185358],
+ [95.03860571883365, 29.76166618469001],
+ [95.03932258585421, 29.76170436456548],
+ [95.04003738892985, 29.76174273062808],
+ [95.04075025083816, 29.76178094997509],
+ [95.0414610559133, 29.76181870813213],
+ [95.04216961904287, 29.761855638407084],
+ [95.04287591713418, 29.761891331889718],
+ [95.04357986124926, 29.761925397709096],
+ [95.04428137757625, 29.761957488479126],
+ [95.04498041854592, 29.76198725048925],
+ [95.04567682817188, 29.762014317811357],
+ [95.04637032968634, 29.762038376323694],
+ [95.04706059416637, 29.762059099770216],
+ [95.04774726432963, 29.762076162373777],
+ [95.0484300050609, 29.762089241174117],
+ [95.04910871445378, 29.762098042845082],
+ [95.04978328153793, 29.762102280852183],
+ [95.05045359964508, 29.76210167552205],
+ [95.05111966253706, 29.76209602004179],
+ [95.05178153406797, 29.762085106891018],
+ [95.05243927503516, 29.762068731547185],
+ [95.05309287649075, 29.762046750046103],
+ [95.0537422946664, 29.762019099359485],
+ [95.05438748396233, 29.761985721609257],
+ [95.05502839823626, 29.76194655859307],
+ [95.05566488201883, 29.761901557942874],
+ [95.05629656919591, 29.761850805510885],
+ [95.05692313234233, 29.761794428680094],
+ [95.0575442743842, 29.761732580860688],
+ [95.0581596433054, 29.761665348138973],
+ [95.05876888708963, 29.761592816601354],
+ [95.05937164047754, 29.761515065256333],
+ [95.05996759228947, 29.761432144038746],
+ [95.06055643134583, 29.761344102883623],
+ [95.06113793491645, 29.761251010034922],
+ [95.06171214230999, 29.761153046649387],
+ [95.06227907948092, 29.761050389948267],
+ [95.06283877238438, 29.760943217152814],
+ [95.06339127381165, 29.760831691663462],
+ [95.06393669678933, 29.760716002374487],
+ [95.06447520396281, 29.76059636241658],
+ [95.06500695797821, 29.760472984920362],
+ [95.06553212847378, 29.760346104258282],
+ [95.0660508986937, 29.760216015040477],
+ [95.06656344194985, 29.760083025494016],
+ [95.06707002648291, 29.75994741412334],
+ [95.06757112978441, 29.759809440866206],
+ [95.06806722979658, 29.759669344181514],
+ [95.06855878142073, 29.759527354008487],
+ [95.06904617625263, 29.759383697903765],
+ [95.06952978875404, 29.75923861533451],
+ [95.07000993080214, 29.759092371156385],
+ [95.07048679175114, 29.758945227682446],
+ [95.07096044787545, 29.75879742836973],
+ [95.07143096114058, 29.758649219939148],
+ [95.0718984144853, 29.758500858117706],
+ [95.07236278188816, 29.7583525823887],
+ [95.07282412506945, 29.758204644682806],
+ [95.07328275575983, 29.75805728963777],
+ [95.07373905641253, 29.757910760813612],
+ [95.07419366476313, 29.757765217208473],
+ [95.07464735762416, 29.757620800921966],
+ [95.07510085345471, 29.757477677507868],
+ [95.07555467766437, 29.757336168750566],
+ [95.07600940811365, 29.757196598118206],
+ [95.07646537399586, 29.75705931280275],
+ [95.0769228207089, 29.756924677394206],
+ [95.07738220221682, 29.756793075496777],
+ [95.07784401968648, 29.75666487927172],
+ [95.07830874492939, 29.756540496044202],
+ [95.07877690647402, 29.756420332181715],
+ [95.07924898851259, 29.75630478841808],
+ [95.07972503722137, 29.756194196891926],
+ [95.08020511490892, 29.756088882533362],
+ [95.0806891403115, 29.75598918720403],
+ [95.08117690920173, 29.75589531641115],
+ [95.08166835685006, 29.755807414283098],
+ [95.08216335868525, 29.75572566824862],
+ [95.08266177736347, 29.755650250535062],
+ [95.08316349491537, 29.75558120546187],
+ [95.08366839703267, 29.755518567048284],
+ [95.08417639041532, 29.75546236367944],
+ [95.08468755179344, 29.755412571989652],
+ [95.08520236790308, 29.755369015997044],
+ [95.08572134650697, 29.75533148313236],
+ [95.0862450098908, 29.755299740305322],
+ [95.08677390781156, 29.75527358808779],
+ [95.08730861289804, 29.755252808551163],
+ [95.08784970300886, 29.755237175354623],
+ [95.08839755885471, 29.755226476280296],
+ [95.08895256438073, 29.755220494902016],
+ [95.089514993805, 29.755219019351184],
+ [95.09008489086116, 29.7552217729881],
+ [95.09066229928165, 29.75522847917293],
+ [95.09124726342738, 29.755238870403907],
+ [95.09183976966378, 29.755252726598844],
+ [95.09243978867215, 29.75526985018834],
+ [95.09304723439128, 29.755290065097345],
+ [95.09366184648091, 29.75531326126932],
+ [95.09428337414857, 29.755339326723966],
+ [95.09491171647382, 29.755368102171502],
+ [95.09554680939114, 29.75539940595205],
+ [95.09618846028675, 29.755433126230766],
+ [95.09683632409143, 29.75546923335011],
+ [95.09749004228215, 29.75550775219342],
+ [95.09814924669702, 29.755548754655436],
+ [95.0988136358514, 29.755592374644042],
+ [95.09948290826172, 29.755638746066982],
+ [95.1001568080277, 29.75568798494813],
+ [95.10083517891061, 29.75574017449467],
+ [95.10151797539464, 29.75579531974171],
+ [95.1022051519645, 29.755853425724286],
+ [95.10289664375364, 29.755914488290983],
+ [95.10359258928374, 29.755978570204803],
+ [95.10429306658138, 29.756045742645284],
+ [95.10499798654989, 29.756116067070348],
+ [95.10570717321444, 29.75618958016383],
+ [95.10642032295875, 29.75626636089044],
+ [95.10713711848761, 29.756346492746122],
+ [95.10785729025027, 29.75643004436662],
+ [95.10858043622838, 29.75651688160893],
+ [95.10930611534633, 29.75660684892344],
+ [95.11003407093642, 29.756699686157475],
+ [95.11076414467685, 29.756795123665622],
+ [95.1114960914754, 29.756892893838618],
+ [95.11222971288655, 29.756992700238396],
+ [95.1129649452222, 29.75709420093414],
+ [95.11370170201873, 29.75719709582746],
+ [95.11443986012442, 29.757301125099488],
+ [95.11517935555177, 29.7574061249826],
+ [95.11592009761476, 29.757511940391662],
+ [95.11666232015585, 29.75761835330566],
+ [95.11740624233691, 29.757725222810585],
+ [95.11815181076378, 29.75783253698326],
+ [95.11889913308254, 29.757940178669305],
+ [95.11964841222917, 29.758048000558695],
+ [95.12039993276164, 29.758155854652614],
+ [95.12115399312397, 29.75826357999786],
+ [95.1219108497459, 29.75837102690515],
+ [95.1226706293697, 29.758478081829693],
+ [95.12343325561484, 29.758584686897258],
+ [95.12419857627997, 29.758690818430438],
+ [95.12496638982559, 29.75879646083105],
+ [95.12573649209446, 29.7589015818837],
+ [95.12650863318528, 29.75900618637391],
+ [95.12728253192327, 29.759110282431784],
+ [95.12805798566751, 29.75921386162033],
+ [95.12883477913662, 29.759316919371038],
+ [95.12961273528985, 29.759419445656786],
+ [95.13039166301432, 29.759521458216526],
+ [95.13117134363408, 29.759622963323043],
+ [95.13195155721434, 29.759723948972997],
+ [95.13273211930314, 29.759824349786275],
+ [95.13351286507051, 29.759924061406032],
+ [95.13428648274362, 29.76002351015658],
+ [95.1350533298064, 29.760122544307915],
+ [95.1358137532818, 29.760221010686855],
+ [95.13656784419986, 29.760318809952974],
+ [95.13731567503761, 29.76041584848236],
+ [95.1380573752464, 29.760511990985425],
+ [95.13879310931623, 29.76060704815151],
+ [95.13952306473344, 29.760700794123938],
+ [95.14024751710419, 29.7607929520901],
+ [95.14096671686433, 29.760883206230545],
+ [95.14168092332761, 29.76097123202995],
+ [95.14239029599311, 29.761056732470486],
+ [95.14309486625548, 29.761139484506582],
+ [95.14379454089128, 29.761219462160696],
+ [95.14448922306659, 29.76129664046317],
+ [95.14517882147311, 29.76137100941381],
+ [95.14586312132259, 29.761442532574584],
+ [95.14654188135431, 29.761511168945386],
+ [95.14721489938523, 29.761576901934955],
+ [95.14788204807155, 29.761639772673718],
+ [95.14854319868547, 29.76169982923195],
+ [95.14919822095698, 29.761757127412878],
+ [95.14984699116548, 29.76181173598209],
+ [95.15048960377052, 29.761863851723042],
+ [95.15112617637942, 29.761913696049017],
+ [95.15175681293137, 29.761961561816054],
+ [95.15238148064795, 29.762007691856205],
+ [95.15300009096235, 29.762052309028526],
+ [95.1533539374323, 29.762086082676035],
+ [95.15370650809008, 29.762118928860186],
+ [95.15405759583123, 29.762150875711065],
+ [95.15440704121897, 29.76218191319173],
+ [95.1547548321985, 29.762211967913583],
+ [95.15510097264206, 29.762240955288657],
+ [95.15544525415498, 29.762268829619945],
+ [95.15578751039571, 29.76229553455492],
+ [95.15612769998111, 29.762320941845203],
+ [95.15646565712565, 29.762344985615734],
+ [95.156801142589, 29.76236761294652],
+ [95.1571338046714, 29.76238883654028],
+ [95.15746323934037, 29.76240869370805],
+ [95.15778903282519, 29.762427217766984],
+ [95.15811077257146, 29.762444433666733],
+ [95.15842800577592, 29.762460368791256],
+ [95.15874028837707, 29.76247502889767],
+ [95.15904716834646, 29.76248842410003],
+ [95.1593481499996, 29.762500590502704],
+ [95.15964271930007, 29.76251153961251],
+ [95.1599303416933, 29.76252129267978],
+ [95.16021045104225, 29.762529892932115],
+ [95.16048243037355, 29.762537389252305],
+ [95.16074559672008, 29.762543832974302],
+ [95.1609993202866, 29.762549265122786],
+ [95.16124294069552, 29.762553753099137],
+ [95.16147571071544, 29.762557390653928],
+ [95.16169677155058, 29.762560323342807]
+]
diff --git a/remotion-best-practices/remotion-maps/techniques/cesium/assets/city-path.json b/remotion-best-practices/remotion-maps/techniques/cesium/assets/city-path.json
new file mode 100644
index 0000000..821973f
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/cesium/assets/city-path.json
@@ -0,0 +1,12 @@
+[
+ [-74.0135, 40.7047],
+ [-74.0102, 40.7104],
+ [-74.0074, 40.7167],
+ [-74.0047, 40.7232],
+ [-74.0017, 40.7297],
+ [-73.9988, 40.7362],
+ [-73.9954, 40.7429],
+ [-73.9917, 40.7496],
+ [-73.9882, 40.7563],
+ [-73.9848, 40.7631]
+]
diff --git a/remotion-best-practices/remotion-maps/techniques/cesium/assets/example-Root.tsx b/remotion-best-practices/remotion-maps/techniques/cesium/assets/example-Root.tsx
new file mode 100644
index 0000000..9a27a0b
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/cesium/assets/example-Root.tsx
@@ -0,0 +1,39 @@
+import React from 'react';
+import {Composition} from 'remotion';
+import {CesiumFlythrough, type CesiumFlythroughProps} from './CesiumFlythrough';
+import cityPath from './city-path.json';
+
+export const RemotionRoot: React.FC = () => (
+ <>
+ out.png --frame=N --gl=angle --timeout=180000 # validate framing/bank first
+bunx remotion render src/index.ts out.mp4 --gl=angle --concurrency=1 --timeout=180000
+```
+
+`--gl=angle` is mandatory. Use `--concurrency=1`; `settle()` already serializes tile loading.
diff --git a/remotion-best-practices/remotion-maps/techniques/cesium/references/3d-troubleshooting.md b/remotion-best-practices/remotion-maps/techniques/cesium/references/3d-troubleshooting.md
new file mode 100644
index 0000000..488eb9d
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/cesium/references/3d-troubleshooting.md
@@ -0,0 +1,57 @@
+# 3D Flyover — troubleshooting
+
+## The headless dead-end (why we render through Remotion)
+
+Cesium's globe **will not draw in a standalone headless Playwright/Chromium** harness. Verified on
+Apple M4 (ANGLE Metal active, WebGL working): the skybox/stars render, but the globe surface produces
+**zero draw commands** (`scene.frameState.commandList.length === 0`), `globe.tilesLoaded` never goes
+true, and frames come back as the black starfield. No network failures; `sampleTerrainMostDetailed`
+succeeds (terrain data is reachable). Dead-ends tried, all failed:
+
+- default render loop, manual `scene.render()`, manual `viewer.render()`, headed mode (context-destroyed).
+
+**What works:** render Cesium **through Remotion** — same headless Chrome, but driven by Remotion's frame
+loop with these four non-negotiables:
+
+1. `useDefaultRenderLoop = false` — drive frames by hand.
+2. Per frame call **`viewer.render()`**, NOT `scene.render()`. `viewer.render()` does the full frame
+ (`initializeFrame` → tile streaming → render); `scene.render()` skips frame-init, so tiles never
+ advance and the globe never appears. **This is the single most important line.**
+3. `contextOptions: { webgl: { preserveDrawingBuffer: true } }` so Remotion's screenshot captures pixels.
+4. Gate init + every frame with `delayRender(…, {timeoutInMilliseconds})` — tile loading can exceed Remotion's
+ default; use 60–120 s.
+
+The standalone `flythrough.html` / `render.mjs` / `probe.mjs` from the original spike are kept only as the
+record of this dead-end. The canonical render path is the Remotion component
+(`../assets/CesiumFlythrough.tsx`).
+
+## Symptom → fix
+
+| Symptom | Cause | Fix |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Frames are black with stars | Globe not drawing (headless Playwright, or `scene.render()` used) | Render through Remotion; use `viewer.render()`; `useDefaultRenderLoop=false`. |
+| Screenshots blank/transparent | No `preserveDrawingBuffer` | `contextOptions:{ webgl:{ preserveDrawingBuffer:true } }`. |
+| "delayRender timed out" | Cold tiles exceed the default | `delayRender(…, {timeoutInMilliseconds: 120000})` + `--timeout=180000`. |
+| Globe is a dark/navy sphere | Imagery layer didn't attach | `baseLayer:false` then `viewer.imageryLayers.addImageryProvider(...)`. |
+| High-pitch frame shows a void/starfield above the horizon | No atmosphere | `viewer.scene.skyAtmosphere.show = true`. |
+| 403 on tiles in headless | Domain-locked MapTiler key | Use an **unrestricted** key. |
+| Google root tileset returns 403 | Map Tiles API disabled, billing absent, wrong key, or application restriction blocks local headless rendering | Enable Map Tiles API and billing; restrict the key to that API while allowing the Remotion request. |
+| Google scene shows a duplicate/competing surface | MapTiler or the Cesium globe is still enabled | Do not add MapTiler; set `viewer.scene.globe.show=false`. |
+| Google mesh remains coarse | Screen-space error is too high or the capture starts before refinement | Lower `maximumScreenSpaceError`; settle on `tileset.tilesLoaded`. |
+| WebGL unavailable / software renderer | Missing GL flag | Render with `--gl=angle`. |
+| Camera looks at sky / ground, not terrain | Pitch sign / convention | Cesium pitch 0 = horizon, negative = down (inverse of MapLibre); `-(90 - PITCH_FROM_NADIR)`. |
+| Aim/turn-probe clamps near the end | Path too short | `PATHKM ≥ TRAVEL_KM + 2·LOOK_AHEAD_KM`; raise `WINDOW_KM` in prep. |
+| Path feels like straight-then-corner | Douglas-Peucker simplification | Use resample → moving-average smooth (see architecture §2), not `turf.simplify`. |
+| Camera bumps left and right instead of swerving | Sparse route vertices are still being followed as straight segments | Keep `pathSmoothingPasses={3}`; use sparse intentional control points and arc-length movement. |
+
+## Gotchas checklist
+
+- **`viewer.render()`, never `scene.render()`** per frame. The single biggest trap.
+- Cesium loads from **CDN**; set `window.CESIUM_BASE_URL` _before_ injecting the script.
+- `preserveDrawingBuffer: true` or screenshots are blank.
+- `delayRender` uses `timeoutInMilliseconds`; set it to at least 60,000.
+- Terrain: `baseLayer:false`, then add MapTiler imagery.
+- Google: no MapTiler, hide the globe, retain `showCreditsOnScreen:true`.
+- Always `skyAtmosphere.show = true`.
+- Validate the path's heading-delta probe and render one **still** (framing + bank) before the full mp4.
+- Cesium pitch/roll conventions are inverted vs MapLibre.
diff --git a/remotion-best-practices/remotion-maps/techniques/cesium/scripts/prep-cesium-path.mjs b/remotion-best-practices/remotion-maps/techniques/cesium/scripts/prep-cesium-path.mjs
new file mode 100644
index 0000000..dbb3f0f
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/cesium/scripts/prep-cesium-path.mjs
@@ -0,0 +1,161 @@
+// Camera-path generator for the Cesium flythrough. Turns a river/route centerline GeoJSON into a LONG,
+// CONTINUOUSLY-curving camera path so the camera banks through smooth flowing curves (no
+// straight-then-corner). Method: clip → resample to even spacing → moving-average smooth (inherently
+// continuous curvature) → dampen lateral deviation toward the straight chord (dials swerve amplitude).
+// No Douglas-Peucker (that concentrates curvature at sparse control points → corners).
+//
+// RUN (out of the box, against the shipped sample):
+// node prep-cesium-path.mjs
+// → reads assets/sample-river.geojson (override: node prep-cesium-path.mjs )
+// → writes assets/cesium-path.json (then import that JSON in CesiumFlythrough.tsx, or copy it
+// into your Remotion project's src/geo/ and adjust the import)
+//
+// ADAPT for a new location: change START (a point ON your centerline where the corridor opens),
+// WINDOW_KM, and DAMP/SMOOTH below. Input must be a single LineString feature (features[0].geometry).
+
+import {readFileSync, writeFileSync, mkdirSync} from 'fs';
+import {dirname, resolve} from 'path';
+import {fileURLToPath} from 'url';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const IN = process.argv[2] || resolve(__dir, '../assets/sample-river.geojson');
+const OUT = process.argv[3] || resolve(__dir, '../assets/cesium-path.json');
+const havKm = (a, b) => {
+ const R = 6371,
+ r = Math.PI / 180,
+ dLat = (b[1] - a[1]) * r,
+ dLng = (b[0] - a[0]) * r;
+ const h =
+ Math.sin(dLat / 2) ** 2 +
+ Math.cos(a[1] * r) * Math.cos(b[1] * r) * Math.sin(dLng / 2) ** 2;
+ return 2 * R * Math.asin(Math.sqrt(h));
+};
+
+const gorge = JSON.parse(readFileSync(IN, 'utf8')).features[0].geometry
+ .coordinates;
+
+// ADAPT: clip ~24 km of river from the reach where the flythrough opens. START must be a point ON the
+// centerline (the script snaps to the nearest vertex). The sample's opening is the Yarlung gorge:
+const START = [94.968, 29.757];
+let s0 = 0,
+ best = Infinity;
+gorge.forEach((p, i) => {
+ const d = havKm(p, START);
+ if (d < best) {
+ best = d;
+ s0 = i;
+ }
+});
+const WINDOW_KM = 30; // clip to ~end of gorge data; smoothing+dampening shrink it to the usable corridor
+const clip = [];
+for (let i = s0, acc = 0; i < gorge.length; i++) {
+ if (i > s0) acc += havKm(gorge[i - 1], gorge[i]);
+ if (acc > WINDOW_KM) break;
+ clip.push(gorge[i]);
+}
+
+// Resample to even arc-length spacing so curvature is distributed evenly along the path.
+const STEP_KM = 0.1;
+const resample = (coords) => {
+ const out = [coords[0].slice()];
+ let carry = 0,
+ from = coords[0];
+ for (let i = 1; i < coords.length; i++) {
+ let segLen = havKm(from, coords[i]);
+ while (carry + segLen >= STEP_KM) {
+ const t = (STEP_KM - carry) / segLen;
+ const np = [
+ from[0] + (coords[i][0] - from[0]) * t,
+ from[1] + (coords[i][1] - from[1]) * t,
+ ];
+ out.push(np);
+ from = np;
+ segLen = havKm(from, coords[i]);
+ carry = 0;
+ }
+ carry += segLen;
+ from = coords[i];
+ }
+ return out;
+};
+
+// Moving-average smoothing — inherently continuous (no kinks). Window in points; repeat for extra glass.
+const smoothMA = (coords, w, passes) => {
+ let c = coords;
+ for (let p = 0; p < passes; p++) {
+ c = c.map((_, i) => {
+ let sx = 0,
+ sy = 0,
+ n = 0;
+ for (
+ let j = Math.max(0, i - w);
+ j <= Math.min(c.length - 1, i + w);
+ j++
+ ) {
+ sx += c[j][0];
+ sy += c[j][1];
+ n++;
+ }
+ return [sx / n, sy / n];
+ });
+ }
+ return c;
+};
+
+const SMOOTH_W = 28; // ±2.8 km window — turns meanders into smooth flowing curves
+const SMOOTH_PASSES = 2;
+const DAMP = 0.45; // keep 45% of the (already-smooth) deviation → gentle, continuous swerve
+
+const even = resample(clip);
+const sm = smoothMA(even, SMOOTH_W, SMOOTH_PASSES);
+
+const lat0 = (sm[0][1] * Math.PI) / 180;
+const kx = 111.32 * Math.cos(lat0),
+ ky = 110.57;
+const toXY = (p) => [(p[0] - sm[0][0]) * kx, (p[1] - sm[0][1]) * ky];
+const toLL = (xy) => [sm[0][0] + xy[0] / kx, sm[0][1] + xy[1] / ky];
+const A = toXY(sm[0]),
+ B = toXY(sm[sm.length - 1]);
+const AB = [B[0] - A[0], B[1] - A[1]],
+ len2 = AB[0] ** 2 + AB[1] ** 2;
+const path = sm.map((p) => {
+ const P = toXY(p);
+ const t = ((P[0] - A[0]) * AB[0] + (P[1] - A[1]) * AB[1]) / len2;
+ const proj = [A[0] + t * AB[0], A[1] + t * AB[1]];
+ return toLL([
+ proj[0] + (P[0] - proj[0]) * DAMP,
+ proj[1] + (P[1] - proj[1]) * DAMP,
+ ]);
+});
+
+mkdirSync(dirname(OUT), {recursive: true});
+writeFileSync(OUT, JSON.stringify(path));
+
+let len = 0;
+for (let i = 1; i < path.length; i++) len += havKm(path[i - 1], path[i]);
+console.log(
+ `cesium-path: clip ${clip.length} → resample ${even.length} → smooth → ${path.length} pts · ${len.toFixed(1)} km`,
+);
+const bear = (a, b) => {
+ const r = Math.PI / 180;
+ const y = Math.sin((b[0] - a[0]) * r) * Math.cos(b[1] * r);
+ const x =
+ Math.cos(a[1] * r) * Math.sin(b[1] * r) -
+ Math.sin(a[1] * r) * Math.cos(b[1] * r) * Math.cos((b[0] - a[0]) * r);
+ return (Math.atan2(y, x) * 180) / Math.PI;
+};
+// heading sampled every ~1.5 km — should change gradually & continuously (no big jumps = no corners)
+const stepPts = Math.round(1.5 / STEP_KM);
+let prev = null,
+ hs = [];
+for (let i = 0; i + stepPts < path.length; i += stepPts) {
+ const h = bear(path[i], path[i + stepPts]);
+ if (prev !== null) {
+ let d = h - prev;
+ while (d > 180) d -= 360;
+ while (d < -180) d += 360;
+ hs.push(d.toFixed(0));
+ }
+ prev = h;
+}
+console.log(` heading deltas every 1.5km (deg): ${hs.join(', ')}`);
diff --git a/remotion-best-practices/remotion-maps/techniques/mapbox/TECHNIQUE.md b/remotion-best-practices/remotion-maps/techniques/mapbox/TECHNIQUE.md
new file mode 100644
index 0000000..5af3fe1
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/mapbox/TECHNIQUE.md
@@ -0,0 +1,449 @@
+---
+name: maps-mapbox
+description: Make deterministic Remotion 2D map animations with Mapbox GL JS and Turf. Use when the user chooses Mapbox for animated routes, map markers, labels, camera movement, or Mapbox styles.
+metadata:
+ tags: map, map animation, mapbox, turf, geojson, route animation
+---
+
+Use Mapbox GL JS for rendering maps in Remotion when the user wants Mapbox styles or higher-fidelity map visuals and has a Mapbox access token. Use Turf for geospatial operations such as great-circle routes, distances, slicing lines, and positions along routes.
+
+Use this technique only when the user has a Mapbox access token and wants Mapbox styles or data.
+
+## Core rules
+
+- Prefer `@turf/turf` for geospatial work. Do not hand-roll distance, great-circle, route slicing, or coordinate interpolation unless the user explicitly needs a custom non-geodesic effect.
+- Use GeoJSON sources and Mapbox layers for lines, markers, and labels. Avoid DOM `Marker` elements unless the user specifically asks for HTML markers.
+- Keep the live map camera static by default. Before moving it on every frame, read [moving-map stability](references/render-stability.md). Prefer a fixed map plate for satellite imagery, hillshade, or a modest 2D reframe.
+- Use a live per-frame camera only after rendering a short MP4 and checking for shimmer. This 2D technique does not provide genuine terrain, pitch, bearing, or banking.
+- Disable non-deterministic map behavior: `interactive: false`, `fadeDuration: 0`.
+- Drive animation from `useCurrentFrame()`; do not use CSS transitions or browser-timed animation.
+- Use `delayRender()` / `continueRender()` around map loading and per-frame map updates.
+- Set `preserveDrawingBuffer: true` and render WebGL with `bunx remotion ... --gl=angle`.
+- Before continuing the initial render, add sources/layers, apply the frame-0 camera with `jumpTo()` or `setFreeCameraOptions()`, then wait for `idle`.
+- Do not add a `mapInstance.remove()` cleanup function; it can interfere with Remotion's render lifecycle.
+- Use Mapbox style URLs such as `mapbox://styles/mapbox/standard` or a user-provided custom style.
+- Do not install `@types/mapbox-gl`; Mapbox GL JS ships its own types.
+- Keep required provider attribution visible and verify current provider terms before rendering.
+- Record the source and effective date of custom or disputed geography.
+- Inspect rendered pixels, not only Studio playback, at every required aspect ratio.
+
+Coordinates in Mapbox, Turf, and GeoJSON are `[longitude, latitude]`.
+
+```ts
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+```
+
+## Prerequisites
+
+Install Mapbox GL JS and Turf with the project's package manager.
+
+```bash
+npm i mapbox-gl @turf/turf
+```
+
+```bash
+bun i mapbox-gl @turf/turf
+```
+
+```bash
+yarn add mapbox-gl @turf/turf
+```
+
+```bash
+pnpm i mapbox-gl @turf/turf
+```
+
+Import the Mapbox CSS once in the component or an app-level stylesheet:
+
+```ts
+import 'mapbox-gl/dist/mapbox-gl.css';
+```
+
+Mapbox requires a public access token. Prefer passing it as an input prop or reading it from an environment variable that is available to the bundled Remotion code.
+
+```ts
+const mapboxAccessToken = process.env.REMOTION_MAPBOX_TOKEN;
+
+if (!mapboxAccessToken) {
+ throw new Error('Set REMOTION_MAPBOX_TOKEN to render Mapbox maps.');
+}
+```
+
+## Basic map example
+
+```tsx
+import {useEffect, useRef, useState} from 'react';
+import {AbsoluteFill, useDelayRender, useVideoConfig} from 'remotion';
+import mapboxgl from 'mapbox-gl';
+import 'mapbox-gl/dist/mapbox-gl.css';
+
+const zurich: [number, number] = [8.5417, 47.3769];
+
+const mapboxAccessToken = process.env.REMOTION_MAPBOX_TOKEN;
+
+if (!mapboxAccessToken) {
+ throw new Error('Set REMOTION_MAPBOX_TOKEN to render Mapbox maps.');
+}
+
+export const MyComposition = () => {
+ const containerRef = useRef(null);
+ const {delayRender, continueRender} = useDelayRender();
+ const {width, height} = useVideoConfig();
+ const [loadingHandle] = useState(() => delayRender('Loading Mapbox map'));
+
+ useEffect(() => {
+ if (!containerRef.current) {
+ return;
+ }
+
+ const mapInstance = new mapboxgl.Map({
+ accessToken: mapboxAccessToken,
+ container: containerRef.current,
+ style: 'mapbox://styles/mapbox/standard',
+ center: zurich,
+ zoom: 7,
+ interactive: false,
+ attributionControl: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {
+ preserveDrawingBuffer: true,
+ },
+ });
+
+ mapInstance.on('load', () => {
+ mapInstance.jumpTo({center: zurich, zoom: 7});
+ mapInstance.once('idle', () => {
+ continueRender(loadingHandle);
+ });
+ });
+ }, [continueRender, loadingHandle]);
+
+ return (
+
+
+
+ );
+};
+```
+
+Animated examples should keep the loaded map in React state and skip per-frame updates until that state is set.
+
+## Animated flight route example
+
+This example shows the recommended pattern for route animations:
+
+- Turf creates the route and markers.
+- Turf slices the route for line reveal animation.
+- Mapbox renders the route with GeoJSON sources and layers.
+- The camera uses `jumpTo()` with animated center, zoom, bearing, and pitch.
+- Frame 0 is prepared before `continueRender()`.
+
+```tsx
+import * as turf from '@turf/turf';
+import {useEffect, useRef, useState} from 'react';
+import {
+ AbsoluteFill,
+ Easing,
+ interpolate,
+ useCurrentFrame,
+ useDelayRender,
+ useVideoConfig,
+} from 'remotion';
+import mapboxgl, {type GeoJSONSource, type Map} from 'mapbox-gl';
+import 'mapbox-gl/dist/mapbox-gl.css';
+
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+
+const mapboxAccessToken = process.env.REMOTION_MAPBOX_TOKEN;
+
+if (!mapboxAccessToken) {
+ throw new Error('Set REMOTION_MAPBOX_TOKEN to render Mapbox maps.');
+}
+
+const greatCircleLine = (from: [number, number], to: [number, number]) => {
+ const route = turf.greatCircle(from, to, {npoints: 100});
+
+ if (route.geometry.type === 'LineString') {
+ return turf.lineString(route.geometry.coordinates);
+ }
+
+ // Great-circle routes crossing the antimeridian can become MultiLineString.
+ // Keep the example valid by choosing the longest segment.
+ const longestSegment = route.geometry.coordinates.reduce((longest, segment) => {
+ return segment.length > longest.length ? segment : longest;
+ });
+
+ return turf.lineString(longestSegment);
+};
+
+const targetRoute = greatCircleLine(zurich, newYork);
+const targetRouteDistance = turf.length(targetRoute);
+
+const cityMarkers = turf.featureCollection([
+ turf.point(zurich, {name: 'Zurich'}),
+ turf.point(newYork, {name: 'New York'}),
+]);
+
+const clampProgress = (progress: number) => Math.min(1, Math.max(0, progress));
+
+const distanceAlong = (totalDistance: number, progress: number) => {
+ // Keep the route non-empty at progress 0; Turf can error on zero-length slices.
+ return Math.max(0.001, totalDistance * clampProgress(progress));
+};
+
+const getPartialTargetRoute = (progress: number) => {
+ return turf.lineSliceAlong(
+ targetRoute,
+ 0,
+ distanceAlong(targetRouteDistance, progress),
+ );
+};
+
+const getCameraOptions = (progress: number) => {
+ const target = turf.along(
+ targetRoute,
+ distanceAlong(targetRouteDistance, progress),
+ ).geometry.coordinates as [number, number];
+
+ return {
+ center: target,
+ zoom: interpolate(progress, [0, 0.5, 1], [7, 2.4, 8], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ }),
+ bearing: interpolate(progress, [0, 1], [-20, 35], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ }),
+ pitch: interpolate(progress, [0, 0.25, 0.75, 1], [25, 55, 55, 30], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ }),
+ };
+};
+
+export const MyComposition = () => {
+ const containerRef = useRef(null);
+ const frame = useCurrentFrame();
+ const {delayRender, continueRender} = useDelayRender();
+ const {durationInFrames, height, width} = useVideoConfig();
+ const [map, setMap] = useState(null);
+ const [loadingHandle] = useState(() => delayRender('Loading Mapbox map'));
+
+ useEffect(() => {
+ if (!containerRef.current) {
+ return;
+ }
+
+ const mapInstance = new mapboxgl.Map({
+ accessToken: mapboxAccessToken,
+ container: containerRef.current,
+ style: 'mapbox://styles/mapbox/standard',
+ center: zurich,
+ zoom: 7,
+ interactive: false,
+ attributionControl: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {
+ preserveDrawingBuffer: true,
+ },
+ });
+
+ mapInstance.on('load', () => {
+ mapInstance.addSource('trace', {
+ type: 'geojson',
+ data: getPartialTargetRoute(0),
+ });
+
+ mapInstance.addLayer({
+ id: 'trace-line',
+ type: 'line',
+ source: 'trace',
+ layout: {
+ 'line-cap': 'round',
+ 'line-join': 'round',
+ },
+ paint: {
+ 'line-color': '#111111',
+ 'line-width': 7,
+ },
+ });
+
+ mapInstance.addSource('city-markers', {
+ type: 'geojson',
+ data: cityMarkers,
+ });
+
+ mapInstance.addLayer({
+ id: 'city-marker-dots',
+ type: 'circle',
+ source: 'city-markers',
+ paint: {
+ 'circle-color': '#f03b20',
+ 'circle-radius': 12,
+ 'circle-stroke-color': '#ffffff',
+ 'circle-stroke-width': 4,
+ },
+ });
+
+ mapInstance.addLayer({
+ id: 'city-marker-labels',
+ type: 'symbol',
+ source: 'city-markers',
+ layout: {
+ 'text-allow-overlap': true,
+ 'text-anchor': 'top',
+ 'text-field': ['get', 'name'],
+ 'text-offset': [0, 0.9],
+ 'text-size': 28,
+ },
+ paint: {
+ 'text-color': '#111111',
+ 'text-halo-color': '#ffffff',
+ 'text-halo-width': 3,
+ },
+ });
+
+ mapInstance.jumpTo(getCameraOptions(0));
+ mapInstance.once('idle', () => {
+ setMap(mapInstance);
+ continueRender(loadingHandle);
+ });
+ });
+ }, [continueRender, loadingHandle]);
+
+ useEffect(() => {
+ if (!map) {
+ return;
+ }
+
+ const handle = delayRender('Rendering Mapbox frame');
+ const timelineProgress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ });
+ const travelProgress = interpolate(timelineProgress, [0.2, 0.82], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ });
+ const trace = map.getSource('trace') as GeoJSONSource | undefined;
+
+ trace?.setData(getPartialTargetRoute(travelProgress));
+ map.jumpTo(getCameraOptions(travelProgress));
+
+ map.once('idle', () => continueRender(handle));
+ // Force an idle event even if the camera parameters are unchanged from the previous frame.
+ map.triggerRepaint();
+ }, [continueRender, delayRender, durationInFrames, frame, map]);
+
+ return (
+
+
+
+ );
+};
+```
+
+## Camera guidance
+
+For a validated live-camera route animation, animate `center`, `zoom`, `bearing`, and `pitch` with `jumpTo()`:
+
+```ts
+map.jumpTo({
+ center,
+ zoom,
+ bearing,
+ pitch,
+});
+```
+
+Keep route progress and camera progress separate if the camera needs to lead, lag, zoom out, or zoom back in. For cinematic 3D camera moves, load the 3D flyover branch from the parent skill.
+
+## Lines
+
+Use GeoJSON sources for lines. Unless the user asks, do not add glow effects or extra decorative points.
+
+For geodesic flight routes, use Turf:
+
+```ts
+const line = greatCircleLine(start, end);
+const distance = turf.length(line);
+const partialLine = turf.lineSliceAlong(
+ line,
+ 0,
+ // Keep the route non-empty at progress 0.
+ Math.max(0.001, distance * progress),
+);
+```
+
+For a visually straight line on the map, use a simple GeoJSON `LineString` between the two points instead of `greatCircle()`.
+
+## Markers and labels
+
+Use map-native GeoJSON layers for markers and labels:
+
+```tsx
+mapInstance.addSource('markers', {
+ type: 'geojson',
+ data: turf.featureCollection([
+ turf.point([-118.2437, 34.0522], {name: 'Los Angeles'}),
+ ]),
+});
+
+mapInstance.addLayer({
+ id: 'marker-dots',
+ type: 'circle',
+ source: 'markers',
+ paint: {
+ 'circle-color': '#f03b20',
+ 'circle-radius': 12,
+ 'circle-stroke-color': '#ffffff',
+ 'circle-stroke-width': 4,
+ },
+});
+
+mapInstance.addLayer({
+ id: 'marker-labels',
+ type: 'symbol',
+ source: 'markers',
+ layout: {
+ 'text-allow-overlap': true,
+ 'text-anchor': 'top',
+ 'text-field': ['get', 'name'],
+ 'text-offset': [0, 0.9],
+ 'text-size': 28,
+ },
+ paint: {
+ 'text-color': '#111111',
+ 'text-halo-color': '#ffffff',
+ 'text-halo-width': 3,
+ },
+});
+```
+
+Make marker sizes and label font sizes large enough for the composition resolution.
+
+## Styles
+
+Default to Mapbox Standard:
+
+```ts
+style: 'mapbox://styles/mapbox/standard'
+```
+
+If the user requests another style, use any valid Mapbox style URL.
+
+## Rendering
+
+For WebGL map renders, prefer single concurrency and ANGLE:
+
+```bash
+bunx remotion render [composition-id] out/video.mp4 --gl=angle --concurrency=1
+```
+
+Use the equivalent package runner for the project. In npm projects, use `npx`; in Bun projects, use `bunx`.
diff --git a/remotion-best-practices/remotion-maps/techniques/mapbox/references/render-stability.md b/remotion-best-practices/remotion-maps/techniques/mapbox/references/render-stability.md
new file mode 100644
index 0000000..fc40033
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/mapbox/references/render-stability.md
@@ -0,0 +1,64 @@
+# Moving Map Render Stability
+
+Read this reference before building a moving 2D MapTiler scene or diagnosing a wavering Remotion render.
+
+## Symptom and cause
+
+If basemap detail shimmers or jitters during a pan/zoom, the likely cause is per-frame `map.jumpTo()`.
+Headless MapTiler capture can resample both vector hillshade and satellite imagery differently frame to
+frame. Tile retries, easing changes, and label changes do not solve that renderer effect.
+
+## Required pattern: fixed map plate
+
+For any 2D pan/zoom:
+
+1. Render the MapTiler canvas once at the largest required zoom in an oversized container. Size it from the camera route and keep each dimension below the browser's reliable WebGL render-buffer limit (commonly 4096 px). Do **not** blindly use 3×: a 1920×1080 composition becomes 5760 px wide and Chromium may silently downsample it, causing visible pixelation during the CSS zoom.
+2. Keep the map's camera static.
+3. For each frame, calculate the approved target centre/zoom, then move the canvas with CSS `translate` + `scale`.
+4. Apply the same transform to every projected HTML overlay.
+5. Continue to animate GeoJSON data and paint properties imperatively; only the renderer camera is frozen.
+
+Keep pitch and bearing constant. Use a 3D engine such as Cesium for genuine changing pitch/bearing or a terrain flythrough.
+
+```ts
+const baseZoom = Math.max(start.zoom, end.zoom);
+const map = new maptilersdk.Map({
+ container,
+ style,
+ center: end.center,
+ zoom: baseZoom,
+ pitch: end.pitch ?? 0,
+ bearing: end.bearing ?? 0,
+ interactive: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {preserveDrawingBuffer: true},
+});
+
+// Per Remotion frame. `camera` is the approved centre/zoom interpolation.
+const projected = map.project(camera.center);
+const scale = 2 ** (camera.zoom - baseZoom);
+const plate = {
+ transform: `translate(${width / 2 - projected.x * scale}px, ${height / 2 - projected.y * scale}px) scale(${scale})`,
+ transformOrigin: "0 0",
+};
+
+// Convert label projection with exactly the same plate transform.
+const labelX = labelPoint.x * scale + width / 2 - projected.x * scale;
+const labelY = labelPoint.y * scale + height / 2 - projected.y * scale;
+```
+
+### Plate sizing and sharpness
+
+- Render at the maximum zoom reached by **any** camera waypoint, including intermediate or hold cameras. The CSS scale should never exceed `1`; otherwise the plate is being enlarged.
+- Centre the frozen map on the midpoint of the camera route's geographic extent, not automatically on the final camera. This minimizes required overscan.
+- Keep the largest canvas dimension at or below 4096 px unless the actual render environment has been tested with a larger `MAX_RENDERBUFFER_SIZE`.
+- For 1920×1080, a 3840×2160 plate is a safe default. For 1080×1920, use approximately 2700×3840 when the route needs extra horizontal pan room.
+- If the route cannot fit within that plate at the required zoom, split the shot into two fixed plates with a deliberate editorial transition. Do not trade sharpness for one enormous canvas.
+- Distinguish failure modes: repeating shimmer means the live renderer is moving; steadily soft tiles during a CSS push means the fixed plate is underspecified, internally downsampled, or being scaled above `1`.
+
+## Verification
+
+- Render a short MP4, not only a Studio preview.
+- Inspect static terrain texture and satellite detail while the camera moves.
+- If any underlying map detail wavers, use the fixed map plate. Do not approve it as a minor preview artefact.
+- Render WebGL with `--gl=angle`, `preserveDrawingBuffer:true`, and conservative concurrency (`1`) while validating.
diff --git a/remotion-best-practices/remotion-maps/techniques/maplibre/TECHNIQUE.md b/remotion-best-practices/remotion-maps/techniques/maplibre/TECHNIQUE.md
new file mode 100644
index 0000000..94ef160
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/maplibre/TECHNIQUE.md
@@ -0,0 +1,484 @@
+---
+name: maps-maplibre
+description: Make deterministic Remotion 2D map animations with MapLibre GL JS and Turf. Use when the user chooses MapLibre for animated routes, map markers, labels, and camera movement.
+metadata:
+ tags: map, map animation, maplibre, turf, geojson, route animation
+---
+
+Use MapLibre GL JS for rendering maps in Remotion. Use Turf for geospatial operations such as great-circle routes, distances, slicing lines, and positions along routes.
+
+## Core rules
+
+- Prefer `@turf/turf` for geospatial work. Do not hand-roll distance, great-circle, route slicing, or coordinate interpolation unless the user explicitly needs a custom non-geodesic effect.
+- Use GeoJSON sources and MapLibre layers for lines, markers, and labels. Avoid DOM `Marker` elements unless the user specifically asks for HTML markers.
+- Keep the live map camera static by default. Before moving it on every frame, read [moving-map stability](references/render-stability.md). Prefer a fixed map plate for satellite imagery, hillshade, or a modest 2D reframe.
+- Use a live per-frame camera only after rendering a short MP4 and checking for shimmer. This 2D technique does not provide genuine terrain, pitch, bearing, or banking.
+- Disable non-deterministic map behavior: `interactive: false`, `fadeDuration: 0`.
+- Drive animation from `useCurrentFrame()`; do not use CSS transitions or browser-timed animation.
+- Use `delayRender()` / `continueRender()` around map loading and per-frame map updates.
+- Set `preserveDrawingBuffer: true` and render WebGL with `bunx remotion ... --gl=angle`.
+- Before continuing the initial render, add sources/layers, apply the frame-0 camera with `jumpTo()`, then wait for `idle`.
+- Do not add a `mapInstance.remove()` cleanup function; it can interfere with Remotion's render lifecycle.
+- Use standard MapLibre style JSON URLs and layer/source APIs.
+- Do not install `@types/maplibre-gl`; MapLibre ships its own types.
+- Keep required provider attribution visible and verify the current terms of the chosen style and tile providers before rendering.
+- Record the source and effective date of custom or disputed geography.
+- Inspect rendered pixels, not only Studio playback, at every required aspect ratio.
+
+Coordinates in MapLibre, Turf, and GeoJSON are `[longitude, latitude]`.
+
+```ts
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+```
+
+## Prerequisites
+
+Install MapLibre and Turf with the project's package manager.
+
+```bash
+npm i maplibre-gl @turf/turf
+```
+
+```bash
+bun i maplibre-gl @turf/turf
+```
+
+```bash
+yarn add maplibre-gl @turf/turf
+```
+
+```bash
+pnpm i maplibre-gl @turf/turf
+```
+
+Import the MapLibre CSS once in the component or an app-level stylesheet:
+
+```ts
+import 'maplibre-gl/dist/maplibre-gl.css';
+```
+
+## Basic map example
+
+```tsx
+import {useEffect, useRef, useState} from 'react';
+import {AbsoluteFill, useDelayRender, useVideoConfig} from 'remotion';
+import * as maplibregl from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+
+const zurich: [number, number] = [8.5417, 47.3769];
+
+export const MyComposition = () => {
+ const containerRef = useRef(null);
+ const {delayRender, continueRender} = useDelayRender();
+ const {width, height} = useVideoConfig();
+ const [loadingHandle] = useState(() => delayRender('Loading map'));
+
+ useEffect(() => {
+ if (!containerRef.current) {
+ return;
+ }
+
+ maplibregl.setWorkerUrl(
+ URL.createObjectURL(
+ new Blob(
+ [`import "https://unpkg.com/maplibre-gl@${maplibregl.getVersion()}/dist/maplibre-gl-worker.mjs";`],
+ {type: 'text/javascript'},
+ ),
+ ),
+ );
+
+ const mapInstance = new maplibregl.Map({
+ container: containerRef.current,
+ style: 'https://demotiles.maplibre.org/style.json',
+ center: zurich,
+ zoom: 7,
+ interactive: false,
+ attributionControl: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {
+ preserveDrawingBuffer: true,
+ },
+ });
+
+ mapInstance.on('load', () => {
+ mapInstance.jumpTo({center: zurich, zoom: 7});
+ mapInstance.once('idle', () => {
+ continueRender(loadingHandle);
+ });
+ });
+ }, [continueRender, loadingHandle]);
+
+ return (
+
+
+
+ );
+};
+```
+
+Animated examples should keep the loaded map in React state and skip per-frame updates until that state is set.
+
+## Animated flight route example
+
+This example shows the recommended pattern for route animations:
+
+- Turf creates the route and markers.
+- Turf slices the route for line reveal animation.
+- The camera has a separate route from the target route.
+- MapLibre's `calculateCameraOptionsFromTo()` is used for camera movement.
+- Frame 0 is prepared before `continueRender()`.
+
+```tsx
+import * as turf from '@turf/turf';
+import {useEffect, useRef, useState} from 'react';
+import {
+ AbsoluteFill,
+ Easing,
+ interpolate,
+ useCurrentFrame,
+ useDelayRender,
+ useVideoConfig,
+} from 'remotion';
+import * as maplibregl from 'maplibre-gl';
+import {type GeoJSONSource, type Map} from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+
+const greatCircleLine = (from: [number, number], to: [number, number]) => {
+ const route = turf.greatCircle(from, to, {npoints: 100});
+
+ if (route.geometry.type === 'LineString') {
+ return turf.lineString(route.geometry.coordinates);
+ }
+
+ // Great-circle routes crossing the antimeridian can become MultiLineString.
+ // Keep the example valid by choosing the longest segment.
+ const longestSegment = route.geometry.coordinates.reduce((longest, segment) => {
+ return segment.length > longest.length ? segment : longest;
+ });
+
+ return turf.lineString(longestSegment);
+};
+
+const targetRoute = greatCircleLine(zurich, newYork);
+const targetRouteDistance = turf.length(targetRoute);
+
+const cameraRoute = greatCircleLine(zurich, newYork);
+const cameraRouteDistance = turf.length(cameraRoute);
+
+const cityMarkers = turf.featureCollection([
+ turf.point(zurich, {name: 'Zurich'}),
+ turf.point(newYork, {name: 'New York'}),
+]);
+
+const clampProgress = (progress: number) => Math.min(1, Math.max(0, progress));
+
+const distanceAlong = (totalDistance: number, progress: number) => {
+ // Keep the route non-empty at progress 0; Turf can error on zero-length slices.
+ return Math.max(0.001, totalDistance * clampProgress(progress));
+};
+
+const getPartialTargetRoute = (progress: number) => {
+ return turf.lineSliceAlong(
+ targetRoute,
+ 0,
+ distanceAlong(targetRouteDistance, progress),
+ );
+};
+
+const getCameraOptions = (
+ map: Map,
+ progress: number,
+ cameraAltitudeMeters: number,
+ cameraLatitudeOffset: number,
+) => {
+ const target = turf.along(
+ targetRoute,
+ distanceAlong(targetRouteDistance, progress),
+ ).geometry.coordinates;
+ const camera = turf.along(
+ cameraRoute,
+ distanceAlong(cameraRouteDistance, progress),
+ ).geometry.coordinates;
+
+ return map.calculateCameraOptionsFromTo(
+ new maplibregl.LngLat(camera[0], camera[1] - cameraLatitudeOffset),
+ cameraAltitudeMeters,
+ new maplibregl.LngLat(target[0], target[1]),
+ );
+};
+
+export const MyComposition = () => {
+ const containerRef = useRef(null);
+ const frame = useCurrentFrame();
+ const {delayRender, continueRender} = useDelayRender();
+ const {durationInFrames, height, width} = useVideoConfig();
+ const [map, setMap] = useState(null);
+ const [loadingHandle] = useState(() => delayRender('Loading MapLibre map'));
+
+ useEffect(() => {
+ if (!containerRef.current) {
+ return;
+ }
+
+ maplibregl.setWorkerUrl(
+ URL.createObjectURL(
+ new Blob(
+ [`import "https://unpkg.com/maplibre-gl@${maplibregl.getVersion()}/dist/maplibre-gl-worker.mjs";`],
+ {type: 'text/javascript'},
+ ),
+ ),
+ );
+
+ const mapInstance = new maplibregl.Map({
+ container: containerRef.current,
+ style: 'https://demotiles.maplibre.org/style.json',
+ center: zurich,
+ zoom: 7,
+ interactive: false,
+ attributionControl: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {
+ preserveDrawingBuffer: true,
+ },
+ });
+
+ mapInstance.on('load', () => {
+ mapInstance.addSource('trace', {
+ type: 'geojson',
+ data: getPartialTargetRoute(0),
+ });
+
+ mapInstance.addLayer({
+ id: 'trace-line',
+ type: 'line',
+ source: 'trace',
+ layout: {
+ 'line-cap': 'round',
+ 'line-join': 'round',
+ },
+ paint: {
+ 'line-color': '#111111',
+ 'line-width': 7,
+ },
+ });
+
+ mapInstance.addSource('city-markers', {
+ type: 'geojson',
+ data: cityMarkers,
+ });
+
+ mapInstance.addLayer({
+ id: 'city-marker-dots',
+ type: 'circle',
+ source: 'city-markers',
+ paint: {
+ 'circle-color': '#f03b20',
+ 'circle-radius': 12,
+ 'circle-stroke-color': '#ffffff',
+ 'circle-stroke-width': 4,
+ },
+ });
+
+ mapInstance.addLayer({
+ id: 'city-marker-labels',
+ type: 'symbol',
+ source: 'city-markers',
+ layout: {
+ 'text-allow-overlap': true,
+ 'text-anchor': 'top',
+ 'text-field': ['get', 'name'],
+ 'text-offset': [0, 0.9],
+ 'text-size': 28,
+ },
+ paint: {
+ 'text-color': '#111111',
+ 'text-halo-color': '#ffffff',
+ 'text-halo-width': 3,
+ },
+ });
+
+ mapInstance.jumpTo(getCameraOptions(mapInstance, 0, 180000, 1.1));
+ mapInstance.once('idle', () => {
+ setMap(mapInstance);
+ continueRender(loadingHandle);
+ });
+ });
+ }, [continueRender, loadingHandle]);
+
+ useEffect(() => {
+ if (!map) {
+ return;
+ }
+
+ const handle = delayRender('Rendering MapLibre frame');
+ const timelineProgress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ });
+ const travelProgress = interpolate(timelineProgress, [0.2, 0.82], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ });
+ const cameraAltitudeMeters = interpolate(
+ timelineProgress,
+ [0, 0.28, 0.74, 1],
+ [180000, 2200000, 2200000, 180000],
+ {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ },
+ );
+ const cameraLatitudeOffset = interpolate(
+ timelineProgress,
+ [0, 0.28, 0.74, 1],
+ [1.1, 8, 8, 1.1],
+ {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ },
+ );
+ const trace = map.getSource('trace') as GeoJSONSource | undefined;
+
+ trace?.setData(getPartialTargetRoute(travelProgress));
+ map.jumpTo(
+ getCameraOptions(
+ map,
+ travelProgress,
+ cameraAltitudeMeters,
+ cameraLatitudeOffset,
+ ),
+ );
+
+ map.once('idle', () => continueRender(handle));
+ // Force an idle event even if the camera parameters are unchanged from the previous frame.
+ map.triggerRepaint();
+ }, [continueRender, delayRender, durationInFrames, frame, map]);
+
+ return (
+
+
+
+ );
+};
+```
+
+## Camera guidance
+
+Use MapLibre's camera helper for camera movement:
+
+```ts
+map.calculateCameraOptionsFromTo(cameraLngLat, cameraAltitudeMeters, targetLngLat);
+```
+
+A good pattern is to keep two concepts separate:
+
+- `targetRoute`: where the animated line is and where the camera looks.
+- `cameraRoute`: where the camera moves.
+
+Then use Turf to read positions from both routes for the same progress value:
+
+```ts
+const target = turf.along(targetRoute, targetDistance * progress).geometry.coordinates;
+const camera = turf.along(cameraRoute, cameraDistance * progress).geometry.coordinates;
+
+map.jumpTo(
+ map.calculateCameraOptionsFromTo(
+ new maplibregl.LngLat(camera[0], camera[1]),
+ cameraAltitudeMeters,
+ new maplibregl.LngLat(target[0], target[1]),
+ ),
+);
+```
+
+For zoom-out / travel / zoom-in animations, animate travel progress separately from camera altitude. Camera altitude is measured in meters. This avoids heavy custom camera math.
+
+## Lines
+
+Use GeoJSON sources for lines. Unless the user asks, do not add glow effects or extra decorative points.
+
+For geodesic flight routes, use Turf:
+
+```ts
+const line = greatCircleLine(start, end);
+const distance = turf.length(line);
+const partialLine = turf.lineSliceAlong(
+ line,
+ 0,
+ // Keep the route non-empty at progress 0.
+ Math.max(0.001, distance * progress),
+);
+```
+
+For a visually straight line on the map, use a simple GeoJSON `LineString` between the two points instead of `greatCircle()`.
+
+## Markers and labels
+
+Use map-native GeoJSON layers for markers and labels:
+
+```tsx
+mapInstance.addSource('markers', {
+ type: 'geojson',
+ data: turf.featureCollection([
+ turf.point([-118.2437, 34.0522], {name: 'Los Angeles'}),
+ ]),
+});
+
+mapInstance.addLayer({
+ id: 'marker-dots',
+ type: 'circle',
+ source: 'markers',
+ paint: {
+ 'circle-color': '#f03b20',
+ 'circle-radius': 12,
+ 'circle-stroke-color': '#ffffff',
+ 'circle-stroke-width': 4,
+ },
+});
+
+mapInstance.addLayer({
+ id: 'marker-labels',
+ type: 'symbol',
+ source: 'markers',
+ layout: {
+ 'text-allow-overlap': true,
+ 'text-anchor': 'top',
+ 'text-field': ['get', 'name'],
+ 'text-offset': [0, 0.9],
+ 'text-size': 28,
+ },
+ paint: {
+ 'text-color': '#111111',
+ 'text-halo-color': '#ffffff',
+ 'text-halo-width': 3,
+ },
+});
+```
+
+Make marker sizes and label font sizes large enough for the composition resolution.
+
+## Styles
+
+Default to the stock MapLibre demo style:
+
+```ts
+style: 'https://demotiles.maplibre.org/style.json'
+```
+
+If the user requests another style, use any valid MapLibre style JSON URL.
+
+## Rendering
+
+For WebGL map renders, prefer single concurrency and ANGLE:
+
+```bash
+bunx remotion render [composition-id] out/video.mp4 --gl=angle --concurrency=1
+```
+
+Use the equivalent package runner for the project. In npm projects, use `npx`; in Bun projects, use `bunx`.
diff --git a/remotion-best-practices/remotion-maps/techniques/maplibre/references/render-stability.md b/remotion-best-practices/remotion-maps/techniques/maplibre/references/render-stability.md
new file mode 100644
index 0000000..fc40033
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/maplibre/references/render-stability.md
@@ -0,0 +1,64 @@
+# Moving Map Render Stability
+
+Read this reference before building a moving 2D MapTiler scene or diagnosing a wavering Remotion render.
+
+## Symptom and cause
+
+If basemap detail shimmers or jitters during a pan/zoom, the likely cause is per-frame `map.jumpTo()`.
+Headless MapTiler capture can resample both vector hillshade and satellite imagery differently frame to
+frame. Tile retries, easing changes, and label changes do not solve that renderer effect.
+
+## Required pattern: fixed map plate
+
+For any 2D pan/zoom:
+
+1. Render the MapTiler canvas once at the largest required zoom in an oversized container. Size it from the camera route and keep each dimension below the browser's reliable WebGL render-buffer limit (commonly 4096 px). Do **not** blindly use 3×: a 1920×1080 composition becomes 5760 px wide and Chromium may silently downsample it, causing visible pixelation during the CSS zoom.
+2. Keep the map's camera static.
+3. For each frame, calculate the approved target centre/zoom, then move the canvas with CSS `translate` + `scale`.
+4. Apply the same transform to every projected HTML overlay.
+5. Continue to animate GeoJSON data and paint properties imperatively; only the renderer camera is frozen.
+
+Keep pitch and bearing constant. Use a 3D engine such as Cesium for genuine changing pitch/bearing or a terrain flythrough.
+
+```ts
+const baseZoom = Math.max(start.zoom, end.zoom);
+const map = new maptilersdk.Map({
+ container,
+ style,
+ center: end.center,
+ zoom: baseZoom,
+ pitch: end.pitch ?? 0,
+ bearing: end.bearing ?? 0,
+ interactive: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {preserveDrawingBuffer: true},
+});
+
+// Per Remotion frame. `camera` is the approved centre/zoom interpolation.
+const projected = map.project(camera.center);
+const scale = 2 ** (camera.zoom - baseZoom);
+const plate = {
+ transform: `translate(${width / 2 - projected.x * scale}px, ${height / 2 - projected.y * scale}px) scale(${scale})`,
+ transformOrigin: "0 0",
+};
+
+// Convert label projection with exactly the same plate transform.
+const labelX = labelPoint.x * scale + width / 2 - projected.x * scale;
+const labelY = labelPoint.y * scale + height / 2 - projected.y * scale;
+```
+
+### Plate sizing and sharpness
+
+- Render at the maximum zoom reached by **any** camera waypoint, including intermediate or hold cameras. The CSS scale should never exceed `1`; otherwise the plate is being enlarged.
+- Centre the frozen map on the midpoint of the camera route's geographic extent, not automatically on the final camera. This minimizes required overscan.
+- Keep the largest canvas dimension at or below 4096 px unless the actual render environment has been tested with a larger `MAX_RENDERBUFFER_SIZE`.
+- For 1920×1080, a 3840×2160 plate is a safe default. For 1080×1920, use approximately 2700×3840 when the route needs extra horizontal pan room.
+- If the route cannot fit within that plate at the required zoom, split the shot into two fixed plates with a deliberate editorial transition. Do not trade sharpness for one enormous canvas.
+- Distinguish failure modes: repeating shimmer means the live renderer is moving; steadily soft tiles during a CSS push means the fixed plate is underspecified, internally downsampled, or being scaled above `1`.
+
+## Verification
+
+- Render a short MP4, not only a Studio preview.
+- Inspect static terrain texture and satellite detail while the camera moves.
+- If any underlying map detail wavers, use the fixed map plate. Do not approve it as a minor preview artefact.
+- Render WebGL with `--gl=angle`, `preserveDrawingBuffer:true`, and conservative concurrency (`1`) while validating.
diff --git a/remotion-best-practices/remotion-maps/techniques/maptiler/TECHNIQUE.md b/remotion-best-practices/remotion-maps/techniques/maptiler/TECHNIQUE.md
new file mode 100644
index 0000000..d358791
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/maptiler/TECHNIQUE.md
@@ -0,0 +1,80 @@
+# MapTiler maps in Remotion
+
+MapTiler is a good solution for map animations where geographics features should be drawn as annotations on top of the map: Country borders, rivers, labels for POIs.
+
+## MapTiler SDK (`@maptiler/sdk`)
+
+Draw the basemap plus MapTiler Planet vector layers and custom GeoJSON into a WebGL canvas. Default styled-vector starting point: `MapStyle.BASIC`; satellite is an equally valid choice.
+
+## Remotion
+
+Imperatively update `setData`/`setPaintProperty`.
+
+Use `jumpTo` only for a static shot, or a fixed map plate for any pan/zoom.
+Gate with [`delayRender`](https://www.remotion.dev/docs/delay-render.md) until `map.once('idle')`.
+
+Use `preserveDrawingBuffer:true`.
+
+Render labels as positioned [``](https://www.remotion.dev/docs/interactive.md) elements.
+
+Env `REMOTION_MAPTILER_KEY` (unrestricted). Init the map once (ref guard); update imperatively per frame.
+
+When constructing MapLibre/MapTiler layer objects, omit optional properties that are absent.
+In particular, use `...(layer.filter ? {filter: layer.filter} : {})`; do not pass `filter: undefined`. An undefined filter can suppress the layer while separately created halo or border layers continue rendering, producing missing country fills and dark marker halos with no coloured cores.
+
+Drive animation from `useCurrentFrame()` rather than CSS transitions or browser timers.
+
+## Choose the source for each map element
+
+Do not begin by manufacturing GeoJSON. First check whether MapTiler Planet already exposes the element as filtered vector data.
+
+### MapTiler vector
+
+Use it when the feature exists in a provider `source-layer`, its attributes support an exact filter, and provider geometry is editorially acceptable.
+
+### Hybrid
+
+Use it when ordinary geographic context can come from MapTiler while the claim depends on custom
+evidence.
+
+Animate each layer according to its source and meaning.
+
+MapTiler vector features remain split across tiles. Do not use them for a semantic start-to-end line draw; extract, verify, order, and bake that element to GeoJSON first. Read **`references/map-data-sources.md`** and reuse **`assets/MapTilerVectorElement.ts`** for provider-layer setup and per-frame paint updates.
+
+## Motion stability
+
+**Do not call `map.jumpTo()` on every Remotion frame when the camera moves.** In headless capture it can make both MapTiler hillshade **and satellite imagery** shimmer/jitter, even when the source tiles load correctly. This is renderer resampling, not a data, network, or label problem.
+
+For the implementation, read **`references/render-stability.md`** before building or debugging any moving map. It contains the fixed-map-plate recipe, diagnostics, and render checks.
+
+- Use the live MapTiler camera only for a static shot.
+- Keep pitch and bearing constant for a fixed plate. This technique does not implement a genuine changing 3D camera.
+- Verify the moving preview and a short rendered MP4 before approving a beat. If any basemap detail wavers, switch to the fixed-plate pattern; do not try to solve it with tile retries or camera easing.
+
+## Drawing rivers
+
+Use `turf.lineSliceAlong(line, 0, lineKm*reveal)` to draw rivers.
+
+## Source selection
+
+Use MapTiler vector layers for suitable provider features and custom GeoJSON for story-specific or ordered geometry. If the beat needs country-entry triggers or a progressive line draw, run `scripts/prep-geo.mjs` to bake `country-meta.json`, `borders.geojson`, and the ordered line. Details → `references/map-data-sources.md` and `references/map-geo-prep.md`.
+
+## Keep it minmal
+
+Strip clutter on `load`: remove `symbol` layers (place labels) and `/other border/i` (admin-1 inner borders); hide the logo via CSS. Keep country + disputed borders.
+
+## Files
+
+Use as reference:
+
+- `assets/RiverReveal.tsx` — the main component.
+- `assets/MapTilerVectorElement.ts` — filtered MapTiler Planet elements.
+- `assets/CountryLabel.tsx` — reusable example label.
+- `assets/tokens.ts` — example palette and durations.
+- `assets/example-Root.tsx` — minimal composition scaffold.
+- `assets/sample-data/` — example route and generated country metadata.
+- `scripts/prep-geo.mjs` — geo pipeline.
+- `references/map-explainer-architecture.md` — timing model and implementation.
+- `references/map-data-sources.md` — provider vector versus custom GeoJSON selection.
+- `references/map-geo-prep.md` — basemap stripping and geo preparation.
+- `references/render-stability.md` — camera motion and stable headless renders.
diff --git a/remotion-best-practices/remotion-maps/techniques/maptiler/assets/CountryLabel.tsx b/remotion-best-practices/remotion-maps/techniques/maptiler/assets/CountryLabel.tsx
new file mode 100644
index 0000000..3e4b887
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/maptiler/assets/CountryLabel.tsx
@@ -0,0 +1,70 @@
+import React from 'react';
+import {Easing, interpolate} from 'remotion';
+
+// Reusable country label. Supply typography and final values from the consuming project; the CSS custom
+// properties below provide neutral fallbacks. Positioned by its centre (x,y in screen px).
+export const CountryLabel: React.FC<{
+ name: string;
+ color: string;
+ reveal: number;
+ x: number;
+ y: number;
+}> = ({name, color, reveal, x, y}) => {
+ const e = interpolate(reveal, [0, 1], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.3333333333333333, 1, 0.6666666666666666, 1),
+ });
+ return (
+
+
+ {/* accent rule — draws out from the centre in the country's colour */}
+
+
+ {name}
+
+
+
;
+ paint: Record;
+};
+
+const SOURCE_ID = 'maptiler-planet';
+
+export const addMapTilerVectorElement = (
+ map: any,
+ apiKey: string,
+ element: MapTilerVectorElement,
+ beforeId?: string,
+) => {
+ if (!map.getSource(SOURCE_ID)) {
+ map.addSource(SOURCE_ID, {
+ type: 'vector',
+ url: `https://api.maptiler.com/tiles/v3/tiles.json?key=${apiKey}`,
+ });
+ }
+
+ if (map.getLayer(element.id)) return;
+
+ map.addLayer(
+ {
+ id: element.id,
+ type: element.type,
+ source: SOURCE_ID,
+ 'source-layer': element.sourceLayer,
+ ...(element.filter ? {filter: element.filter} : {}),
+ ...(element.minzoom === undefined ? {} : {minzoom: element.minzoom}),
+ ...(element.maxzoom === undefined ? {} : {maxzoom: element.maxzoom}),
+ ...(element.layout ? {layout: element.layout} : {}),
+ paint: element.paint,
+ },
+ beforeId,
+ );
+};
+
+export const setVectorElementPaint = (
+ map: any,
+ layerId: string,
+ paint: Record,
+) => {
+ for (const [property, value] of Object.entries(paint)) {
+ map.setPaintProperty(layerId, property, value);
+ }
+};
+
+// Example:
+//
+// addMapTilerVectorElement(map, process.env.REMOTION_MAPTILER_KEY!, {
+// id: "story-river",
+// sourceLayer: "waterway",
+// type: "line",
+// filter: [
+// "all",
+// ["==", ["get", "class"], "river"],
+// ["==", ["coalesce", ["get", "name_en"], ["get", "name"]], "Yarlung Tsangpo"],
+// ],
+// layout: {"line-cap": "round", "line-join": "round"},
+// paint: {"line-color": "#E8F7FF", "line-width": 3, "line-opacity": 0},
+// });
+//
+// Per Remotion frame:
+// setVectorElementPaint(map, "story-river", {
+// "line-opacity": reveal,
+// "line-width": 2 + reveal * 2,
+// });
diff --git a/remotion-best-practices/remotion-maps/techniques/maptiler/assets/RiverReveal.tsx b/remotion-best-practices/remotion-maps/techniques/maptiler/assets/RiverReveal.tsx
new file mode 100644
index 0000000..a0ade54
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/maptiler/assets/RiverReveal.tsx
@@ -0,0 +1,363 @@
+import * as maptilersdk from '@maptiler/sdk';
+import * as turf from '@turf/turf';
+import React, {useEffect, useRef, useState} from 'react';
+import '@maptiler/sdk/dist/maptiler-sdk.css';
+import {
+ AbsoluteFill,
+ Easing,
+ continueRender,
+ delayRender,
+ interpolate,
+ useCurrentFrame,
+ useVideoConfig,
+} from 'remotion';
+import {CountryLabel} from './CountryLabel';
+import countryMeta from './sample-data/country-meta.json';
+import flowCoords from './sample-data/yarlung-flow.json';
+import {COLORS, COUNTRY, COUNTRY_DARK, FILL_OPACITY} from './tokens';
+
+// Sample route reveal. Replace the imported sample geometry, names, timing, and visual tokens in the
+// consuming production. The renderer stays static; approved centre/zoom motion is a CSS plate transform.
+
+maptilersdk.config.apiKey = process.env.REMOTION_MAPTILER_KEY as string;
+
+const line = turf.lineString(flowCoords as [number, number][]);
+const lineKm = turf.length(line);
+
+const START = {
+ center: [89.6, 27.7] as [number, number],
+ zoom: 4.75,
+ pitch: 0,
+ bearing: 0,
+};
+const END = {
+ center: [90.2, 27.0] as [number, number],
+ zoom: 5.05,
+ pitch: 0,
+ bearing: 0,
+};
+const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+const clamp01 = (v: number) => Math.max(0, Math.min(1, v));
+
+const ORDER = ['china', 'india', 'bangladesh'] as const;
+type Country = (typeof ORDER)[number];
+const META = countryMeta as Record<
+ Country,
+ {stop: number; anchor: [number, number]; border: [number, number][][]}
+>;
+const countryPolygons = {
+ type: 'FeatureCollection' as const,
+ features: ORDER.map((country) => ({
+ type: 'Feature' as const,
+ properties: {country},
+ geometry: {
+ type: 'MultiPolygon' as const,
+ coordinates: META[country].border.map((ring) => [ring]),
+ },
+ })),
+};
+
+// Pre-build each country's border as ordered segments with cumulative lengths (for the multi-segment draw).
+const DRAW = Object.fromEntries(
+ ORDER.map((c) => {
+ const segLines = META[c].border.map((s) => turf.lineString(s));
+ const segLen = segLines.map((l) => turf.length(l));
+ const cum: number[] = [];
+ let acc = 0;
+ for (const L of segLen) {
+ cum.push(acc);
+ acc += L;
+ }
+ return [c, {segLines, segLen, cum, total: acc}];
+ }),
+) as Record<
+ Country,
+ {segLines: any[]; segLen: number[]; cum: number[]; total: number}
+>;
+
+// Reveal the portion of the border between fromKm and toKm as a MultiLineString (no joins across gaps).
+const sliceBorder = (
+ d: (typeof DRAW)[Country],
+ fromKm: number,
+ toKm: number,
+) => {
+ const out: number[][][] = [];
+ for (let i = 0; i < d.segLines.length; i++) {
+ const start = d.cum[i],
+ end = start + d.segLen[i];
+ const a = Math.max(fromKm, start),
+ b = Math.min(toKm, end);
+ if (b - a <= 0.0008) continue;
+ out.push(
+ turf.lineSliceAlong(d.segLines[i], a - start, b - start).geometry
+ .coordinates,
+ );
+ }
+ return {
+ type: 'Feature' as const,
+ properties: {},
+ geometry: {type: 'MultiLineString' as const, coordinates: out},
+ };
+};
+const EMPTY = {
+ type: 'Feature' as const,
+ properties: {},
+ geometry: {type: 'MultiLineString' as const, coordinates: [] as number[][][]},
+};
+
+// --- Timing (seconds). River draws over [RIVER_START, RIVER_END]; each country triggers when the river
+// reaches it (stop · span), then runs border → fill → label. Beat length is derived from these. ---
+const RIVER_START = 0.3;
+const RIVER_END = 8.0;
+const BORDER_S = 2.5;
+const FILL_S = 1.0;
+const LABEL_S = 0.7;
+const trigger = (c: Country) =>
+ RIVER_START + META[c].stop * (RIVER_END - RIVER_START);
+
+export const RiverReveal: React.FC = () => {
+ const ref = useRef(null);
+ const started = useRef(false);
+ const frame = useCurrentFrame();
+ const {fps, durationInFrames, width, height} = useVideoConfig();
+ const [map, setMap] = useState(null);
+ const [labels, setLabels] = useState<
+ Record
+ >({});
+ const [plate, setPlate] = useState({x: 0, y: 0, scale: 1});
+ const [handle] = useState(() => delayRender('maptiler init A'));
+
+ useEffect(() => {
+ if (!ref.current || started.current) return;
+ started.current = true;
+ const m = new maptilersdk.Map({
+ container: ref.current,
+ style: maptilersdk.MapStyle.BASIC,
+ center: END.center,
+ zoom: Math.max(START.zoom, END.zoom),
+ pitch: END.pitch,
+ bearing: END.bearing,
+ interactive: false,
+ attributionControl: true,
+ navigationControl: false,
+ geolocateControl: false,
+ maptilerLogo: true,
+ fadeDuration: 0,
+ canvasContextAttributes: {preserveDrawingBuffer: true},
+ } as any);
+
+ m.on('load', () => {
+ // Strip basemap labels (symbols) AND the inner admin-1 borders ('Other border[ dash]',
+ // admin_level 3–10) to cut basemap clutter. Keep country + disputed borders.
+ for (const l of m.getStyle().layers as any[])
+ if (l.type === 'symbol' || /other border/i.test(l.id))
+ m.removeLayer(l.id);
+
+ m.addSource('countries', {type: 'geojson', data: countryPolygons});
+ for (const c of ORDER) {
+ m.addLayer({
+ id: `fill-${c}`,
+ type: 'fill',
+ source: 'countries',
+ filter: ['==', ['get', 'country'], c],
+ paint: {'fill-color': COUNTRY[c], 'fill-opacity': 0},
+ });
+ }
+ // Per country: just the border that draws on, settled to a darker shade of the country colour
+ // (the electricity now lives on the river, not the borders).
+ for (const c of ORDER) {
+ m.addSource(`trail-${c}`, {type: 'geojson', data: EMPTY});
+ m.addLayer({
+ id: `trail-${c}`,
+ type: 'line',
+ source: `trail-${c}`,
+ layout: {'line-cap': 'round', 'line-join': 'round'},
+ paint: {
+ 'line-color': COUNTRY_DARK[c],
+ 'line-width': 2,
+ 'line-opacity': 0.95,
+ },
+ });
+ }
+
+ const seed = turf.lineSliceAlong(
+ line,
+ 0,
+ Math.max(0.001, lineKm * 0.001),
+ );
+ m.addSource('river', {type: 'geojson', data: seed});
+ m.addSource('river-head', {type: 'geojson', data: seed});
+ // Electric water: soft blue glow → icy core → white-hot leading head with its own glow.
+ m.addLayer({
+ id: 'river-glow',
+ type: 'line',
+ source: 'river',
+ layout: {'line-cap': 'round', 'line-join': 'round'},
+ paint: {
+ 'line-color': '#49C6FF',
+ 'line-width': 11,
+ 'line-opacity': 0.32,
+ 'line-blur': 6,
+ },
+ });
+ m.addLayer({
+ id: 'river-line',
+ type: 'line',
+ source: 'river',
+ layout: {'line-cap': 'round', 'line-join': 'round'},
+ paint: {'line-color': COLORS.river, 'line-width': 3},
+ });
+ m.addLayer({
+ id: 'river-headglow',
+ type: 'line',
+ source: 'river-head',
+ layout: {'line-cap': 'round', 'line-join': 'round'},
+ paint: {
+ 'line-color': COLORS.riverHeadGlow,
+ 'line-width': 16,
+ 'line-opacity': 0,
+ 'line-blur': 9,
+ },
+ });
+ m.addLayer({
+ id: 'river-head',
+ type: 'line',
+ source: 'river-head',
+ layout: {'line-cap': 'round', 'line-join': 'round'},
+ paint: {
+ 'line-color': COLORS.riverHead,
+ 'line-width': 4.5,
+ 'line-opacity': 0,
+ },
+ });
+
+ m.once('idle', () => {
+ setMap(m);
+ continueRender(handle);
+ });
+ });
+ }, [handle]);
+
+ useEffect(() => {
+ if (!map) return;
+ const h = delayRender(`frame A ${frame}`);
+ const t = frame / fps; // seconds
+ const tt = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ });
+
+ // River draw
+ const reveal = interpolate(t, [RIVER_START, RIVER_END], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ });
+ const riverDrawnKm = lineKm * reveal;
+ (map.getSource('river') as any)?.setData(
+ turf.lineSliceAlong(line, 0, Math.max(0.001, riverDrawnKm)),
+ );
+ // Electric draw-head leading the river: white-hot core + glow, fading out once the river completes.
+ const riverHeadKm = lineKm * 0.03;
+ (map.getSource('river-head') as any)?.setData(
+ turf.lineSliceAlong(
+ line,
+ Math.max(0, riverDrawnKm - riverHeadKm),
+ Math.max(0.001, riverDrawnKm),
+ ),
+ );
+ let riverHeadFade = 0;
+ if (reveal > 0.002 && reveal < 0.999) riverHeadFade = 1;
+ else if (reveal >= 0.999)
+ riverHeadFade = 1 - clamp01((t - RIVER_END) / 0.5);
+ map.setPaintProperty(
+ 'river-headglow',
+ 'line-opacity',
+ 0.85 * riverHeadFade,
+ );
+ map.setPaintProperty('river-head', 'line-opacity', riverHeadFade);
+
+ const camera = {
+ center: [
+ lerp(START.center[0], END.center[0], tt),
+ lerp(START.center[1], END.center[1], tt),
+ ] as [number, number],
+ zoom: lerp(START.zoom, END.zoom, tt),
+ };
+ const cameraPoint = map.project(camera.center);
+ const plateScale = 2 ** (camera.zoom - Math.max(START.zoom, END.zoom));
+ const plateX = width / 2 - cameraPoint.x * plateScale;
+ const plateY = height / 2 - cameraPoint.y * plateScale;
+
+ const pos: Record = {};
+ for (const c of ORDER) {
+ const d = DRAW[c];
+ const lt = t - trigger(c); // local seconds since this country triggered
+
+ // 1) border draws on (constant duration), settling to a darker shade — no electric head
+ const bp = interpolate(clamp01(lt / BORDER_S), [0, 1], [0, 1], {
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ });
+ (map.getSource(`trail-${c}`) as any)?.setData(
+ bp <= 0 ? EMPTY : sliceBorder(d, 0, d.total * bp),
+ );
+
+ // 2) fill blooms in (overshoot then settle) after the border completes
+ const fp = clamp01((lt - BORDER_S) / FILL_S);
+ const fo = interpolate(
+ fp,
+ [0, 0.6, 1],
+ [0, FILL_OPACITY * 1.25, FILL_OPACITY],
+ {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.3333333333333333, 1, 0.6666666666666666, 1),
+ },
+ );
+ map.setPaintProperty(`fill-${c}`, 'fill-opacity', fp <= 0 ? 0 : fo);
+
+ // 3) label rises in after the fill
+ const lp = clamp01((lt - BORDER_S - FILL_S) / LABEL_S);
+ const p = map.project(META[c].anchor);
+ pos[c] = {
+ x: p.x * plateScale + plateX,
+ y: p.y * plateScale + plateY,
+ reveal: lp,
+ };
+ }
+ setLabels(pos);
+
+ setPlate({x: plateX, y: plateY, scale: plateScale});
+ map.once('idle', () => continueRender(h));
+ map.triggerRepaint();
+ }, [map, frame, fps, durationInFrames, width, height]);
+
+ return (
+
+
+
+ {ORDER.map((c) =>
+ labels[c] ? (
+
+
+ );
+};
diff --git a/remotion-best-practices/remotion-maps/techniques/maptiler/assets/example-Root.tsx b/remotion-best-practices/remotion-maps/techniques/maptiler/assets/example-Root.tsx
new file mode 100644
index 0000000..4e25267
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/maptiler/assets/example-Root.tsx
@@ -0,0 +1,22 @@
+// Minimal Remotion scaffold for the map explainer. In a Remotion project (`bunx create-video@latest`,
+// blank template), this is `src/Root.tsx`; `src/index.ts` is just `registerRoot(RemotionRoot)`.
+//
+// The Composition sets DURATION (the beat) and dimensions. The component reads durationInFrames / width /
+// height from useVideoConfig(). The beat must be long enough for the last country's full sequence after
+// the river reaches it. See references/map-explainer-architecture.md §2.
+// Render with: bunx remotion render src/index.ts MapExplainer out.mp4 --gl=angle --concurrency=1 --timeout=120000
+
+import React from 'react';
+import {Composition} from 'remotion';
+import {RiverReveal} from './RiverReveal'; // → src/components/RiverReveal.tsx in your project
+
+export const RemotionRoot: React.FC = () => (
+ .geojson
+const FRAME_BBOX = [76, 14, 104, 33.5]; // [W,S,E,N] visible extent — fallback for label anchoring only
+const ANCHOR_BBOX = {
+ china: [82, 27, 96, 32],
+ india: [76, 14, 99, 31],
+ bangladesh: [86, 20, 93, 27],
+}; // [W,S,E,N] per-country label "story region"
+const NUDGE = {china: [0, 0.6], india: [-1.0, 0], bangladesh: [0, -0.6]}; // [lng,lat] label nudge
+const RIVER_SIMPLIFY_TOL = 0.006; // degrees — smooths the draw-on (bigger = simpler)
+const OUT_RIVER = resolve(root, 'out/river-flow.json');
+const OUT_META = resolve(root, 'out/country-meta.json');
+const OUT_BORDERS = resolve(root, 'out/borders.geojson');
+// =====================================================
+
+const havKm = (a, b) => {
+ const R = 6371,
+ r = Math.PI / 180;
+ const dLat = (b[1] - a[1]) * r,
+ dLng = (b[0] - a[0]) * r;
+ const h =
+ Math.sin(dLat / 2) ** 2 +
+ Math.cos(a[1] * r) * Math.cos(b[1] * r) * Math.sin(dLng / 2) ** 2;
+ return 2 * R * Math.asin(Math.sqrt(h));
+};
+
+// --- River draw-on line: take the clean routed LineString, strip a dangling final hop, simplify so the
+// wide-zoom draw-on reads as one smooth thread (no bezier — meander overshoot on a long river). ---
+const routed = read(RIVER).features[0].geometry.coordinates;
+let end = routed.length;
+while (end > 2 && havKm(routed[end - 2], routed[end - 1]) > 15) end--; // drop a final cross-braid jump if present
+const flow = turf.simplify(turf.lineString(routed.slice(0, end)), {
+ tolerance: RIVER_SIMPLIFY_TOL,
+ highQuality: true,
+}).geometry.coordinates;
+
+// --- Borders + country fills (one source, filtered per country in the component) ---
+const borders = {type: 'FeatureCollection', features: []};
+const polys = {};
+for (const name of COUNTRIES) {
+ const fc = read(BORDER(name));
+ polys[name] = fc;
+ for (const f of fc.features) {
+ f.properties = {...(f.properties || {}), country: name};
+ borders.features.push(f);
+ }
+}
+
+// --- Reveal stops: arc-length fraction of `flow` where the river first ENTERS each country. The first
+// country (headwaters) is the source, so its stop is 0; the rest are computed. ---
+const flowKm = turf.length(turf.lineString(flow));
+const insideCountry = (pt, name) =>
+ polys[name].features.some((f) => turf.booleanPointInPolygon(pt, f));
+const stops = {};
+COUNTRIES.forEach((c, i) => {
+ stops[c] = i === 0 ? 0 : 1;
+}); // 0 = headwaters; 1 = sentinel until entered
+let acc = 0;
+for (let i = 0; i < flow.length; i++) {
+ if (i > 0) acc += havKm(flow[i - 1], flow[i]);
+ const frac = acc / (flowKm || 1);
+ const pt = turf.point(flow[i]);
+ for (const c of COUNTRIES)
+ if (stops[c] === 1 && insideCountry(pt, c)) stops[c] = frac;
+}
+
+// --- Per-country meta: anchor = pole of inaccessibility of the visible landmass (centred, away from
+// borders/edges) within the country's story region + a NUDGE; border = every exterior ring from the
+// complete named source. Never crop a country or bilateral boundary to the viewport. ---
+const biggestPoly = (geom) => {
+ const rings =
+ geom.type === 'MultiPolygon' ? geom.coordinates : [geom.coordinates];
+ let best = null,
+ bestA = -1;
+ for (const c of rings) {
+ const p = turf.polygon(c);
+ const a = turf.area(p);
+ if (a > bestA) {
+ bestA = a;
+ best = p;
+ }
+ }
+ return best;
+};
+const largestPolygon = (fc) => {
+ let best = null,
+ bestA = -1;
+ for (const f of fc.features) {
+ const p = biggestPoly(f.geometry),
+ a = turf.area(p);
+ if (a > bestA) {
+ bestA = a;
+ best = p;
+ }
+ }
+ return best;
+};
+const completeExteriorSegments = (fc) => {
+ const segments = [];
+ for (const feature of fc.features) {
+ const polygons =
+ feature.geometry.type === 'MultiPolygon'
+ ? feature.geometry.coordinates
+ : [feature.geometry.coordinates];
+ for (const polygon of polygons)
+ if (polygon[0]?.length > 1) segments.push(polygon[0]);
+ }
+ return segments;
+};
+const poleOfInaccessibility = (poly) => {
+ const bb = turf.bbox(poly),
+ boundary = turf.polygonToLine(poly),
+ N = 46;
+ let best = null,
+ bestD = -1;
+ for (let i = 0; i <= N; i++)
+ for (let j = 0; j <= N; j++) {
+ const lng = bb[0] + ((bb[2] - bb[0]) * i) / N,
+ lat = bb[1] + ((bb[3] - bb[1]) * j) / N;
+ const pt = turf.point([lng, lat]);
+ if (!turf.booleanPointInPolygon(pt, poly)) continue;
+ const d = turf.pointToLineDistance(pt, boundary);
+ if (d > bestD) {
+ bestD = d;
+ best = [lng, lat];
+ }
+ }
+ return best;
+};
+const countryMeta = {};
+for (const name of COUNTRIES) {
+ const poly = largestPolygon(polys[name]);
+ const storyRegion = biggestPoly(
+ turf.bboxClip(poly, ANCHOR_BBOX[name] || FRAME_BBOX).geometry,
+ );
+ const pole = poleOfInaccessibility(storyRegion);
+ const segs = completeExteriorSegments(polys[name]);
+ const nudge = NUDGE[name] || [0, 0];
+ countryMeta[name] = {
+ stop: stops[name],
+ anchor: [pole[0] + nudge[0], pole[1] + nudge[1]],
+ border: segs,
+ };
+}
+
+mkdirSync(dirname(OUT_RIVER), {recursive: true});
+writeFileSync(OUT_RIVER, JSON.stringify(flow));
+writeFileSync(OUT_META, JSON.stringify(countryMeta));
+writeFileSync(OUT_BORDERS, JSON.stringify(borders));
+console.log(
+ 'river:',
+ flow.length,
+ 'pts ·',
+ flowKm.toFixed(0),
+ 'km · entry stops',
+ JSON.stringify(stops),
+);
+for (const n of COUNTRIES) {
+ const km = countryMeta[n].border.reduce(
+ (s, seg) => s + turf.length(turf.lineString(seg)),
+ 0,
+ );
+ console.log(
+ ` ${n}: anchor ${countryMeta[n].anchor.map((v) => v.toFixed(2)).join(',')} · border ${km.toFixed(0)} km`,
+ );
+}
+console.log(
+ "\nNext: copy out/river-flow.json + out/country-meta.json → your project's src/geo/ ; out/borders.geojson → public/geo/",
+);
diff --git a/remotion-best-practices/remotion-maps/techniques/static-map/TECHNIQUE.md b/remotion-best-practices/remotion-maps/techniques/static-map/TECHNIQUE.md
new file mode 100644
index 0000000..808ec93
--- /dev/null
+++ b/remotion-best-practices/remotion-maps/techniques/static-map/TECHNIQUE.md
@@ -0,0 +1,37 @@
+---
+name: remotion-maps-static
+description: Create a deterministic static locator map in Remotion when neither the camera nor geographic data animates.
+---
+
+# Static map
+
+Use a static image when the map only provides location context. This is the smallest, fastest, and
+most deterministic map technique.
+
+## Build
+
+1. Export or request a map image at the composition's final aspect ratio and at least its rendered
+ pixel dimensions.
+2. Store the image in the Remotion project's `public/` directory.
+3. Render it with `CanvasImage` and `staticFile()`.
+4. Add labels or markers as ordinary Remotion elements if they remain fixed.
+
+```tsx
+import React from 'react';
+import {AbsoluteFill, CanvasImage, staticFile} from 'remotion';
+
+export const StaticMap: React.FC = () => {
+ return (
+ <>
+ ` and include proper lighting.
+`` MUST have a `width` and `height` prop.
+
+```tsx
+import { ThreeCanvas } from "@remotion/three";
+import { useVideoConfig } from "remotion";
+
+const { width, height } = useVideoConfig();
+
+
+
+
+ ;
+```
+
+## No animations not driven by `useCurrentFrame()`
+
+Shaders, models etc MUST NOT animate by themselves.
+No animations are allowed unless they are driven by `useCurrentFrame()`.
+Otherwise, it will cause flickering during rendering.
+
+Using `useFrame()` from `@react-three/fiber` is forbidden.
+
+## Animate using `useCurrentFrame()`
+
+Use `useCurrentFrame()` to perform animations.
+
+```tsx
+const frame = useCurrentFrame();
+const rotationY = frame * 0.02;
+
+
+ ;
+```
+
+## Using `` inside ``
+
+The `layout` prop of any `` inside a `` must be set to `none`.
+
+```tsx
+import { Sequence } from "remotion";
+import { ThreeCanvas } from "@remotion/three";
+
+const { width, height } = useVideoConfig();
+
+
+
+
+
+
+ ;
+```
diff --git a/remotion-best-practices/remotion-markup/REFERENCE.md b/remotion-best-practices/remotion-markup/REFERENCE.md
new file mode 100644
index 0000000..c05f131
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/REFERENCE.md
@@ -0,0 +1,365 @@
+---
+name: remotion-markup
+description: Content, animation and effects best practices
+version: 4.0.526
+---
+
+This is guidance for writing Remotion React Markup.
+If this is not relevant, load [Remotion Best Practices](../SKILL.md) instead.
+
+## Preserve user changes
+
+Users may make edits in the code outside of the conversation.
+
+If you detect a surprising change made in the meanwhile, don't overwrite it, assume it was intentional or ask for confirmation.
+
+## General rules
+
+Drive animations using `useCurrentFrame()` and `interpolate()`.
+CSS `transition` or `animation` will not render correctly, they need to refactored.
+Tailwind animation class will not render correctly, they need to be refactored.
+
+Use `Easing.bezier()` and `Easing.spring()` to customize timing.
+
+Structure your markup according to [Remotion Interactivity Best Practices](../remotion-interactivity/REFERENCE.md)
+
+```tsx
+import { useCurrentFrame, Easing, interpolate, Interactive } from "remotion";
+
+export const FadeIn = () => {
+ const frame = useCurrentFrame();
+
+ return (
+
+ Hello World!
+
+ );
+};
+```
+
+Keep the `interpolate()` call inline in the `style` prop.
+Use `scale`, `translate`, `rotate` CSS properties over `transform`.
+
+```tsx
+// 👍 Inline editable keyframes and transform shorthands
+style={{
+ scale: interpolate(frame, [0, 100], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.spring({damping: 200}),
+ output: 'perceptual-scale' // For `scale` animations, use "output: 'perceptual-scale'"
+ }),
+ translate: interpolate(frame, [0, 100], ["0px 0px", "100px 100px"], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.spring({damping: 200}),
+ }),
+ rotate: interpolate(frame, [0, 100], ["20deg", "90deg"], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.spring({damping: 200}),
+ }),
+}}
+
+// 👎 Non-inline values and transform strings become harder to edit in Studio
+const scale = interpolate(frame, [0, 100], [0, 1]);
+
+style={{
+ transform: `scale(${scale})`,
+}}
+```
+
+## Assets
+
+Place assets in the `public/` folder at your project root.
+Use `staticFile()` to reference files from the `public/` folder.
+
+## Media components
+
+Add video and audio using `` and `` from `@remotion/media`.
+Add images using the `` component.
+Add animated GIFs, APNG, WebP or AVIF images using ``, use `@remotion/gif` if not using Chrome.
+Use `staticFile()` for files in `public/` or pass a remote URL directly:
+
+```tsx
+import { Audio, Video } from "@remotion/media";
+import { staticFile, CanvasImage, AnimatedImage } from "remotion";
+
+export const MyComposition = () => {
+ return (
+ <>
+
+
+ Title
+
+
+ Subtitle
+
+
+ );
+}
+```
+
+## Delaying, trimming
+
+Most components (``, `` ``, ``, ``, ``, `` from `remotion`, `` and `` from `@remotion/media`, ``, and more) support the following props:
+
+### from
+
+```tsx
+` from `remotion`, which has them.
+
+- `layout="absolute-fill"` makes the Sequence behave like AbsoluteFill
+- `layout="none"` is "headless" mode, no wrapper element is used.
+
+## Maps
+
+See [Remotion Maps](./remotion-maps/REFERENCE.md) if wanting to include maps in the video.
+
+## Text highlights and annotations
+
+See [text-highlights.md](text-highlights.md) for text highlights (highlight markers), circles, underlines, strike-throughs, crossed-off text, boxes.
+
+## Multi-scene videos
+
+See [multi-scene-video.md](multi-scene-video.md) if planning to make a video with multiple subsequent scenes.
+
+## Voiceover
+
+See [voiceover.md](voiceover.md) for adding an AI-generated voiceover to Remotion compositions using ElevenLabs TTS.
+
+## Embedding Videos
+
+See [embedding-videos.md](embedding-videos.md) for advanced knowledge about embedding videos - trimming, volume, speed, looping, pitch.
+
+## Embedding Audio
+
+See [audio.md](audio.md) for advanced audio features like trimming, volume, speed, pitch.
+
+## Video editing
+
+See [video-editing.md](video-editing.md) for structuring editable video timelines in Remotion Studio.
+
+## Cropping
+
+See [cropping.md](cropping.md) if needing to crop the visible rectangle of a component.
+
+## Transitions
+
+See [transitions.md](transitions.md) for scene transition patterns.
+
+## Visual and pixel effects
+
+When creating a visual effect, consider whether it is feasible using CSS and HTML, or whether a shader is needed.
+Order or preference:
+
+1. Regular HTML + CSS or other web techniques
+2. An effect applied to the element directly (``, ``](html-in-canvas.md), which also accepts `effects`:
+
+- A listed effect via [effects.md](effects.md)
+- A custom `createEffect()` via [effects.md](effects.md) when no preset is available.
+
+## 3D content
+
+See [./3d.md](./3d.md) for 3D content in Remotion using Three.js and React Three Fiber.
+
+## Sound effects
+
+When needing to use sound effects, load the [./sfx.md](./sfx.md) file for more information.
+
+## Audio visualization
+
+When needing to visualize audio (spectrum bars, waveforms, bass-reactive effects), load the [./audio-visualization.md](./audio-visualization.md) file for more information.
+
+## Maps
+
+For static maps, animated routes and markers, geographic explainers, Mapbox, MapLibre, MapTiler, GeoJSON, or 3D geographic flyovers, load [Remotion Maps](./remotion-maps/REFERENCE.md).
+
+## Captions
+
+When dealing with captions or subtitles, load the [Remotion Captions](../remotion-captions/REFERENCE.md) skill for more information.
+
+## Google Fonts
+
+Is the recommended way to load fonts in Remotion. See [google-fonts.md](google-fonts.md) for how to load Google Fonts.
+
+## Local fonts
+
+See [local-fonts.md](local-fonts.md) for how to load local fonts.
+
+## GIFs
+
+See [gifs.md](gifs.md) for how to display GIFs synchronized with Remotion's timeline.
+
+## Advanced Images
+
+See [images.md](images.md) for sizing and positioning images, dynamic image paths, and getting image dimensions.
+
+## Lottie animations
+
+See [lottie.md](lottie.md) for embedding Lottie animations in Remotion.
+
+## Timing
+
+See [timing.md](timing.md) for more timing techniques for `interpolate()`.
+
+## Parameterized videos
+
+See [parameters.md](parameters.md) for making a composition parametrizable by adding a Zod schema.
+
+## Measuring DOM nodes
+
+See [measuring-dom-nodes.md](measuring-dom-nodes.md) for measuring DOM element dimensions in Remotion.
+
+## Measuring text
+
+See [measuring-text.md](measuring-text.md) for measuring text dimensions, fitting text to containers, and checking overflow.
+
+## Using FFmpeg
+
+For some video operations, such as trimming videos or detecting silence, FFmpeg should be used. Load the [./ffmpeg.md](./ffmpeg.md) file for more information.
+
+## Silence detection
+
+When needing to detect and trim silent segments from video or audio files, load the [./silence-detection.md](./silence-detection.md) file.
+
+## Dynamic duration, dimensions and data
+
+See [calculate-metadata.md](calculate-metadata.md) for dynamically set composition duration, dimensions, and props.
+
+## Advanced compositions
+
+See [compositions.md](compositions.md) for how to define stills, folders, default props and for how to nest compositions.
+
+## Advanced sequencing
+
+See [sequencing.md](sequencing.md) for more sequencing patterns - delay, trim, limit duration of items.
+
+## Install modules
+
+Use `npx remotion add` to add new packages with the right version:
+
+```
+npx remotion add @remotion/media
+```
+
+This goes for `@remotion/*` packages, `mediabunny`, `@mediabunny/*`, `zod`, and `@huggingface/transformers`.
+
+## Previewing markup
+
+```
+npx remotion studio --no-open
+```
+
+This will start a long-running process and print the server URL for the preview.
+If server is already started, it will print the URL.
+You can visit a specific composition by navigating to `/[composition-id]`, for example `http://localhost:3000/MapAnimation`.
+
+## Optional: one-frame render check
+
+You can render a single frame with the CLI to sanity-check layout, colors, or timing.
+Skip it for trivial edits, pure refactors, or when you already have enough confidence from Studio or prior renders.
+
+```bash
+npx remotion still [composition-id] --scale=0.25 --frame=30
+```
+
+At 30 fps, `--frame=30` is the one-second mark (`--frame` is zero-based).
diff --git a/remotion-best-practices/remotion-markup/agents/openai.yaml b/remotion-best-practices/remotion-markup/agents/openai.yaml
new file mode 100644
index 0000000..3174fbd
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+ display_name: '/remotion-markup'
+ short_description: 'Apply Remotion animation and effects practices'
+ icon_small: './assets/remotion-icon.svg'
+ icon_large: './assets/remotion-icon.svg'
+ brand_color: '#0B84F3'
+ default_prompt: '$remotion-markup: Apply best Remotion Practices to MyComp.tsx.'
diff --git a/remotion-best-practices/remotion-markup/assets/remotion-icon.svg b/remotion-best-practices/remotion-markup/assets/remotion-icon.svg
new file mode 100644
index 0000000..420dbc7
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/assets/remotion-icon.svg
@@ -0,0 +1,4 @@
+
+Remotion
+
diff --git a/remotion-best-practices/remotion-markup/audio-visualization.md b/remotion-best-practices/remotion-markup/audio-visualization.md
new file mode 100644
index 0000000..733b0d3
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/audio-visualization.md
@@ -0,0 +1,198 @@
+---
+name: audio-visualization
+description: Audio visualization patterns - spectrum bars, waveforms, bass-reactive effects
+metadata:
+ tags: audio, visualization, spectrum, waveform, bass, music, audiogram, frequency
+---
+
+# Audio Visualization in Remotion
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/media-utils
+```
+
+## Loading Audio Data
+
+Use `useWindowedAudioData()` (https://www.remotion.dev/docs/use-windowed-audio-data) to load audio data:
+
+```tsx
+import { useWindowedAudioData } from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+ src: staticFile("podcast.wav"),
+ frame,
+ fps,
+ windowInSeconds: 30,
+});
+```
+
+## Spectrum Bar Visualization
+
+Use `visualizeAudio()` (https://www.remotion.dev/docs/visualize-audio) to get frequency data for bar charts:
+
+```tsx
+import { useWindowedAudioData, visualizeAudio } from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+ src: staticFile("music.mp3"),
+ frame,
+ fps,
+ windowInSeconds: 30,
+});
+
+if (!audioData) {
+ return null;
+}
+
+const frequencies = visualizeAudio({
+ fps,
+ frame,
+ audioData,
+ numberOfSamples: 256,
+ optimizeFor: "speed",
+ dataOffsetInSeconds,
+});
+
+return (
+
+ {frequencies.map((v, i) => (
+
+ ))}
+
` with offsets.
+
+## Waveform Visualization
+
+Use `visualizeAudioWaveform()` (https://www.remotion.dev/docs/media-utils/visualize-audio-waveform) with `createSmoothSvgPath()` (https://www.remotion.dev/docs/media-utils/create-smooth-svg-path) for oscilloscope-style displays:
+
+```tsx
+import {
+ createSmoothSvgPath,
+ useWindowedAudioData,
+ visualizeAudioWaveform,
+} from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { width, fps } = useVideoConfig();
+const HEIGHT = 200;
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+ src: staticFile("voice.wav"),
+ frame,
+ fps,
+ windowInSeconds: 30,
+});
+
+if (!audioData) {
+ return null;
+}
+
+const waveform = visualizeAudioWaveform({
+ fps,
+ frame,
+ audioData,
+ numberOfSamples: 256,
+ windowInSeconds: 0.5,
+ dataOffsetInSeconds,
+});
+
+const path = createSmoothSvgPath({
+ points: waveform.map((y, i) => ({
+ x: (i / (waveform.length - 1)) * width,
+ y: HEIGHT / 2 + (y * HEIGHT) / 2,
+ })),
+});
+
+return (
+
+
+);
+```
+
+## Bass-Reactive Effects
+
+Extract low frequencies for beat-reactive animations:
+
+```tsx
+const frequencies = visualizeAudio({
+ fps,
+ frame,
+ audioData,
+ numberOfSamples: 128,
+ optimizeFor: "speed",
+ dataOffsetInSeconds,
+});
+
+const lowFrequencies = frequencies.slice(0, 32);
+const bassIntensity =
+ lowFrequencies.reduce((sum, v) => sum + v, 0) / lowFrequencies.length;
+
+const scale = 1 + bassIntensity * 0.5;
+const opacity = Math.min(0.6, bassIntensity * 0.8);
+```
+
+## Volume-Based Waveform
+
+Use `getWaveformPortion()` (https://www.remotion.dev/docs/get-waveform-portion) when you need simplified volume data instead of frequency spectrum:
+
+```tsx
+import { getWaveformPortion } from "@remotion/media-utils";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+const currentTimeInSeconds = frame / fps;
+
+const waveform = getWaveformPortion({
+ audioData,
+ startTimeInSeconds: currentTimeInSeconds,
+ durationInSeconds: 5,
+ numberOfSamples: 50,
+});
+
+// Returns array of { index, amplitude } objects (amplitude: 0-1)
+waveform.map((bar) => (
+
+));
+```
+
+## Postprocessing
+
+Low frequencies naturally dominate. Apply logarithmic scaling for visual balance:
+
+```tsx
+const minDb = -100;
+const maxDb = -30;
+
+const scaled = frequencies.map((value) => {
+ const db = 20 * Math.log10(value);
+ return (db - minDb) / (maxDb - minDb);
+});
+```
diff --git a/remotion-best-practices/remotion-markup/audio.md b/remotion-best-practices/remotion-markup/audio.md
new file mode 100644
index 0000000..ad917a4
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/audio.md
@@ -0,0 +1,171 @@
+---
+name: audio
+description: Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
+metadata:
+ tags: audio, media, trim, volume, speed, loop, pitch, mute, sound, sfx
+---
+
+# Using audio in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/media
+```
+
+## Importing Audio
+
+Use `` from `@remotion/media` to add audio to your composition.
+
+```tsx
+import { Audio } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+ return ` components.
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the audio. Values are in frames.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+ ` to delay when it starts:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Audio } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+
+
+);
+```
+
+The audio will start playing after 1 second.
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+
+ interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+ }
+ />
+);
+```
+
+The value of `f` starts at 0 when the audio begins to play, not the composition frame.
+
+## Muting
+
+Use `muted` to silence the audio. It can be set dynamically:
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ = 2 * fps && frame <= 4 * fps} // Mute between 2s and 4s
+ />
+);
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+// 2x speed
+ interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+` to dynamically set duration, dimensions, and transform props before rendering.
+Use it when metadata depends on input props, fetched data, or asset metadata.
+For static dimensions, duration, FPS, and initial props, inline the values on `` instead.
+
+```tsx
+ = async ({
+ props,
+}) => {
+ const durationInSeconds = await getVideoDuration(props.videoSrc);
+
+ return {
+ durationInFrames: Math.ceil(durationInSeconds * 30),
+ };
+};
+```
+
+## Matching dimensions of a video
+
+Use the [`getVideoDimensions`](../remotion-multimedia/get-video-dimensions.md) skill to get the video dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+import { getVideoDimensions } from "./get-video-dimensions";
+
+const calculateMetadata: CalculateMetadataFunction = async ({
+ props,
+}) => {
+ const dimensions = await getVideoDimensions(props.videoSrc);
+
+ return {
+ width: dimensions.width,
+ height: dimensions.height,
+ };
+};
+```
+
+## Setting duration based on multiple videos
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction = async ({
+ props,
+}) => {
+ const metadataPromises = props.videos.map((video) =>
+ getVideoDuration(video.src),
+ );
+ const allMetadata = await Promise.all(metadataPromises);
+
+ const totalDuration = allMetadata.reduce(
+ (sum, durationInSeconds) => sum + durationInSeconds,
+ 0,
+ );
+
+ return {
+ durationInFrames: Math.ceil(totalDuration * 30),
+ };
+};
+```
+
+## Setting a default outName
+
+Set the default output filename based on props:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction = async ({
+ props,
+}) => {
+ return {
+ defaultOutName: `video-${props.id}`, // .mp4 is added automatically
+ };
+};
+```
+
+## Transforming props
+
+Fetch data or transform props before rendering:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction = async ({
+ props,
+ abortSignal,
+}) => {
+ const response = await fetch(props.dataUrl, { signal: abortSignal });
+ const data = await response.json();
+
+ return {
+ props: {
+ ...props,
+ fetchedData: data,
+ },
+ };
+};
+```
+
+The `abortSignal` cancels stale requests when props change in the Studio.
+
+## Return value
+
+All fields are optional. Returned values override the `` props:
+
+- `durationInFrames`: Number of frames
+- `width`: Composition width in pixels
+- `height`: Composition height in pixels
+- `fps`: Frames per second
+- `props`: Transformed props passed to the component
+- `defaultOutName`: Default output filename
+- `defaultCodec`: Default codec for rendering
diff --git a/remotion-best-practices/remotion-markup/compositions.md b/remotion-best-practices/remotion-markup/compositions.md
new file mode 100644
index 0000000..0d1a4ba
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/compositions.md
@@ -0,0 +1,117 @@
+---
+name: compositions
+description: Defining compositions, stills, folders, default props and dynamic metadata
+metadata:
+ tags: composition, still, folder, props, metadata
+---
+
+A `` defines the component, width, height, fps and duration of a renderable video.
+
+## Default Props and scaffold metadata
+
+Pass `defaultProps` to provide initial values for your component.
+Values must be JSON-serializable (`Date`, `Map`, `Set`, and `staticFile()` are supported).
+Use `defaultProps` for composition-wide values that should be visible and editable before the video renders.
+
+For Studio editing, keep `defaultProps` as an inline object literal on `` or ``.
+Do not store it in a variable, import it, spread it, create it with a helper, or wrap it in `satisfies`.
+When scaffolding, keep the component and `` registration in the same file so `width`, `height`, `fps`, `durationInFrames`, and `defaultProps` are visible next to the code that uses them.
+Use `type` declarations for props rather than `interface` to ensure `defaultProps` type safety.
+
+```tsx
+type Props = {
+ readonly title: string;
+};
+
+export const MyComposition = ({ title }: Props) => (
+
+ {title}
+
+);
+
+const defaultProps = { title: "Hello World" };
+
+// 👍 Inline metadata and defaults
+` to organize compositions in the sidebar.
+Folder names can only contain letters, numbers, and hyphens.
+
+```tsx
+import { Composition, Folder } from "remotion";
+
+export const RemotionRoot = () => {
+ return (
+ <>
+
+
+
+
+
+
+
+ );
+};
+```
+
+## Stills
+
+Use `` for single-frame images. It does not require `durationInFrames` or `fps`.
+
+```tsx
+import { Still } from "remotion";
+import { Thumbnail } from "./Thumbnail";
+
+export const RemotionRoot = () => {
+ return (
+ ` component with a `width` and `height` prop to specify the size of the composition.
+
+```tsx
+
+
+
+
+```
diff --git a/remotion-best-practices/remotion-markup/cropping.md b/remotion-best-practices/remotion-markup/cropping.md
new file mode 100644
index 0000000..d445a0a
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/cropping.md
@@ -0,0 +1,34 @@
+# Cropping
+
+Preferably, the `cropLeft`, `cropRight`, `cropTop` and `cropBottom` props are used to crop content.
+It allows for interactively dragging the components and adapting the outlines in the canvas to the crop.
+
+The following components support `crop*` props:
+
+- `` from `remotion`, when `layout="absolute-fill"`
+- `` from `remotion`
+- `` from `remotion`
+- `` from `remotion`
+- `` from `remotion`
+- `` from `@remotion/media`
+- `` from `@remotion/gif`
+- `` from `@remotion/rive`
+
+Crop values are ratios between `0` and `1`.
+A value of `0` applies no crop on that edge.
+A value of `1` is a full crop.
+Keep [Interactivity Best Practices](../remotion-interactivity/REFERENCE.md) also for cropping, to keep it editable and keyframable.
+
+```tsx
+` from `@remotion/media`, ``, ``, and ``.
+
+```tsx
+import {Video} from '@remotion/media';
+import {blur} from '@remotion/effects/blur';
+
+`; `uvTranslate()` and `xyTranslate()` use `@remotion/effects/translate`.
+
+These effects use WebGL2. During renders, enable WebGL with:
+
+```ts
+import {Config} from '@remotion/cli/config';
+
+Config.setChromiumOpenGlRenderer('angle');
+```
+
+## Available effects
+
+`brightness()`, `contrast()`, `colorKey()`, `duotone()`, `grayscale()`, `hue()`, `invert()`, `saturation()`, `tint()`, `linearGradient()`, `linearGradientTint()`, `thermalVision()`, `blur()`, `linearProgressiveBlur()`, `radialProgressiveBlur()`, `zoomBlur()`, `dropShadow()`, `glow()`, `lightTrail()`, `evolve()`, `venetianBlinds()`, `mirror()`, `scale()`, `uvTranslate()`, `xyTranslate()`, `barrelDistortion()`, `chromaticAberration()`, `fisheye()`, `cornerPin()`, `wave()`, `burlap()`, `emboss()`, `dotGrid()`, `halftone()`, `noise()`, `noiseDisplacement()`, `paper()`, `roughenEdges()`, `pattern()`, `pixelate()`, `pixelDissolve()`, `scanlines()`, `speckle()`, `shine()`, `shrinkwrap()`, `vignette()`, `contourLines()`, `checkerboard()`, `halftoneLinearGradient()`, `gridlines()`, `whiteNoise()`, `tvSignalOff()`, `lines()`, `rings()`, `waves()`, `zigzag()`, `lightLeak()`, `starburst()`.
+
+Example:
+
+```tsx
+import {brightness} from "@remotion/effects";
+
+` when the transformation should be reusable, parameterized, editable in Studio, or stackable with other effects.
+
+For quick project-specific effects, keep the effect next to the composition, for example `src/effects/palette-map.ts`. For library effects intended for `@remotion/effects`, follow the repository's `add-effect` skill instead.
+
+`createEffect()` expects:
+
+- `type`: stable reverse-DNS identifier, for example `com.example.paletteMap`.
+- `label`: Studio label, commonly `paletteMap()`.
+- `documentationLink`: URL or `null`.
+- `backend`: `"2d"`, `"webgl2"` or `"webgpu"`.
+- `calculateKey(params)`: stable string containing every resolved parameter that changes output.
+- `setup(target)`: create reusable backend state, or return `null`.
+- `apply({source, target, width, height, params, state, flipSourceY})`: draw the transformed result into `target`.
+- `cleanup(state)`: free resources created by `setup()`.
+- `schema`: an `InteractivitySchema` for Studio controls. `disabled` is added automatically.
+- `validateParams(params)`: throw on missing or invalid values.
+
+Use `backend: "2d"` for simple pixel, filter, drawImage, or image-data effects. Use WebGL2 only when shader math or GPU performance is needed; during renders, enable WebGL as shown above.
+
+```ts
+import {createEffect, type InteractivitySchema} from 'remotion';
+
+type MyEffectParams = {
+ readonly amount?: number;
+};
+
+const myEffectSchema = {
+ amount: {
+ type: 'number',
+ min: 0,
+ max: 1,
+ step: 0.01,
+ default: 1,
+ description: 'Amount',
+ },
+} as const satisfies InteractivitySchema;
+
+const resolve = (params: MyEffectParams) => ({
+ amount: params.amount ?? 1,
+});
+
+export const myEffect = createEffect({
+ type: 'com.example.myEffect',
+ label: 'myEffect()',
+ documentationLink: null,
+ backend: '2d',
+ calculateKey: (params) => {
+ const {amount} = resolve(params);
+ return `my-effect-${amount}`;
+ },
+ setup: () => null,
+ apply: ({source, target, width, height, params}) => {
+ const ctx = target.getContext('2d');
+ if (!ctx) {
+ throw new Error('Could not get a 2D context for myEffect().');
+ }
+
+ const {amount} = resolve(params);
+
+ ctx.clearRect(0, 0, width, height);
+ ctx.filter = `opacity(${amount * 100}%)`;
+ ctx.drawImage(source, 0, 0, width, height);
+ ctx.filter = 'none';
+ },
+ cleanup: () => undefined,
+ schema: myEffectSchema,
+ validateParams: ({amount = 1}) => {
+ if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0 || amount > 1) {
+ throw new TypeError('amount must be a number between 0 and 1');
+ }
+ },
+});
+```
+
+For a WebGL2 effect, compile/link shaders in `setup()`, keep the program, fullscreen quad, texture, and uniform locations in state, upload `source` in `apply()`, and free GPU resources in `cleanup()`. Minimal shape:
+
+```ts
+import {createEffect, type InteractivitySchema} from 'remotion';
+
+type RgbShiftParams = {
+ readonly amount?: number;
+};
+
+type RgbShiftState = {
+ readonly gl: WebGL2RenderingContext;
+ readonly program: WebGLProgram;
+ readonly vao: WebGLVertexArrayObject;
+ readonly vbo: WebGLBuffer;
+ readonly texture: WebGLTexture;
+ readonly uSource: WebGLUniformLocation | null;
+ readonly uOffset: WebGLUniformLocation | null;
+};
+
+const rgbShiftSchema = {
+ amount: {
+ type: 'number',
+ min: 0,
+ max: 80,
+ step: 1,
+ default: 12,
+ description: 'Amount',
+ },
+} as const satisfies InteractivitySchema;
+
+export const rgbShift = createEffect({
+ type: 'com.example.rgbShift',
+ label: 'rgbShift()',
+ documentationLink: null,
+ backend: 'webgl2',
+ calculateKey: ({amount = 12}) => `rgb-shift-${amount}`,
+ setup: (target) => {
+ const gl = target.getContext('webgl2', {
+ premultipliedAlpha: true,
+ alpha: true,
+ preserveDrawingBuffer: true,
+ });
+ if (!gl) {
+ throw new Error('Could not get a WebGL2 context for rgbShift().');
+ }
+
+ gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+
+ // Compile/link shaders, create a fullscreen quad VAO/VBO, create a
+ // CLAMP_TO_EDGE RGBA texture, and get uSource/uOffset uniform locations.
+ return createRgbShiftState(gl);
+ },
+ apply: ({source, width, height, params, state, flipSourceY}) => {
+ const amount = params.amount ?? 12;
+ const {gl} = state;
+
+ gl.viewport(0, 0, width, height);
+ gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, flipSourceY);
+ gl.activeTexture(gl.TEXTURE0);
+ gl.bindTexture(gl.TEXTURE_2D, state.texture);
+ gl.texImage2D(
+ gl.TEXTURE_2D,
+ 0,
+ gl.RGBA,
+ gl.RGBA,
+ gl.UNSIGNED_BYTE,
+ source as TexImageSource,
+ );
+
+ gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+ gl.useProgram(state.program);
+ if (state.uSource) gl.uniform1i(state.uSource, 0);
+ if (state.uOffset) gl.uniform2f(state.uOffset, amount / width, 0);
+ gl.bindVertexArray(state.vao);
+ gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+ },
+ cleanup: ({gl, program, vao, vbo, texture}) => {
+ gl.deleteTexture(texture);
+ gl.deleteBuffer(vbo);
+ gl.deleteProgram(program);
+ gl.deleteVertexArray(vao);
+ },
+ schema: rgbShiftSchema,
+ validateParams: ({amount = 12}) => {
+ if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0 || amount > 80) {
+ throw new TypeError('amount must be a number between 0 and 80');
+ }
+ },
+});
+```
+
+For a complete 2D and WebGL2 pair, see `packages/example/src/EffectsTestbed/sample-posterize-2d.ts` and `packages/example/src/EffectsTestbed/sample-rgb-shift-webgl.ts`.
+
+Use the returned factory in an `effects` array:
+
+```tsx
+import {CanvasImage, staticFile} from 'remotion';
+import {myEffect} from './effects/my-effect';
+
+export const MyComp: React.FC = () => {
+ return (
+ ` from `@remotion/media` to embed videos into your composition.
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+ return ` to delay when it appears:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Video } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+
+
+);
+```
+
+The video will appear after 1 second.
+
+## Sizing and Position
+
+Use the `style` prop to control size and position:
+
+```tsx
+
+ interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+ }
+ />
+);
+```
+
+Use `muted` to silence the video entirely:
+
+```tsx
+ interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+` component. This is non-destructive, requires no re-encoding, and you can change the trim at any time.
+
+```tsx
+import {Video} from '@remotion/media';
+
+` to display a GIF, APNG, AVIF or WebP image synchronized with Remotion's timeline:
+
+```tsx
+import { AnimatedImage, staticFile } from "remotion";
+
+export const MyComposition = () => {
+ return (
+ ` does not work (only supported in Chrome and Firefox), you can use `` from `@remotion/gif` instead.
+
+```bash
+npx remotion add @remotion/gif # If project uses npm
+bunx remotion add @remotion/gif # If project uses bun
+yarn remotion add @remotion/gif # If project uses yarn
+pnpm exec remotion add @remotion/gif # If project uses pnpm
+```
+
+```tsx
+import { Gif } from "@remotion/gif";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+ return ` component has the same props as `` but only supports GIF files.
diff --git a/remotion-best-practices/remotion-markup/google-fonts.md b/remotion-best-practices/remotion-markup/google-fonts.md
new file mode 100644
index 0000000..9fd4d32
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/google-fonts.md
@@ -0,0 +1,76 @@
+---
+name: fonts
+description: Loading Google Fonts and local fonts in Remotion
+metadata:
+ tags: fonts, google-fonts, typography, text
+---
+
+# Using fonts in Remotion
+
+## Google Fonts with @remotion/google-fonts
+
+The recommended way to use Google Fonts. It's type-safe and automatically blocks rendering until the font is ready.
+
+### Prerequisites
+
+First, the @remotion/google-fonts package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/google-fonts # If project uses npm
+bunx remotion add @remotion/google-fonts # If project uses bun
+yarn remotion add @remotion/google-fonts # If project uses yarn
+pnpm exec remotion add @remotion/google-fonts # If project uses pnpm
+```
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Lobster";
+
+const { fontFamily } = loadFont();
+
+export const MyComposition = () => {
+ return (
+
+ Hello World
+
+ );
+};
+```
+
+Preferrably, specify only needed weights and subsets to reduce file size:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Roboto";
+
+const { fontFamily } = loadFont("normal", {
+ weights: ["400", "700"],
+ subsets: ["latin"],
+});
+```
+
+## Using in components
+
+Call `loadFont()` at the top level of your component or in a separate file that's imported early:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Montserrat";
+
+const { fontFamily } = loadFont("normal", {
+ weights: ["400", "700"],
+ subsets: ["latin"],
+});
+
+export const Title: React.FC<{ text: string }> = ({ text }) => {
+ return (
+
+ {text}
+
+ );
+};
+```
diff --git a/remotion-best-practices/remotion-markup/html-in-canvas.md b/remotion-best-practices/remotion-markup/html-in-canvas.md
new file mode 100644
index 0000000..d263801
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/html-in-canvas.md
@@ -0,0 +1,128 @@
+# Using `` in Remotion
+
+Renders children into a `` so you can post-process them with the Canvas 2D API or WebGL.
+
+Only works in Chrome 149+ with the `chrome://flags/#canvas-draw-element` flag enabled.
+Give the user a notice.
+
+## Nesting
+
+Do not nest `` components. Remotion rejects nesting because Chrome does not reliably render nested HTML-in-canvas subtrees.
+
+## Enabling WebGL during renders
+
+If you make use of WebGL during renders, you need to enable it:
+
+From the CLI:
+
+```bash
+npx remotion render --gl=angle
+```
+
+Set it as the default for Studio and CLI (advised):
+
+```ts
+import { Config } from "@remotion/cli/config";
+
+Config.setChromiumOpenGlRenderer("angle");
+```
+
+## Basic usage
+
+By default, draws to canvas with no effect applied:
+
+```tsx
+import { HtmlInCanvas } from "remotion";
+
+export const MyComp = () => {
+ return (
+
+
+ Hello
+
+
+ );
+};
+```
+
+## 2D effect with `onPaint`
+
+`onPaint` runs whenever the content updates. Call `ctx.drawElementImage(elementImage, 0, 0)` to draw the captured DOM, and assign the returned transform to `element.style.transform` so DOM selection still aligns with the painted output.
+
+```tsx
+import {
+ AbsoluteFill,
+ HtmlInCanvas,
+ type HtmlInCanvasOnPaint,
+ useCurrentFrame,
+ useVideoConfig,
+} from "remotion";
+import { useCallback } from "react";
+
+export const Blur = () => {
+ const frame = useCurrentFrame();
+ const { width, height, fps } = useVideoConfig();
+
+ const onPaint: HtmlInCanvasOnPaint = useCallback(
+ ({ canvas, element, elementImage }) => {
+ const ctx = canvas.getContext("2d");
+ if (!ctx) throw new Error("Failed to acquire 2D context");
+
+ const blurPx = 4 + 18 * (0.5 + 0.5 * Math.sin((frame / fps) * Math.PI));
+
+ ctx.reset();
+ ctx.filter = `blur(${blurPx}px)`;
+ const transform = ctx.drawElementImage(elementImage, 0, 0);
+ element.style.transform = transform.toString();
+ },
+ [frame, fps],
+ );
+
+ return (
+
+
+
+ Hello
+
+
+
+ );
+};
+```
+
+## WebGL effects
+
+For WebGL, set up the context, program, and texture in `onInit` and return a cleanup function. Inside `onPaint`, upload the captured DOM with `gl.texElementImage2D(...)` and draw.
+
+```tsx
+const onInit: HtmlInCanvasOnInit = useCallback(({ canvas }) => {
+ const gl = canvas.getContext("webgl2", { alpha: true, premultipliedAlpha: true });
+ if (!gl) {
+ throw new Error(
+ "WebGL2 unavailable. Try rendering with the --gl=angle option. See https://remotion.dev/docs/gl-options.",
+ );
+ }
+ gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+ // compile program, create texture, set up VAO...
+ return () => {
+ // delete program, texture, buffers...
+ };
+}, []);
+
+const onPaint: HtmlInCanvasOnPaint = useCallback(({ elementImage }) => {
+ gl.texElementImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, elementImage);
+ gl.drawArrays(gl.TRIANGLES, 0, 6);
+}, []);
+```
+
+For a fully working minimal example, see https://github.com/remotion-dev/remotion/blob/main/packages/docs/components/demos/HtmlInCanvasDocsDemoWebGL.tsx.
+
+## Async `onPaint`
+
+`onPaint` may be `async`. Remotion holds the frame open via `delayRender()` until the promise resolves. Useful for multi-pass effects with `createImageBitmap`.
diff --git a/remotion-best-practices/remotion-markup/images.md b/remotion-best-practices/remotion-markup/images.md
new file mode 100644
index 0000000..b86985f
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/images.md
@@ -0,0 +1,73 @@
+## Sizing and positioning
+
+Use the `style` prop to control size and position:
+
+```tsx
+`. Animate `progress` from `0` to `1`; the light leak reveals during the first half and retracts during the second half.
+
+Typically use it inside a `` to play over the cut point between two scenes. See the **transitions** rule for `` and overlay usage.
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/effects
+```
+
+## Light leak overlay component
+
+Keep the `progress` calculation inline so it is editable in Remotion Studio:
+
+```tsx
+import {lightLeak} from '@remotion/effects/light-leak';
+import {interpolate, Solid, useCurrentFrame, useVideoConfig} from 'remotion';
+
+const LightLeakOverlay: React.FC<{
+ seed?: number;
+ hueShift?: number;
+}> = ({seed = 0, hueShift = 0}) => {
+ const frame = useCurrentFrame();
+ const {durationInFrames, height, width} = useVideoConfig();
+
+ return (
+
+
+
+
+
+
+
+ ;
+```
+
+## Options
+
+- `progress?` — controls the evolve/retract phase from `0` to `1`. Effects do not animate on their own, so drive it with `useCurrentFrame()` and `interpolate()`. Default: `0.5`.
+- `seed?` — determines the shape of the light leak pattern. Different seeds produce different patterns. Default: `0`.
+- `hueShift?` — rotates the hue in degrees (`0`–`360`). Default: `0` (yellow-to-orange). `120` = green, `240` = blue.
+- `disabled?` — skips the effect when `true`. Default: `false`.
+
+## Customizing the look
+
+```tsx
+// Blue-tinted light leak with a different pattern
+` as a decorative layer in any composition:
+
+```tsx
+import {AbsoluteFill} from 'remotion';
+
+const MyComp: React.FC = () => (
+
+
+);
+```
+
+`lightLeak()` uses WebGL2. Enable WebGL during rendering with `Config.setChromiumOpenGlRenderer("angle")`.
diff --git a/remotion-best-practices/remotion-markup/local-fonts.md b/remotion-best-practices/remotion-markup/local-fonts.md
new file mode 100644
index 0000000..94ab7e5
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/local-fonts.md
@@ -0,0 +1,69 @@
+For local font files, use the `@remotion/fonts` package.
+
+### Prerequisites
+
+First, install @remotion/fonts:
+
+```bash
+npx remotion add @remotion/fonts # If project uses npm
+bunx remotion add @remotion/fonts # If project uses bun
+yarn remotion add @remotion/fonts # If project uses yarn
+pnpm exec remotion add @remotion/fonts # If project uses pnpm
+```
+
+### Loading a local font
+
+Place your font file in the `public/` folder and use `loadFont()`:
+
+```tsx
+import { loadFont } from "@remotion/fonts";
+import { staticFile } from "remotion";
+
+await loadFont({
+ family: "MyFont",
+ url: staticFile("MyFont-Regular.woff2"),
+});
+
+export const MyComposition = () => {
+ return (
+
+ Hello World
+
+ );
+};
+```
+
+### Loading multiple weights
+
+Load each weight separately with the same family name:
+
+```tsx
+import { loadFont } from "@remotion/fonts";
+import { staticFile } from "remotion";
+
+await Promise.all([
+ loadFont({
+ family: "Inter",
+ url: staticFile("Inter-Regular.woff2"),
+ weight: "400",
+ }),
+ loadFont({
+ family: "Inter",
+ url: staticFile("Inter-Bold.woff2"),
+ weight: "700",
+ }),
+]);
+```
+
+### Available options
+
+```tsx
+loadFont({
+ family: "MyFont", // Required: name to use in CSS
+ url: staticFile("font.woff2"), // Required: font file URL
+ format: "woff2", // Optional: auto-detected from extension
+ weight: "400", // Optional: font weight
+ style: "normal", // Optional: normal or italic
+ display: "block", // Optional: font-display behavior
+});
+```
diff --git a/remotion-best-practices/remotion-markup/lottie.md b/remotion-best-practices/remotion-markup/lottie.md
new file mode 100644
index 0000000..f146cfe
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/lottie.md
@@ -0,0 +1,73 @@
+---
+name: lottie
+description: Embedding Lottie animations in Remotion.
+metadata:
+ category: Animation
+---
+
+# Using Lottie Animations in Remotion
+
+## Prerequisites
+
+First, the @remotion/lottie package needs to be installed.
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/lottie # If project uses npm
+bunx remotion add @remotion/lottie # If project uses bun
+yarn remotion add @remotion/lottie # If project uses yarn
+pnpm exec remotion add @remotion/lottie # If project uses pnpm
+```
+
+## Displaying a Lottie file
+
+To import a Lottie animation:
+
+- Fetch the Lottie asset
+- Wrap the loading process in `delayRender()` and `continueRender()`
+- Save the animation data in a state
+- Render the Lottie animation using the `Lottie` component from the `@remotion/lottie` package
+
+```tsx
+import { Lottie, LottieAnimationData } from "@remotion/lottie";
+import { useEffect, useState } from "react";
+import { cancelRender, continueRender, delayRender } from "remotion";
+
+export const MyAnimation = () => {
+ const [handle] = useState(() => delayRender("Loading Lottie animation"));
+
+ const [animationData, setAnimationData] =
+ useState(null);
+
+ useEffect(() => {
+ fetch("https://assets4.lottiefiles.com/packages/lf20_zyquagfl.json")
+ .then((data) => data.json())
+ .then((json) => {
+ setAnimationData(json);
+ continueRender(handle);
+ })
+ .catch((err) => {
+ cancelRender(err);
+ });
+ }, [handle]);
+
+ if (!animationData) {
+ return null;
+ }
+
+ return (null);
+ const scale = useCurrentScale();
+ const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+
+ useEffect(() => {
+ if (!ref.current) return;
+ const rect = ref.current.getBoundingClientRect();
+ setDimensions({
+ width: rect.width / scale,
+ height: rect.height / scale,
+ });
+ }, [scale]);
+
+ return (
+
+ Content to measure
+
+ );
+};
+```
diff --git a/remotion-best-practices/remotion-markup/measuring-text.md b/remotion-best-practices/remotion-markup/measuring-text.md
new file mode 100644
index 0000000..8faca93
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/measuring-text.md
@@ -0,0 +1,146 @@
+---
+name: measuring-text
+description: Measuring text dimensions, fitting text to containers, and checking overflow
+metadata:
+ tags: measure, text, layout, dimensions, fitText, fillTextBox
+---
+
+# Measuring text in Remotion
+
+## Prerequisites
+
+Install @remotion/layout-utils if it is not already installed:
+
+```bash
+npx remotion add @remotion/layout-utils
+```
+
+## Measuring text dimensions
+
+Use `measureText()` to calculate the width and height of text:
+
+```tsx
+import { measureText } from "@remotion/layout-utils";
+
+const { width, height } = measureText({
+ text: "Hello World",
+ fontFamily: "Arial",
+ fontSize: 32,
+ fontWeight: "bold",
+});
+```
+
+Results are cached - duplicate calls return the cached result.
+
+## Fitting text to a width
+
+Use `fitText()` to find the optimal font size for a container:
+
+```tsx
+import { fitText } from "@remotion/layout-utils";
+
+const { fontSize } = fitText({
+ text: "Hello World",
+ withinWidth: 600,
+ fontFamily: "Inter",
+ fontWeight: "bold",
+});
+
+return (
+
+ Hello World
+
+);
+```
+
+## Checking text overflow
+
+Use `fillTextBox()` to check if text exceeds a box:
+
+```tsx
+import { fillTextBox } from "@remotion/layout-utils";
+
+const box = fillTextBox({ maxBoxWidth: 400, maxLines: 3 });
+
+const words = ["Hello", "World", "This", "is", "a", "test"];
+for (const word of words) {
+ const { exceedsBox } = box.add({
+ text: word + " ",
+ fontFamily: "Arial",
+ fontSize: 24,
+ });
+ if (exceedsBox) {
+ // Text would overflow, handle accordingly
+ break;
+ }
+}
+```
+
+## Best practices
+
+**Load fonts first:** Only call measurement functions after fonts are loaded.
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Inter";
+
+const { fontFamily, waitUntilDone } = loadFont("normal", {
+ weights: ["400"],
+ subsets: ["latin"],
+});
+
+waitUntilDone().then(() => {
+ // Now safe to measure
+ const { width } = measureText({
+ text: "Hello",
+ fontFamily,
+ fontSize: 32,
+ });
+});
+```
+
+**Use validateFontIsLoaded:** Catch font loading issues early:
+
+```tsx
+measureText({
+ text: "Hello",
+ fontFamily: "MyCustomFont",
+ fontSize: 32,
+ validateFontIsLoaded: true, // Throws if font not loaded
+});
+```
+
+**Match font properties:** Use the same properties for measurement and rendering:
+
+```tsx
+const fontStyle = {
+ fontFamily: "Inter",
+ fontSize: 32,
+ fontWeight: "bold" as const,
+ letterSpacing: "0.5px",
+};
+
+const { width } = measureText({
+ text: "Hello",
+ ...fontStyle,
+});
+
+return (
+
+ Hello
+
+);
+```
+
+**Avoid padding and border:** Use `outline` instead of `border` to prevent layout differences:
+
+```tsx
+
+ Text
+
+```
diff --git a/remotion-best-practices/remotion-markup/multi-scene-video.md b/remotion-best-practices/remotion-markup/multi-scene-video.md
new file mode 100644
index 0000000..bdfcb5d
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/multi-scene-video.md
@@ -0,0 +1,81 @@
+If the video being created is a multi-scene video, it should be structured in a special way.
+Create a new folder and put each scene in a separate file.
+
+```tsx
+// SceneA.tsx
+export const SceneA: React.FC = () => {
+ return // ...
+}
+```
+
+```tsx
+// SceneB.tsx
+export const SceneB: React.FC = () => {
+ return // ...
+}
+```
+
+Install `@remotion/transitions` if not yet available:
+
+```
+npx remotion add @remotion/transitions
+```
+
+// MyVideo.tsx
+```tsx
+import {TransitionSeries} from '@remotion/transitions';
+
+const MyVideo: React.FC = () => {
+ return (
+
+
+
+
+
+
+ )
+}
+```
+
+It could also make sense to register each scene individually in the root file so it can be edited there.
+If a composition with the same component is registered, one can double click the sequence in the main composition and jump to that composition.
+
+```tsx
+export const Root: React.FC = () => {
+ return (
+ <>
+
+
+ > = () => {
+ return (
+
+
+ {props.title}
+
+
+ );
+};
+```
+
+In the root file, the schema can be passed to the composition:
+
+```tsx title="src/Root.tsx"
+import { Composition } from "remotion";
+import { MycComponent, MyCompositionSchema } from "./MyComposition";
+
+export const RemotionRoot = () => {
+ return (
+
+Remotion
+
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/TECHNIQUE.md b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/TECHNIQUE.md
new file mode 100644
index 0000000..b58e4a4
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/TECHNIQUE.md
@@ -0,0 +1,89 @@
+# CesiumJS — 3D flyovers in Remotion
+
+Instructions for achieving map animations with "flight-simulator" perspective in Remotion.
+
+## Modes
+
+| Mode | Data | Use for |
+| ----------- | ----------------------------------------------------- | ------------------------------------------------------ |
+| `landscape` | MapTiler `terrain-quantized-mesh-v2` + `satellite-v2` | Mountains, gorges, rivers, coastlines and rural routes |
+| `city` | Google Photorealistic 3D Tiles | Cities, architecture and recognizable landmarks |
+
+Do not use footprint extrusions for city flyovers. They produce crude building blocks rather than
+textured architecture.
+
+## Credentials
+
+For `landscape`, set:
+
+```text
+REMOTION_MAPTILER_KEY=...
+```
+
+Create a MapTiler key at https://cloud.maptiler.com/account/keys/.
+
+For `city`, set:
+
+```text
+REMOTION_GOOGLE_MAPS_API_KEY=...
+```
+
+Create a billing-enabled Google Map Tiles API key by following
+https://developers.google.com/maps/documentation/tile/get-api-key. Enable the **Map Tiles API** and
+restrict the key to that API. Ensure its application restriction permits local headless Remotion
+requests.
+
+## Build the flight
+
+1. Copy `assets/CesiumFlythrough.tsx`, a path JSON and `assets/example-Root.tsx` into the Remotion
+ project, or import the component directly.
+2. Supply the camera route as `[longitude, latitude][]`. Use only meaningful control points; do not hand-author dozens of tiny corrections.
+3. Leave `pathSmoothingPasses={3}` initially. The component applies repeated Chaikin corner cutting, turning straight-then-corner input into a continuous swerve. Increase to `4` for a softer route or reduce to `2` when the camera must follow a tight corridor.
+4. Set absolute camera altitudes for the location. City cameras normally fly lower than landscape
+ cameras.
+5. Render a middle-frame still before rendering the full video.
+
+```tsx
+((resolve, reject) => {
+ if ((window as any).Cesium) return resolve((window as any).Cesium);
+ (window as any).CESIUM_BASE_URL = CDN;
+ const css = document.createElement('link');
+ css.rel = 'stylesheet';
+ css.href = `${CDN}Widgets/widgets.css`;
+ document.head.appendChild(css);
+ const script = document.createElement('script');
+ script.src = `${CDN}Cesium.js`;
+ script.onload = () => resolve((window as any).Cesium);
+ script.onerror = () =>
+ reject(new Error(`Failed to load CesiumJS ${CESIUM_VER}`));
+ document.head.appendChild(script);
+ });
+
+export const CesiumFlythrough: React.FC = ({
+ mode = 'landscape',
+ path = terrainPath as LngLat[],
+ pathSmoothingPasses = 3,
+ altitudeStart = 4600,
+ altitudeEnd = 4300,
+ lookAheadKm = 1.5,
+ travelKm = 13,
+ pitchFromNadir = 76,
+ verticalExaggeration = 1.1,
+ maximumScreenSpaceError = 8,
+}) => {
+ const containerRef = useRef(null);
+ const started = useRef(false);
+ const viewerRef = useRef(null);
+ const tilesetRef = useRef(null);
+ const frame = useCurrentFrame();
+ const {durationInFrames, fps, width, height} = useVideoConfig();
+ const [ready, setReady] = useState(false);
+ const [handle] = useState(() =>
+ delayRender(`cesium init: ${mode}`, {timeoutInMilliseconds: 120000}),
+ );
+ const walker = useMemo(
+ () => makePathWalker(smoothFlightPath(path, pathSmoothingPasses)),
+ [path, pathSmoothingPasses],
+ );
+
+ const setCamera = (C: any, viewer: any, progress: number) => {
+ const maxTravel = Math.max(0, walker.lengthKm - lookAheadKm * 2);
+ const cameraDistance = Math.min(travelKm, maxTravel) * progress;
+ const camera = walker.along(cameraDistance);
+ const aim = walker.along(cameraDistance + lookAheadKm);
+ const aim2 = walker.along(cameraDistance + lookAheadKm * 2);
+ const heading = bearing(camera, aim);
+ let headingDelta = bearing(aim, aim2) - heading;
+ while (headingDelta > Math.PI) headingDelta -= 2 * Math.PI;
+ while (headingDelta < -Math.PI) headingDelta += 2 * Math.PI;
+ viewer.camera.setView({
+ destination: C.Cartesian3.fromDegrees(
+ camera[0],
+ camera[1],
+ lerp(altitudeStart, altitudeEnd, progress),
+ ),
+ orientation: {
+ heading,
+ pitch: C.Math.toRadians(-(90 - pitchFromNadir)),
+ roll: clamp(headingDelta * BANK_GAIN, -MAX_BANK, MAX_BANK),
+ },
+ });
+ };
+
+ const tilesAreLoaded = (viewer: any) => {
+ if (mode === 'landscape') return viewer.scene.globe.tilesLoaded;
+ return Boolean(tilesetRef.current?.tilesLoaded);
+ };
+
+ const settle = (viewer: any) =>
+ new Promise((resolve) => {
+ let stable = 0;
+ let ticks = 0;
+ const tick = () => {
+ viewer.render();
+ ticks++;
+ stable = tilesAreLoaded(viewer) ? stable + 1 : 0;
+ if (stable > 8 || ticks > 600) {
+ viewer.render();
+ resolve();
+ } else {
+ setTimeout(tick, 8);
+ }
+ };
+ tick();
+ });
+
+ useEffect(() => {
+ if (started.current) return;
+ started.current = true;
+ (async () => {
+ if (mode === 'landscape' && !MAPTILER_KEY) {
+ throw new Error(
+ 'Set REMOTION_MAPTILER_KEY. Create a key at https://cloud.maptiler.com/account/keys/',
+ );
+ }
+ if (mode === 'city' && !GOOGLE_MAPS_API_KEY) {
+ throw new Error(
+ 'Set REMOTION_GOOGLE_MAPS_API_KEY. Create a Map Tiles API key at https://developers.google.com/maps/documentation/tile/get-api-key',
+ );
+ }
+ if (mode === 'city' && durationInFrames / fps > 30) {
+ throw new Error(
+ 'Google Photorealistic 3D Tiles compositions must not exceed 30 seconds',
+ );
+ }
+
+ const C = await loadCesium();
+ const viewer = new C.Viewer(containerRef.current, {
+ baseLayer: false,
+ baseLayerPicker: false,
+ geocoder: false,
+ homeButton: false,
+ sceneModePicker: false,
+ navigationHelpButton: false,
+ animation: false,
+ timeline: false,
+ fullscreenButton: false,
+ infoBox: false,
+ selectionIndicator: false,
+ contextOptions: {webgl: {preserveDrawingBuffer: true}},
+ });
+ if (mode === 'landscape') {
+ viewer.imageryLayers.addImageryProvider(
+ new C.UrlTemplateImageryProvider({
+ url: `https://api.maptiler.com/tiles/satellite-v2/{z}/{x}/{y}.jpg?key=${MAPTILER_KEY}`,
+ maximumLevel: 20,
+ }),
+ );
+ viewer.terrainProvider = await C.CesiumTerrainProvider.fromUrl(
+ `https://api.maptiler.com/tiles/terrain-quantized-mesh-v2/?key=${MAPTILER_KEY}`,
+ {requestVertexNormals: true},
+ );
+ viewer.creditDisplay.addStaticCredit(
+ new C.Credit(
+ '© MapTiler ',
+ true,
+ ),
+ );
+ }
+ if (mode === 'city') {
+ viewer.scene.globe.show = false;
+ const tileset = await C.Cesium3DTileset.fromUrl(
+ `https://tile.googleapis.com/v1/3dtiles/root.json?key=${GOOGLE_MAPS_API_KEY}`,
+ {
+ showCreditsOnScreen: true,
+ maximumScreenSpaceError,
+ },
+ );
+ viewer.scene.primitives.add(tileset);
+ tilesetRef.current = tileset;
+ }
+
+ viewer.useDefaultRenderLoop = false;
+ viewer.scene.skyAtmosphere.show = true;
+ viewer.scene.fog.enabled = true;
+ viewer.scene.globe.enableLighting = false;
+ viewer.scene.verticalExaggeration = verticalExaggeration;
+ (window as any).__CESIUM_FLYOVER__ = {C, mode};
+ viewerRef.current = viewer;
+ setCamera(C, viewer, 0);
+ await settle(viewer);
+ setReady(true);
+ continueRender(handle);
+ })().catch((error) => cancelRender(error));
+ }, [durationInFrames, fps, handle, mode]);
+
+ useEffect(() => {
+ if (!ready) return;
+ const frameHandle = delayRender(`cesium ${mode} frame ${frame}`, {
+ timeoutInMilliseconds: 60000,
+ });
+ const C = (window as any).__CESIUM_FLYOVER__.C;
+ const viewer = viewerRef.current;
+ const progress = durationInFrames <= 1 ? 0 : frame / (durationInFrames - 1);
+ setCamera(C, viewer, progress);
+ settle(viewer).then(() => continueRender(frameHandle));
+ }, [ready, frame, durationInFrames, mode]);
+
+ return (
+
+
+ {mode === 'city' ? (
+
+ For promotional purposes only
+
+ ) : null}
+
+ );
+};
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/cesium-path.json b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/cesium-path.json
new file mode 100644
index 0000000..32b60ba
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/cesium-path.json
@@ -0,0 +1,299 @@
+[
+ [94.986139893537, 29.76417312959953],
+ [94.98637054463002, 29.764163024004816],
+ [94.98661427422437, 29.764153025681516],
+ [94.9868698103708, 29.764142908388347],
+ [94.98713600736019, 29.764132461562934],
+ [94.98741179569139, 29.76412145291623],
+ [94.9876962466277, 29.764109663422126],
+ [94.98798853462426, 29.764096898390772],
+ [94.98828790834106, 29.764082995679242],
+ [94.98859364523021, 29.764067827511347],
+ [94.98890509685035, 29.764051279216236],
+ [94.98922167960325, 29.76403324759024],
+ [94.98954294512464, 29.76401367774424],
+ [94.9898685550894, 29.76399255290906],
+ [94.99019820264337, 29.76396985787546],
+ [94.9905316178847, 29.763945606334815],
+ [94.9908685732739, 29.763919866576575],
+ [94.99120886105722, 29.763892700951896],
+ [94.99155229116181, 29.7638641665054],
+ [94.99189872300363, 29.76383429811986],
+ [94.99224811692223, 29.763803085651237],
+ [94.99260053337049, 29.763770509641105],
+ [94.99295601118384, 29.76373658086857],
+ [94.99331456742908, 29.763701322339223],
+ [94.99367598745215, 29.763664830647013],
+ [94.99404000156176, 29.763627219082974],
+ [94.99440635968021, 29.763588592698778],
+ [94.99477481502787, 29.76354905236459],
+ [94.9951451006731, 29.763508748648892],
+ [94.99578766204738, 29.763462125646818],
+ [94.99643710580968, 29.763412119743368],
+ [94.99709296623192, 29.763358988682928],
+ [94.99775479298779, 29.763302979031952],
+ [94.99842214521965, 29.763244327404465],
+ [94.99909470569231, 29.763183258547627],
+ [94.9997722961385, 29.76312010454948],
+ [95.00045474013422, 29.763055184243758],
+ [95.00114189582168, 29.762988795623112],
+ [95.00183368970049, 29.762921207778405],
+ [95.0025300799095, 29.76285270023514],
+ [95.00323103443773, 29.762783549665084],
+ [95.00393658318124, 29.76271400155497],
+ [95.00464681949704, 29.76264432424487],
+ [95.00536183331896, 29.76257477740286],
+ [95.00608171146906, 29.762505612813378],
+ [95.00680653793428, 29.762437075077955],
+ [95.00753639864557, 29.762369398844733],
+ [95.00827137837749, 29.762302811854063],
+ [95.00901153006761, 29.762237519590354],
+ [95.00975680776318, 29.76217368790719],
+ [95.01050716875933, 29.762111478518566],
+ [95.0112626067996, 29.76205102042169],
+ [95.01202312290016, 29.761992432502932],
+ [95.01278871942189, 29.76193583156792],
+ [95.01355940108247, 29.761881333165324],
+ [95.01433525277555, 29.761829093407865],
+ [95.01511636205572, 29.761779224166457],
+ [95.01590278872715, 29.76173180995877],
+ [95.0166868810408, 29.76168612055982],
+ [95.01746871725406, 29.761642332250204],
+ [95.0182483756254, 29.76160062131038],
+ [95.01902596675926, 29.761561177619345],
+ [95.019801682618, 29.761524238306453],
+ [95.02057570378254, 29.76149004865798],
+ [95.02134818878243, 29.761458838563573],
+ [95.02211921065114, 29.761430763930672],
+ [95.02288888930805, 29.761405973069504],
+ [95.02365734467304, 29.761384614290225],
+ [95.02442469666667, 29.761366835902948],
+ [95.02519095257038, 29.761352731197437],
+ [95.02595602043016, 29.761342344990513],
+ [95.02671980829304, 29.761335722099044],
+ [95.02748221022355, 29.76133286485609],
+ [95.02824308111781, 29.761333684556867],
+ [95.02900227020879, 29.761338090875398],
+ [95.02975960629327, 29.76134599002589],
+ [95.03051480114966, 29.76135728786741],
+ [95.03126749207338, 29.761371921751238],
+ [95.03201723576402, 29.761389829130785],
+ [95.03276363398774, 29.761410893146387],
+ [95.03350632277824, 29.761434973117545],
+ [95.03424521675927, 29.76146183394706],
+ [95.03498037607913, 29.761491215377145],
+ [95.035711917426, 29.761522866578012],
+ [95.03643998610582, 29.761556530192124],
+ [95.03716475930274, 29.761591886465347],
+ [95.03788653744915, 29.761628566185358],
+ [95.03860571883365, 29.76166618469001],
+ [95.03932258585421, 29.76170436456548],
+ [95.04003738892985, 29.76174273062808],
+ [95.04075025083816, 29.76178094997509],
+ [95.0414610559133, 29.76181870813213],
+ [95.04216961904287, 29.761855638407084],
+ [95.04287591713418, 29.761891331889718],
+ [95.04357986124926, 29.761925397709096],
+ [95.04428137757625, 29.761957488479126],
+ [95.04498041854592, 29.76198725048925],
+ [95.04567682817188, 29.762014317811357],
+ [95.04637032968634, 29.762038376323694],
+ [95.04706059416637, 29.762059099770216],
+ [95.04774726432963, 29.762076162373777],
+ [95.0484300050609, 29.762089241174117],
+ [95.04910871445378, 29.762098042845082],
+ [95.04978328153793, 29.762102280852183],
+ [95.05045359964508, 29.76210167552205],
+ [95.05111966253706, 29.76209602004179],
+ [95.05178153406797, 29.762085106891018],
+ [95.05243927503516, 29.762068731547185],
+ [95.05309287649075, 29.762046750046103],
+ [95.0537422946664, 29.762019099359485],
+ [95.05438748396233, 29.761985721609257],
+ [95.05502839823626, 29.76194655859307],
+ [95.05566488201883, 29.761901557942874],
+ [95.05629656919591, 29.761850805510885],
+ [95.05692313234233, 29.761794428680094],
+ [95.0575442743842, 29.761732580860688],
+ [95.0581596433054, 29.761665348138973],
+ [95.05876888708963, 29.761592816601354],
+ [95.05937164047754, 29.761515065256333],
+ [95.05996759228947, 29.761432144038746],
+ [95.06055643134583, 29.761344102883623],
+ [95.06113793491645, 29.761251010034922],
+ [95.06171214230999, 29.761153046649387],
+ [95.06227907948092, 29.761050389948267],
+ [95.06283877238438, 29.760943217152814],
+ [95.06339127381165, 29.760831691663462],
+ [95.06393669678933, 29.760716002374487],
+ [95.06447520396281, 29.76059636241658],
+ [95.06500695797821, 29.760472984920362],
+ [95.06553212847378, 29.760346104258282],
+ [95.0660508986937, 29.760216015040477],
+ [95.06656344194985, 29.760083025494016],
+ [95.06707002648291, 29.75994741412334],
+ [95.06757112978441, 29.759809440866206],
+ [95.06806722979658, 29.759669344181514],
+ [95.06855878142073, 29.759527354008487],
+ [95.06904617625263, 29.759383697903765],
+ [95.06952978875404, 29.75923861533451],
+ [95.07000993080214, 29.759092371156385],
+ [95.07048679175114, 29.758945227682446],
+ [95.07096044787545, 29.75879742836973],
+ [95.07143096114058, 29.758649219939148],
+ [95.0718984144853, 29.758500858117706],
+ [95.07236278188816, 29.7583525823887],
+ [95.07282412506945, 29.758204644682806],
+ [95.07328275575983, 29.75805728963777],
+ [95.07373905641253, 29.757910760813612],
+ [95.07419366476313, 29.757765217208473],
+ [95.07464735762416, 29.757620800921966],
+ [95.07510085345471, 29.757477677507868],
+ [95.07555467766437, 29.757336168750566],
+ [95.07600940811365, 29.757196598118206],
+ [95.07646537399586, 29.75705931280275],
+ [95.0769228207089, 29.756924677394206],
+ [95.07738220221682, 29.756793075496777],
+ [95.07784401968648, 29.75666487927172],
+ [95.07830874492939, 29.756540496044202],
+ [95.07877690647402, 29.756420332181715],
+ [95.07924898851259, 29.75630478841808],
+ [95.07972503722137, 29.756194196891926],
+ [95.08020511490892, 29.756088882533362],
+ [95.0806891403115, 29.75598918720403],
+ [95.08117690920173, 29.75589531641115],
+ [95.08166835685006, 29.755807414283098],
+ [95.08216335868525, 29.75572566824862],
+ [95.08266177736347, 29.755650250535062],
+ [95.08316349491537, 29.75558120546187],
+ [95.08366839703267, 29.755518567048284],
+ [95.08417639041532, 29.75546236367944],
+ [95.08468755179344, 29.755412571989652],
+ [95.08520236790308, 29.755369015997044],
+ [95.08572134650697, 29.75533148313236],
+ [95.0862450098908, 29.755299740305322],
+ [95.08677390781156, 29.75527358808779],
+ [95.08730861289804, 29.755252808551163],
+ [95.08784970300886, 29.755237175354623],
+ [95.08839755885471, 29.755226476280296],
+ [95.08895256438073, 29.755220494902016],
+ [95.089514993805, 29.755219019351184],
+ [95.09008489086116, 29.7552217729881],
+ [95.09066229928165, 29.75522847917293],
+ [95.09124726342738, 29.755238870403907],
+ [95.09183976966378, 29.755252726598844],
+ [95.09243978867215, 29.75526985018834],
+ [95.09304723439128, 29.755290065097345],
+ [95.09366184648091, 29.75531326126932],
+ [95.09428337414857, 29.755339326723966],
+ [95.09491171647382, 29.755368102171502],
+ [95.09554680939114, 29.75539940595205],
+ [95.09618846028675, 29.755433126230766],
+ [95.09683632409143, 29.75546923335011],
+ [95.09749004228215, 29.75550775219342],
+ [95.09814924669702, 29.755548754655436],
+ [95.0988136358514, 29.755592374644042],
+ [95.09948290826172, 29.755638746066982],
+ [95.1001568080277, 29.75568798494813],
+ [95.10083517891061, 29.75574017449467],
+ [95.10151797539464, 29.75579531974171],
+ [95.1022051519645, 29.755853425724286],
+ [95.10289664375364, 29.755914488290983],
+ [95.10359258928374, 29.755978570204803],
+ [95.10429306658138, 29.756045742645284],
+ [95.10499798654989, 29.756116067070348],
+ [95.10570717321444, 29.75618958016383],
+ [95.10642032295875, 29.75626636089044],
+ [95.10713711848761, 29.756346492746122],
+ [95.10785729025027, 29.75643004436662],
+ [95.10858043622838, 29.75651688160893],
+ [95.10930611534633, 29.75660684892344],
+ [95.11003407093642, 29.756699686157475],
+ [95.11076414467685, 29.756795123665622],
+ [95.1114960914754, 29.756892893838618],
+ [95.11222971288655, 29.756992700238396],
+ [95.1129649452222, 29.75709420093414],
+ [95.11370170201873, 29.75719709582746],
+ [95.11443986012442, 29.757301125099488],
+ [95.11517935555177, 29.7574061249826],
+ [95.11592009761476, 29.757511940391662],
+ [95.11666232015585, 29.75761835330566],
+ [95.11740624233691, 29.757725222810585],
+ [95.11815181076378, 29.75783253698326],
+ [95.11889913308254, 29.757940178669305],
+ [95.11964841222917, 29.758048000558695],
+ [95.12039993276164, 29.758155854652614],
+ [95.12115399312397, 29.75826357999786],
+ [95.1219108497459, 29.75837102690515],
+ [95.1226706293697, 29.758478081829693],
+ [95.12343325561484, 29.758584686897258],
+ [95.12419857627997, 29.758690818430438],
+ [95.12496638982559, 29.75879646083105],
+ [95.12573649209446, 29.7589015818837],
+ [95.12650863318528, 29.75900618637391],
+ [95.12728253192327, 29.759110282431784],
+ [95.12805798566751, 29.75921386162033],
+ [95.12883477913662, 29.759316919371038],
+ [95.12961273528985, 29.759419445656786],
+ [95.13039166301432, 29.759521458216526],
+ [95.13117134363408, 29.759622963323043],
+ [95.13195155721434, 29.759723948972997],
+ [95.13273211930314, 29.759824349786275],
+ [95.13351286507051, 29.759924061406032],
+ [95.13428648274362, 29.76002351015658],
+ [95.1350533298064, 29.760122544307915],
+ [95.1358137532818, 29.760221010686855],
+ [95.13656784419986, 29.760318809952974],
+ [95.13731567503761, 29.76041584848236],
+ [95.1380573752464, 29.760511990985425],
+ [95.13879310931623, 29.76060704815151],
+ [95.13952306473344, 29.760700794123938],
+ [95.14024751710419, 29.7607929520901],
+ [95.14096671686433, 29.760883206230545],
+ [95.14168092332761, 29.76097123202995],
+ [95.14239029599311, 29.761056732470486],
+ [95.14309486625548, 29.761139484506582],
+ [95.14379454089128, 29.761219462160696],
+ [95.14448922306659, 29.76129664046317],
+ [95.14517882147311, 29.76137100941381],
+ [95.14586312132259, 29.761442532574584],
+ [95.14654188135431, 29.761511168945386],
+ [95.14721489938523, 29.761576901934955],
+ [95.14788204807155, 29.761639772673718],
+ [95.14854319868547, 29.76169982923195],
+ [95.14919822095698, 29.761757127412878],
+ [95.14984699116548, 29.76181173598209],
+ [95.15048960377052, 29.761863851723042],
+ [95.15112617637942, 29.761913696049017],
+ [95.15175681293137, 29.761961561816054],
+ [95.15238148064795, 29.762007691856205],
+ [95.15300009096235, 29.762052309028526],
+ [95.1533539374323, 29.762086082676035],
+ [95.15370650809008, 29.762118928860186],
+ [95.15405759583123, 29.762150875711065],
+ [95.15440704121897, 29.76218191319173],
+ [95.1547548321985, 29.762211967913583],
+ [95.15510097264206, 29.762240955288657],
+ [95.15544525415498, 29.762268829619945],
+ [95.15578751039571, 29.76229553455492],
+ [95.15612769998111, 29.762320941845203],
+ [95.15646565712565, 29.762344985615734],
+ [95.156801142589, 29.76236761294652],
+ [95.1571338046714, 29.76238883654028],
+ [95.15746323934037, 29.76240869370805],
+ [95.15778903282519, 29.762427217766984],
+ [95.15811077257146, 29.762444433666733],
+ [95.15842800577592, 29.762460368791256],
+ [95.15874028837707, 29.76247502889767],
+ [95.15904716834646, 29.76248842410003],
+ [95.1593481499996, 29.762500590502704],
+ [95.15964271930007, 29.76251153961251],
+ [95.1599303416933, 29.76252129267978],
+ [95.16021045104225, 29.762529892932115],
+ [95.16048243037355, 29.762537389252305],
+ [95.16074559672008, 29.762543832974302],
+ [95.1609993202866, 29.762549265122786],
+ [95.16124294069552, 29.762553753099137],
+ [95.16147571071544, 29.762557390653928],
+ [95.16169677155058, 29.762560323342807]
+]
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/city-path.json b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/city-path.json
new file mode 100644
index 0000000..821973f
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/city-path.json
@@ -0,0 +1,12 @@
+[
+ [-74.0135, 40.7047],
+ [-74.0102, 40.7104],
+ [-74.0074, 40.7167],
+ [-74.0047, 40.7232],
+ [-74.0017, 40.7297],
+ [-73.9988, 40.7362],
+ [-73.9954, 40.7429],
+ [-73.9917, 40.7496],
+ [-73.9882, 40.7563],
+ [-73.9848, 40.7631]
+]
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/example-Root.tsx b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/example-Root.tsx
new file mode 100644
index 0000000..9a27a0b
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/assets/example-Root.tsx
@@ -0,0 +1,39 @@
+import React from 'react';
+import {Composition} from 'remotion';
+import {CesiumFlythrough, type CesiumFlythroughProps} from './CesiumFlythrough';
+import cityPath from './city-path.json';
+
+export const RemotionRoot: React.FC = () => (
+ <>
+ out.png --frame=N --gl=angle --timeout=180000 # validate framing/bank first
+bunx remotion render src/index.ts out.mp4 --gl=angle --concurrency=1 --timeout=180000
+```
+
+`--gl=angle` is mandatory. Use `--concurrency=1`; `settle()` already serializes tile loading.
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/references/3d-troubleshooting.md b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/references/3d-troubleshooting.md
new file mode 100644
index 0000000..488eb9d
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/references/3d-troubleshooting.md
@@ -0,0 +1,57 @@
+# 3D Flyover — troubleshooting
+
+## The headless dead-end (why we render through Remotion)
+
+Cesium's globe **will not draw in a standalone headless Playwright/Chromium** harness. Verified on
+Apple M4 (ANGLE Metal active, WebGL working): the skybox/stars render, but the globe surface produces
+**zero draw commands** (`scene.frameState.commandList.length === 0`), `globe.tilesLoaded` never goes
+true, and frames come back as the black starfield. No network failures; `sampleTerrainMostDetailed`
+succeeds (terrain data is reachable). Dead-ends tried, all failed:
+
+- default render loop, manual `scene.render()`, manual `viewer.render()`, headed mode (context-destroyed).
+
+**What works:** render Cesium **through Remotion** — same headless Chrome, but driven by Remotion's frame
+loop with these four non-negotiables:
+
+1. `useDefaultRenderLoop = false` — drive frames by hand.
+2. Per frame call **`viewer.render()`**, NOT `scene.render()`. `viewer.render()` does the full frame
+ (`initializeFrame` → tile streaming → render); `scene.render()` skips frame-init, so tiles never
+ advance and the globe never appears. **This is the single most important line.**
+3. `contextOptions: { webgl: { preserveDrawingBuffer: true } }` so Remotion's screenshot captures pixels.
+4. Gate init + every frame with `delayRender(…, {timeoutInMilliseconds})` — tile loading can exceed Remotion's
+ default; use 60–120 s.
+
+The standalone `flythrough.html` / `render.mjs` / `probe.mjs` from the original spike are kept only as the
+record of this dead-end. The canonical render path is the Remotion component
+(`../assets/CesiumFlythrough.tsx`).
+
+## Symptom → fix
+
+| Symptom | Cause | Fix |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Frames are black with stars | Globe not drawing (headless Playwright, or `scene.render()` used) | Render through Remotion; use `viewer.render()`; `useDefaultRenderLoop=false`. |
+| Screenshots blank/transparent | No `preserveDrawingBuffer` | `contextOptions:{ webgl:{ preserveDrawingBuffer:true } }`. |
+| "delayRender timed out" | Cold tiles exceed the default | `delayRender(…, {timeoutInMilliseconds: 120000})` + `--timeout=180000`. |
+| Globe is a dark/navy sphere | Imagery layer didn't attach | `baseLayer:false` then `viewer.imageryLayers.addImageryProvider(...)`. |
+| High-pitch frame shows a void/starfield above the horizon | No atmosphere | `viewer.scene.skyAtmosphere.show = true`. |
+| 403 on tiles in headless | Domain-locked MapTiler key | Use an **unrestricted** key. |
+| Google root tileset returns 403 | Map Tiles API disabled, billing absent, wrong key, or application restriction blocks local headless rendering | Enable Map Tiles API and billing; restrict the key to that API while allowing the Remotion request. |
+| Google scene shows a duplicate/competing surface | MapTiler or the Cesium globe is still enabled | Do not add MapTiler; set `viewer.scene.globe.show=false`. |
+| Google mesh remains coarse | Screen-space error is too high or the capture starts before refinement | Lower `maximumScreenSpaceError`; settle on `tileset.tilesLoaded`. |
+| WebGL unavailable / software renderer | Missing GL flag | Render with `--gl=angle`. |
+| Camera looks at sky / ground, not terrain | Pitch sign / convention | Cesium pitch 0 = horizon, negative = down (inverse of MapLibre); `-(90 - PITCH_FROM_NADIR)`. |
+| Aim/turn-probe clamps near the end | Path too short | `PATHKM ≥ TRAVEL_KM + 2·LOOK_AHEAD_KM`; raise `WINDOW_KM` in prep. |
+| Path feels like straight-then-corner | Douglas-Peucker simplification | Use resample → moving-average smooth (see architecture §2), not `turf.simplify`. |
+| Camera bumps left and right instead of swerving | Sparse route vertices are still being followed as straight segments | Keep `pathSmoothingPasses={3}`; use sparse intentional control points and arc-length movement. |
+
+## Gotchas checklist
+
+- **`viewer.render()`, never `scene.render()`** per frame. The single biggest trap.
+- Cesium loads from **CDN**; set `window.CESIUM_BASE_URL` _before_ injecting the script.
+- `preserveDrawingBuffer: true` or screenshots are blank.
+- `delayRender` uses `timeoutInMilliseconds`; set it to at least 60,000.
+- Terrain: `baseLayer:false`, then add MapTiler imagery.
+- Google: no MapTiler, hide the globe, retain `showCreditsOnScreen:true`.
+- Always `skyAtmosphere.show = true`.
+- Validate the path's heading-delta probe and render one **still** (framing + bank) before the full mp4.
+- Cesium pitch/roll conventions are inverted vs MapLibre.
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/scripts/prep-cesium-path.mjs b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/scripts/prep-cesium-path.mjs
new file mode 100644
index 0000000..dbb3f0f
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/cesium/scripts/prep-cesium-path.mjs
@@ -0,0 +1,161 @@
+// Camera-path generator for the Cesium flythrough. Turns a river/route centerline GeoJSON into a LONG,
+// CONTINUOUSLY-curving camera path so the camera banks through smooth flowing curves (no
+// straight-then-corner). Method: clip → resample to even spacing → moving-average smooth (inherently
+// continuous curvature) → dampen lateral deviation toward the straight chord (dials swerve amplitude).
+// No Douglas-Peucker (that concentrates curvature at sparse control points → corners).
+//
+// RUN (out of the box, against the shipped sample):
+// node prep-cesium-path.mjs
+// → reads assets/sample-river.geojson (override: node prep-cesium-path.mjs )
+// → writes assets/cesium-path.json (then import that JSON in CesiumFlythrough.tsx, or copy it
+// into your Remotion project's src/geo/ and adjust the import)
+//
+// ADAPT for a new location: change START (a point ON your centerline where the corridor opens),
+// WINDOW_KM, and DAMP/SMOOTH below. Input must be a single LineString feature (features[0].geometry).
+
+import {readFileSync, writeFileSync, mkdirSync} from 'fs';
+import {dirname, resolve} from 'path';
+import {fileURLToPath} from 'url';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const IN = process.argv[2] || resolve(__dir, '../assets/sample-river.geojson');
+const OUT = process.argv[3] || resolve(__dir, '../assets/cesium-path.json');
+const havKm = (a, b) => {
+ const R = 6371,
+ r = Math.PI / 180,
+ dLat = (b[1] - a[1]) * r,
+ dLng = (b[0] - a[0]) * r;
+ const h =
+ Math.sin(dLat / 2) ** 2 +
+ Math.cos(a[1] * r) * Math.cos(b[1] * r) * Math.sin(dLng / 2) ** 2;
+ return 2 * R * Math.asin(Math.sqrt(h));
+};
+
+const gorge = JSON.parse(readFileSync(IN, 'utf8')).features[0].geometry
+ .coordinates;
+
+// ADAPT: clip ~24 km of river from the reach where the flythrough opens. START must be a point ON the
+// centerline (the script snaps to the nearest vertex). The sample's opening is the Yarlung gorge:
+const START = [94.968, 29.757];
+let s0 = 0,
+ best = Infinity;
+gorge.forEach((p, i) => {
+ const d = havKm(p, START);
+ if (d < best) {
+ best = d;
+ s0 = i;
+ }
+});
+const WINDOW_KM = 30; // clip to ~end of gorge data; smoothing+dampening shrink it to the usable corridor
+const clip = [];
+for (let i = s0, acc = 0; i < gorge.length; i++) {
+ if (i > s0) acc += havKm(gorge[i - 1], gorge[i]);
+ if (acc > WINDOW_KM) break;
+ clip.push(gorge[i]);
+}
+
+// Resample to even arc-length spacing so curvature is distributed evenly along the path.
+const STEP_KM = 0.1;
+const resample = (coords) => {
+ const out = [coords[0].slice()];
+ let carry = 0,
+ from = coords[0];
+ for (let i = 1; i < coords.length; i++) {
+ let segLen = havKm(from, coords[i]);
+ while (carry + segLen >= STEP_KM) {
+ const t = (STEP_KM - carry) / segLen;
+ const np = [
+ from[0] + (coords[i][0] - from[0]) * t,
+ from[1] + (coords[i][1] - from[1]) * t,
+ ];
+ out.push(np);
+ from = np;
+ segLen = havKm(from, coords[i]);
+ carry = 0;
+ }
+ carry += segLen;
+ from = coords[i];
+ }
+ return out;
+};
+
+// Moving-average smoothing — inherently continuous (no kinks). Window in points; repeat for extra glass.
+const smoothMA = (coords, w, passes) => {
+ let c = coords;
+ for (let p = 0; p < passes; p++) {
+ c = c.map((_, i) => {
+ let sx = 0,
+ sy = 0,
+ n = 0;
+ for (
+ let j = Math.max(0, i - w);
+ j <= Math.min(c.length - 1, i + w);
+ j++
+ ) {
+ sx += c[j][0];
+ sy += c[j][1];
+ n++;
+ }
+ return [sx / n, sy / n];
+ });
+ }
+ return c;
+};
+
+const SMOOTH_W = 28; // ±2.8 km window — turns meanders into smooth flowing curves
+const SMOOTH_PASSES = 2;
+const DAMP = 0.45; // keep 45% of the (already-smooth) deviation → gentle, continuous swerve
+
+const even = resample(clip);
+const sm = smoothMA(even, SMOOTH_W, SMOOTH_PASSES);
+
+const lat0 = (sm[0][1] * Math.PI) / 180;
+const kx = 111.32 * Math.cos(lat0),
+ ky = 110.57;
+const toXY = (p) => [(p[0] - sm[0][0]) * kx, (p[1] - sm[0][1]) * ky];
+const toLL = (xy) => [sm[0][0] + xy[0] / kx, sm[0][1] + xy[1] / ky];
+const A = toXY(sm[0]),
+ B = toXY(sm[sm.length - 1]);
+const AB = [B[0] - A[0], B[1] - A[1]],
+ len2 = AB[0] ** 2 + AB[1] ** 2;
+const path = sm.map((p) => {
+ const P = toXY(p);
+ const t = ((P[0] - A[0]) * AB[0] + (P[1] - A[1]) * AB[1]) / len2;
+ const proj = [A[0] + t * AB[0], A[1] + t * AB[1]];
+ return toLL([
+ proj[0] + (P[0] - proj[0]) * DAMP,
+ proj[1] + (P[1] - proj[1]) * DAMP,
+ ]);
+});
+
+mkdirSync(dirname(OUT), {recursive: true});
+writeFileSync(OUT, JSON.stringify(path));
+
+let len = 0;
+for (let i = 1; i < path.length; i++) len += havKm(path[i - 1], path[i]);
+console.log(
+ `cesium-path: clip ${clip.length} → resample ${even.length} → smooth → ${path.length} pts · ${len.toFixed(1)} km`,
+);
+const bear = (a, b) => {
+ const r = Math.PI / 180;
+ const y = Math.sin((b[0] - a[0]) * r) * Math.cos(b[1] * r);
+ const x =
+ Math.cos(a[1] * r) * Math.sin(b[1] * r) -
+ Math.sin(a[1] * r) * Math.cos(b[1] * r) * Math.cos((b[0] - a[0]) * r);
+ return (Math.atan2(y, x) * 180) / Math.PI;
+};
+// heading sampled every ~1.5 km — should change gradually & continuously (no big jumps = no corners)
+const stepPts = Math.round(1.5 / STEP_KM);
+let prev = null,
+ hs = [];
+for (let i = 0; i + stepPts < path.length; i += stepPts) {
+ const h = bear(path[i], path[i + stepPts]);
+ if (prev !== null) {
+ let d = h - prev;
+ while (d > 180) d -= 360;
+ while (d < -180) d += 360;
+ hs.push(d.toFixed(0));
+ }
+ prev = h;
+}
+console.log(` heading deltas every 1.5km (deg): ${hs.join(', ')}`);
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/mapbox/TECHNIQUE.md b/remotion-best-practices/remotion-markup/remotion-maps/techniques/mapbox/TECHNIQUE.md
new file mode 100644
index 0000000..5af3fe1
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/mapbox/TECHNIQUE.md
@@ -0,0 +1,449 @@
+---
+name: maps-mapbox
+description: Make deterministic Remotion 2D map animations with Mapbox GL JS and Turf. Use when the user chooses Mapbox for animated routes, map markers, labels, camera movement, or Mapbox styles.
+metadata:
+ tags: map, map animation, mapbox, turf, geojson, route animation
+---
+
+Use Mapbox GL JS for rendering maps in Remotion when the user wants Mapbox styles or higher-fidelity map visuals and has a Mapbox access token. Use Turf for geospatial operations such as great-circle routes, distances, slicing lines, and positions along routes.
+
+Use this technique only when the user has a Mapbox access token and wants Mapbox styles or data.
+
+## Core rules
+
+- Prefer `@turf/turf` for geospatial work. Do not hand-roll distance, great-circle, route slicing, or coordinate interpolation unless the user explicitly needs a custom non-geodesic effect.
+- Use GeoJSON sources and Mapbox layers for lines, markers, and labels. Avoid DOM `Marker` elements unless the user specifically asks for HTML markers.
+- Keep the live map camera static by default. Before moving it on every frame, read [moving-map stability](references/render-stability.md). Prefer a fixed map plate for satellite imagery, hillshade, or a modest 2D reframe.
+- Use a live per-frame camera only after rendering a short MP4 and checking for shimmer. This 2D technique does not provide genuine terrain, pitch, bearing, or banking.
+- Disable non-deterministic map behavior: `interactive: false`, `fadeDuration: 0`.
+- Drive animation from `useCurrentFrame()`; do not use CSS transitions or browser-timed animation.
+- Use `delayRender()` / `continueRender()` around map loading and per-frame map updates.
+- Set `preserveDrawingBuffer: true` and render WebGL with `bunx remotion ... --gl=angle`.
+- Before continuing the initial render, add sources/layers, apply the frame-0 camera with `jumpTo()` or `setFreeCameraOptions()`, then wait for `idle`.
+- Do not add a `mapInstance.remove()` cleanup function; it can interfere with Remotion's render lifecycle.
+- Use Mapbox style URLs such as `mapbox://styles/mapbox/standard` or a user-provided custom style.
+- Do not install `@types/mapbox-gl`; Mapbox GL JS ships its own types.
+- Keep required provider attribution visible and verify current provider terms before rendering.
+- Record the source and effective date of custom or disputed geography.
+- Inspect rendered pixels, not only Studio playback, at every required aspect ratio.
+
+Coordinates in Mapbox, Turf, and GeoJSON are `[longitude, latitude]`.
+
+```ts
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+```
+
+## Prerequisites
+
+Install Mapbox GL JS and Turf with the project's package manager.
+
+```bash
+npm i mapbox-gl @turf/turf
+```
+
+```bash
+bun i mapbox-gl @turf/turf
+```
+
+```bash
+yarn add mapbox-gl @turf/turf
+```
+
+```bash
+pnpm i mapbox-gl @turf/turf
+```
+
+Import the Mapbox CSS once in the component or an app-level stylesheet:
+
+```ts
+import 'mapbox-gl/dist/mapbox-gl.css';
+```
+
+Mapbox requires a public access token. Prefer passing it as an input prop or reading it from an environment variable that is available to the bundled Remotion code.
+
+```ts
+const mapboxAccessToken = process.env.REMOTION_MAPBOX_TOKEN;
+
+if (!mapboxAccessToken) {
+ throw new Error('Set REMOTION_MAPBOX_TOKEN to render Mapbox maps.');
+}
+```
+
+## Basic map example
+
+```tsx
+import {useEffect, useRef, useState} from 'react';
+import {AbsoluteFill, useDelayRender, useVideoConfig} from 'remotion';
+import mapboxgl from 'mapbox-gl';
+import 'mapbox-gl/dist/mapbox-gl.css';
+
+const zurich: [number, number] = [8.5417, 47.3769];
+
+const mapboxAccessToken = process.env.REMOTION_MAPBOX_TOKEN;
+
+if (!mapboxAccessToken) {
+ throw new Error('Set REMOTION_MAPBOX_TOKEN to render Mapbox maps.');
+}
+
+export const MyComposition = () => {
+ const containerRef = useRef(null);
+ const {delayRender, continueRender} = useDelayRender();
+ const {width, height} = useVideoConfig();
+ const [loadingHandle] = useState(() => delayRender('Loading Mapbox map'));
+
+ useEffect(() => {
+ if (!containerRef.current) {
+ return;
+ }
+
+ const mapInstance = new mapboxgl.Map({
+ accessToken: mapboxAccessToken,
+ container: containerRef.current,
+ style: 'mapbox://styles/mapbox/standard',
+ center: zurich,
+ zoom: 7,
+ interactive: false,
+ attributionControl: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {
+ preserveDrawingBuffer: true,
+ },
+ });
+
+ mapInstance.on('load', () => {
+ mapInstance.jumpTo({center: zurich, zoom: 7});
+ mapInstance.once('idle', () => {
+ continueRender(loadingHandle);
+ });
+ });
+ }, [continueRender, loadingHandle]);
+
+ return (
+
+
+
+ );
+};
+```
+
+Animated examples should keep the loaded map in React state and skip per-frame updates until that state is set.
+
+## Animated flight route example
+
+This example shows the recommended pattern for route animations:
+
+- Turf creates the route and markers.
+- Turf slices the route for line reveal animation.
+- Mapbox renders the route with GeoJSON sources and layers.
+- The camera uses `jumpTo()` with animated center, zoom, bearing, and pitch.
+- Frame 0 is prepared before `continueRender()`.
+
+```tsx
+import * as turf from '@turf/turf';
+import {useEffect, useRef, useState} from 'react';
+import {
+ AbsoluteFill,
+ Easing,
+ interpolate,
+ useCurrentFrame,
+ useDelayRender,
+ useVideoConfig,
+} from 'remotion';
+import mapboxgl, {type GeoJSONSource, type Map} from 'mapbox-gl';
+import 'mapbox-gl/dist/mapbox-gl.css';
+
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+
+const mapboxAccessToken = process.env.REMOTION_MAPBOX_TOKEN;
+
+if (!mapboxAccessToken) {
+ throw new Error('Set REMOTION_MAPBOX_TOKEN to render Mapbox maps.');
+}
+
+const greatCircleLine = (from: [number, number], to: [number, number]) => {
+ const route = turf.greatCircle(from, to, {npoints: 100});
+
+ if (route.geometry.type === 'LineString') {
+ return turf.lineString(route.geometry.coordinates);
+ }
+
+ // Great-circle routes crossing the antimeridian can become MultiLineString.
+ // Keep the example valid by choosing the longest segment.
+ const longestSegment = route.geometry.coordinates.reduce((longest, segment) => {
+ return segment.length > longest.length ? segment : longest;
+ });
+
+ return turf.lineString(longestSegment);
+};
+
+const targetRoute = greatCircleLine(zurich, newYork);
+const targetRouteDistance = turf.length(targetRoute);
+
+const cityMarkers = turf.featureCollection([
+ turf.point(zurich, {name: 'Zurich'}),
+ turf.point(newYork, {name: 'New York'}),
+]);
+
+const clampProgress = (progress: number) => Math.min(1, Math.max(0, progress));
+
+const distanceAlong = (totalDistance: number, progress: number) => {
+ // Keep the route non-empty at progress 0; Turf can error on zero-length slices.
+ return Math.max(0.001, totalDistance * clampProgress(progress));
+};
+
+const getPartialTargetRoute = (progress: number) => {
+ return turf.lineSliceAlong(
+ targetRoute,
+ 0,
+ distanceAlong(targetRouteDistance, progress),
+ );
+};
+
+const getCameraOptions = (progress: number) => {
+ const target = turf.along(
+ targetRoute,
+ distanceAlong(targetRouteDistance, progress),
+ ).geometry.coordinates as [number, number];
+
+ return {
+ center: target,
+ zoom: interpolate(progress, [0, 0.5, 1], [7, 2.4, 8], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ }),
+ bearing: interpolate(progress, [0, 1], [-20, 35], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ }),
+ pitch: interpolate(progress, [0, 0.25, 0.75, 1], [25, 55, 55, 30], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ }),
+ };
+};
+
+export const MyComposition = () => {
+ const containerRef = useRef(null);
+ const frame = useCurrentFrame();
+ const {delayRender, continueRender} = useDelayRender();
+ const {durationInFrames, height, width} = useVideoConfig();
+ const [map, setMap] = useState(null);
+ const [loadingHandle] = useState(() => delayRender('Loading Mapbox map'));
+
+ useEffect(() => {
+ if (!containerRef.current) {
+ return;
+ }
+
+ const mapInstance = new mapboxgl.Map({
+ accessToken: mapboxAccessToken,
+ container: containerRef.current,
+ style: 'mapbox://styles/mapbox/standard',
+ center: zurich,
+ zoom: 7,
+ interactive: false,
+ attributionControl: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {
+ preserveDrawingBuffer: true,
+ },
+ });
+
+ mapInstance.on('load', () => {
+ mapInstance.addSource('trace', {
+ type: 'geojson',
+ data: getPartialTargetRoute(0),
+ });
+
+ mapInstance.addLayer({
+ id: 'trace-line',
+ type: 'line',
+ source: 'trace',
+ layout: {
+ 'line-cap': 'round',
+ 'line-join': 'round',
+ },
+ paint: {
+ 'line-color': '#111111',
+ 'line-width': 7,
+ },
+ });
+
+ mapInstance.addSource('city-markers', {
+ type: 'geojson',
+ data: cityMarkers,
+ });
+
+ mapInstance.addLayer({
+ id: 'city-marker-dots',
+ type: 'circle',
+ source: 'city-markers',
+ paint: {
+ 'circle-color': '#f03b20',
+ 'circle-radius': 12,
+ 'circle-stroke-color': '#ffffff',
+ 'circle-stroke-width': 4,
+ },
+ });
+
+ mapInstance.addLayer({
+ id: 'city-marker-labels',
+ type: 'symbol',
+ source: 'city-markers',
+ layout: {
+ 'text-allow-overlap': true,
+ 'text-anchor': 'top',
+ 'text-field': ['get', 'name'],
+ 'text-offset': [0, 0.9],
+ 'text-size': 28,
+ },
+ paint: {
+ 'text-color': '#111111',
+ 'text-halo-color': '#ffffff',
+ 'text-halo-width': 3,
+ },
+ });
+
+ mapInstance.jumpTo(getCameraOptions(0));
+ mapInstance.once('idle', () => {
+ setMap(mapInstance);
+ continueRender(loadingHandle);
+ });
+ });
+ }, [continueRender, loadingHandle]);
+
+ useEffect(() => {
+ if (!map) {
+ return;
+ }
+
+ const handle = delayRender('Rendering Mapbox frame');
+ const timelineProgress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ });
+ const travelProgress = interpolate(timelineProgress, [0.2, 0.82], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ });
+ const trace = map.getSource('trace') as GeoJSONSource | undefined;
+
+ trace?.setData(getPartialTargetRoute(travelProgress));
+ map.jumpTo(getCameraOptions(travelProgress));
+
+ map.once('idle', () => continueRender(handle));
+ // Force an idle event even if the camera parameters are unchanged from the previous frame.
+ map.triggerRepaint();
+ }, [continueRender, delayRender, durationInFrames, frame, map]);
+
+ return (
+
+
+
+ );
+};
+```
+
+## Camera guidance
+
+For a validated live-camera route animation, animate `center`, `zoom`, `bearing`, and `pitch` with `jumpTo()`:
+
+```ts
+map.jumpTo({
+ center,
+ zoom,
+ bearing,
+ pitch,
+});
+```
+
+Keep route progress and camera progress separate if the camera needs to lead, lag, zoom out, or zoom back in. For cinematic 3D camera moves, load the 3D flyover branch from the parent skill.
+
+## Lines
+
+Use GeoJSON sources for lines. Unless the user asks, do not add glow effects or extra decorative points.
+
+For geodesic flight routes, use Turf:
+
+```ts
+const line = greatCircleLine(start, end);
+const distance = turf.length(line);
+const partialLine = turf.lineSliceAlong(
+ line,
+ 0,
+ // Keep the route non-empty at progress 0.
+ Math.max(0.001, distance * progress),
+);
+```
+
+For a visually straight line on the map, use a simple GeoJSON `LineString` between the two points instead of `greatCircle()`.
+
+## Markers and labels
+
+Use map-native GeoJSON layers for markers and labels:
+
+```tsx
+mapInstance.addSource('markers', {
+ type: 'geojson',
+ data: turf.featureCollection([
+ turf.point([-118.2437, 34.0522], {name: 'Los Angeles'}),
+ ]),
+});
+
+mapInstance.addLayer({
+ id: 'marker-dots',
+ type: 'circle',
+ source: 'markers',
+ paint: {
+ 'circle-color': '#f03b20',
+ 'circle-radius': 12,
+ 'circle-stroke-color': '#ffffff',
+ 'circle-stroke-width': 4,
+ },
+});
+
+mapInstance.addLayer({
+ id: 'marker-labels',
+ type: 'symbol',
+ source: 'markers',
+ layout: {
+ 'text-allow-overlap': true,
+ 'text-anchor': 'top',
+ 'text-field': ['get', 'name'],
+ 'text-offset': [0, 0.9],
+ 'text-size': 28,
+ },
+ paint: {
+ 'text-color': '#111111',
+ 'text-halo-color': '#ffffff',
+ 'text-halo-width': 3,
+ },
+});
+```
+
+Make marker sizes and label font sizes large enough for the composition resolution.
+
+## Styles
+
+Default to Mapbox Standard:
+
+```ts
+style: 'mapbox://styles/mapbox/standard'
+```
+
+If the user requests another style, use any valid Mapbox style URL.
+
+## Rendering
+
+For WebGL map renders, prefer single concurrency and ANGLE:
+
+```bash
+bunx remotion render [composition-id] out/video.mp4 --gl=angle --concurrency=1
+```
+
+Use the equivalent package runner for the project. In npm projects, use `npx`; in Bun projects, use `bunx`.
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/mapbox/references/render-stability.md b/remotion-best-practices/remotion-markup/remotion-maps/techniques/mapbox/references/render-stability.md
new file mode 100644
index 0000000..fc40033
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/mapbox/references/render-stability.md
@@ -0,0 +1,64 @@
+# Moving Map Render Stability
+
+Read this reference before building a moving 2D MapTiler scene or diagnosing a wavering Remotion render.
+
+## Symptom and cause
+
+If basemap detail shimmers or jitters during a pan/zoom, the likely cause is per-frame `map.jumpTo()`.
+Headless MapTiler capture can resample both vector hillshade and satellite imagery differently frame to
+frame. Tile retries, easing changes, and label changes do not solve that renderer effect.
+
+## Required pattern: fixed map plate
+
+For any 2D pan/zoom:
+
+1. Render the MapTiler canvas once at the largest required zoom in an oversized container. Size it from the camera route and keep each dimension below the browser's reliable WebGL render-buffer limit (commonly 4096 px). Do **not** blindly use 3×: a 1920×1080 composition becomes 5760 px wide and Chromium may silently downsample it, causing visible pixelation during the CSS zoom.
+2. Keep the map's camera static.
+3. For each frame, calculate the approved target centre/zoom, then move the canvas with CSS `translate` + `scale`.
+4. Apply the same transform to every projected HTML overlay.
+5. Continue to animate GeoJSON data and paint properties imperatively; only the renderer camera is frozen.
+
+Keep pitch and bearing constant. Use a 3D engine such as Cesium for genuine changing pitch/bearing or a terrain flythrough.
+
+```ts
+const baseZoom = Math.max(start.zoom, end.zoom);
+const map = new maptilersdk.Map({
+ container,
+ style,
+ center: end.center,
+ zoom: baseZoom,
+ pitch: end.pitch ?? 0,
+ bearing: end.bearing ?? 0,
+ interactive: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {preserveDrawingBuffer: true},
+});
+
+// Per Remotion frame. `camera` is the approved centre/zoom interpolation.
+const projected = map.project(camera.center);
+const scale = 2 ** (camera.zoom - baseZoom);
+const plate = {
+ transform: `translate(${width / 2 - projected.x * scale}px, ${height / 2 - projected.y * scale}px) scale(${scale})`,
+ transformOrigin: "0 0",
+};
+
+// Convert label projection with exactly the same plate transform.
+const labelX = labelPoint.x * scale + width / 2 - projected.x * scale;
+const labelY = labelPoint.y * scale + height / 2 - projected.y * scale;
+```
+
+### Plate sizing and sharpness
+
+- Render at the maximum zoom reached by **any** camera waypoint, including intermediate or hold cameras. The CSS scale should never exceed `1`; otherwise the plate is being enlarged.
+- Centre the frozen map on the midpoint of the camera route's geographic extent, not automatically on the final camera. This minimizes required overscan.
+- Keep the largest canvas dimension at or below 4096 px unless the actual render environment has been tested with a larger `MAX_RENDERBUFFER_SIZE`.
+- For 1920×1080, a 3840×2160 plate is a safe default. For 1080×1920, use approximately 2700×3840 when the route needs extra horizontal pan room.
+- If the route cannot fit within that plate at the required zoom, split the shot into two fixed plates with a deliberate editorial transition. Do not trade sharpness for one enormous canvas.
+- Distinguish failure modes: repeating shimmer means the live renderer is moving; steadily soft tiles during a CSS push means the fixed plate is underspecified, internally downsampled, or being scaled above `1`.
+
+## Verification
+
+- Render a short MP4, not only a Studio preview.
+- Inspect static terrain texture and satellite detail while the camera moves.
+- If any underlying map detail wavers, use the fixed map plate. Do not approve it as a minor preview artefact.
+- Render WebGL with `--gl=angle`, `preserveDrawingBuffer:true`, and conservative concurrency (`1`) while validating.
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/maplibre/TECHNIQUE.md b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maplibre/TECHNIQUE.md
new file mode 100644
index 0000000..94ef160
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maplibre/TECHNIQUE.md
@@ -0,0 +1,484 @@
+---
+name: maps-maplibre
+description: Make deterministic Remotion 2D map animations with MapLibre GL JS and Turf. Use when the user chooses MapLibre for animated routes, map markers, labels, and camera movement.
+metadata:
+ tags: map, map animation, maplibre, turf, geojson, route animation
+---
+
+Use MapLibre GL JS for rendering maps in Remotion. Use Turf for geospatial operations such as great-circle routes, distances, slicing lines, and positions along routes.
+
+## Core rules
+
+- Prefer `@turf/turf` for geospatial work. Do not hand-roll distance, great-circle, route slicing, or coordinate interpolation unless the user explicitly needs a custom non-geodesic effect.
+- Use GeoJSON sources and MapLibre layers for lines, markers, and labels. Avoid DOM `Marker` elements unless the user specifically asks for HTML markers.
+- Keep the live map camera static by default. Before moving it on every frame, read [moving-map stability](references/render-stability.md). Prefer a fixed map plate for satellite imagery, hillshade, or a modest 2D reframe.
+- Use a live per-frame camera only after rendering a short MP4 and checking for shimmer. This 2D technique does not provide genuine terrain, pitch, bearing, or banking.
+- Disable non-deterministic map behavior: `interactive: false`, `fadeDuration: 0`.
+- Drive animation from `useCurrentFrame()`; do not use CSS transitions or browser-timed animation.
+- Use `delayRender()` / `continueRender()` around map loading and per-frame map updates.
+- Set `preserveDrawingBuffer: true` and render WebGL with `bunx remotion ... --gl=angle`.
+- Before continuing the initial render, add sources/layers, apply the frame-0 camera with `jumpTo()`, then wait for `idle`.
+- Do not add a `mapInstance.remove()` cleanup function; it can interfere with Remotion's render lifecycle.
+- Use standard MapLibre style JSON URLs and layer/source APIs.
+- Do not install `@types/maplibre-gl`; MapLibre ships its own types.
+- Keep required provider attribution visible and verify the current terms of the chosen style and tile providers before rendering.
+- Record the source and effective date of custom or disputed geography.
+- Inspect rendered pixels, not only Studio playback, at every required aspect ratio.
+
+Coordinates in MapLibre, Turf, and GeoJSON are `[longitude, latitude]`.
+
+```ts
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+```
+
+## Prerequisites
+
+Install MapLibre and Turf with the project's package manager.
+
+```bash
+npm i maplibre-gl @turf/turf
+```
+
+```bash
+bun i maplibre-gl @turf/turf
+```
+
+```bash
+yarn add maplibre-gl @turf/turf
+```
+
+```bash
+pnpm i maplibre-gl @turf/turf
+```
+
+Import the MapLibre CSS once in the component or an app-level stylesheet:
+
+```ts
+import 'maplibre-gl/dist/maplibre-gl.css';
+```
+
+## Basic map example
+
+```tsx
+import {useEffect, useRef, useState} from 'react';
+import {AbsoluteFill, useDelayRender, useVideoConfig} from 'remotion';
+import * as maplibregl from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+
+const zurich: [number, number] = [8.5417, 47.3769];
+
+export const MyComposition = () => {
+ const containerRef = useRef(null);
+ const {delayRender, continueRender} = useDelayRender();
+ const {width, height} = useVideoConfig();
+ const [loadingHandle] = useState(() => delayRender('Loading map'));
+
+ useEffect(() => {
+ if (!containerRef.current) {
+ return;
+ }
+
+ maplibregl.setWorkerUrl(
+ URL.createObjectURL(
+ new Blob(
+ [`import "https://unpkg.com/maplibre-gl@${maplibregl.getVersion()}/dist/maplibre-gl-worker.mjs";`],
+ {type: 'text/javascript'},
+ ),
+ ),
+ );
+
+ const mapInstance = new maplibregl.Map({
+ container: containerRef.current,
+ style: 'https://demotiles.maplibre.org/style.json',
+ center: zurich,
+ zoom: 7,
+ interactive: false,
+ attributionControl: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {
+ preserveDrawingBuffer: true,
+ },
+ });
+
+ mapInstance.on('load', () => {
+ mapInstance.jumpTo({center: zurich, zoom: 7});
+ mapInstance.once('idle', () => {
+ continueRender(loadingHandle);
+ });
+ });
+ }, [continueRender, loadingHandle]);
+
+ return (
+
+
+
+ );
+};
+```
+
+Animated examples should keep the loaded map in React state and skip per-frame updates until that state is set.
+
+## Animated flight route example
+
+This example shows the recommended pattern for route animations:
+
+- Turf creates the route and markers.
+- Turf slices the route for line reveal animation.
+- The camera has a separate route from the target route.
+- MapLibre's `calculateCameraOptionsFromTo()` is used for camera movement.
+- Frame 0 is prepared before `continueRender()`.
+
+```tsx
+import * as turf from '@turf/turf';
+import {useEffect, useRef, useState} from 'react';
+import {
+ AbsoluteFill,
+ Easing,
+ interpolate,
+ useCurrentFrame,
+ useDelayRender,
+ useVideoConfig,
+} from 'remotion';
+import * as maplibregl from 'maplibre-gl';
+import {type GeoJSONSource, type Map} from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+
+const greatCircleLine = (from: [number, number], to: [number, number]) => {
+ const route = turf.greatCircle(from, to, {npoints: 100});
+
+ if (route.geometry.type === 'LineString') {
+ return turf.lineString(route.geometry.coordinates);
+ }
+
+ // Great-circle routes crossing the antimeridian can become MultiLineString.
+ // Keep the example valid by choosing the longest segment.
+ const longestSegment = route.geometry.coordinates.reduce((longest, segment) => {
+ return segment.length > longest.length ? segment : longest;
+ });
+
+ return turf.lineString(longestSegment);
+};
+
+const targetRoute = greatCircleLine(zurich, newYork);
+const targetRouteDistance = turf.length(targetRoute);
+
+const cameraRoute = greatCircleLine(zurich, newYork);
+const cameraRouteDistance = turf.length(cameraRoute);
+
+const cityMarkers = turf.featureCollection([
+ turf.point(zurich, {name: 'Zurich'}),
+ turf.point(newYork, {name: 'New York'}),
+]);
+
+const clampProgress = (progress: number) => Math.min(1, Math.max(0, progress));
+
+const distanceAlong = (totalDistance: number, progress: number) => {
+ // Keep the route non-empty at progress 0; Turf can error on zero-length slices.
+ return Math.max(0.001, totalDistance * clampProgress(progress));
+};
+
+const getPartialTargetRoute = (progress: number) => {
+ return turf.lineSliceAlong(
+ targetRoute,
+ 0,
+ distanceAlong(targetRouteDistance, progress),
+ );
+};
+
+const getCameraOptions = (
+ map: Map,
+ progress: number,
+ cameraAltitudeMeters: number,
+ cameraLatitudeOffset: number,
+) => {
+ const target = turf.along(
+ targetRoute,
+ distanceAlong(targetRouteDistance, progress),
+ ).geometry.coordinates;
+ const camera = turf.along(
+ cameraRoute,
+ distanceAlong(cameraRouteDistance, progress),
+ ).geometry.coordinates;
+
+ return map.calculateCameraOptionsFromTo(
+ new maplibregl.LngLat(camera[0], camera[1] - cameraLatitudeOffset),
+ cameraAltitudeMeters,
+ new maplibregl.LngLat(target[0], target[1]),
+ );
+};
+
+export const MyComposition = () => {
+ const containerRef = useRef(null);
+ const frame = useCurrentFrame();
+ const {delayRender, continueRender} = useDelayRender();
+ const {durationInFrames, height, width} = useVideoConfig();
+ const [map, setMap] = useState(null);
+ const [loadingHandle] = useState(() => delayRender('Loading MapLibre map'));
+
+ useEffect(() => {
+ if (!containerRef.current) {
+ return;
+ }
+
+ maplibregl.setWorkerUrl(
+ URL.createObjectURL(
+ new Blob(
+ [`import "https://unpkg.com/maplibre-gl@${maplibregl.getVersion()}/dist/maplibre-gl-worker.mjs";`],
+ {type: 'text/javascript'},
+ ),
+ ),
+ );
+
+ const mapInstance = new maplibregl.Map({
+ container: containerRef.current,
+ style: 'https://demotiles.maplibre.org/style.json',
+ center: zurich,
+ zoom: 7,
+ interactive: false,
+ attributionControl: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {
+ preserveDrawingBuffer: true,
+ },
+ });
+
+ mapInstance.on('load', () => {
+ mapInstance.addSource('trace', {
+ type: 'geojson',
+ data: getPartialTargetRoute(0),
+ });
+
+ mapInstance.addLayer({
+ id: 'trace-line',
+ type: 'line',
+ source: 'trace',
+ layout: {
+ 'line-cap': 'round',
+ 'line-join': 'round',
+ },
+ paint: {
+ 'line-color': '#111111',
+ 'line-width': 7,
+ },
+ });
+
+ mapInstance.addSource('city-markers', {
+ type: 'geojson',
+ data: cityMarkers,
+ });
+
+ mapInstance.addLayer({
+ id: 'city-marker-dots',
+ type: 'circle',
+ source: 'city-markers',
+ paint: {
+ 'circle-color': '#f03b20',
+ 'circle-radius': 12,
+ 'circle-stroke-color': '#ffffff',
+ 'circle-stroke-width': 4,
+ },
+ });
+
+ mapInstance.addLayer({
+ id: 'city-marker-labels',
+ type: 'symbol',
+ source: 'city-markers',
+ layout: {
+ 'text-allow-overlap': true,
+ 'text-anchor': 'top',
+ 'text-field': ['get', 'name'],
+ 'text-offset': [0, 0.9],
+ 'text-size': 28,
+ },
+ paint: {
+ 'text-color': '#111111',
+ 'text-halo-color': '#ffffff',
+ 'text-halo-width': 3,
+ },
+ });
+
+ mapInstance.jumpTo(getCameraOptions(mapInstance, 0, 180000, 1.1));
+ mapInstance.once('idle', () => {
+ setMap(mapInstance);
+ continueRender(loadingHandle);
+ });
+ });
+ }, [continueRender, loadingHandle]);
+
+ useEffect(() => {
+ if (!map) {
+ return;
+ }
+
+ const handle = delayRender('Rendering MapLibre frame');
+ const timelineProgress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ });
+ const travelProgress = interpolate(timelineProgress, [0.2, 0.82], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ });
+ const cameraAltitudeMeters = interpolate(
+ timelineProgress,
+ [0, 0.28, 0.74, 1],
+ [180000, 2200000, 2200000, 180000],
+ {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ },
+ );
+ const cameraLatitudeOffset = interpolate(
+ timelineProgress,
+ [0, 0.28, 0.74, 1],
+ [1.1, 8, 8, 1.1],
+ {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ },
+ );
+ const trace = map.getSource('trace') as GeoJSONSource | undefined;
+
+ trace?.setData(getPartialTargetRoute(travelProgress));
+ map.jumpTo(
+ getCameraOptions(
+ map,
+ travelProgress,
+ cameraAltitudeMeters,
+ cameraLatitudeOffset,
+ ),
+ );
+
+ map.once('idle', () => continueRender(handle));
+ // Force an idle event even if the camera parameters are unchanged from the previous frame.
+ map.triggerRepaint();
+ }, [continueRender, delayRender, durationInFrames, frame, map]);
+
+ return (
+
+
+
+ );
+};
+```
+
+## Camera guidance
+
+Use MapLibre's camera helper for camera movement:
+
+```ts
+map.calculateCameraOptionsFromTo(cameraLngLat, cameraAltitudeMeters, targetLngLat);
+```
+
+A good pattern is to keep two concepts separate:
+
+- `targetRoute`: where the animated line is and where the camera looks.
+- `cameraRoute`: where the camera moves.
+
+Then use Turf to read positions from both routes for the same progress value:
+
+```ts
+const target = turf.along(targetRoute, targetDistance * progress).geometry.coordinates;
+const camera = turf.along(cameraRoute, cameraDistance * progress).geometry.coordinates;
+
+map.jumpTo(
+ map.calculateCameraOptionsFromTo(
+ new maplibregl.LngLat(camera[0], camera[1]),
+ cameraAltitudeMeters,
+ new maplibregl.LngLat(target[0], target[1]),
+ ),
+);
+```
+
+For zoom-out / travel / zoom-in animations, animate travel progress separately from camera altitude. Camera altitude is measured in meters. This avoids heavy custom camera math.
+
+## Lines
+
+Use GeoJSON sources for lines. Unless the user asks, do not add glow effects or extra decorative points.
+
+For geodesic flight routes, use Turf:
+
+```ts
+const line = greatCircleLine(start, end);
+const distance = turf.length(line);
+const partialLine = turf.lineSliceAlong(
+ line,
+ 0,
+ // Keep the route non-empty at progress 0.
+ Math.max(0.001, distance * progress),
+);
+```
+
+For a visually straight line on the map, use a simple GeoJSON `LineString` between the two points instead of `greatCircle()`.
+
+## Markers and labels
+
+Use map-native GeoJSON layers for markers and labels:
+
+```tsx
+mapInstance.addSource('markers', {
+ type: 'geojson',
+ data: turf.featureCollection([
+ turf.point([-118.2437, 34.0522], {name: 'Los Angeles'}),
+ ]),
+});
+
+mapInstance.addLayer({
+ id: 'marker-dots',
+ type: 'circle',
+ source: 'markers',
+ paint: {
+ 'circle-color': '#f03b20',
+ 'circle-radius': 12,
+ 'circle-stroke-color': '#ffffff',
+ 'circle-stroke-width': 4,
+ },
+});
+
+mapInstance.addLayer({
+ id: 'marker-labels',
+ type: 'symbol',
+ source: 'markers',
+ layout: {
+ 'text-allow-overlap': true,
+ 'text-anchor': 'top',
+ 'text-field': ['get', 'name'],
+ 'text-offset': [0, 0.9],
+ 'text-size': 28,
+ },
+ paint: {
+ 'text-color': '#111111',
+ 'text-halo-color': '#ffffff',
+ 'text-halo-width': 3,
+ },
+});
+```
+
+Make marker sizes and label font sizes large enough for the composition resolution.
+
+## Styles
+
+Default to the stock MapLibre demo style:
+
+```ts
+style: 'https://demotiles.maplibre.org/style.json'
+```
+
+If the user requests another style, use any valid MapLibre style JSON URL.
+
+## Rendering
+
+For WebGL map renders, prefer single concurrency and ANGLE:
+
+```bash
+bunx remotion render [composition-id] out/video.mp4 --gl=angle --concurrency=1
+```
+
+Use the equivalent package runner for the project. In npm projects, use `npx`; in Bun projects, use `bunx`.
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/maplibre/references/render-stability.md b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maplibre/references/render-stability.md
new file mode 100644
index 0000000..fc40033
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maplibre/references/render-stability.md
@@ -0,0 +1,64 @@
+# Moving Map Render Stability
+
+Read this reference before building a moving 2D MapTiler scene or diagnosing a wavering Remotion render.
+
+## Symptom and cause
+
+If basemap detail shimmers or jitters during a pan/zoom, the likely cause is per-frame `map.jumpTo()`.
+Headless MapTiler capture can resample both vector hillshade and satellite imagery differently frame to
+frame. Tile retries, easing changes, and label changes do not solve that renderer effect.
+
+## Required pattern: fixed map plate
+
+For any 2D pan/zoom:
+
+1. Render the MapTiler canvas once at the largest required zoom in an oversized container. Size it from the camera route and keep each dimension below the browser's reliable WebGL render-buffer limit (commonly 4096 px). Do **not** blindly use 3×: a 1920×1080 composition becomes 5760 px wide and Chromium may silently downsample it, causing visible pixelation during the CSS zoom.
+2. Keep the map's camera static.
+3. For each frame, calculate the approved target centre/zoom, then move the canvas with CSS `translate` + `scale`.
+4. Apply the same transform to every projected HTML overlay.
+5. Continue to animate GeoJSON data and paint properties imperatively; only the renderer camera is frozen.
+
+Keep pitch and bearing constant. Use a 3D engine such as Cesium for genuine changing pitch/bearing or a terrain flythrough.
+
+```ts
+const baseZoom = Math.max(start.zoom, end.zoom);
+const map = new maptilersdk.Map({
+ container,
+ style,
+ center: end.center,
+ zoom: baseZoom,
+ pitch: end.pitch ?? 0,
+ bearing: end.bearing ?? 0,
+ interactive: false,
+ fadeDuration: 0,
+ canvasContextAttributes: {preserveDrawingBuffer: true},
+});
+
+// Per Remotion frame. `camera` is the approved centre/zoom interpolation.
+const projected = map.project(camera.center);
+const scale = 2 ** (camera.zoom - baseZoom);
+const plate = {
+ transform: `translate(${width / 2 - projected.x * scale}px, ${height / 2 - projected.y * scale}px) scale(${scale})`,
+ transformOrigin: "0 0",
+};
+
+// Convert label projection with exactly the same plate transform.
+const labelX = labelPoint.x * scale + width / 2 - projected.x * scale;
+const labelY = labelPoint.y * scale + height / 2 - projected.y * scale;
+```
+
+### Plate sizing and sharpness
+
+- Render at the maximum zoom reached by **any** camera waypoint, including intermediate or hold cameras. The CSS scale should never exceed `1`; otherwise the plate is being enlarged.
+- Centre the frozen map on the midpoint of the camera route's geographic extent, not automatically on the final camera. This minimizes required overscan.
+- Keep the largest canvas dimension at or below 4096 px unless the actual render environment has been tested with a larger `MAX_RENDERBUFFER_SIZE`.
+- For 1920×1080, a 3840×2160 plate is a safe default. For 1080×1920, use approximately 2700×3840 when the route needs extra horizontal pan room.
+- If the route cannot fit within that plate at the required zoom, split the shot into two fixed plates with a deliberate editorial transition. Do not trade sharpness for one enormous canvas.
+- Distinguish failure modes: repeating shimmer means the live renderer is moving; steadily soft tiles during a CSS push means the fixed plate is underspecified, internally downsampled, or being scaled above `1`.
+
+## Verification
+
+- Render a short MP4, not only a Studio preview.
+- Inspect static terrain texture and satellite detail while the camera moves.
+- If any underlying map detail wavers, use the fixed map plate. Do not approve it as a minor preview artefact.
+- Render WebGL with `--gl=angle`, `preserveDrawingBuffer:true`, and conservative concurrency (`1`) while validating.
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/TECHNIQUE.md b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/TECHNIQUE.md
new file mode 100644
index 0000000..d358791
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/TECHNIQUE.md
@@ -0,0 +1,80 @@
+# MapTiler maps in Remotion
+
+MapTiler is a good solution for map animations where geographics features should be drawn as annotations on top of the map: Country borders, rivers, labels for POIs.
+
+## MapTiler SDK (`@maptiler/sdk`)
+
+Draw the basemap plus MapTiler Planet vector layers and custom GeoJSON into a WebGL canvas. Default styled-vector starting point: `MapStyle.BASIC`; satellite is an equally valid choice.
+
+## Remotion
+
+Imperatively update `setData`/`setPaintProperty`.
+
+Use `jumpTo` only for a static shot, or a fixed map plate for any pan/zoom.
+Gate with [`delayRender`](https://www.remotion.dev/docs/delay-render.md) until `map.once('idle')`.
+
+Use `preserveDrawingBuffer:true`.
+
+Render labels as positioned [``](https://www.remotion.dev/docs/interactive.md) elements.
+
+Env `REMOTION_MAPTILER_KEY` (unrestricted). Init the map once (ref guard); update imperatively per frame.
+
+When constructing MapLibre/MapTiler layer objects, omit optional properties that are absent.
+In particular, use `...(layer.filter ? {filter: layer.filter} : {})`; do not pass `filter: undefined`. An undefined filter can suppress the layer while separately created halo or border layers continue rendering, producing missing country fills and dark marker halos with no coloured cores.
+
+Drive animation from `useCurrentFrame()` rather than CSS transitions or browser timers.
+
+## Choose the source for each map element
+
+Do not begin by manufacturing GeoJSON. First check whether MapTiler Planet already exposes the element as filtered vector data.
+
+### MapTiler vector
+
+Use it when the feature exists in a provider `source-layer`, its attributes support an exact filter, and provider geometry is editorially acceptable.
+
+### Hybrid
+
+Use it when ordinary geographic context can come from MapTiler while the claim depends on custom
+evidence.
+
+Animate each layer according to its source and meaning.
+
+MapTiler vector features remain split across tiles. Do not use them for a semantic start-to-end line draw; extract, verify, order, and bake that element to GeoJSON first. Read **`references/map-data-sources.md`** and reuse **`assets/MapTilerVectorElement.ts`** for provider-layer setup and per-frame paint updates.
+
+## Motion stability
+
+**Do not call `map.jumpTo()` on every Remotion frame when the camera moves.** In headless capture it can make both MapTiler hillshade **and satellite imagery** shimmer/jitter, even when the source tiles load correctly. This is renderer resampling, not a data, network, or label problem.
+
+For the implementation, read **`references/render-stability.md`** before building or debugging any moving map. It contains the fixed-map-plate recipe, diagnostics, and render checks.
+
+- Use the live MapTiler camera only for a static shot.
+- Keep pitch and bearing constant for a fixed plate. This technique does not implement a genuine changing 3D camera.
+- Verify the moving preview and a short rendered MP4 before approving a beat. If any basemap detail wavers, switch to the fixed-plate pattern; do not try to solve it with tile retries or camera easing.
+
+## Drawing rivers
+
+Use `turf.lineSliceAlong(line, 0, lineKm*reveal)` to draw rivers.
+
+## Source selection
+
+Use MapTiler vector layers for suitable provider features and custom GeoJSON for story-specific or ordered geometry. If the beat needs country-entry triggers or a progressive line draw, run `scripts/prep-geo.mjs` to bake `country-meta.json`, `borders.geojson`, and the ordered line. Details → `references/map-data-sources.md` and `references/map-geo-prep.md`.
+
+## Keep it minmal
+
+Strip clutter on `load`: remove `symbol` layers (place labels) and `/other border/i` (admin-1 inner borders); hide the logo via CSS. Keep country + disputed borders.
+
+## Files
+
+Use as reference:
+
+- `assets/RiverReveal.tsx` — the main component.
+- `assets/MapTilerVectorElement.ts` — filtered MapTiler Planet elements.
+- `assets/CountryLabel.tsx` — reusable example label.
+- `assets/tokens.ts` — example palette and durations.
+- `assets/example-Root.tsx` — minimal composition scaffold.
+- `assets/sample-data/` — example route and generated country metadata.
+- `scripts/prep-geo.mjs` — geo pipeline.
+- `references/map-explainer-architecture.md` — timing model and implementation.
+- `references/map-data-sources.md` — provider vector versus custom GeoJSON selection.
+- `references/map-geo-prep.md` — basemap stripping and geo preparation.
+- `references/render-stability.md` — camera motion and stable headless renders.
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/assets/CountryLabel.tsx b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/assets/CountryLabel.tsx
new file mode 100644
index 0000000..3e4b887
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/assets/CountryLabel.tsx
@@ -0,0 +1,70 @@
+import React from 'react';
+import {Easing, interpolate} from 'remotion';
+
+// Reusable country label. Supply typography and final values from the consuming project; the CSS custom
+// properties below provide neutral fallbacks. Positioned by its centre (x,y in screen px).
+export const CountryLabel: React.FC<{
+ name: string;
+ color: string;
+ reveal: number;
+ x: number;
+ y: number;
+}> = ({name, color, reveal, x, y}) => {
+ const e = interpolate(reveal, [0, 1], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.3333333333333333, 1, 0.6666666666666666, 1),
+ });
+ return (
+
+
+ {/* accent rule — draws out from the centre in the country's colour */}
+
+
+ {name}
+
+
+
;
+ paint: Record;
+};
+
+const SOURCE_ID = 'maptiler-planet';
+
+export const addMapTilerVectorElement = (
+ map: any,
+ apiKey: string,
+ element: MapTilerVectorElement,
+ beforeId?: string,
+) => {
+ if (!map.getSource(SOURCE_ID)) {
+ map.addSource(SOURCE_ID, {
+ type: 'vector',
+ url: `https://api.maptiler.com/tiles/v3/tiles.json?key=${apiKey}`,
+ });
+ }
+
+ if (map.getLayer(element.id)) return;
+
+ map.addLayer(
+ {
+ id: element.id,
+ type: element.type,
+ source: SOURCE_ID,
+ 'source-layer': element.sourceLayer,
+ ...(element.filter ? {filter: element.filter} : {}),
+ ...(element.minzoom === undefined ? {} : {minzoom: element.minzoom}),
+ ...(element.maxzoom === undefined ? {} : {maxzoom: element.maxzoom}),
+ ...(element.layout ? {layout: element.layout} : {}),
+ paint: element.paint,
+ },
+ beforeId,
+ );
+};
+
+export const setVectorElementPaint = (
+ map: any,
+ layerId: string,
+ paint: Record,
+) => {
+ for (const [property, value] of Object.entries(paint)) {
+ map.setPaintProperty(layerId, property, value);
+ }
+};
+
+// Example:
+//
+// addMapTilerVectorElement(map, process.env.REMOTION_MAPTILER_KEY!, {
+// id: "story-river",
+// sourceLayer: "waterway",
+// type: "line",
+// filter: [
+// "all",
+// ["==", ["get", "class"], "river"],
+// ["==", ["coalesce", ["get", "name_en"], ["get", "name"]], "Yarlung Tsangpo"],
+// ],
+// layout: {"line-cap": "round", "line-join": "round"},
+// paint: {"line-color": "#E8F7FF", "line-width": 3, "line-opacity": 0},
+// });
+//
+// Per Remotion frame:
+// setVectorElementPaint(map, "story-river", {
+// "line-opacity": reveal,
+// "line-width": 2 + reveal * 2,
+// });
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/assets/RiverReveal.tsx b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/assets/RiverReveal.tsx
new file mode 100644
index 0000000..a0ade54
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/assets/RiverReveal.tsx
@@ -0,0 +1,363 @@
+import * as maptilersdk from '@maptiler/sdk';
+import * as turf from '@turf/turf';
+import React, {useEffect, useRef, useState} from 'react';
+import '@maptiler/sdk/dist/maptiler-sdk.css';
+import {
+ AbsoluteFill,
+ Easing,
+ continueRender,
+ delayRender,
+ interpolate,
+ useCurrentFrame,
+ useVideoConfig,
+} from 'remotion';
+import {CountryLabel} from './CountryLabel';
+import countryMeta from './sample-data/country-meta.json';
+import flowCoords from './sample-data/yarlung-flow.json';
+import {COLORS, COUNTRY, COUNTRY_DARK, FILL_OPACITY} from './tokens';
+
+// Sample route reveal. Replace the imported sample geometry, names, timing, and visual tokens in the
+// consuming production. The renderer stays static; approved centre/zoom motion is a CSS plate transform.
+
+maptilersdk.config.apiKey = process.env.REMOTION_MAPTILER_KEY as string;
+
+const line = turf.lineString(flowCoords as [number, number][]);
+const lineKm = turf.length(line);
+
+const START = {
+ center: [89.6, 27.7] as [number, number],
+ zoom: 4.75,
+ pitch: 0,
+ bearing: 0,
+};
+const END = {
+ center: [90.2, 27.0] as [number, number],
+ zoom: 5.05,
+ pitch: 0,
+ bearing: 0,
+};
+const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+const clamp01 = (v: number) => Math.max(0, Math.min(1, v));
+
+const ORDER = ['china', 'india', 'bangladesh'] as const;
+type Country = (typeof ORDER)[number];
+const META = countryMeta as Record<
+ Country,
+ {stop: number; anchor: [number, number]; border: [number, number][][]}
+>;
+const countryPolygons = {
+ type: 'FeatureCollection' as const,
+ features: ORDER.map((country) => ({
+ type: 'Feature' as const,
+ properties: {country},
+ geometry: {
+ type: 'MultiPolygon' as const,
+ coordinates: META[country].border.map((ring) => [ring]),
+ },
+ })),
+};
+
+// Pre-build each country's border as ordered segments with cumulative lengths (for the multi-segment draw).
+const DRAW = Object.fromEntries(
+ ORDER.map((c) => {
+ const segLines = META[c].border.map((s) => turf.lineString(s));
+ const segLen = segLines.map((l) => turf.length(l));
+ const cum: number[] = [];
+ let acc = 0;
+ for (const L of segLen) {
+ cum.push(acc);
+ acc += L;
+ }
+ return [c, {segLines, segLen, cum, total: acc}];
+ }),
+) as Record<
+ Country,
+ {segLines: any[]; segLen: number[]; cum: number[]; total: number}
+>;
+
+// Reveal the portion of the border between fromKm and toKm as a MultiLineString (no joins across gaps).
+const sliceBorder = (
+ d: (typeof DRAW)[Country],
+ fromKm: number,
+ toKm: number,
+) => {
+ const out: number[][][] = [];
+ for (let i = 0; i < d.segLines.length; i++) {
+ const start = d.cum[i],
+ end = start + d.segLen[i];
+ const a = Math.max(fromKm, start),
+ b = Math.min(toKm, end);
+ if (b - a <= 0.0008) continue;
+ out.push(
+ turf.lineSliceAlong(d.segLines[i], a - start, b - start).geometry
+ .coordinates,
+ );
+ }
+ return {
+ type: 'Feature' as const,
+ properties: {},
+ geometry: {type: 'MultiLineString' as const, coordinates: out},
+ };
+};
+const EMPTY = {
+ type: 'Feature' as const,
+ properties: {},
+ geometry: {type: 'MultiLineString' as const, coordinates: [] as number[][][]},
+};
+
+// --- Timing (seconds). River draws over [RIVER_START, RIVER_END]; each country triggers when the river
+// reaches it (stop · span), then runs border → fill → label. Beat length is derived from these. ---
+const RIVER_START = 0.3;
+const RIVER_END = 8.0;
+const BORDER_S = 2.5;
+const FILL_S = 1.0;
+const LABEL_S = 0.7;
+const trigger = (c: Country) =>
+ RIVER_START + META[c].stop * (RIVER_END - RIVER_START);
+
+export const RiverReveal: React.FC = () => {
+ const ref = useRef(null);
+ const started = useRef(false);
+ const frame = useCurrentFrame();
+ const {fps, durationInFrames, width, height} = useVideoConfig();
+ const [map, setMap] = useState(null);
+ const [labels, setLabels] = useState<
+ Record
+ >({});
+ const [plate, setPlate] = useState({x: 0, y: 0, scale: 1});
+ const [handle] = useState(() => delayRender('maptiler init A'));
+
+ useEffect(() => {
+ if (!ref.current || started.current) return;
+ started.current = true;
+ const m = new maptilersdk.Map({
+ container: ref.current,
+ style: maptilersdk.MapStyle.BASIC,
+ center: END.center,
+ zoom: Math.max(START.zoom, END.zoom),
+ pitch: END.pitch,
+ bearing: END.bearing,
+ interactive: false,
+ attributionControl: true,
+ navigationControl: false,
+ geolocateControl: false,
+ maptilerLogo: true,
+ fadeDuration: 0,
+ canvasContextAttributes: {preserveDrawingBuffer: true},
+ } as any);
+
+ m.on('load', () => {
+ // Strip basemap labels (symbols) AND the inner admin-1 borders ('Other border[ dash]',
+ // admin_level 3–10) to cut basemap clutter. Keep country + disputed borders.
+ for (const l of m.getStyle().layers as any[])
+ if (l.type === 'symbol' || /other border/i.test(l.id))
+ m.removeLayer(l.id);
+
+ m.addSource('countries', {type: 'geojson', data: countryPolygons});
+ for (const c of ORDER) {
+ m.addLayer({
+ id: `fill-${c}`,
+ type: 'fill',
+ source: 'countries',
+ filter: ['==', ['get', 'country'], c],
+ paint: {'fill-color': COUNTRY[c], 'fill-opacity': 0},
+ });
+ }
+ // Per country: just the border that draws on, settled to a darker shade of the country colour
+ // (the electricity now lives on the river, not the borders).
+ for (const c of ORDER) {
+ m.addSource(`trail-${c}`, {type: 'geojson', data: EMPTY});
+ m.addLayer({
+ id: `trail-${c}`,
+ type: 'line',
+ source: `trail-${c}`,
+ layout: {'line-cap': 'round', 'line-join': 'round'},
+ paint: {
+ 'line-color': COUNTRY_DARK[c],
+ 'line-width': 2,
+ 'line-opacity': 0.95,
+ },
+ });
+ }
+
+ const seed = turf.lineSliceAlong(
+ line,
+ 0,
+ Math.max(0.001, lineKm * 0.001),
+ );
+ m.addSource('river', {type: 'geojson', data: seed});
+ m.addSource('river-head', {type: 'geojson', data: seed});
+ // Electric water: soft blue glow → icy core → white-hot leading head with its own glow.
+ m.addLayer({
+ id: 'river-glow',
+ type: 'line',
+ source: 'river',
+ layout: {'line-cap': 'round', 'line-join': 'round'},
+ paint: {
+ 'line-color': '#49C6FF',
+ 'line-width': 11,
+ 'line-opacity': 0.32,
+ 'line-blur': 6,
+ },
+ });
+ m.addLayer({
+ id: 'river-line',
+ type: 'line',
+ source: 'river',
+ layout: {'line-cap': 'round', 'line-join': 'round'},
+ paint: {'line-color': COLORS.river, 'line-width': 3},
+ });
+ m.addLayer({
+ id: 'river-headglow',
+ type: 'line',
+ source: 'river-head',
+ layout: {'line-cap': 'round', 'line-join': 'round'},
+ paint: {
+ 'line-color': COLORS.riverHeadGlow,
+ 'line-width': 16,
+ 'line-opacity': 0,
+ 'line-blur': 9,
+ },
+ });
+ m.addLayer({
+ id: 'river-head',
+ type: 'line',
+ source: 'river-head',
+ layout: {'line-cap': 'round', 'line-join': 'round'},
+ paint: {
+ 'line-color': COLORS.riverHead,
+ 'line-width': 4.5,
+ 'line-opacity': 0,
+ },
+ });
+
+ m.once('idle', () => {
+ setMap(m);
+ continueRender(handle);
+ });
+ });
+ }, [handle]);
+
+ useEffect(() => {
+ if (!map) return;
+ const h = delayRender(`frame A ${frame}`);
+ const t = frame / fps; // seconds
+ const tt = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ });
+
+ // River draw
+ const reveal = interpolate(t, [RIVER_START, RIVER_END], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ });
+ const riverDrawnKm = lineKm * reveal;
+ (map.getSource('river') as any)?.setData(
+ turf.lineSliceAlong(line, 0, Math.max(0.001, riverDrawnKm)),
+ );
+ // Electric draw-head leading the river: white-hot core + glow, fading out once the river completes.
+ const riverHeadKm = lineKm * 0.03;
+ (map.getSource('river-head') as any)?.setData(
+ turf.lineSliceAlong(
+ line,
+ Math.max(0, riverDrawnKm - riverHeadKm),
+ Math.max(0.001, riverDrawnKm),
+ ),
+ );
+ let riverHeadFade = 0;
+ if (reveal > 0.002 && reveal < 0.999) riverHeadFade = 1;
+ else if (reveal >= 0.999)
+ riverHeadFade = 1 - clamp01((t - RIVER_END) / 0.5);
+ map.setPaintProperty(
+ 'river-headglow',
+ 'line-opacity',
+ 0.85 * riverHeadFade,
+ );
+ map.setPaintProperty('river-head', 'line-opacity', riverHeadFade);
+
+ const camera = {
+ center: [
+ lerp(START.center[0], END.center[0], tt),
+ lerp(START.center[1], END.center[1], tt),
+ ] as [number, number],
+ zoom: lerp(START.zoom, END.zoom, tt),
+ };
+ const cameraPoint = map.project(camera.center);
+ const plateScale = 2 ** (camera.zoom - Math.max(START.zoom, END.zoom));
+ const plateX = width / 2 - cameraPoint.x * plateScale;
+ const plateY = height / 2 - cameraPoint.y * plateScale;
+
+ const pos: Record = {};
+ for (const c of ORDER) {
+ const d = DRAW[c];
+ const lt = t - trigger(c); // local seconds since this country triggered
+
+ // 1) border draws on (constant duration), settling to a darker shade — no electric head
+ const bp = interpolate(clamp01(lt / BORDER_S), [0, 1], [0, 1], {
+ easing: Easing.bezier(0.645, 0.045, 0.355, 1),
+ });
+ (map.getSource(`trail-${c}`) as any)?.setData(
+ bp <= 0 ? EMPTY : sliceBorder(d, 0, d.total * bp),
+ );
+
+ // 2) fill blooms in (overshoot then settle) after the border completes
+ const fp = clamp01((lt - BORDER_S) / FILL_S);
+ const fo = interpolate(
+ fp,
+ [0, 0.6, 1],
+ [0, FILL_OPACITY * 1.25, FILL_OPACITY],
+ {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.3333333333333333, 1, 0.6666666666666666, 1),
+ },
+ );
+ map.setPaintProperty(`fill-${c}`, 'fill-opacity', fp <= 0 ? 0 : fo);
+
+ // 3) label rises in after the fill
+ const lp = clamp01((lt - BORDER_S - FILL_S) / LABEL_S);
+ const p = map.project(META[c].anchor);
+ pos[c] = {
+ x: p.x * plateScale + plateX,
+ y: p.y * plateScale + plateY,
+ reveal: lp,
+ };
+ }
+ setLabels(pos);
+
+ setPlate({x: plateX, y: plateY, scale: plateScale});
+ map.once('idle', () => continueRender(h));
+ map.triggerRepaint();
+ }, [map, frame, fps, durationInFrames, width, height]);
+
+ return (
+
+
+
+ {ORDER.map((c) =>
+ labels[c] ? (
+
+
+ );
+};
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/assets/example-Root.tsx b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/assets/example-Root.tsx
new file mode 100644
index 0000000..4e25267
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/maptiler/assets/example-Root.tsx
@@ -0,0 +1,22 @@
+// Minimal Remotion scaffold for the map explainer. In a Remotion project (`bunx create-video@latest`,
+// blank template), this is `src/Root.tsx`; `src/index.ts` is just `registerRoot(RemotionRoot)`.
+//
+// The Composition sets DURATION (the beat) and dimensions. The component reads durationInFrames / width /
+// height from useVideoConfig(). The beat must be long enough for the last country's full sequence after
+// the river reaches it. See references/map-explainer-architecture.md §2.
+// Render with: bunx remotion render src/index.ts MapExplainer out.mp4 --gl=angle --concurrency=1 --timeout=120000
+
+import React from 'react';
+import {Composition} from 'remotion';
+import {RiverReveal} from './RiverReveal'; // → src/components/RiverReveal.tsx in your project
+
+export const RemotionRoot: React.FC = () => (
+ .geojson
+const FRAME_BBOX = [76, 14, 104, 33.5]; // [W,S,E,N] visible extent — fallback for label anchoring only
+const ANCHOR_BBOX = {
+ china: [82, 27, 96, 32],
+ india: [76, 14, 99, 31],
+ bangladesh: [86, 20, 93, 27],
+}; // [W,S,E,N] per-country label "story region"
+const NUDGE = {china: [0, 0.6], india: [-1.0, 0], bangladesh: [0, -0.6]}; // [lng,lat] label nudge
+const RIVER_SIMPLIFY_TOL = 0.006; // degrees — smooths the draw-on (bigger = simpler)
+const OUT_RIVER = resolve(root, 'out/river-flow.json');
+const OUT_META = resolve(root, 'out/country-meta.json');
+const OUT_BORDERS = resolve(root, 'out/borders.geojson');
+// =====================================================
+
+const havKm = (a, b) => {
+ const R = 6371,
+ r = Math.PI / 180;
+ const dLat = (b[1] - a[1]) * r,
+ dLng = (b[0] - a[0]) * r;
+ const h =
+ Math.sin(dLat / 2) ** 2 +
+ Math.cos(a[1] * r) * Math.cos(b[1] * r) * Math.sin(dLng / 2) ** 2;
+ return 2 * R * Math.asin(Math.sqrt(h));
+};
+
+// --- River draw-on line: take the clean routed LineString, strip a dangling final hop, simplify so the
+// wide-zoom draw-on reads as one smooth thread (no bezier — meander overshoot on a long river). ---
+const routed = read(RIVER).features[0].geometry.coordinates;
+let end = routed.length;
+while (end > 2 && havKm(routed[end - 2], routed[end - 1]) > 15) end--; // drop a final cross-braid jump if present
+const flow = turf.simplify(turf.lineString(routed.slice(0, end)), {
+ tolerance: RIVER_SIMPLIFY_TOL,
+ highQuality: true,
+}).geometry.coordinates;
+
+// --- Borders + country fills (one source, filtered per country in the component) ---
+const borders = {type: 'FeatureCollection', features: []};
+const polys = {};
+for (const name of COUNTRIES) {
+ const fc = read(BORDER(name));
+ polys[name] = fc;
+ for (const f of fc.features) {
+ f.properties = {...(f.properties || {}), country: name};
+ borders.features.push(f);
+ }
+}
+
+// --- Reveal stops: arc-length fraction of `flow` where the river first ENTERS each country. The first
+// country (headwaters) is the source, so its stop is 0; the rest are computed. ---
+const flowKm = turf.length(turf.lineString(flow));
+const insideCountry = (pt, name) =>
+ polys[name].features.some((f) => turf.booleanPointInPolygon(pt, f));
+const stops = {};
+COUNTRIES.forEach((c, i) => {
+ stops[c] = i === 0 ? 0 : 1;
+}); // 0 = headwaters; 1 = sentinel until entered
+let acc = 0;
+for (let i = 0; i < flow.length; i++) {
+ if (i > 0) acc += havKm(flow[i - 1], flow[i]);
+ const frac = acc / (flowKm || 1);
+ const pt = turf.point(flow[i]);
+ for (const c of COUNTRIES)
+ if (stops[c] === 1 && insideCountry(pt, c)) stops[c] = frac;
+}
+
+// --- Per-country meta: anchor = pole of inaccessibility of the visible landmass (centred, away from
+// borders/edges) within the country's story region + a NUDGE; border = every exterior ring from the
+// complete named source. Never crop a country or bilateral boundary to the viewport. ---
+const biggestPoly = (geom) => {
+ const rings =
+ geom.type === 'MultiPolygon' ? geom.coordinates : [geom.coordinates];
+ let best = null,
+ bestA = -1;
+ for (const c of rings) {
+ const p = turf.polygon(c);
+ const a = turf.area(p);
+ if (a > bestA) {
+ bestA = a;
+ best = p;
+ }
+ }
+ return best;
+};
+const largestPolygon = (fc) => {
+ let best = null,
+ bestA = -1;
+ for (const f of fc.features) {
+ const p = biggestPoly(f.geometry),
+ a = turf.area(p);
+ if (a > bestA) {
+ bestA = a;
+ best = p;
+ }
+ }
+ return best;
+};
+const completeExteriorSegments = (fc) => {
+ const segments = [];
+ for (const feature of fc.features) {
+ const polygons =
+ feature.geometry.type === 'MultiPolygon'
+ ? feature.geometry.coordinates
+ : [feature.geometry.coordinates];
+ for (const polygon of polygons)
+ if (polygon[0]?.length > 1) segments.push(polygon[0]);
+ }
+ return segments;
+};
+const poleOfInaccessibility = (poly) => {
+ const bb = turf.bbox(poly),
+ boundary = turf.polygonToLine(poly),
+ N = 46;
+ let best = null,
+ bestD = -1;
+ for (let i = 0; i <= N; i++)
+ for (let j = 0; j <= N; j++) {
+ const lng = bb[0] + ((bb[2] - bb[0]) * i) / N,
+ lat = bb[1] + ((bb[3] - bb[1]) * j) / N;
+ const pt = turf.point([lng, lat]);
+ if (!turf.booleanPointInPolygon(pt, poly)) continue;
+ const d = turf.pointToLineDistance(pt, boundary);
+ if (d > bestD) {
+ bestD = d;
+ best = [lng, lat];
+ }
+ }
+ return best;
+};
+const countryMeta = {};
+for (const name of COUNTRIES) {
+ const poly = largestPolygon(polys[name]);
+ const storyRegion = biggestPoly(
+ turf.bboxClip(poly, ANCHOR_BBOX[name] || FRAME_BBOX).geometry,
+ );
+ const pole = poleOfInaccessibility(storyRegion);
+ const segs = completeExteriorSegments(polys[name]);
+ const nudge = NUDGE[name] || [0, 0];
+ countryMeta[name] = {
+ stop: stops[name],
+ anchor: [pole[0] + nudge[0], pole[1] + nudge[1]],
+ border: segs,
+ };
+}
+
+mkdirSync(dirname(OUT_RIVER), {recursive: true});
+writeFileSync(OUT_RIVER, JSON.stringify(flow));
+writeFileSync(OUT_META, JSON.stringify(countryMeta));
+writeFileSync(OUT_BORDERS, JSON.stringify(borders));
+console.log(
+ 'river:',
+ flow.length,
+ 'pts ·',
+ flowKm.toFixed(0),
+ 'km · entry stops',
+ JSON.stringify(stops),
+);
+for (const n of COUNTRIES) {
+ const km = countryMeta[n].border.reduce(
+ (s, seg) => s + turf.length(turf.lineString(seg)),
+ 0,
+ );
+ console.log(
+ ` ${n}: anchor ${countryMeta[n].anchor.map((v) => v.toFixed(2)).join(',')} · border ${km.toFixed(0)} km`,
+ );
+}
+console.log(
+ "\nNext: copy out/river-flow.json + out/country-meta.json → your project's src/geo/ ; out/borders.geojson → public/geo/",
+);
diff --git a/remotion-best-practices/remotion-markup/remotion-maps/techniques/static-map/TECHNIQUE.md b/remotion-best-practices/remotion-markup/remotion-maps/techniques/static-map/TECHNIQUE.md
new file mode 100644
index 0000000..5f23bbc
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/remotion-maps/techniques/static-map/TECHNIQUE.md
@@ -0,0 +1,37 @@
+---
+name: remotion-maps-static
+description: Create a deterministic static locator map in Remotion when neither the camera nor geographic data animates.
+---
+
+# Static map
+
+Use a static image when the map only provides location context. This is the smallest, fastest, and
+most deterministic map technique.
+
+## Build
+
+1. Export or request a map image at the composition's final aspect ratio and at least its rendered
+ pixel dimensions.
+2. Store the image in the Remotion project's `public/` directory.
+3. Render it with `CanvasImage` and `staticFile()`.
+4. Add labels or markers as ordinary Remotion elements if they remain fixed.
+
+```tsx
+import React from 'react';
+import {AbsoluteFill, CanvasImage, staticFile} from 'remotion';
+
+export const StaticMap: React.FC = () => {
+ return (
+ <>
+ ` to delay when an element appears in the timeline.
+
+```tsx
+const Main = () => {
+ return (
+
+
+
+
+
+
+
+
+ );
+}
+
+export const Title = () => {
+ const frame = useCurrentFrame();
+
+ return (
+
+ Title
+
+ );
+};
+
+export const Subtitle = () => {
+ const frame = useCurrentFrame();
+
+ return (
+
+ Subtitle
+
+ );
+};
+```
+
+This will by default wrap the component in an absolute fill element.
+If the items should not be wrapped, use the `layout` prop:
+
+```tsx
+
+
+```
+
+## Premounting
+
+This loads the component in the timeline before it is actually played.
+Always premount any ``!
+
+```tsx
+
+
+```
+
+## Series
+
+Use `` when elements should play one after another without overlap.
+
+```tsx
+import { Series } from "remotion";
+
+
+
+
+
+
+
+
+ ;
+```
+
+Same as with ``, the items will be wrapped in an absolute fill element by default when using ``, unless the `layout` prop is set to `none`.
+
+### Series with overlaps
+
+Use negative offset for overlapping sequences:
+
+```tsx
+
+
+
+
+ {/* Starts 15 frames before SceneA ends */}
+
+
+```
+
+## Frame References Inside Sequences
+
+Inside a Sequence, `useCurrentFrame()` returns the local frame (starting from 0):
+
+```tsx
+
+
+```
+
+## Nested Sequences
+
+Sequences can be nested for complex timing:
+
+```tsx
+
+
+
+
+
+
+```
+
+## Nesting compositions within another
+
+To add a composition within another composition, you can use the `` component with a `width`, `height`, `durationInFrames` prop to specify the size of the composition.
+This will override the values of `useVideoConfig()` when calling inside that component.
+
+```tsx
+
+
+
+
+```
diff --git a/remotion-best-practices/remotion-markup/sfx.md b/remotion-best-practices/remotion-markup/sfx.md
new file mode 100644
index 0000000..ba2dd83
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/sfx.md
@@ -0,0 +1,51 @@
+---
+name: sfx
+description: Including sound effects
+metadata:
+ tags: sfx, sound, effect, audio
+---
+
+To include a sound effect, use the `` tag:
+
+```tsx
+import { Audio } from "@remotion/sfx";
+
+` component
+
+Apply the detected trim points using `trimBefore` and `trimAfter` (values are in frames):
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile, useVideoConfig } from "remotion";
+
+const { fps } = useVideoConfig();
+
+`, ``, ``, ``, ``, ``, or ``. The component determines both the annotation style and whether it renders behind or on top of the text.
+
+Drive `progress` from `useCurrentFrame()` so the annotation is deterministic and synchronized with the video:
+
+```tsx
+import {Circle, Highlight} from '@remotion/rough-notation';
+import {interpolate, useCurrentFrame} from 'remotion';
+
+export const TextAnnotations: React.FC = () => {
+ const frame = useCurrentFrame();
+
+ return (
+
+ This is{' '}
+
+ important
+
+ , and this is{' '}
+
+ connected
+
+ .
+
+ );
+};
+```
+
+Keep `progress` inline, hardcoded and use `interpolate` for maximum [Studio interactivity](../remotion-interactivity/REFERENCE.md).
diff --git a/remotion-best-practices/remotion-markup/timing.md b/remotion-best-practices/remotion-markup/timing.md
new file mode 100644
index 0000000..4c224f8
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/timing.md
@@ -0,0 +1,111 @@
+Drive motion with `interpolate()` over an explicit frame range.
+To customize timing, use **`Easing.bezier`** or `Easing.spring`.
+
+A simple linear interpolation is done using the `interpolate` function.
+
+```ts title="Going from 0 to 1 over 0.3 seconds"
+import { interpolate } from "remotion";
+
+const opacity = interpolate(frame, [0, 0.3 * fps], [0, 1]);
+```
+
+By default, the values are not clamped, so the value can go outside the range [0, 1].
+Here is how they can be clamped:
+
+```ts title="Going from 0 to 1 over 0.3 seconds with extrapolation"
+const opacity = interpolate(frame, [0, 0.3 * fps], [0, 1], {
+ extrapolateRight: "clamp",
+ extrapolateLeft: "clamp",
+});
+```
+
+## Studio-editable animation patterns
+
+When an animation should be editable in Remotion Studio, keep the `interpolate()` call directly in the `style` prop and prefer individual CSS transform properties:
+
+```tsx
+// 👍 Inline editable keyframes and transform shorthands
+style={{
+ scale: interpolate(frame, [0, 100], [0, 1]),
+ translate: interpolate(frame, [0, 100], ["0px 0px", "100px 100px"]),
+ rotate: interpolate(frame, [0, 100], ["20deg", "90deg"]),
+}}
+
+// 👎 Hidden values and transform strings become computed in Studio
+const translateY = interpolate(frame, [0, 100], [0, 120]);
+const rotation = interpolate(frame, [0, 100], [0, 20]);
+
+style={{
+ transform: `translateY(${translateY}px) rotate(${rotation}deg)`,
+}}
+```
+
+Use `transform` strings only when individual CSS transform properties do not cover the effect, such as `skew()`, `perspective()`, or order-sensitive multi-transform chains.
+
+## Spring easing
+
+A nice push movement with no bounce:
+
+```ts
+import { interpolate, Easing } from "remotion";
+
+const opacity = interpolate(frame, [0, 0.3 * fps], [0, 1], {
+ easing: Easing.spring({damping: 200}),
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+});
+```
+
+## Bézier easing
+
+Pass values like you would to a CSS cubic-bezier function.
+
+```ts
+import { interpolate, Easing } from "remotion";
+
+const opacity = interpolate(frame, [0, 0.3 * fps], [0, 1], {
+ easing: Easing.bezier(0.16, 1, 0.3, 1),
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+});
+```
+
+## Animating scale
+
+When animating scale, if the output is linear, the perceived scale would be smaller the larger the scale gets.
+Use this option to compensate:
+
+```ts
+const scale = interpolate(frame, [0, 0.3 * fps], [0, 1], {
+ easing: Easing.bezier(0.16, 1, 0.3, 1),
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ output: 'perceptual-scale' // <- Add this to scale animations
+});
+```
+
+## Multiple keyframes
+
+Add as many keyframes as you want. For multiple easings, pass an array with `n - 1` items:
+
+```ts
+const scale = interpolate(frame, [0, 1 * fps, 9 * fps, 10 * fps], [0, 1, 1, 0], {
+ easing: [Easing.bezier(0.16, 1, 0.3, 1), Easing.linear, Easing.spring({damping: 200})],
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ output: 'perceptual-scale' // <- Add this to scale animations
+});
+```
+
+## Posterization
+
+You can intentionally reduce the frame rate for artistic reason. Use if it makes sense.
+
+```ts
+const scale = interpolate(frame, [0, 1 * fps], [0, 1], {
+ easing: Easing.bezier(0.16, 1, 0.3, 1),
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ posterize: 3 // Only every 3rd frame is sampled
+});
+```
diff --git a/remotion-best-practices/remotion-markup/transitions.md b/remotion-best-practices/remotion-markup/transitions.md
new file mode 100644
index 0000000..a2630d3
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/transitions.md
@@ -0,0 +1,239 @@
+---
+name: transitions
+description: Scene transitions and overlays for Remotion using TransitionSeries.
+metadata:
+ tags: transitions, overlays, fade, slide, wipe, scenes
+---
+
+## TransitionSeries
+
+`` arranges scenes and supports two ways to enhance the cut point between them:
+
+- **Transitions** (``) — crossfade, slide, wipe, etc. between two scenes. Shortens the timeline because both scenes play simultaneously during the transition.
+- **Overlays** (``) — render an effect (e.g. a light leak) on top of the cut point without shortening the timeline.
+
+Children are absolutely positioned.
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/transitions
+```
+
+## Transition example
+
+```tsx
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
+
+
+
+
+
+
+ ;
+```
+
+## Overlay example
+
+Any React component can be used as an overlay. For a ready-made effect, see the **light-leaks** rule.
+
+```tsx
+import {lightLeak} from '@remotion/effects/light-leak';
+import {TransitionSeries} from '@remotion/transitions';
+import {interpolate, Solid, useCurrentFrame, useVideoConfig} from 'remotion';
+
+const LightLeakOverlay: React.FC = () => {
+ const frame = useCurrentFrame();
+ const {durationInFrames, height, width} = useVideoConfig();
+
+ return (
+
+
+
+
+
+
+
+ ;
+```
+
+## Mixing transitions and overlays
+
+Transitions and overlays can coexist in the same ``, but an overlay cannot be adjacent to a transition or another overlay.
+
+```tsx
+import {lightLeak} from '@remotion/effects/light-leak';
+import {TransitionSeries, linearTiming} from '@remotion/transitions';
+import {fade} from '@remotion/transitions/fade';
+import {interpolate, Solid, useCurrentFrame, useVideoConfig} from 'remotion';
+
+const LightLeakOverlay: React.FC = () => {
+ const frame = useCurrentFrame();
+ const {durationInFrames, height, width} = useVideoConfig();
+
+ return (
+
+
+
+
+
+
+
+
+
+ ;
+```
+
+## Transition props
+
+`` requires:
+
+- `presentation` — the visual effect (e.g. `fade()`, `slide()`, `wipe()`).
+- `timing` — controls speed and easing (e.g. `linearTiming()`, `springTiming()`).
+
+## Overlay props
+
+`` accepts:
+
+- `durationInFrames` — how long the overlay is visible (positive integer).
+- `offset?` — shifts the overlay relative to the cut point center. Positive = later, negative = earlier. Default: `0`.
+
+## Available transition types
+
+Import transitions from their respective modules:
+
+```tsx
+import { fade } from "@remotion/transitions/fade";
+import { slide } from "@remotion/transitions/slide";
+import { wipe } from "@remotion/transitions/wipe";
+import { flip } from "@remotion/transitions/flip";
+import { clockWipe } from "@remotion/transitions/clock-wipe";
+```
+
+## Slide transition with direction
+
+```tsx
+import { slide } from "@remotion/transitions/slide";
+
+` directly in the composition and hardcode its timing props. `from={0}` may be omitted:
+
+```tsx
+` must be a separate JSX node. Add a descriptive `name` when useful in the Studio timeline.
+- `from`, `durationInFrames`, and `trimBefore` must be hardcoded frame values. Do not compute them.
+- Import `` from `@remotion/media`.
+
+Moving or resizing one of these clips does not reposition later clips. Gaps and overlaps are therefore allowed.
+
+## Ripple editing with `TransitionSeries`
+
+“Ripple editing” is the standard video-editing term for changing one clip and automatically shifting everything after it.
+In Remotion, a `` provides this sequential, cascading timing model while also allowing transitions between clips.
+
+Read [transitions.md](transitions.md) for transition types, timing options, installation instructions, and composition-duration calculation.
+
+Keep the markup like this:
+
+```tsx
+
+
+
+
+
+
+
+
+```
+
+- The `` is the editable clip row in the Studio timeline.
+- Dragging its right edge changes `durationInFrames` and repositions every later sequence.
+- Do not set `from` on ``; the series calculates each start frame.
+- Hardcode all numeric values.
+- Do not programmatically create multiple `` (no `.map`). Each instance must be hard-coded.
+- Import `` from `@remotion/media`. Import `` from `@remotion/transitions`. If needing to install: `npx remotion add @remotion/media @remotion/transitions`
diff --git a/remotion-best-practices/remotion-markup/voiceover.md b/remotion-best-practices/remotion-markup/voiceover.md
new file mode 100644
index 0000000..f4b022c
--- /dev/null
+++ b/remotion-best-practices/remotion-markup/voiceover.md
@@ -0,0 +1,99 @@
+---
+name: voiceover
+description: Adding AI-generated voiceover to Remotion compositions using TTS
+metadata:
+ tags: voiceover, audio, elevenlabs, tts, speech, calculateMetadata, dynamic duration
+---
+
+# Adding AI voiceover to a Remotion composition
+
+Use ElevenLabs TTS to generate speech audio per scene, then use [`calculateMetadata`](./calculate-metadata.md) to dynamically size the composition to match the audio.
+
+## Prerequisites
+
+By default this guide uses **ElevenLabs** as the TTS provider (`ELEVENLABS_API_KEY` environment variable). Users may substitute any TTS service that can produce an audio file.
+
+If the user has not specified a TTS provider, recommend ElevenLabs and ask for their API key.
+
+Ensure the environment variable is available when running the generation script:
+
+```bash
+node --strip-types generate-voiceover.ts
+```
+
+## Generating audio with ElevenLabs
+
+Create a script that reads the config, calls the ElevenLabs API for each scene, and writes MP3 files to the `public/` directory so Remotion can access them via `staticFile()`.
+
+The core API call for a single scene:
+
+```ts title="generate-voiceover.ts"
+const response = await fetch(
+ `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`,
+ {
+ method: "POST",
+ headers: {
+ "xi-api-key": process.env.ELEVENLABS_API_KEY!,
+ "Content-Type": "application/json",
+ Accept: "audio/mpeg",
+ },
+ body: JSON.stringify({
+ text: "Welcome to the show.",
+ model_id: "eleven_multilingual_v2",
+ voice_settings: {
+ stability: 0.5,
+ similarity_boost: 0.75,
+ style: 0.3,
+ },
+ }),
+ },
+);
+
+const audioBuffer = Buffer.from(await response.arrayBuffer());
+writeFileSync(`public/voiceover/${compositionId}/${scene.id}.mp3`, audioBuffer);
+```
+
+## Dynamic composition duration with calculateMetadata
+
+Use [`calculateMetadata`](./calculate-metadata.md) to measure the [audio durations](../remotion-multimedia/get-audio-duration.md) and set the composition length accordingly.
+
+```tsx
+import { CalculateMetadataFunction, staticFile } from "remotion";
+import { getAudioDuration } from "./get-audio-duration";
+
+const FPS = 30;
+
+const SCENE_AUDIO_FILES = [
+ "voiceover/my-comp/scene-01-intro.mp3",
+ "voiceover/my-comp/scene-02-main.mp3",
+ "voiceover/my-comp/scene-03-outro.mp3",
+];
+
+export const calculateMetadata: CalculateMetadataFunction = async ({
+ props,
+}) => {
+ const durations = await Promise.all(
+ SCENE_AUDIO_FILES.map((file) => getAudioDuration(staticFile(file))),
+ );
+
+ const sceneDurations = durations.map((durationInSeconds) => {
+ return durationInSeconds * FPS;
+ });
+
+ return {
+ durationInFrames: Math.ceil(sceneDurations.reduce((sum, d) => sum + d, 0)),
+ };
+};
+```
+
+The computed `sceneDurations` are passed into the component via a `voiceover` prop so the component knows how long each scene should be.
+
+If the composition uses [``](./transitions.md), subtract the overlap from total duration: [./transitions.md#calculating-total-composition-duration](./transitions.md#calculating-total-composition-duration)
+
+## Rendering audio in the component
+
+See [audio.md](./audio.md) for more information on how to render audio in the component.
+
+## Delaying audio start
+
+See [audio.md#delaying](./audio.md#delaying) for more information on how to delay the audio start.
diff --git a/remotion-best-practices/remotion-multimedia/REFERENCE.md b/remotion-best-practices/remotion-multimedia/REFERENCE.md
new file mode 100644
index 0000000..09ab75f
--- /dev/null
+++ b/remotion-best-practices/remotion-multimedia/REFERENCE.md
@@ -0,0 +1,20 @@
+---
+name: remotion-multimedia
+description: Interacting with Mediabunny
+version: 4.0.526
+---
+
+Mediabunny is a multimedia library for dealing with audio and video in the browser.
+Here is a compact overview of its capabilities: https://mediabunny.dev/llms.txt
+
+## Getting audio duration
+
+See [get-audio-duration.md](get-audio-duration.md) for getting the duration of an audio file in seconds with Mediabunny.
+
+## Getting video dimensions
+
+See [get-video-dimensions.md](get-video-dimensions.md) for getting the width and height of a video file with Mediabunny.
+
+## Getting video duration
+
+See [get-video-duration.md](get-video-duration.md) for getting the duration of a video file in seconds with Mediabunny.
diff --git a/remotion-best-practices/remotion-multimedia/agents/openai.yaml b/remotion-best-practices/remotion-multimedia/agents/openai.yaml
new file mode 100644
index 0000000..fbb5246
--- /dev/null
+++ b/remotion-best-practices/remotion-multimedia/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+ display_name: '/remotion-multimedia'
+ short_description: 'Inspect browser-based audio and video media'
+ icon_small: './assets/remotion-icon.svg'
+ icon_large: './assets/remotion-icon.svg'
+ brand_color: '#0B84F3'
+ default_prompt: '$remotion-multimedia: Make my video the same duration as the footage'
diff --git a/remotion-best-practices/remotion-multimedia/assets/remotion-icon.svg b/remotion-best-practices/remotion-multimedia/assets/remotion-icon.svg
new file mode 100644
index 0000000..420dbc7
--- /dev/null
+++ b/remotion-best-practices/remotion-multimedia/assets/remotion-icon.svg
@@ -0,0 +1,4 @@
+
+Remotion
+
diff --git a/remotion-best-practices/remotion-multimedia/get-audio-duration.md b/remotion-best-practices/remotion-multimedia/get-audio-duration.md
new file mode 100644
index 0000000..e2336c7
--- /dev/null
+++ b/remotion-best-practices/remotion-multimedia/get-audio-duration.md
@@ -0,0 +1,56 @@
+---
+name: get-audio-duration
+description: Getting the duration of an audio file in seconds with Mediabunny
+metadata:
+ tags: duration, audio, length, time, seconds, mp3, wav
+---
+
+# Getting audio duration with Mediabunny
+
+Mediabunny can extract the duration of an audio file. It works in browser, Node.js, and Bun environments.
+
+## Getting audio duration
+
+```tsx title="get-audio-duration.ts"
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getAudioDuration = async (src: string) => {
+ const input = new Input({
+ formats: ALL_FORMATS,
+ source: new UrlSource(src),
+ });
+
+ const durationInSeconds = await input.computeDuration();
+ return durationInSeconds;
+};
+```
+
+## Usage
+
+```tsx
+const duration = await getAudioDuration("https://remotion.media/audio.mp3");
+console.log(duration); // e.g. 180.5 (seconds)
+```
+
+## Using with staticFile in Remotion
+
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getAudioDuration(staticFile("audio.mp3"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+ formats: ALL_FORMATS,
+ source: new FileSource(file), // File object from input or drag-drop
+});
+```
diff --git a/remotion-best-practices/remotion-multimedia/get-video-dimensions.md b/remotion-best-practices/remotion-multimedia/get-video-dimensions.md
new file mode 100644
index 0000000..e73014e
--- /dev/null
+++ b/remotion-best-practices/remotion-multimedia/get-video-dimensions.md
@@ -0,0 +1,66 @@
+---
+name: get-video-dimensions
+description: Getting the width and height of a video file with Mediabunny
+metadata:
+ tags: dimensions, width, height, resolution, size, video
+---
+
+# Getting video dimensions with Mediabunny
+
+Mediabunny can extract the width and height of a video file. It works in browser, Node.js, and Bun environments.
+
+## Getting video dimensions
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getVideoDimensions = async (src: string) => {
+ const input = new Input({
+ formats: ALL_FORMATS,
+ source: new UrlSource(src),
+ });
+
+ const videoTrack = await input.getPrimaryVideoTrack();
+ if (!videoTrack) {
+ throw new Error("No video track found");
+ }
+
+ return {
+ width: videoTrack.displayWidth,
+ height: videoTrack.displayHeight,
+ };
+};
+```
+
+## Usage
+
+```tsx
+const dimensions = await getVideoDimensions("https://remotion.media/video.mp4");
+console.log(dimensions.width); // e.g. 1920
+console.log(dimensions.height); // e.g. 1080
+```
+
+## Using with local files
+
+For local files, use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+ formats: ALL_FORMATS,
+ source: new FileSource(file), // File object from input or drag-drop
+});
+
+const videoTrack = await input.getPrimaryVideoTrack();
+const width = videoTrack.displayWidth;
+const height = videoTrack.displayHeight;
+```
+
+## Using with staticFile in Remotion
+
+```tsx
+import { staticFile } from "remotion";
+
+const dimensions = await getVideoDimensions(staticFile("video.mp4"));
+```
diff --git a/remotion-best-practices/remotion-multimedia/get-video-duration.md b/remotion-best-practices/remotion-multimedia/get-video-duration.md
new file mode 100644
index 0000000..9fd125f
--- /dev/null
+++ b/remotion-best-practices/remotion-multimedia/get-video-duration.md
@@ -0,0 +1,58 @@
+---
+name: get-video-duration
+description: Getting the duration of a video file in seconds with Mediabunny
+metadata:
+ tags: duration, video, length, time, seconds
+---
+
+# Getting video duration with Mediabunny
+
+Mediabunny can extract the duration of a video file. It works in browser, Node.js, and Bun environments.
+
+## Getting video duration
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getVideoDuration = async (src: string) => {
+ const input = new Input({
+ formats: ALL_FORMATS,
+ source: new UrlSource(src),
+ });
+
+ const durationInSeconds = await input.computeDuration();
+ return durationInSeconds;
+};
+```
+
+## Usage
+
+```tsx
+const duration = await getVideoDuration("https://remotion.media/video.mp4");
+console.log(duration); // e.g. 10.5 (seconds)
+```
+
+## Video files from the public/ directory
+
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getVideoDuration(staticFile("video.mp4"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+ formats: ALL_FORMATS,
+ source: new FileSource(file), // File object from input or drag-drop
+});
+
+const durationInSeconds = await input.computeDuration();
+```
diff --git a/remotion-best-practices/remotion-render/REFERENCE.md b/remotion-best-practices/remotion-render/REFERENCE.md
new file mode 100644
index 0000000..6e60afb
--- /dev/null
+++ b/remotion-best-practices/remotion-render/REFERENCE.md
@@ -0,0 +1,27 @@
+---
+name: remotion-render
+description: Export a Remotion video
+version: 4.0.526
+---
+
+## General rendering strategy
+
+Render a video using:
+
+```
+npx remotion render
+```
+
+Full list of options: https://www.remotion.dev/docs/cli/render.md
+
+Render a still using:
+
+```
+npx remotion still
+```
+
+Full list of options: https://www.remotion.dev/docs/cli/still.md
+
+## Transparent videos
+
+See [Transparent videos](./transparent-videos.md) for rendering out a video with transparency.
diff --git a/remotion-best-practices/remotion-render/agents/openai.yaml b/remotion-best-practices/remotion-render/agents/openai.yaml
new file mode 100644
index 0000000..da473ab
--- /dev/null
+++ b/remotion-best-practices/remotion-render/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+ display_name: '/remotion-render'
+ short_description: 'Export Remotion videos and stills'
+ icon_small: './assets/remotion-icon.svg'
+ icon_large: './assets/remotion-icon.svg'
+ brand_color: '#0B84F3'
+ default_prompt: '$remotion-render: Render this as transparent ProRes'
diff --git a/remotion-best-practices/remotion-render/assets/remotion-icon.svg b/remotion-best-practices/remotion-render/assets/remotion-icon.svg
new file mode 100644
index 0000000..420dbc7
--- /dev/null
+++ b/remotion-best-practices/remotion-render/assets/remotion-icon.svg
@@ -0,0 +1,4 @@
+
+Remotion
+
diff --git a/remotion-best-practices/remotion-render/transparent-videos.md b/remotion-best-practices/remotion-render/transparent-videos.md
new file mode 100644
index 0000000..dce5de5
--- /dev/null
+++ b/remotion-best-practices/remotion-render/transparent-videos.md
@@ -0,0 +1,106 @@
+---
+name: transparent-videos
+description: Rendering transparent videos in Remotion
+metadata:
+ tags: transparent, alpha, codec, vp9, prores, webm
+---
+
+# Rendering Transparent Videos
+
+Remotion can render transparent videos in two ways: as a ProRes video or as a WebM video.
+
+## Transparent ProRes
+
+Ideal for when importing into video editing software.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva444p10le --codec=prores --prores-profile=4444 MyComp out.mov
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva444p10le");
+Config.setCodec("prores");
+Config.setProResProfile("4444");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction = async ({
+ props,
+}) => {
+ return {
+ defaultCodec: "prores",
+ defaultVideoImageFormat: "png",
+ defaultPixelFormat: "yuva444p10le",
+ defaultProResProfile: "4444",
+ };
+};
+
+ = async ({
+ props,
+}) => {
+ return {
+ defaultCodec: "vp8",
+ defaultVideoImageFormat: "png",
+ defaultPixelFormat: "yuva420p",
+ };
+};
+
+`
+
+This component allows embedding a Remotion preview in a React app. See [Player](player.md) for more information about the Player.
+
+## Rendering
+
+There are client-side and server-side rendering options available. See [Rendering](rendering.md) for advice on how to choose, and about the Lambda, Vercel, Node.js and Cloudflare options.
+
+## With Vue
+
+See https://www.remotion.dev/docs/vue.md for how to use Remotion with Vue.
+
+## Angular
+
+See https://www.remotion.dev/docs/angular.md for how to use Remotion with Angular.
+
+## Svelte
+
+See https://www.remotion.dev/docs/svelte.md for how to use Remotion with Svelte.
diff --git a/remotion-best-practices/remotion-saas/agents/openai.yaml b/remotion-best-practices/remotion-saas/agents/openai.yaml
new file mode 100644
index 0000000..e9507e5
--- /dev/null
+++ b/remotion-best-practices/remotion-saas/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+ display_name: '/remotion-saas'
+ short_description: 'Build apps that preview and render videos'
+ icon_small: './assets/remotion-icon.svg'
+ icon_large: './assets/remotion-icon.svg'
+ brand_color: '#0B84F3'
+ default_prompt: '$remotion-saas: Turn my video into an app.'
diff --git a/remotion-best-practices/remotion-saas/assets/remotion-icon.svg b/remotion-best-practices/remotion-saas/assets/remotion-icon.svg
new file mode 100644
index 0000000..420dbc7
--- /dev/null
+++ b/remotion-best-practices/remotion-saas/assets/remotion-icon.svg
@@ -0,0 +1,4 @@
+
+Remotion
+
diff --git a/remotion-best-practices/remotion-saas/framework.md b/remotion-best-practices/remotion-saas/framework.md
new file mode 100644
index 0000000..afb3b77
--- /dev/null
+++ b/remotion-best-practices/remotion-saas/framework.md
@@ -0,0 +1,21 @@
+---
+name: framework
+description: Choose a framework for a Remotion-based app.
+metadata:
+ tags: remotion, saas, templates, nextjs, react-router, vercel, lambda, cloudflare
+---
+
+Remotion can be used with any React framework.
+
+We offer the following templates:
+
+- Next.js App Router with Tailwind: https://github.com/remotion-dev/template-next-app-dir-tailwind. Uses Lambda as default rendering choice.
+- Next.js App Router without Tailwind: https://www.remotion.dev/templates/next-no-tailwind. Uses Lambda as default rendering choice.
+- Next.js Pages Router: https://github.com/remotion-dev/template-next-pages-dir. Uses Lambda as default rendering choice.
+- Vercel Sandbox rendering: https://github.com/remotion-dev/template-vercel. Uses Vercel as default rendering choice.
+- React Router 7: https://github.com/remotion-dev/template-react-router. Uses Lambda as default rendering choice.
+- Express.js render server: `packages/template-render-server`: https://github.com/remotion-dev/template-render-server. Uses Node.js as default rendering choice.
+
+These can be cloned directly, or used as a reference.
+
+For an existing app, see https://www.remotion.dev/docs/brownfield-installation.md.
diff --git a/remotion-best-practices/remotion-saas/player.md b/remotion-best-practices/remotion-saas/player.md
new file mode 100644
index 0000000..7cc9185
--- /dev/null
+++ b/remotion-best-practices/remotion-saas/player.md
@@ -0,0 +1,33 @@
+---
+name: player
+description: Embed a Remotion preview in a React app with @remotion/player.
+metadata:
+ tags: remotion, player, preview, react
+---
+
+Use `@remotion/player` when the user wants an interactive preview in React.
+
+```tsx
+import {Player} from '@remotion/player';
+import {MyVideo} from './remotion/MyVideo';
+
+export const App: React.FC = () => {
+ return (
+ ` | Set `error`, `warn`, `info` (default), or `verbose` logging. |
+| `--port=` | Request a Studio server port; otherwise Remotion finds a free port. |
+| `--force-new` | Start another Studio instance even when one is already running for the same project and port. |
diff --git a/remotion-best-practices/remotion-studio/agents/openai.yaml b/remotion-best-practices/remotion-studio/agents/openai.yaml
new file mode 100644
index 0000000..dd0ff18
--- /dev/null
+++ b/remotion-best-practices/remotion-studio/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+ display_name: '/remotion-studio'
+ short_description: 'Preview your video'
+ icon_small: './assets/remotion-icon.svg'
+ icon_large: './assets/remotion-icon.svg'
+ brand_color: '#0B84F3'
+ default_prompt: '$remotion-studio.'
diff --git a/remotion-best-practices/remotion-studio/assets/remotion-icon.svg b/remotion-best-practices/remotion-studio/assets/remotion-icon.svg
new file mode 100644
index 0000000..420dbc7
--- /dev/null
+++ b/remotion-best-practices/remotion-studio/assets/remotion-icon.svg
@@ -0,0 +1,4 @@
+
+Remotion
+
diff --git a/remotion-best-practices/remotion-upgrade/REFERENCE.md b/remotion-best-practices/remotion-upgrade/REFERENCE.md
new file mode 100644
index 0000000..e1e16db
--- /dev/null
+++ b/remotion-best-practices/remotion-upgrade/REFERENCE.md
@@ -0,0 +1,31 @@
+---
+name: remotion-upgrade
+description: Upgrade Remotion, and related packages
+version: 4.0.526
+---
+
+# Upgrade Remotion
+
+1. Inspect the project manifests and lockfile to identify the package manager and workspaces. Preserve unrelated changes.
+2. Determine whether `@remotion/cli` is locally available. If it is, run:
+
+ ```bash
+ npx remotion upgrade
+ ```
+
+ This also updates project-local Remotion skills. Skip the manual upgrade below.
+
+3. If `@remotion/cli` is not available, upgrade manually:
+ - Get the latest stable Remotion version with `npm view remotion version`.
+ - Find every installed `remotion` and `@remotion/*` dependency across the project and upgrade them all to that exact version. Preserve their dependency sections and the project's workspace or catalog conventions.
+ - Read the `@remotion/studio` dependencies for the target Remotion version using `npm view @remotion/studio@ dependencies --json`. Align installed auxiliary packages such as `zod`, `mediabunny`, and `@huggingface/transformers` with the versions listed there. Use the `mediabunny` version for installed `@mediabunny/*` packages.
+ - Run the project's package manager to update its lockfile.
+4. If `@remotion/cli` is not available, update the installed Remotion skills:
+
+ ```bash
+ npx skills update remotion-best-practices remotion-captions remotion-create remotion-docs remotion-interactivity remotion-maps remotion-markup remotion-multimedia remotion-render remotion-saas remotion-studio remotion-upgrade --yes
+ ```
+
+5. Review the manifest and lockfile diff. Ensure all Remotion packages use one version and installed auxiliary packages use their recommended versions. If the CLI is available, run `npx remotion versions` as an additional check.
+
+The [Remotion releases](https://github.com/remotion-dev/remotion/releases) contain the changelog and may be useful for summarizing relevant changes after the upgrade.
diff --git a/remotion-best-practices/remotion-upgrade/agents/openai.yaml b/remotion-best-practices/remotion-upgrade/agents/openai.yaml
new file mode 100644
index 0000000..b8b1905
--- /dev/null
+++ b/remotion-best-practices/remotion-upgrade/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+ display_name: '/remotion-upgrade'
+ short_description: 'Upgrade Remotion and related dependencies'
+ icon_small: './assets/remotion-icon.svg'
+ icon_large: './assets/remotion-icon.svg'
+ brand_color: '#0B84F3'
+ default_prompt: '$remotion-upgrade: Upgrade my project.'
diff --git a/remotion-best-practices/remotion-upgrade/assets/remotion-icon.svg b/remotion-best-practices/remotion-upgrade/assets/remotion-icon.svg
new file mode 100644
index 0000000..420dbc7
--- /dev/null
+++ b/remotion-best-practices/remotion-upgrade/assets/remotion-icon.svg
@@ -0,0 +1,4 @@
+
+Remotion
+
diff --git a/resilient-forms-validation/SKILL.md b/resilient-forms-validation/SKILL.md
new file mode 100644
index 0000000..c06be25
--- /dev/null
+++ b/resilient-forms-validation/SKILL.md
@@ -0,0 +1,164 @@
+---
+name: resilient-forms-validation
+description: >-
+ Build high-resilience, accessible web forms with unified schema validation (Zod / Valibot),
+ React 19 Actions / React Hook Form, optimistic UX, draft auto-save persistence, and strict WCAG error announcements.
+---
+
+# Resilient Forms & Accessible Schema Validation
+
+Ce skill encadre la création de formulaires web de niveau entreprise. Il élimine les formulaires artisanaux fragiles (multiples `useState` non validés, perte de données lors du rechargement, spinners bloquants) au profit d'un contrat de validation de schéma unifié, d'une résilience hors-ligne et d'une accessibilité irréprochable.
+
+---
+
+## 🎯 Déclencheurs d'Activation
+
+Activez ce skill dès que :
+1. Vous créez ou refactorisez un formulaire (inscription, authentification, paiement, paramètres utilisateur, formulaires multi-étapes).
+2. Vous validez des entrées utilisateur côté client et côté serveur avec **Zod** ou **Valibot**.
+3. Vous implémentez des mutations asynchrones avec **React 19 Actions** (`useActionState`) ou **React Hook Form**.
+4. Vous devez garantir la persistance des brouillons (*draft auto-save*) face aux rafraîchissements intempestifs.
+5. Vous auditez l'accessibilité des erreurs de saisie selon le critère WCAG 3.3 (Identification des erreurs et suggestions).
+
+---
+
+## 📐 1. Les 4 Piliers d'un Formulaire Résilient
+
+1. **Schéma Unique Partagé (Zod)** : Le même schéma TypeScript valide la saisie en temps réel côté client et protège l'endpoint API côté serveur.
+2. **Accessibilité des Erreurs (WCAG 3.3)** :
+ - Chaque champ en erreur porte `aria-invalid="true"`.
+ - Les messages d'erreur sont reliés au champ via `aria-describedby="field-error-id"`.
+ - Un conteneur avec `role="alert"` ou `aria-live="polite"` annonce les erreurs aux lecteurs d'écran sans déplacer brutalement le curseur.
+3. **Persistance Locale Automatique des Brouillons** : Pour les formulaires longs (> 3 champs), les valeurs sont sauvegardées dans `sessionStorage` ou `localStorage` pour éviter la perte de données en cas de crash d'onglet.
+4. **Mutations Non Bloquantes** : Ne jamais afficher d'overlay gris qui fige l'écran entier. Seul le bouton d'action affiche un état en cours, tout en restant désactivé pour empêcher la double soumission.
+
+---
+
+## 💻 2. Exemple d'Implémentation de Référence (Zod + React 19 Action)
+
+```tsx
+'use client';
+
+import React, { useActionState } from 'react';
+import { z } from 'zod';
+
+// 1. Schéma Zod Partagé
+export const ContactSchema = z.object({
+ name: z.string().min(2, 'Le nom doit comporter au moins 2 caractères'),
+ email: z.string().email('Adresse email invalide'),
+ message: z.string().min(10, 'Votre message doit comporter au moins 10 caractères'),
+});
+
+type FormState = {
+ success?: boolean;
+ errors?: Record;
+ values?: { name: string; email: string; message: string };
+};
+
+// 2. Action Serveur / Handler Typé
+async function submitContactAction(prevState: FormState, formData: FormData): Promise {
+ const rawData = {
+ name: formData.get('name') as string,
+ email: formData.get('email') as string,
+ message: formData.get('message') as string,
+ };
+
+ const validated = ContactSchema.safeParse(rawData);
+ if (!validated.success) {
+ return {
+ success: false,
+ errors: validated.error.flatten().fieldErrors,
+ values: rawData,
+ };
+ }
+
+ // Traitement backend sécurisé...
+ return { success: true };
+}
+
+// 3. Composant Formulaire Accessible
+export const ResilientContactForm = () => {
+ const [state, formAction, isPending] = useActionState(submitContactAction, {});
+
+ return (
+
+ );
+};
+```
+
+---
+
+## 📋 Checklist de Conformité Formulaires
+
+- [ ] Un schéma Zod ou Valibot est défini et partagé entre validation UI et API.
+- [ ] L'attribut `noValidate` est présent sur ` 
+ 
+
+