7lab_groove_test 中文文档教程

Question

node-groove

Node.js 绑定到 libgroove - 通用音乐播放器后端库。

在 freenode 上的 #libgroove 中进行现场讨论。

以下是主要界面。 有关详细信息，请参阅下面的 API 文档。

• GrooveFile - represents an open audio file.
• GroovePlaylist - put files in the playlist, and the playlist decodes the files and fills up the attached sinks.
• GroovePlayer - attach this sink to a playlist to play the decoded audio over the system's speakers.
• GrooveEncoder - attach this sink to a playlist to obtain encoded audio buffers, such as an mp3 stream.
• GrooveLoudnessDetector - attach this sink to a playlist to compute how loud files sound to the human ear, along with the "true peak" value. You can use this to implement ReplayGain.
• GrooveFingerprinter - attach this sink to a playlist to compute an acoustid fingerprint. This can be used to look up a file by its audio content and figure out which tags should be applied.
• GrooveWaveformBuilder - attach this sink to a playlist to compute a JSON representation of an audio file. This can be used to display a visualization of the audio file.

Usage

1. Install libgroove to your system. libgroove is a set of 4 libraries; node-groove depends on all of them. So for example on ubuntu, make sure to install libgroove-dev, libgrooveplayer-dev, libgrooveloudness-dev, and libgroovefingerprinter-dev.
2. npm install --save groove

Versions

• node-groove >=3.0.0 depends on libgroove >=5.0.0
• node-groove >=2.4.0 <3.0.0 depends on libgroove >=4.3.0 <5.0.0
• node-groove 2.3.4 depends on libgroove <4.3.0

有关发行说明和升级指南，请参阅 CHANGELOG.md。

Get Metadata from File

var groove = require('groove');

groove.open("danse-macabre.ogg", function(err, file) {
  if (err) throw err;
  console.log(file.metadata());
  console.log("duration:", file.duration());
  file.close(function(err) {
    if (err) throw err;
  });
});

More Examples

• example/metadata.js - read or update metadata in a media file
• example/playlist.js - play several files in a row and then exit
• example/replaygain.js - compute replaygain values for media files
• example/transcode.js - convert and splice several files together
• example/fingerprint.js - create an acoustid fingerprint for media files
• example/devices.js - list the playback devices on the system
• example/waveform.js - calculate a waveformjs compatible representation of a media file

API Documentation

globals

groove.setLogging(level)

level 可以是：

• groove.LOG_QUIET
• groove.LOG_ERROR
• groove.LOG_WARNING
• groove.LOG_INFO

groove.loudnessToReplayGain(loudness)

将 LUFS 中的响度值转换为 ReplayGain 建议的 dB 调整。

groove.dBToFloat(dB)

将 dB 格式音量调整转换为浮点增益格式。

groove.getVersion()

返回具有以下属性的对象：

• major
• minor
• patch

GrooveFile

groove.open(filename, callback)

callback(err, file)

file.close(callback)

callback(err)

file.duration()

以秒为单位。

file.shortNames()

格式的短名称的逗号分隔列表。

file.getMetadata(key, [flags])

标志：

• groove.TAG_MATCH_CASE
• groove.TAG_DONT_OVERWRITE
• groove.TAG_APPEND

file.setMetadata(key, value, [flags])

有关标志，请参阅 getMetadata。

为 value 传递 null 以删除键。

file.metadata()

这将返回一个填充了所有元数据的对象。 更新对象什么都不做。 使用 setMetadata 来 更新元数据，然后保存将更改写入磁盘。

file.dirty

布尔值 save 是否会做任何事情。

file.filename

传递给 groove.open 的字符串

file.overrideDuration(duration)

如果您确定文件的实际持续时间，请调用此函数 设置文件的实际持续时间（以秒为单位）。 GrooveWaveformBuilder 将使用此值代替 file.duration()。

仅当没有 GroovePlaylistItem 引用此文件时才必须调用此方法。

file.save(callback)

callback(err)

GroovePlaylist

groove.createPlaylist()

保持音频缓冲区满的播放列表管理器。 发送缓冲区 到你的扬声器，使用 playlist.createPlayer()。

注意：您可能只想要一个播放列表。 在 node-groove 中，播放列表是 低级音频处理概念，不要与面向用户混淆 用户可以在其中添加、删除和重新排序歌曲的播放列表。

playlist.destroy()

完成播放列表后，您必须销毁它。

playlist.items()

返回播放列表项的只读数组。 使用playlist.insert 和playlist.remove 进行修改。

[playlistItem1, playlistItem2, ...]

playlist.play()

playlist.pause()

playlist.seek(playlistItem, position)

寻找 playlistItem，位置 秒进入歌曲。

playlist.insert(file, gain, peak, nextPlaylistItem)

使用文件创建一个新的播放列表项并将其放入之前的播放列表中 <代码>下一个播放列表项。 如果 nextPlaylistItem 为 null，则附加新的 项添加到播放列表。

gain 是仅适用于此项目的浮点格式音量调整。 默认为 1.0

peak 为 float 格式，参见 item.peak。 默认为 1.0

