# @audio/encode-mp4 中文文档

规范地址：https://npmcn.com/package/%40audio/encode-mp4/

版本：1\.2\.1
npm 元数据更新时间：2026-10-07T10:51:45.733Z
中文译文更新时间：2026-11-07T06:09:36.722Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40audio/encode-mp4
原文对照：https://npmcn.com/package/%40audio/encode-mp4/?lang=original
项目主页：https://github.com/audiojs/encode/tree/main/packages/encode-mp4
源码仓库：https://github.com/audiojs/encode

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

- 包体积（解压后）：91.8 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：4 个
- 首次发布：2026-08-28T21:36:15.575Z
- 最新版本发布：2026-10-07T10:51:45.455Z
- 近 30 天下载量：2065（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

编码 PCM 音频样本到 MP4/M4A (ISO BMFF) — 纯 JS muxer, remuxer 和 iTunes-tag 写入器

## 安装

```sh
npm install @audio/encode-mp4
```

也可以使用：`pnpm add @audio/encode-mp4`、`yarn add @audio/encode-mp4`、`bun add @audio/encode-mp4`

## README

# @ audio/ encode- mp4 (英语) [![npm](https://img.shields.io/npm/v/@audio/encode-mp4)](https://www.npmjs.com/package/@audio/encode-mp4) [![MIT](https://img.shields.io/badge/MIT-%E0%A5%90-white)](https://github.com/krishnized/license)

纯 JS MP4/M4A/MOV muxer, remuxer, 和 iTunes-tag 作者

```
npm install @audio/encode-mp4
```

```js
import mp4 from '@audio/encode-mp4'
import { mux } from '@audio/encode-mp4/mux'
import { remux } from '@audio/encode-mp4/remux'
import { writeMeta } from '@audio/encode-mp4/meta'
```

除了在ISO/IEC 14496-12(ISOBMFF)盒中包装预编码访问单元之外,没有编码知识. `mux()` 将 AAC、ALAC、Opus、FLAC、MP3或原始PCM样本包成完整 `.m4a`编号 :`.mp4` 文件(在mdat前移动,因此它会逐渐流出/播放). `remux()` 互换或剥取已存在的MP4/MOV的音频音轨而无需触摸视频. `writeMeta()` 将iTunes风格的标签重写到位. 默认导出将驱动编码器端到 `m4a` 伞形格式. `decode-mp4` (这个生态系统的分解器)和 `decode-aac/meta` 是否检查了每盒的两样东西 .

### `mux(track, opts)` → `Uint8Array`

```js
let file = mux({
  codec: 'aac',              // 'aac' | 'alac' | 'opus' | 'flac' | 'mp3' | 'pcm'
  sampleRate: 44100,
  channels: 2,
  samples,                   // Uint8Array[] — one access unit per entry (raw AAC AU, no ADTS)
  config: audioSpecificConfig,
  durations: 1024,           // per-AU duration in `timescale` units — a number or per-AU array
  priming: 2112,             // encoder delay, PCM samples — edit list + iTunSMPB (aac)
}, { meta: { title: 'Song' }, chapters: [{ time: 0, title: 'Intro' }] })
```

