# @api\.video/media-recorder 中文文档

规范地址：https://npmcn.com/package/%40api.video/media-recorder/

版本：1\.0\.11
npm 元数据更新时间：2025-05-22T12:54:34.331Z
中文译文更新时间：2026-11-06T18:10:22.007Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40api.video/media-recorder
原文对照：https://npmcn.com/package/%40api.video/media-recorder/?lang=original
项目主页：https://github.com/apivideo/api.video-typescript-media-recorder#readme
源码仓库：https://github.com/apivideo/api.video-typescript-media-recorder

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

- 包体积（解压后）：143 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2021-11-10T11:50:31.249Z
- 最新版本发布：2024-09-24T12:46:22.939Z
- 近 30 天下载量：2504（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 0 个）

## 中文简介

api.video 媒体记录器 - 轻松地从你的网络相机上传视频

## 安装

```sh
npm install @api.video/media-recorder
```

也可以使用：`pnpm add @api.video/media-recorder`、`yarn add @api.video/media-recorder`、`bun add @api.video/media-recorder`

## README

[![badge](https://img.shields.io/twitter/follow/api_video?style=social)](https://twitter.com/intent/follow?screen_name=api_video)   [![badge](https://img.shields.io/github/stars/apivideo/api.video-typescript-media-recorder?style=social)](https://github.com/apivideo/api.video-typescript-media-recorder)   [![badge](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fcommunity.api.video)](https://community.api.video/) ![](https://github.com/apivideo/.github/blob/main/assets/apivideo_banner.png)

# api.video 媒体记录器

![npm](https://img.shields.io/npm/v/@api.video/media-recorder) ![ts](https://badgen.net/badge/-/TypeScript/blue?icon=typescript&label)

[视频](https://api.video/) 是产品制造者的视频基础设施。 闪电快视频 API 用于在您的应用程序中集成,缩放,并管理点播后低空直播功能.

## 目录

-   [目录](https://npmcn.com/package/%40api.video/media-recorder/#readme-table-of-contents)
-   [项目说明](https://npmcn.com/package/%40api.video/media-recorder/#readme-project-description)
-   [开始](https://npmcn.com/package/%40api.video/media-recorder/#readme-getting-started)
    -   [安装](https://npmcn.com/package/%40api.video/media-recorder/#readme-installation)
        -   [安装方法 1: 需要js](https://npmcn.com/package/%40api.video/media-recorder/#readme-installation-method-1-requirejs)
        -   [安装方法 # 2 : 打字符](https://npmcn.com/package/%40api.video/media-recorder/#readme-installation-method-2-typescript)
        -   [在 Javascript 计划中简单包含](https://npmcn.com/package/%40api.video/media-recorder/#readme-simple-include-in-a-javascript-project)
-   [文档](https://npmcn.com/package/%40api.video/media-recorder/#readme-documentation)
    -   [证据](https://npmcn.com/package/%40api.video/media-recorder/#readme-instantiation)
        -   [选项](https://npmcn.com/package/%40api.video/media-recorder/#readme-options)
            -   [使用授权的上传符( 建议):](https://npmcn.com/package/%40api.video/media-recorder/#readme-using-a-delegated-upload-token-recommended)
            -   [使用访问符( 损坏 ) :](https://npmcn.com/package/%40api.video/media-recorder/#readme-using-an-access-token-discouraged)
            -   [共同选项](https://npmcn.com/package/%40api.video/media-recorder/#readme-common-options)
        -   [示例](https://npmcn.com/package/%40api.video/media-recorder/#readme-example)
    -   [方法](https://npmcn.com/package/%40api.video/media-recorder/#readme-methods)
        -   [`start(options?: { timeslice?: number })`](https://npmcn.com/package/%40api.video/media-recorder/#readme-startoptions--timeslice-number-)
            -   [选项](https://npmcn.com/package/%40api.video/media-recorder/#readme-options-1)
        -   [`stop(): Promise<VideoUploadResponse>`](https://npmcn.com/package/%40api.video/media-recorder/#readme-stop-promisevideouploadresponse)
        -   [`addEventListener(event: string, listener: Function)`](https://npmcn.com/package/%40api.video/media-recorder/#readme-addeventlistenerevent-string-listener-function)
        -   [`getMediaRecorderState(): RecordingState`](https://npmcn.com/package/%40api.video/media-recorder/#readme-getmediarecorderstate-recordingstate)
-   [完整实例](https://npmcn.com/package/%40api.video/media-recorder/#readme-full-example)

## 项目说明

便于上传数据到一个字节库 [媒体结构](https://developer.mozilla.org/fr/docs/Web/API/MediaStream) (原始内容存档于2018-09-28). to api.video. 它可以方便地从用户的网络相机上上传到api.video,也可以从屏幕录制.

## 开始

### 安装

#### 安装方法 1: 需要js

如果您使用需要js, 您可以将库添加为您的项目依赖性

```sh
$ npm install --save @api.video/media-recorder
```

然后可以在脚本中使用库 :

```javascript
var { ApiVideoMediaRecorder } = require('@api.video/media-recorder');

var recorder = new ApiVideoMediaRecorder(mediaStream, {
    uploadToken: "YOUR_DELEGATED_TOKEN"
    // ... other optional options
}); 
```

#### 安装方法 # 2 : 打字符

如果您使用 Typescript, 您可以将库添加为您的项目依赖性

```sh
$ npm install --save @api.video/media-recorder
```

然后可以在脚本中使用库 :

```typescript
import { ApiVideoMediaRecorder } from '@api.video/media-recorder'

const recorder = new ApiVideoMediaRecorder(mediaStream, {file: files[0],
    uploadToken: "YOUR_DELEGATED_TOKEN"
    // ... other optional options
});
```

#### 在 Javascript 计划中简单包含

将库包含在您的 HTML 文件里 :

```html
<head>
    ...
    <script src="https://unpkg.com/@api.video/media-recorder" defer></script>
</head>
```

然后,一旦 `window.onload` 事件已被三进制, 使用 `new ApiVideoMediaRecorder()`数字 :

```html
...
<script type="text/javascript"> 
    const recorder = new ApiVideoMediaRecorder(mediaStream, {
        uploadToken: "YOUR_DELEGATED_TOKEN"
    });
    recorder.start();
    // ...
    recorder.stop().then((video) => console.log(video));
</script>
```

## 文档

### 证据

#### 选项

媒体记录器对象使用一个 [媒体结构](https://developer.mozilla.org/fr/docs/Web/API/MediaStream) 还有一个 `options` 对象。 要提供选项取决于您要认证到 API 的方式: 要么使用授权的上传符( recommanded) , 要么使用通常的访问符.

##### 使用授权的上传符( 建议):

在从客户端上传时,使用授权上传符进行认证是最佳选项. 更多关于授权上传信条 [授权上传](https://api.video/blog/tutorials/delegated-uploads/)。 。 。 .

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 上传脚本 | **对** | 字符串 | 您的上传标志 |
| 视频 | 没有 | 字符串 | 现有视频的编号 |
| _常见选项(见铃声)_ |  |  |  |

##### 使用访问符( 损坏 ) :

**3⁄4 ̄ ̧漯B**: 注意暴露您的访问符客户端会导致巨大的安全问题. 只有你知道自己在做什么,才使用这种方法:).

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 访问脚本 | **对** | 字符串 | 您的访问符 |
| 视频 | **对** | 字符串 | 现有视频的编号 |
| _常见选项(见铃声)_ |  |  |  |

##### 共同选项

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 爱比荷斯 | 没有 | 字符串 | api.video 主机(默认:ws.api.video) |
| 重试 | 没有 | 编号 | aPI 调用失败时重试的次数( 默认: 5) |
| 视频Name | 没有 | 字符串 | 您录制的视频名称( 覆盖默认的“ 文件” 名称) |

#### 示例

```javascript
    const mediaRecorder = new ApiVideoMediaRecorder(myMediaStream, {
        uploadToken: "YOUR_DELEGATED_TOKEN",
        retries: 10,
    });
```

### 方法

#### `start(options?: { timeslice?: number })`

开始()方法开始上传从MediaStream检索的内容. 这需要选择 `options` 参数.

##### 选项

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 时间 | 无( 默认: 5000) | 编号 | 要记录到每个 Blob 的毫秒数 . |

**示例**

```javascript
    // ... mediaRecorder instantiation

    mediaRecorder.start();
    // or, with a 2 seconds timeslice:
    // mediaRecorder.start({ timeslice: 2000 });
```

#### `stop(): Promise<VideoUploadResponse>`

开始()方法停止了媒体录制. 它上传了从MediaStream上检索到的最后一部分内容(这将开始将视频部分汇总在api.video侧). 它不需要参数。 它返回了一个承诺 解决新创建的视频.

#### `addEventListener(event: string, listener: Function)`

为媒体记录器定义事件收听器 。 现有活动如下:

-   `"error"`: 当发生错误时
-   `"recordingStopped"`: 当录音停止时
-   `"videoPlayable"`: 当视频可以播放时

**示例**

```javascript
    // ... mediaRecorder instantiation

    mediaRecorder.addEventListener("error", (event) => {
       console.log(event.data);
    });
```

#### `getMediaRecorderState(): RecordingState`

返回底线状态 [媒体记录](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder). 状态可以是以下之一: `inactive`, (中文(简体) ), `paused`, (中文(简体) ), `recording`。 。 。 .

**示例**

```javascript
    // ... mediaRecorder instantiation

    mediaRecorder.stop()
        .then(video => console.log(video));
```

## 完整实例

```html
<html>
    <head>
        <script src="../dist/index.js"></script>
        <style>
            #container {
                display: flex;
                flex-direction: column;
                align-items: center;
            }
            #video {
                width: 640;
                height: 480;
                border: 1px solid gray;
            }
            #container div {
                margin: 10px 0;
            }
        </style>
    </head>

    <body>
        <div id="container">
            <div>
                <video id="video"></video>
            </div>
            <div>
                <button id="start" disabled>start recording</button>
                <button id="stop" disabled>stop recording</button>
            </div>
            <div>
                <p>Video link: <span id="video-link"><i>will be displayed when the recording is finished</i></span></p>
            </div>
        </div>
        
        <script> 
            const video = document.querySelector('#video');
            const startButton = document.getElementById("start");
            const stopButton = document.getElementById("stop");
            const videoLink = document.getElementById("video-link");
            let stream, recorder;

            var constraints = window.constraints = {
                audio: true,
                video: true
            };

            navigator.mediaDevices.getUserMedia(constraints).then((s) => {
                stream = s;
                video.srcObject = s;
                video.play();
                startButton.disabled = false;
            });

            document.getElementById("start").addEventListener("click", () => {
                recorder = new ApiVideoMediaRecorder(stream, {
                    uploadToken: "UPLOAD_TOKEN"
                });
                
                recorder.start();
                
                startButton.disabled = true;
                stopButton.disabled = false;
            });

            document.getElementById("stop").addEventListener("click", () => {
                startButton.disabled = false;
                stopButton.disabled = true;

                recorder.stop().then(v => videoLink.innerHTML = v.assets.player);
            });
        </script>
    </body>
</html>
```

## 常见问题

### @api\.video/media-recorder 是什么？

api\.video 媒体记录器 - 轻松地从你的网络相机上传视频

### 如何安装 @api\.video/media-recorder？

在项目目录运行 npm install @api\.video/media-recorder，或使用 pnpm add / yarn add / bun add。

### @api\.video/media-recorder 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @api\.video/media-recorder 支持 ESM 还是 CommonJS？

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

### @api\.video/media-recorder 可以商用吗？

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

### @api\.video/media-recorder 的下载量有多少？

根据 npm 官方下载统计，@api\.video/media-recorder 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,504 次，日均约 83 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @api\.video/media-recorder 还在维护吗？

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