# @blaineam/videojs-vr 中文文档

规范地址：https://npmcn.com/package/%40blaineam/videojs-vr/

版本：3\.3\.0
npm 元数据更新时间：2026-05-03T18:42:20.633Z
中文译文更新时间：2026-11-08T06:08:22.590Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40blaineam/videojs-vr
原文对照：https://npmcn.com/package/%40blaineam/videojs-vr/?lang=original
项目主页：https://github.com/blaineam/videojs-vr#readme
源码仓库：https://github.com/blaineam/videojs-vr

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.2 MB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：5 个
- 首次发布：2025-12-23T01:08:34.116Z
- 最新版本发布：2026-05-03T18:42:20.389Z
- 近 30 天下载量：5440（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

一个插件,用于为视频.js添加360,180和VR的视频支持,并配有完整的WebXR支持,VR HUD控制,以及In-VR媒体展廊.

## 安装

```sh
npm install @blaineam/videojs-vr
```

也可以使用：`pnpm add @blaineam/videojs-vr`、`yarn add @blaineam/videojs-vr`、`bun add @blaineam/videojs-vr`

## README

# 视频-vr

将视频元素转化为HTML5全景360视频播放器的视频.js插件. 在Meta Quest,HTC Vive等设备上浸入VR取景,以及其它WebXR相容头等设备上,项目视频被完整地支持到不同形状上.

**维护者 :** 布莱恩·米勒

**公关欢迎!** 鼓励提交、错误报告和特性请求.

## 安装

```sh
npm install @blaineam/videojs-vr
```

## 特征

-   **完整 WebXR 支持**: Modern WebXR API 支持在Quest, Vive 等头像上浸入 VR 体验
-   **多重预测**:支持360,180相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接
-   **玻璃外形 VR UI**: 美丽的被霜玻璃设计 有半透明面板和细微的梯度,用于浸润而无侵扰的界面
-   **VR HUD 控制器**: 装有刷新栏、播放/暂停和导航控制的In-VR用户界面
-   **VR 图片库面板**: 在使用可滚动缩略图和丸形持续时间徽章的VR模式时浏览并选择媒体
-   **主计长支助**: 完全 VR 控制器与指针射线和抓取切换的相互作用
-   **定向控制**: 调整取景角度,以方便在任何位置取景
-   **立体声支持**: 立体视觉内容的正左/右眼渲染

## 浏览器支持

最新版本为:

### 桌面

-   颜色
-   火花
-   萨法里

### 移动

-   Android上的颜色
-   IOS上的萨法里

### VR 头像 (WebXR)

-   Meta 查询 (查询2,查询3,查询Pro)
-   HTC 活性 /活性 Pro
-   阀门索引
-   Windows 混合现实头盔
-   任何兼容 WebXR 的设备

## 快速启动

### 脚本标记

```html
<script src="//path/to/video.min.js"></script>
<script src="//path/to/videojs-vr.min.js"></script>
<script>
  var player = videojs('my-video');

  player.vr({
    projection: '360',
    enableVRHUD: true,
    enableVRGallery: true
  });
</script>
```

### ES 模块/机舱

```js
import videojs from 'video.js';
import '@blaineam/videojs-vr';

const player = videojs('my-video');

player.vr({
  projection: '360',
  enableVRHUD: true,
  enableVRGallery: true,
  onNext: () => console.log('Next video'),
  onPrevious: () => console.log('Previous video'),
  onFavorite: () => console.log('Toggle favorite')
});
```

## 投影类型

### 标准预测

| 预测 | 说明 |
| --- | --- |
| `'360'` 编号 : `'Sphere'` 编号 : `'equirectangular'` | 完整的360度球面视频 |
| `'180'` | 180度半球道视频 |
| `'180_MONO'` | 180度单镜录像 |
| `'Cube'` 编号 : `'360_CUBE'` | 360度立方体地图视频 |
| `'NONE'` | 标准平面视频( 无 VR 投影) |
| `'AUTO'` | 自动检测从 `player.mediainfo.projection` |

### 边行(预测)

相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相相 插件自动分离这些, 用于在 VR 头像中进行适当的立体视觉查看 .

| 预测 | 说明 |
| --- | --- |
| `'360_LR'` | 360度并有左/右相眼 |
| `'360_TB'` | 360度, 有上下双眼布局 |
| `'180_LR'` | 180度并有左/右相眼 |
| `'SBS_MONO'` | 平面屏幕并列 - 在 WebXR 中显示立体声 3D, 在浏览器中显示单相 |

### 等角立方体(EAC)

| 预测 | 说明 |
| --- | --- |
| `'EAC'` | YouTube的等角立方体格式 |
| `'EAC_LR'` | 与左/右相邻的东非共同体 |

### 鱼眼预测(自3.2.0起)

鱼眼源是圆形图像通过广角镜头拍摄. 插件将圆盘重新投影到一个带有自定义遮光器的球体上,这样相机就可以自然地在被捕获的视野内环视. 盘子外的碎片被丢弃,所以信箱保持干净.

