升级用户请阅读发布说明。

handbrake-js

Handbrake-js是为node.js设计的Handbrake（v1.6.1）。它旨在为在node.js中构建视频转码软件提供精简稳定的基础。

HandBrake是一个将视频从几乎任何格式转换为一系列现代、广泛支持的编解码器的工具。它可以处理大多数常见的多媒体文件以及不含任何复制保护的DVD或BluRay源。

输出：

文件容器：.MP4(.M4V)和.MKV
视频编码器：H.264(x264)、H.265(x265) MPEG-4和MPEG-2 (libav)、VP8 (libvpx)和Theora(libtheora)
音频编码器：AAC、CoreAudio AAC/HE-AAC（仅限OS X）、MP3、Flac、AC3或Vorbis
音频直通：AC-3、DTS、DTS-HD、AAC和MP3轨道

阅读更多关于功能的信息。

兼容平台

已在Mac OSX、Ubuntu 14、Windows XP、Windows 7和Windows 8.1上测试通过。

Ubuntu 14.04注意事项：由于这个原因，在Ubuntu 14.04及以后版本上转码为MP4会失败。

安装

系统要求

只需要node.js。在Mac和Windows上，其他所有内容都会自动安装。但在Linux上，您必须使用以下命令手动安装HandbrakeCLI：

sudo add-apt-repository --yes ppa:stebbins/handbrake-releases
sudo apt-get update -qq
sudo apt-get install -qq handbrake-cli

作为库使用

进入您的项目目录，然后运行：

$ npm install handbrake-js --save

Mac / Linux用户可能需要使用sudo运行。

现在您可以开始在应用程序中进行编码。

const hbjs = require('handbrake-js')

hbjs.spawn({ input: 'something.avi', output: 'something.m4v' })
  .on('error', err => {
    // 无效的用户输入，未找到视频等
  })
  .on('progress', progress => {
    console.log(
      '完成百分比: %s, 预计剩余时间: %s',
      progress.percentComplete,
      progress.eta
    )
  })

作为命令行应用程序使用

从任何目录运行以下命令：

$ npm install -g handbrake-js

Mac / Linux用户可能需要使用sudo运行。

现在，您可以像使用HandbrakeCLI一样调用handbrake，使用所有常用的选项。默认情况下，只输出统计信息，传递--verbose参数会打印原始HandbrakeCLI输出。以下命令将AVI转码为更通用的H.264（mp4）：

$ handbrake --input '某集.avi' --output '某集.mp4' --preset Normal
任务      % 完成     FPS       平均FPS   预计剩余时间
编码中    1.07       131.76    158.12    00h21m11s

HandbrakeCLI路径

在某些情况或环境（如Docker）中，您可能需要指定自定义HandbrakeCLI路径。您可以在环境变量中指定路径：

HANDBRAKECLI_PATH="./example/HandbrakeCLI"

..或在程序中通过选项传递HandbrakeCLIPath。请参阅下面的API文档以获取说明。另外，请查看examples文件夹中的示例代码。

API参考

Node.js版Handbrake。

示例

const hbjs = require('handbrake-js')

handbrake-js
- 静态
  - .spawn([options]) ⇒ <code>Handbrake</code>
  - .exec(options, [onComplete])
  - .run(options) ⇒ <code>Promise</code>
- 内部
  - ~Handbrake ⇐ <code>EventEmitter</code>
    - .output : <code>string</code>
    - .options : <code>object</code>
    - .eError
    - .cancel()
    - "start"
    - "begin"
    - "progress" (progress)
    - "output" (output)
    - "error" (error)
    - "end"
    - "complete"
    - "cancelled"

hbjs.spawn([options]) ⇒ <code>Handbrake</code>

使用提供的选项生成一个HandbrakeCLI进程，返回一个Handbrake实例，您可以在其上监听事件。

类型：<code>handbrake-js</code>的静态方法

参数	类型	描述
[options]	<code>object</code>	直接传递给HandbrakeCLI的选项
[options.HandbrakeCLIPath]	<code>string</code>	覆盖内置的`HandbrakeCLI`二进制路径。

示例

const hbjs = require('handbrake-js')

const options = {
  input: 'something.avi',
  output: 'something.mp4',
  preset: 'Normal',
  rotate: 1
}
hbjs.spawn(options)
  .on('error', console.error)
  .on('output', console.log)

hbjs.exec(options, [onComplete])

使用提供的选项运行HandbrakeCLI，并在完成时调用提供的回调函数。exec方法最适合短期任务，您可以等待输出完成。

类型: <code>handbrake-js</code>的静态方法