返回新添加的播放列表项。

将文件添加到播放列表后，您不能 file.close() 它直到 您首先将其从播放列表中删除。

playlist.remove(playlistItem)

从播放列表中删除 playlistItem。

请注意，您有责任对每个文件调用 file.close() 您使用 groove.open 打开。 playlist.remove 不会关闭文件。

playlist.position()

返回 {item, pos} 其中 item 是当前播放列表项 decoded 和 pos 是解码头进入歌曲的秒数。

请注意，通常您对播放头的位置更感兴趣， 不是解码头。 返回播放头的示例方法是 player.position() 和 encoder.position()。

playlist.playing()

返回 true 或 false。

playlist.clear()

删除所有播放列表项。

playlist.count()

播放列表中有多少项目。

playlist.gain

playlist.setGain(value)

在 0.0 和 1.0 之间。 您可能希望将其保留为 1.0，因为使用 replaygain 通常会大大降低您的音量。

playlist.setItemGainPeak(playlistItem, gain, peak)

gain 是一个浮点数，它只影响指定播放列表项的音量。 要从 dB 转换为浮点数，请使用 exp(log(10) * 0.05 * dBValue)。

请参阅 item.peak

playlist.setFillMode(mode)

mode 可以是：

• groove.EVERY_SINK_FULL

  如果任何接收器未满，播放列表将解码音频。 如果有任何汇 耗尽速度不够快，数据将缓冲在播放列表中。

• groove.ANY_SINK_FULL

  这是默认行为。 使用此行为，播放列表将停止 当任何连接的接收器已满时解码音频，然后恢复解码 音频每个水槽都没有装满。

默认为 groove.EVERY_SINK_FULL。

GroovePlaylistItem

这些不是直接实例化的； 相反，它们是从 playlist.items()。

GroovePlaylistItem 只是指向 GroovePlaylist 的指针。 如果你 从播放列表中删除播放列表项目，任何播放列表项目引用您 到处都是悬垂的指针。

item.file

只读。

item.gain

播放文件时应用到文件的浮动格式的音量调整。 这通常用于响度补偿，例如 ReplayGain。 要从 dB 转换为浮点数，请使用 groove.dBToFloat

只读。 使用playlist.setItemGain修改。

item.peak

此播放列表项目的样本峰值假定为 1.0 浮点数 格式。 如果您确定峰值小于 1.0，您 可以设置这个值，这可能允许音量调整使用 纯放大器而不是压缩器。 这导致稍微 更好的音频质量。

只读。 使用playlist.setItemPeak 修改。

item.id

每次从 groove 中获得一个播放列表项目，您将获得一个新的 JavaScript 对象，但它可能指向相同的底层 libgroove 指针 作为另一个。 id 字段是一种检查两个播放列表项是否引用的方法 同一个。

只读。

GroovePlayer

groove.getDevices()

在调用此函数之前，您必须先调用 <代码>groove.connectSoundBackend()。

返回一个像这样的对象：

{
  list: [
    {
      name: "User-Friendly Device Name",
      id: "unique device ID that persists across plugs and unplugs",
      isRaw: false, // true if this device would claim exclusive access
      probeError: 3, // non zero if scanning this device did not work
    },
    //...
  ],
  defaultIndex: 0,
}

groove.connectSoundBackend([backend])

backend 是可选的。 如果留空，最好的后端是自动的 选择。 否则它可以是以下之一：

• groove.BACKEND_JACK
• groove.BACKEND_PULSEAUDIO
• groove.BACKEND_ALSA
• groove.BACKEND_COREAUDIO
• groove.BACKEND_WASAPI
• groove.BACKEND_DUMMY

groove.disconnectSoundBackend()

groove.createPlayer()

创建一个 GroovePlayer 实例，然后您可以通过设置对其进行配置 特性。

player.device

在调用 attach() 之前，将其设置为其中一个设备 从 groove.getDevices() 返回。

player.attach(playlist, callback)

将音频发送到声音设备。

callback(err)

player.detach(callback)

callback(err)

player.position()

返回 {item, pos} 其中 item 是当前播放列表项 played 和 pos 是播放头进入歌曲的秒数。

player.on('nowplaying', handler)

当正在播放的项目改变时触发。 它可以是 null。

handler()

player.on('bufferunderrun', handler)

当发生缓冲区欠载时触发。 理想情况下，您永远不会看到这一点。

handler()

player.on('devicereopened', handler)

当您将 useExactAudioFormat 设置为 true 并且音频设备时触发 已关闭并重新打开以匹配传入的音频数据。

handler()

GrooveEncoder

groove.createEncoder()

encoder.bitRate

通过选择一个

encoder.formatShortName

可选的目标比特率来选择编码质量——帮助 libgroove 猜测要使用的格式。 avconv -formats 以获得可能性列表。

encoder.codecShortName

可选 - 帮助 libgroove 猜测使用哪个编解码器。 avconv-codecs 以获得可能性列表。

encoder.filename

可选 - 提供示例文件名以帮助 libgroove 猜测 使用哪种格式/编解码器。

encoder.mimeType