| 预测 | 说明 |
| --- | --- |
| `'FISHEYE_180'` | 单向180度鱼眼圆盘 |
| `'FISHEYE_200'` | 单面200°鱼眼圆盘(覆盖MKX200型镜头) |
| `'FISHEYE_220'` | 单体220°鱼眼圆盘(VRCA220等) |
| `'FISHEYE_360'` | 双鱼眼 360° — 纹理左半部的前半球, 右半部后半球 (Ricoh Theta- system 生地) |
| `'FISHEYE_180_LR'` | 180° 有左/右眼并肩的鱼眼(每半个是一双全圆盘) |
| `'FISHEYE_200_LR'` | 200°鱼眼,LR立体声 |
| `'FISHEYE_220_LR'` | 220°鱼眼,LR立体 |
| `'FISHEYE_360_LR'` | 立体双鱼眼 360° |

LR变体使左眼在 三.js 层上 `0` 财务报告和审定财务报表 `1` 右眼分层 `2` 只有这个 WebXR通过第1层和第2层来进行真实的立体声渲染,而非XR(平面浏览器)的取景者只看到左眼而不是黑色的场景.

## WebXR VR 模式

在兼容WebXR的浏览器(如Meta Quest浏览器)中查看时,插件提供浸入VR体验:

1.  点击 **纸板/ VR 按钮** 在玩家控件中输入 VR 模式
2.  **抓紧了** 在您的 VR 控制器上显示/隐藏 VR HUD
3.  使用 **拇指笔** 改为:
    -   左/右:通过视频搜索
    -   上/下: 在画廊中滚动( 当打开时)
4.  **指向并单击** 使用控制器与按钮交互
5.  新闻 **按钮** 切换/暂停

### VR HUD 控制器

VR HUD在VR模式下提供这些控制:

| 按钮 | 函数 |
| --- | --- |
| **退出( X)** | 退出 VR 模式 |
| **图片库** | 打开媒体画廊面板 |
| **上一个** | 转到上一个媒体项目 |
| **播放/暂停** | 切换视频播放 |
| **下一个** | 转到下一条媒体项目 |
| **重设方向** | 将视图重置为默认方向 |
| **拖动处理** | 拖放以调整取景角度( 用于躺下等) |
| **预测** | 打开投影模式选择器 |
| **最喜欢** | 切换最爱状态( 如果提供回调) |

《宣言》还包括: **刷新栏** 以可拖动的手柄显示当前播放位置.

## VR 图片库面板

VR 图片库允许用户在保留 VR 时浏览并选择媒体 :

```js
player.vr({
  projection: '360',
  enableVRGallery: true,
  mediaItems: [
    {
      title: 'Beach Sunset',
      thumbnail: '/thumbnails/beach.jpg',
      url: '/videos/beach-360.mp4',
      duration: 180 // seconds (optional)
    },
    {
      title: 'Mountain View',
      thumbnail: '/thumbnails/mountain.jpg',
      url: '/videos/mountain-360.mp4',
      duration: 240
    }
  ],
  onMediaSelect: (item, index) => {
    // Handle media selection
    player.src({ src: item.url, type: 'video/mp4' });
  }
});
```

### 图片库特征

-   **可滚动网格**: 有平滑滚动的4列缩略图网格
-   **懒惰装入**: 缩略图可见时的负载
-   **VR 主计长支助**: 指向并单击以选择,使用拇指棒来滚动
-   **鼠标/触摸支持**: 非 VR 模式下的工作
-   **期限徽章**: 在缩略图上显示视频持续时间

### 动态图片库更新

```js
// Update gallery items at runtime
player.vr().setGalleryItems([
  { title: 'New Video', thumbnail: '/thumb.jpg', url: '/video.mp4' }
]);

// Show/hide gallery programmatically
player.vr().showGallery();
player.vr().hideGallery();
player.vr().toggleGallery();
```

## API 参考

### 选项

```js
player.vr({
  // Projection mode
  projection: '360',           // See projection types above
  sphereDetail: 32,            // Sphere mesh detail (higher = smoother)

  // VR HUD options
  enableVRHUD: true,           // Enable in-VR controls
  enableVRGallery: true,       // Enable in-VR media gallery
  showHUDOnStart: true,        // Show HUD when entering VR
  hudAutoHideDelay: 5000,      // Auto-hide HUD after ms (0 to disable)
  hudDistance: 1.5,            // Distance of HUD from viewer
  hudHeight: 1.5,              // Height of HUD
  hudScale: 0.015,             // Scale of HUD elements

  // Behavior options
  forceCardboard: false,       // Force cardboard button on all devices
  motionControls: true,        // Enable gyroscope/device orientation
  disableTogglePlay: false,    // Disable click-to-play

  // Spatial audio (requires Omnitone library)
  omnitone: null,              // Pass Omnitone library object
  omnitoneOptions: {},         // Omnitone configuration

  // Media gallery items
  mediaItems: [],              // Array of media items for gallery

  // Callbacks
  onNext: () => {},            // Called when next button pressed
  onPrevious: () => {},        // Called when previous button pressed
  onMediaSelect: (item, index) => {}, // Called when gallery item selected
  onGallery: () => {},         // Called when gallery button pressed
  onExit: () => {},            // Called when exit VR pressed
  onProjectionChange: (projection) => {}, // Called when projection changed
  onFavorite: () => {}         // Called when favorite button pressed (enables button)
});
```