参数	类型	描述
options	<code>Object</code>	直接传递给HandbrakeCLI的选项
[options.HandbrakeCLIPath]	<code>string</code>	覆盖内置的`HandbrakeCLI`二进制文件路径。
[onComplete]	<code>function</code>	如果传递，`onComplete(err, stdout, stderr)`将在完成时被调用，`stdout`和`stderr`是包含HandbrakeCLI输出的字符串。

示例

const hbjs = require('handbrake-js')

hbjs.exec({ preset-list: true }, function(err, stdout, stderr){
  if (err) throw err
  console.log(stdout)
})

hbjs.run(options) ⇒ <code>Promise</code>

与hbjs.exec相同，只是它返回一个promise，而不是调用回调。当您不需要hbjs.spawn报告的进度事件时使用此方法。返回一个包含两个属性的对象：stdout和stderr。

类型: <code>handbrake-js</code>的静态方法

参数	类型	描述
options	<code>Object</code>	直接传递给HandbrakeCLI的选项
[options.HandbrakeCLIPath]	<code>string</code>	覆盖内置的`HandbrakeCLI`二进制文件路径。

示例

const hbjs = require('handbrake-js')

async function start () {
  const result = await hbjs.run({ version: true })
  console.log(result.stdout)
  // 打印 'HandBrake 1.3.0'
}

start().catch(console.error)

handbrake-js~Handbrake ⇐ <code>EventEmitter</code>

HandbrakeCLI进程的句柄。发出可监视进度的事件。此类的实例由spawn返回。

类型: <code>handbrake-js</code>的内部类继承: <code>EventEmitter</code> 触发事件: <code>start</code>, <code>begin</code>, <code>progress</code>, <code>output</code>, <code>error</code>, <code>end</code>, <code>complete</code>, <code>cancelled</code>

~Handbrake ⇐ <code>EventEmitter</code>
- .output : <code>string</code>
- .options : <code>object</code>
- .eError
- .cancel()
- "start"
- "begin"
- "progress" (progress)
- "output" (output)
- "error" (error)
- "end"
- "complete"
- "cancelled"

handbrake.output : <code>string</code>

包含所有handbrakeCLI输出的字符串

类型: <code>Handbrake</code>的实例属性

handbrake.options : <code>object</code>

传递给spawn的选项副本

类型: <code>Handbrake</code>的实例属性

handbrake.eError

所有操作错误都通过error事件发出。

类型: <code>Handbrake</code>的实例枚举

属性

名称	默认值	描述
VALIDATION	<code>ValidationError</code>	当您不小心设置相同的输入和输出路径（这会覆盖输入文件），忘记指定输出路径以及其他验证错误时抛出。
INVALID_INPUT	<code>InvalidInput</code>	当指定的输入文件似乎不是视频文件时抛出。
INVALID_PRESET	<code>InvalidPreset</code>	当指定了无效的预设时抛出。
OTHER	<code>Other</code>	当Handbrake崩溃时抛出。
NOT_FOUND	<code>HandbrakeCLINotFound</code>	当安装的HandbrakeCLI二进制文件丢失时抛出。

handbrake.cancel()

取消编码，终止底层HandbrakeCLI进程，然后发出cancelled事件。

类型: <code>Handbrake</code>的实例方法

"start"

在HandbrakeCLI启动时触发。此时还没有发生任何事情。

类型: <code>Handbrake</code>触发的事件

"begin"

在编码开始时触发。如果您期望进行编码但此事件从未触发，说明出现了问题。

类型: <code>Handbrake</code>触发的事件

"progress" (progress)

定期触发，传递一个progress对象。

类型: <code>Handbrake</code>触发的事件

参数	类型	描述
progress	<code>object</code>	编码进度详情
progress.taskNumber	<code>number</code>	当前任务索引
progress.taskCount	<code>number</code>	队列中的总任务数
progress.percentComplete	<code>number</code>	完成百分比
progress.fps	<code>number</code>	每秒帧数
progress.avgFps	<code>number</code>	平均每秒帧数
progress.eta	<code>string</code>	预计完成时间
progress.task	<code>string</code>	任务描述，可能是"Encoding"（编码中）或"Muxing"（混流中）

"output" (output)

类型: 由 <code>Handbrake</code> 发出的事件

参数	类型	描述
output	<code>string</code>	底层HandbrakeCLI进程的`stdout`和`stderr`输出的聚合。

"error" (error)

类型: 由 <code>Handbrake</code> 发出的事件

参数	类型	描述
error	<code>Error</code>	所有操作异常都通过此事件传递。
error.name	<code>eError</code>	唯一的错误标识符
error.message	<code>string</code>	错误描述
error.errno	<code>string</code>	HandbrakeCLI的返回代码