# @cycjimmy/jsmpeg-player 中文文档

规范地址：https://npmcn.com/package/%40cycjimmy/jsmpeg-player/

版本：7\.0\.0
npm 元数据更新时间：2026-11-01T07:27:31.640Z
中文译文更新时间：2026-11-11T06:54:06.903Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：483 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2019-10-12T03:56:37.322Z
- 最新版本发布：2026-11-01T07:27:31.281Z
- 近 30 天下载量：45942（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 7 个）

## 中文简介

MPEG1 基于 JSMpeg 的视频播放器

## 安装

```sh
npm install @cycjimmy/jsmpeg-player
```

也可以使用：`pnpm add @cycjimmy/jsmpeg-player`、`yarn add @cycjimmy/jsmpeg-player`、`bun add @cycjimmy/jsmpeg-player`

## README

# JSMpeg 玩家( TS 玩家)

![Test CI](https://github.com/cycjimmy/jsmpeg-player/workflows/Test%20CI/badge.svg) [![libraries dependency status](https://img.shields.io/librariesio/release/npm/@cycjimmy/jsmpeg-player)](https://libraries.io/github/cycjimmy/jsmpeg-player) [![libraries sourcerank](https://img.shields.io/librariesio/sourcerank/npm/@cycjimmy/jsmpeg-player)](https://libraries.io/npm/@cycjimmy%2Fjsmpeg-player) [![Release date](https://img.shields.io/github/release-date/cycjimmy/jsmpeg-player)](https://github.com/cycjimmy/jsmpeg-player/releases) [![vite](https://img.shields.io/github/package-json/dependency-version/cycjimmy/jsmpeg-player/dev/vite)](https://github.com/vitejs/vite) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) [![npm license](https://img.shields.io/npm/l/@cycjimmy/jsmpeg-player)](https://npmjs.org/package/@cycjimmy/jsmpeg-player)

-   **[jsmpeg 游戏机](https://github.com/cycdpo/jsmpeg-player) 已更名为 @cycjimmy/jsmpeg-player,用于范围化的国家预防机制软件包.**
-   JSMpeg 播放器基于 [齐平格](https://github.com/phoboslab/jsmpeg)。 。 。 .
-   视频必须被压缩为MPEG1/MP2的TS格式.
-   带声音的自动播放被浏览器屏蔽,直到页面收到用户手势: 苹果设备在无声音的情况下自动播放,需要引导用户点击视频图标右下角的视频来解锁声音. Chrome和Safari遵循相同的自動播放政策,即声音会与相片保持同步,并在用户与页面互动后立即启动,或者可以通过同一图标立即解锁. (非自动播放模式下没有类似问题)
-   [演示](https://cycjimmy.github.io/jsmpeg-player/)

## 如何使用

### 安装

[![NPM version](https://img.shields.io/npm/v/@cycjimmy/jsmpeg-player)](https://npmjs.org/package/@cycjimmy/jsmpeg-player) [![NPM bundle size](https://img.shields.io/bundlephobia/min/@cycjimmy/jsmpeg-player)](https://npmjs.org/package/@cycjimmy/jsmpeg-player) [![npm download](https://img.shields.io/npm/dt/@cycjimmy/jsmpeg-player)](https://npmjs.org/package/@cycjimmy/jsmpeg-player)

```shell
$ npm install @cycjimmy/jsmpeg-player --save
# or
$ yarn add @cycjimmy/jsmpeg-player
```

### 使用量

```javascript
import JSMpeg from '@cycjimmy/jsmpeg-player'
```

```javascript
// new JSMpeg.VideoElement(videoWrapper, videoUrl [, options] [, overlayOptions])
```

-   `JSMpeg.VideoElement` 配置 :
    
    -   `videoWrapper`: \[结 元素\] 录像的包装——要么是 **必须符合现有元素的 CSS 选择器**,或DOM元素本身。 一定是个 **容器元素** (例如a) `div`; 不要通过 `<canvas>` 它本身——画布的子孙是倒行逆施的内涵,而永远不会被渲染出,这导致了黑幕. 通过画布 `canvas` 选项。 建议将包装的高度和宽度初始化.
    -   `videoUrl`: \[标\]一非空生弦. 内置来源接受亲属或 `http(s)://` MPEG- TS 资源的 URL( 文件名不必以 `.ts`),或 a `ws://` 编号 : `wss://` URL提供MPEG-TS. 已经创建的 `WebSocket` 实例不被接受。 自定义来源( O)`source` 内 `overlayOptions`定义自己的投入.
    -   `options`: \[标 支持:
        -   `canvas`: \[结 元素\] HTML 画布元素用于视频渲染 。 如果未给出, 渲染器将创建自己的画布元素 。 默认 `''`。 。 。 .
        -   `poster`: \[打入\] URL到一个图像,作为海报在视频播放前显示. (建议手动设置)
        -   `autoplay`曰:\[宝. 是否立即开始播放 。 默认 `false`。 。 。 .
        -   `autoSetWrapperSize`曰:\[宝. 是否在视频加载时自动设置包装元素大小 。 默认 `false`。 。 。 .
        -   `loop`曰:\[宝. 是否循环视频( 只有静态文件) 。 默认 `false`。 。 。 .**\[覆盖\]**
        -   `control`曰:\[宝. 用户是否可以控制 。 内置的播放按钮和点击切换仅适用于静态文件 : `ws://` 编号 : `wss://` 现场源头没有内置的回放控制,必须使用 `play()` 编号 : `pause()`默认 `true`。 。 。 .
        -   `decodeFirstFrame`曰:\[宝. 是否解码并显示视频的第一个帧 。 默认 `true`。 。 。 .
        -   `picMode`: \[Boolean\] 图片模式(没有播放按钮). 默认 `false`。 。 。 .
        -   `progressive`: \[Boolean\] 是否用块装入数据(仅静态文件) 。 默认 `true`。 。 。 .
        -   `chunkSize` \[数目\] 一次装入的字节块大小 。 默认 `1024*1024` (单位:1mb).
        -   `hooks`: \[标 钩子功能
            -   `play`: \[功能\] 视频播放时会起钩子的作用.
            -   `pause`: \[功能\] 视频暂停时会起钩子功能.
            -   `stop`: \[功能\] 视频停止时会起钩子功能.
            -   `load`: \[功能\] 视频建立时的钩子功能.
    -   `overlayOptions`: \[标 更多选项可以查看 [jsmpeg 选项](https://github.com/phoboslab/jsmpeg#usage)
        -   `protocols`: \[String QQ Array\] WebSocket子程序,转发给 `new WebSocket(url, protocols)` (单位:千美元)`ws://` 财务报告和审定财务报表 `wss://` 仅限URL). 能够携带起重机标志。 默认 `undefined`。见 [WebSocket 认证](https://npmcn.com/package/%40cycjimmy/jsmpeg-player/#readme-websocket-authentication)。 。 。 .
        -   `preserveDrawingBuffer`曰:\[宝. 保留WebGL绘图缓冲器,这样画布就可以被读取回来,例如用它来快照 `canvas.toDataURL()`默认 `false`。见 [抓图](https://npmcn.com/package/%40cycjimmy/jsmpeg-player/#readme-snapshot)。 。 。 .
-   `JSMpeg.VideoElement` 实例支持以下方法:
    
    -   `play()`: 开始重播
    -   `pause()`: 暂停播放
    -   `stop()`: 停止播放并寻求开始
    -   `destroy()`:停止回放,释放出出源,渲染器,解码器和音频,以及空的视频包装. 玩家被移除时需要,请查看 [多个玩家](https://npmcn.com/package/%40cycjimmy/jsmpeg-player/#readme-multiple-players)。 。 。 .
-   `JSMpeg.VideoElement.player` 实例 API 可以查看 [JSMPEG (英语). 玩家 API](https://github.com/phoboslab/jsmpeg#jsmpegplayer-api)
    

### 抓图

WebGL 绘图缓冲器一旦一个帧被合成就被清除了,所以不准备就读取画布就会返回黑色图像. 设定 `preserveDrawingBuffer` 内 `overlayOptions`数字 :

```javascript
const video = new JSMpeg.VideoElement('#videoWrapper', 'video.ts', {}, {
  preserveDrawingBuffer: true,
})

// Any time after the first frame has been rendered
const dataUrl = video.els.canvas.toDataURL('image/png')
```

-   当创建了WebGL上下文时会读取旗帜,所以必须在建设时通过——不能在已经运行的玩家上被启用.
-   如果你通过自己的元素 `canvas` 选项,它已经有一个 WebGL 上下文(因为) `getContext('webgl')` 在玩家创建之前就曾呼吁过它),该上下文被再用而旗被忽略. 让玩家创建上下文取而代之.
-   保存缓冲器有性能成本,所以如果不需要快照,就不要挂上国旗.
-   不需要WebGL:与 `disableGl: true` 玩家返回 Canvas 2D 渲染器, 其中 `toDataURL()` 总是有效的,以更高的CPU使用率为代价.

### WebSocket 认证

浏览器无法设置 `Authorization` 在 WebSocket 握手时的标题—— `new WebSocket(url, protocols)` 是WebSocket API提供的所有服务。 最接近浏览器本地化的选项是将信使作为子协议发送到服务器上作为 `Sec-WebSocket-Protocol` 请求头( 退出 URL 并退出访问日志) :

```javascript
const video = new JSMpeg.VideoElement('#videoWrapper', 'wss://example.com/stream', {}, {
  protocols: ['Bearer.<token>'],
})
```

```javascript
const player = new JSMpeg.Player('wss://example.com/stream', {
  protocols: ['Bearer.<token>'],
})
```

-   服务器必须接受子协议和 **回声** 握手反应`Sec-WebSocket-Protocol`) (中文(简体) ). 如果所请求的子protocol中没有一个被响应,浏览器会中止连接.
-   每个值必须是有效的 HTTP 符 ([RFC 7230 (法语)](https://www.rfc-editor.org/rfc/rfc7230#section-3.2.6)没有空格, `+`, (中文(简体) ), `/` 或者说 `=`. JWTs (base64url) 适配;包含这些字符的符号需要基于 cookie 的 Auth 代替(握手自动发送 cookie 用于目标来源).

### 多个玩家

每个 `JSMpeg.VideoElement` 是一个完整,独立的玩家:它打开了自己的源链接,创建了自己的WebGL上下文并运行自己的解码回路. 只有 `AudioContext` 而WASM模块是共享的,因此可以同时玩出多少玩家被浏览器和设备所约束,而不是这个库.

-   浏览器将每页的活的WebGL上下文数上限为(Chrome有16个,一些移动浏览器上更少). 过去的限制 历史最悠久的背景被放弃 画布是黑色的 没有任何例外.
-   每个流被解码在主线程上的软件中,每个玩家都会自行分配解码缓冲(视频为512 KB,默认音频为128 KB). 由多条流组成的网格竞争相同的CPU时间,无论使用何种渲染器.
-   `progressive: true` (默认)整个流每个播放器保留一个开放请求,这与HTTP/1.1的每个源头的~6连接算上. 这仅适用于静态文件; `ws://` 财务报告和审定财务报表 `wss://` 来源不受影响.

**打电话 `destroy()` 当玩家离开时.** 在SPA中,将建筑师返回的实例丢弃,例如将其叫到 `componentDidMount` 而不存储结果 —— 在其标记消失后让玩家运行: socket, WebGL 上下文和解码回路全部存活. 然后几道导航就足以使页面疲惫不堪,由于无所投放,硬重载似乎是唯一的固定.

```text
// React
componentDidMount() {
  this.video = new JSMpeg.VideoElement('#videoWrapper', 'wss://example.com/stream');
}

componentWillUnmount() {
  this.video.destroy();
  this.video = null;
}
```

将许多相机保留在屏幕上:

-   `disableGl: true` —— Canvas 2D 渲染器不消耗WebGL上下文,以更高的CPU使用率为代价.
-   `audio: false` ——省去相机网格的音频解码.
-   仅为可见的平板块创建播放器( 例如: `IntersectionObserver`和 `destroy()` 当他们离开风景区时.
-   服务于缩略图中的低比特率子流;用于软件解码每个流物质的分辨率和比特率大于平分数.

### 在浏览器中使用

[![jsdelivr](https://img.shields.io/jsdelivr/npm/hy/@cycjimmy/jsmpeg-player)](https://www.jsdelivr.com/package/npm/@cycjimmy/jsmpeg-player)

```html
<div id="videoWrapper"></div>
<script src="jsmpeg-player.umd.min.js"></script>
<script>
  var videoUrl = '../static/media/test_video.ts';
  new JSMpeg.VideoElement('#videoWrapper', videoUrl);
</script>
```

## 光盘N

要通过CDN使用,请在您的 HTML 中包含此内容:

```text
<script src="https://cdn.jsdelivr.net/npm/@cycjimmy/jsmpeg-player@7/dist/jsmpeg-player.umd.min.js"></script>
```

## 移动到 v7

v7 放弃了 CommunityJS 构建并提升了节点和浏览器目标. `import` 并且浏览器全局不变,所以大多数消费者根本不需要改变.

-   `dist/jsmpeg-player.cjs` 不再生产 `exports` 不再暴露一个 `require` 条件. `require('@cycjimmy/jsmpeg-player')` 由于节点可以 `require()` 一个 ES 模块,但它返回模块命名空间:使用 `require('@cycjimmy/jsmpeg-player').default`。 。 。 .
-   `main` 财务报告和审定财务报表 `module` 两个点 `dist/jsmpeg-player.esm.js`编辑 `browser` 字段仍然指向用于CDN和遗留工具的UMD构建.
-   `engines.node` 现在 `^22.22.2 || >=24.15.0`,新的建筑工具链的地板. `engines` 因此它只会限制贡献者和消费者,而不是消费者.
-   建设目标 `es2015` 与 `defaults` 浏览器列表,因此IE不再被支持. 贝贝降平已去, 这使得 `jsmpeg-player.esm.js` 大约24% `jsmpeg-player.umd.min.js` 略为小于v6.
-   深道继续通过 `./dist/*` 输出.
-   运行时间 CSS 仍然作为 a 注入 `<style>` 元素; 没有要导入的样式表.

```javascript
// CommonJS consumers: require() can load an ES module from Node 20.19 on
const JSMpeg = require('@cycjimmy/jsmpeg-player').default
```

## 发展

```shell
$ npm run dev          # Vite dev server on top of the root index.html
$ npm run lint         # ESLint (flat config, @antfu/eslint-config)
$ npm run lint:style   # Stylelint for src/**/*.{css,scss}
$ npm test             # node --test
$ npm run package      # build dist/ and assemble .release/
```

`index.html` 在寄存器根是开发条目: 它导入 `src/` 通过Vite,所以变化出现时没有积分. `static/index.html` 是 GitHub 页面演示并装入预建 `jsmpeg-player.umd.js` 一个平地 `<script>` 标记; `npm run build:deployment` 组装到 `.publish/`。见 [捐款额](https://npmcn.com/package/%40cycjimmy/jsmpeg-player/CONTRIBUTING.md) 检查CI运行.

## 为视频/音频编码 [齐平格](https://github.com/phoboslab/jsmpeg) 以 [ffmpeg 数据](https://ffmpeg.org/). 例如:

```shell
$ ffmpeg -i input.mp4 -f mpegts \
         -codec:v mpeg1video -s 640x360 -b:v 700k -r 25 -bf 0 \
         -codec:a mp2 -ar 44100 -ac 1 -b:a 64k \
         output.ts
```

-   选项
    -   `-s`: 视频大小
    -   `-b:v`: 视频比特率
    -   `-r`: 帧率
    -   `-ar`:采样率
    -   `-ac`: 音频频道数量
    -   `-b:a`: 音频比特率

## 常见问题

### @cycjimmy/jsmpeg-player 是什么？

MPEG1 基于 JSMpeg 的视频播放器

### 如何安装 @cycjimmy/jsmpeg-player？

在项目目录运行 npm install @cycjimmy/jsmpeg-player，或使用 pnpm add / yarn add / bun add。

### @cycjimmy/jsmpeg-player 支持 TypeScript 吗？

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

### @cycjimmy/jsmpeg-player 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cycjimmy/jsmpeg-player 可以商用吗？

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

### @cycjimmy/jsmpeg-player 的下载量有多少？

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

### @cycjimmy/jsmpeg-player 还在维护吗？

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