---
title: "MapboxVideoLayer"
description: "Video overlay layer that georeferenced a video to the map using four corner coordinates, with exposed playback controls."
canonical_url: "https://mapbox.mhaibaraai.cn/en/docs/layers/video"
---
# MapboxVideoLayer

> Video overlay layer that georeferenced a video to the map using four corner coordinates, with exposed playback controls.

## Introduction

`MapboxVideoLayer` overlays a video onto the map using four corner coordinates, with multi-format `urls` fallback support. Internally implemented as a `video` source with a `raster` layer. The `play`, `pause`, and `video` methods are exposed via `defineExpose` for programmatic control.

## Usage

Overlay a drone footage video with button-controlled playback:

```vue [VideoLayerExample.vue]
<script setup lang="ts">
const videoLayer = useTemplateRef('videoLayer')

// 四角经纬度：左上 / 右上 / 右下 / 左下
const coordinates: [[number, number], [number, number], [number, number], [number, number]] = [
  [-122.51596391201019, 37.56238816766053],
  [-122.51467645168304, 37.56410183312965],
  [-122.51309394836426, 37.563391708549425],
  [-122.51423120498657, 37.56161849366671]
]

const urls = [
  'https://static-assets.mapbox.com/mapbox-gl-js/drone.mp4',
  'https://static-assets.mapbox.com/mapbox-gl-js/drone.webm'
]
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MapboxMap :options="{ style: 'mapbox://styles/mapbox/satellite-streets-v12', center: [-122.514, 37.563], zoom: 17, bearing: -96 }">
      <div class="absolute left-3 top-3 z-10 flex gap-2">
        <UButton size="xs" color="neutral" variant="solid" @click="videoLayer?.play()">
          Play
        </UButton>
        <UButton size="xs" color="neutral" variant="solid" @click="videoLayer?.pause()">
          Pause
        </UButton>
      </div>
      <MapboxVideoLayer ref="videoLayer" :urls="urls" :coordinates="coordinates" />
    </MapboxMap>
  </div>
</template>
```

## API

### Props

```ts
/**
 * Props for the MapboxVideoLayer component
 */
interface MapboxVideoLayerProps {
  /**
   * 视频地址列表（多格式回退）
   */
  urls: string[];
  /**
   * 四角经纬度：左上/右上/右下/左下
   */
  coordinates: [[number, number], [number, number], [number, number], [number, number]];
  /**
   * 图层 id；省略时自动生成
   */
  layerId?: string | undefined;
  /**
   * 不透明度
   * @default "1"
   */
  opacity?: number | undefined;
  /**
   * 插入到该图层之前
   */
  beforeId?: string | undefined;
}
```

### Expose

Access the component instance via [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref).

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          play
        </span>
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sMK4o">
          ()
        </span>
        
        <span class="spNyl">
          =>
        </span>
        
        <span class="sBMFI">
          void
        </span>
      </code>
      
       <br />
      
       <p>
        Play the video
      </p>
    </td>
  </tr>
  
  <tr>
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          pause
        </span>
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sMK4o">
          ()
        </span>
        
        <span class="spNyl">
          =>
        </span>
        
        <span class="sBMFI">
          void
        </span>
      </code>
      
       <br />
      
       <p>
        Pause the video
      </p>
    </td>
  </tr>
  
  <tr>
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          video
        </span>
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sMK4o">
          ()
        </span>
        
        <span class="spNyl">
          =>
        </span>
        
        <span class="sBMFI">
          HTMLVideoElement
        </span>
        
        <span class="sMK4o">
          |
        </span>
        
        <span class="sBMFI">
          undefined
        </span>
      </code>
      
       <br />
      
       <p>
        The underlying video element
      </p>
    </td>
  </tr>
</tbody>
</table>

## Changelog

See commit history for [src/runtime/components/layers/VideoLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/layers/VideoLayer.vue).


## Sitemap

See the full [sitemap](https://mapbox.mhaibaraai.cn/sitemap.md) for all pages.