可选 - 提供 mime 类型字符串以帮助 libgrooove 猜测 使用哪种格式/编解码器。

encoder.targetAudioFormat

用于编码的所需音频格式设置。 groove.createEncoder() 默认为 44100 Hz， 带符号的 16 位整数，立体声。 这些是偏好； 如果不能使用设置，替代品将 被使用。 在这种情况下，actualAudioFormat 将被更新以反映 替代值。

属性：

• sampleRate
• channelLayout - array of channel ids
• sampleFormat

encoder.actualAudioFormat

groove 将其设置为附加编码器时获得的实际格式。 理想情况下与 targetAudioFormat 相同，但也可能不同。

属性：

• sampleRate
• channelLayout - array of channel ids
• sampleFormat

encoder.sinkBufferSize

接收器缓冲区应该有多大，以样本帧为单位。 createEncoder 默认为 8192

encoder.encodedBufferSize

编码的音频缓冲区应该有多大，以字节为单位。 createEncoder 默认为 16384

encoder.attach(playlist, callback)

callback(err)

encoder.detach(callback)

callback(err)</

encoder.getBuffer()

code> 如果没有缓冲区可用则返回 null，或者具有以下属性的对象：

• buffer - a node Buffer instance which is the encoded data for this chunk this can be null in which case this buffer is actually the end of playlist sentinel.
• item - the GroovePlaylistItem of which this buffer is encoded data for
• pos - position in seconds that this buffer represents in into the item

encoder.on('buffer', handler)

handler()

当有缓冲区可供获取时发出。 你仍然需要得到 使用 getBuffer() 缓冲。

encoder.position()

返回 {item, pos} 其中 item 是当前播放列表项 encoded 和 pos 是编码头进入歌曲的秒数。

GrooveLoudnessDetector

groove.createLoudnessDetector()

返回一个 GrooveLoudnessDetector

detector.infoQueueSize

设置它以确定播放列表中要看多远。

detector.disableAlbum

设置为 true 以仅计算音轨响度。 这更快，需要更少 内存比计算两者。

detector.attach(playlist, callback)

callback(err)

detector.detach(callback)

callback(err)</

detector.getInfo()

code> 如果没有可用信息或具有以下属性的对象，则返回 null：

• loudness - loudness in LUFS
• peak - sample peak in float format of the file
• duration - duration in seconds of the track
• item - the GroovePlaylistItem that this applies to, or null if it applies to the entire album.

detector.position()

返回 {item, pos} 其中 item 是当前正在播放的播放列表项 detected 和 pos 是检测头进入歌曲的秒数。

detector.on('info', handler)

handler()

当有信息可供获取时发出。 您仍然需要获取信息 使用 getInfo()。

GrooveFingerprinter

groove.createFingerprinter()

返回一个 GrooveFingerprinter

groove.encodeFingerprint(rawFingerprint)

给定一个整数数组，它是原始指纹，将它编码成一个 可以提交给 acoustid.org 的字符串。

groove.decodeFingerprint(fingerprint)

给定指纹字符串，返回原始整数列表 指纹数据。

printer.infoQueueSize

设置此项以确定播放列表中要看多远。

printer.attach(playlist, callback)

callback(err)

printer.detach(callback)

callback(err)</

printer.getInfo()

code> 如果没有可用信息或具有以下属性的对象，则返回 null：

• fingerprint - integer array which is the raw fingerprint
• duration - duration in seconds of the track
• item - the GroovePlaylistItem that this applies to, or null if it applies to the entire album.

printer.position()

返回 {item, pos} 其中 item 是当前正在播放的播放列表项 fingerprinted 和 pos 是打印机头进入歌曲的秒数。

printer.on('info', handler)

handler()

当有信息可供获取时发出。 您仍然需要获取信息 使用 getInfo()。

GrooveWaveformBuilder

groove.createWaveformBuilder()

返回一个 GrooveWaveformBuilder

waveform.widthInFrames

波形数据将有多少帧宽。 默认为 1920。

如果您有一首 100 帧的歌曲，并且 widthInFrames 为 50，则每个 波形数据帧会对应原曲的2帧。

printer.infoQueueSizeBytes

设置此项以确定播放列表中要看多远。

waveform.attach(playlist, callback)

callback(err)

waveform.detach(callback)

callback(err)</

waveform.getInfo()

code> 如果没有可用信息或具有以下属性的对象，则返回 null：

• buffer - A Buffer of the waveform data, one unsigned 8 bit integer per widthInFrames.
• expectedDuration - This is the duration in seconds that was used to create the waveform data. If this is different than actualDuration then the data is invalid and must be re-calculated, this time using file.overrideDuration()
• actualDuration - This is the correct duration in seconds for the track, known only after waveform calculation is complete.
• item - the GroovePlaylistItem that this applies to, or null if this info signals the end of playlist.

waveform.position()

返回 {item, pos} 其中 item 是当前正在播放的播放列表项 计算出 pos 是波形头进入歌曲的秒数。

waveform.on('info', handler)

handler()

当有信息可供获取时发出。 您仍然需要获取信息 使用 getInfo()。