| `track` 字段 | 默认 |  |
| --- | --- | --- |
| `codec` | —— 说 | `aac` | `alac` | `opus` | `flac` | `mp3` | `pcm` (必须) |
| `sampleRate`, (中文(简体) ), `channels` | —— 说 | 所需经费 |
| `samples` | —— 说 | `Uint8Array[]`,每个条目一个访问单元(需要) |
| `durations` | 特定代码 | AAC 1024; ALAC 从饼干取出的框架长度; Opus / packet(TOC); FLAC / frame (标题); MP3 1152/576; PCM 从块长度计算 |
| `timescale` | `sampleRate` (奥普斯: `48000`(中文(简体) ) | 样表时间尺度 |
| `config` | —— 说 | 审计咨询委员会: `AudioSpecificConfig` 字节。 拉丁美洲和加勒比:24字节 `ALACSpecificConfig`。 Opus 语句 : `{ preSkip, outputGain?, channelMappingFamily?, channelMappingTable? }`. FLAC: 34字节STREAMINFO. PCM: (英语) `{ bits, float?, be? }`。 MP3: 未使用 |
| `priming`, (中文(简体) ), `padding` | `0` | 编码器延迟/ 跟踪垫, PCM 样本—— 作为编辑列表媒体时间抵消写入, (AAC) 作为 `iTunSMPB` |
| `bitrate` | —— 说 | 位/秒,写入 `esds`编号 :`btrt` |

| `opts` 字段 | 默认 |  |
| --- | --- | --- |
| `brand` | `'M4A '` | `'M4A '` | `'isom'` | `'mp42'` | `'qt '` —— 说 `qt` 写入 `sowt`编号 :`in24`编号 :`fl32` 快速时间 PCM 原子代替 `ipcm`编号 :`fpcm` |
| `meta` | —— 说 | 相同的密钥 `writeMeta` 回放——见下文 |
| `chapters` | —— 说 | `[{ time (s), title }]` -尼罗 `chpl` |
| `creationTime` | 现在 | `Date` |

样本表是紧凑的: `stts` 径长压缩, `stsz` 当每个非盟的长度相同时,使用常数大小的快捷键, `stsc`编号 :`stco` 将每~1s或128个AU(先来者)块, `co64` 只有在抵消超过4GB时。 所有东西被写成一个预先分配的,可生长的缓冲器——没有每箱阵列的散射——所以将一个1小时的AAC音轨(~155k AUs)用到~12ms.

### `remux(src, audio, opts)` → `Uint8Array`

```js
let strippedVideo = remux(videoBytes, null)                 // drop the audio track
let dubbed = remux(videoBytes, { codec: 'opus', ... })       // replace it (track object, mux() shape)
let dubbed2 = remux(videoBytes, mux({ codec: 'alac', ... })) // or a Uint8Array mux() already produced
```

视频(和任何其他非音频音轨——字幕,时码)通过没有修改的复制;只有其 `stco`编号 :`co64` 块抵消被重写`stco`→`co64` 如果新布局推倒了过去 4GB 的偏移). 一个新鲜的 `mdat` 交互视频和音频块按演示时间排列,结果仍然在逐步发挥。 处理64位的盒子大小, `uuid` 框,则, `mdat` 在此之前 `moov`多个 `mdat`s. 向分散的MP4(`moof`) ——这是一整个文件的muxer,而不是一个零碎的-MP4编剧.

### `writeMeta(bytes, { meta, chapters })` → `Uint8Array`

重写 `moov/udta/meta/ilst` (+ 数) `chpl` 用于章节),存在于已存在的MP4/M4A. Moov是先被保存的,而不是迁移到最后,所以当它生长时,每道的块相抵被同一种三角形所转移(只被移动) `udta`'长度变化;没有其他 `moov` 页:1. `meta` 键是准确反向的 `decode-aac/meta`是因为 `parseMeta`数字 : `title artist album albumartist composer genre year track disc comment lyrics copyright bpm key isrc publisher software pictures`。 。 。 . `key`编号 :`isrc`编号 :`publisher` 以 `----` 自由形式原子( `com.apple.iTunes` (原始内容存档于2018-10-29) (中文(简体) ). Convention by mutagen/AtomicParsley)——在这个生态系统中还没有运出过剖析器读出它们,所以它们只写.

### `mp4(opts)` → `{ encode(channels), flush(), free() }`

```js
let enc = await mp4({ sampleRate: 44100, channels: 2, codec: 'flac' })
enc.encode(channelData)   // buffers; always returns an empty Uint8Array
let file = await enc.flush()
enc.free()
```