### 方法

```js
const vr = player.vr();

// Projection
vr.setProjection('360_LR');    // Change projection mode

// VR HUD
vr.showHUD();                  // Show the VR HUD
vr.hideHUD();                  // Hide the VR HUD
vr.toggleHUD();                // Toggle HUD visibility

// VR Gallery
vr.showGallery();              // Show the gallery panel
vr.hideGallery();              // Hide the gallery panel
vr.toggleGallery();            // Toggle gallery visibility
vr.setGalleryItems(items);     // Update gallery media items

// Favorite state
vr.setFavoriteState(true);     // Set favorite button state
vr.getFavoriteState();         // Get current favorite state

// Orientation
vr.setOrientationOffset({ x: 0.5, y: 0, z: 0 }); // Tilt view
vr.resetOrientationOffset();   // Reset to default orientation
vr.recenter();                 // Recenter VR view

// Status
vr.isPresenting();             // Check if currently in VR mode

// Three.js access
vr.camera;                     // THREE.PerspectiveCamera
vr.scene;                      // THREE.Scene
vr.renderer;                   // THREE.WebGLRenderer
vr.cameraVector;               // Camera direction vector
```

### 活动

```js
// VR-specific events
player.on('vr-next', () => {});
player.on('vr-previous', () => {});
player.on('vr-gallery', () => {});
player.on('vr-exit', () => {});
player.on('vr-favorite', () => {});
player.on('vr-media-select', (e, { item, index }) => {});
player.on('vr-projection-change', (e, { projection }) => {});
player.on('vr-orientation-change', (e, euler) => {});
player.on('initialized', () => {});
```

## 自定义按钮

最喜欢的按钮是怎样添加自定义功能的例子. 当 `onFavorite` 提供回调, VR HUD 中最喜爱的按钮 :

```js
player.vr({
  projection: '360',
  onFavorite: () => {
    const isFavorited = !player.vr().getFavoriteState();
    player.vr().setFavoriteState(isFavorited);

    // Save to your backend
    saveFavoriteStatus(currentVideoId, isFavorited);
  }
});

// Update favorite state when loading a new video
player.on('loadedmetadata', () => {
  const isFavorited = checkIfFavorited(currentVideoId);
  player.vr().setFavoriteState(isFavorited);
});
```

## 每个来源预测

使用按来源设定预测 `player.mediainfo`数字 :

```js
player.mediainfo = {
  projection: '360_LR'  // This video is side-by-side 360
};

player.vr({ projection: 'AUTO' }); // Will use mediainfo.projection
```

## 访问 3.js 对象

对于高级定制,三.js对象被曝光:

```js
const vr = player.vr();

// Add custom objects to the scene
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
cube.position.set(0, 0, -5);
vr.scene.add(cube);

// Access camera for custom positioning
console.log(vr.camera.position);
console.log(vr.cameraVector); // Direction camera is facing
```

## 洞穴

-   有关Safari的 HLS 标题将无法见识, 因为它们位于视频元素中的 shadowRoot 内部
-   一些更古老的移动浏览器可能有有限的WebXR支持
-   跨源视频源需要CORS头条

## 发展

```sh
# Install dependencies
npm install

# Start development server
npm start

# Run tests
npm test

# Build for production
npm run build-prod
```

## 许可证

麻省理工学院

## 常见问题

### @blaineam/videojs-vr 是什么？

一个插件,用于为视频\.js添加360,180和VR的视频支持,并配有完整的WebXR支持,VR HUD控制,以及In-VR媒体展廊\.

### 如何安装 @blaineam/videojs-vr？

在项目目录运行 npm install @blaineam/videojs-vr，或使用 pnpm add / yarn add / bun add。

### @blaineam/videojs-vr 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/blaineam\_\_videojs-vr 是否存在。

### @blaineam/videojs-vr 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @blaineam/videojs-vr 可以商用吗？

@blaineam/videojs-vr 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @blaineam/videojs-vr 的下载量有多少？

根据 npm 官方下载统计，@blaineam/videojs-vr 在 2026/10/09 – 2026/11/07 这 30 天内被下载 5,440 次，日均约 181 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @blaineam/videojs-vr 还在维护吗？

最新版本 3\.3\.0 发布于 2026/05/04（6 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2025/12/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。