驱动器 `@audio/encode-aac` (AAC,只浏览器——需要) `AudioEncoder`, (中文(简体) ), `@audio/encode-opus/core` (奥普斯), `@audio/encode-flac` (拉丁美洲和加勒比), `@audio/encode-mp3` (MP3)或平地相接(PCM),然后 `mux()`结果。 全文件容器 : `encode()` 缓冲器, `flush()` 返回完整文件(形状与 `@audio/encode-qoa`) (中文(简体) ). `codec` 默认为 `'aac'` 何时 `globalThis.AudioEncoder` 存在(浏览器),其他 `'flac'`AAC的编码器延迟没有被WebCodecs报告,所以 `priming` 默认为 `2112` 样本 —— 标准 AAC- LC 值从 FAAC 到 FDK- AAC 的每个 LC 编码器; 如果您知道得更清楚, 则超过它 . `encode()` 被分割成任意个个数的块产生字节-同声输出到单个全缓冲调用(PCM,Opus,FLAC,MP3,AAC通过FDK;WebCodecs AAC是浏览器的编码器).

**此处未完成 :** `mux()` 不修剪 MP3/Opus 编码器延迟和为您补丁 `mp4()` does(来自LAME的Info标签,来自Opus编码器的外观):通过 `priming`编号 :`padding` 如果您需要比特精确的空格 MP3/Opus 从 `mux()` (Opus自己的预滑 _实值_ 自动处理 `mux()`因为它是每个Opus包流的内在,而不是编码器特有的未知数). `stco`→`co64` 升级期间 `writeMeta` 而不是写错偏移.

**使用时 :** 写作 `.m4a`编号 :`.mp4` 输出在浏览器或节点中不带相机; 互换视频文件的音频音轨( dugbing, 替换音轨)而不重新编码视频; 标记 M4A 文件 .

## 光谱参考

-   ISO/IEC 14496-12 — ISO Base Media 文件格式(框结构,样本表,编辑列表)
-   ISO/IEC 14496-14 — MP4 文件格式
-   ISO/IEC 14496-1 第8.3节 - `esds` 说明`ES_Descriptor`编号 :`DecoderConfigDescriptor`编号 :`SLConfigDescriptor`(中文(简体) )
-   ISO/IEC 23003-5 — ISOBMFF中的PCM (中文(简体) )`ipcm`编号 :`fpcm`编号 :`pcmC`(中文(简体) )
-   [ISOBMFF 中的 Opus 选项](https://opus-codec.org/docs/opus_in_isobmff.html) —— 说 `Opus` 样本条目 + `dOps`
-   [ISOBMFF 中的 FLAC 定义](https://github.com/xiph/flac/blob/master/doc/isoflac.txt) —— 说 `fLaC` 样本条目 + `dfLa`
-   QuickTime 文件格式——声音样本描述版本0/1/2, `sowt`编号 :`in24`编号 :`fl32`编号 :`enda`
-   iTunes 元数据原子 - [变种. mp4](https://mutagen.readthedocs.io/en/latest/api/mp4.html)原子Parsley文件
-   尼罗分会`chpl`) – 每个ffmpeg格式 `libavformat/movenc.c` `mov_write_chpl_tag`

### 流程输出

`stream: true` 写一个零碎的文件(ISO/IEC 14496-12 §8.8),因为它编码: `ftyp` + 键 `moov` (样本条目,空表格, `mvex`,标签和章节),一旦第一个单元存在,那么 `moof` + 键 `mdat` 每秒媒体。 只有当前碎片的单位被持有. `head()` 之后 `flush()` 返回仅由结尾所知道(FLAC的STREAMINFO)重建的init段,或无效.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40audio/encode-mp4/LICENSE)

[ॐ](https://github.com/krishnized/license/)

## 常见问题

### @audio/encode-mp4 是什么？

编码 PCM 音频样本到 MP4/M4A \(ISO BMFF\) — 纯 JS muxer, remuxer 和 iTunes-tag 写入器

### 如何安装 @audio/encode-mp4？

在项目目录运行 npm install @audio/encode-mp4，或使用 pnpm add / yarn add / bun add。

### @audio/encode-mp4 支持 TypeScript 吗？

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

### @audio/encode-mp4 支持 ESM 还是 CommonJS？

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

### @audio/encode-mp4 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @audio/encode-mp4 可以商用吗？

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

### @audio/encode-mp4 的下载量有多少？

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

### @audio/encode-mp4 还在维护吗？

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